ssl.h 113 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438143914401441144214431444144514461447144814491450145114521453145414551456145714581459146014611462146314641465146614671468146914701471147214731474147514761477147814791480148114821483148414851486148714881489149014911492149314941495149614971498149915001501150215031504150515061507150815091510151115121513151415151516151715181519152015211522152315241525152615271528152915301531153215331534153515361537153815391540154115421543154415451546154715481549155015511552155315541555155615571558155915601561156215631564156515661567156815691570157115721573157415751576157715781579158015811582158315841585158615871588158915901591159215931594159515961597159815991600160116021603160416051606160716081609161016111612161316141615161616171618161916201621162216231624162516261627162816291630163116321633163416351636163716381639164016411642164316441645164616471648164916501651165216531654165516561657165816591660166116621663166416651666166716681669167016711672167316741675167616771678167916801681168216831684168516861687168816891690169116921693169416951696169716981699170017011702170317041705170617071708170917101711171217131714171517161717171817191720172117221723172417251726172717281729173017311732173317341735173617371738173917401741174217431744174517461747174817491750175117521753175417551756175717581759176017611762176317641765176617671768176917701771177217731774177517761777177817791780178117821783178417851786178717881789179017911792179317941795179617971798179918001801180218031804180518061807180818091810181118121813181418151816181718181819182018211822182318241825182618271828182918301831183218331834183518361837183818391840184118421843184418451846184718481849185018511852185318541855185618571858185918601861186218631864186518661867186818691870187118721873187418751876187718781879188018811882188318841885188618871888188918901891189218931894189518961897189818991900190119021903190419051906190719081909191019111912191319141915191619171918191919201921192219231924192519261927192819291930193119321933193419351936193719381939194019411942194319441945194619471948194919501951195219531954195519561957195819591960196119621963196419651966196719681969197019711972197319741975197619771978197919801981198219831984198519861987198819891990199119921993199419951996199719981999200020012002200320042005200620072008200920102011201220132014201520162017201820192020202120222023202420252026202720282029203020312032203320342035203620372038203920402041204220432044204520462047204820492050205120522053205420552056205720582059206020612062206320642065206620672068206920702071207220732074207520762077207820792080208120822083208420852086208720882089209020912092209320942095209620972098209921002101210221032104210521062107210821092110211121122113211421152116211721182119212021212122212321242125212621272128212921302131213221332134213521362137213821392140214121422143214421452146214721482149215021512152215321542155215621572158215921602161216221632164216521662167216821692170217121722173217421752176217721782179218021812182218321842185218621872188218921902191219221932194219521962197219821992200220122022203220422052206220722082209221022112212221322142215221622172218221922202221222222232224222522262227222822292230223122322233223422352236223722382239224022412242224322442245224622472248224922502251225222532254225522562257225822592260226122622263226422652266226722682269227022712272227322742275227622772278227922802281228222832284228522862287228822892290229122922293229422952296229722982299230023012302230323042305230623072308230923102311231223132314231523162317231823192320232123222323232423252326232723282329233023312332233323342335233623372338233923402341234223432344234523462347234823492350235123522353235423552356235723582359236023612362236323642365236623672368236923702371237223732374237523762377237823792380238123822383238423852386238723882389239023912392239323942395239623972398239924002401240224032404240524062407240824092410241124122413241424152416241724182419242024212422242324242425242624272428242924302431243224332434243524362437243824392440244124422443244424452446244724482449245024512452245324542455245624572458245924602461246224632464246524662467246824692470247124722473247424752476247724782479248024812482248324842485248624872488248924902491249224932494249524962497249824992500250125022503250425052506250725082509251025112512251325142515251625172518251925202521252225232524252525262527252825292530253125322533253425352536253725382539254025412542254325442545254625472548254925502551255225532554255525562557255825592560256125622563256425652566256725682569257025712572257325742575257625772578257925802581258225832584258525862587258825892590259125922593259425952596259725982599260026012602260326042605260626072608260926102611261226132614261526162617261826192620262126222623
  1. /**
  2. * \file ssl.h
  3. *
  4. * \brief SSL/TLS functions.
  5. */
  6. /*
  7. * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
  8. * SPDX-License-Identifier: Apache-2.0
  9. *
  10. * Licensed under the Apache License, Version 2.0 (the "License"); you may
  11. * not use this file except in compliance with the License.
  12. * You may obtain a copy of the License at
  13. *
  14. * http://www.apache.org/licenses/LICENSE-2.0
  15. *
  16. * Unless required by applicable law or agreed to in writing, software
  17. * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
  18. * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  19. * See the License for the specific language governing permissions and
  20. * limitations under the License.
  21. *
  22. * This file is part of mbed TLS (https://tls.mbed.org)
  23. */
  24. #ifndef MBEDTLS_SSL_H
  25. #define MBEDTLS_SSL_H
  26. #if !defined(MBEDTLS_CONFIG_FILE)
  27. #include "config.h"
  28. #else
  29. #include MBEDTLS_CONFIG_FILE
  30. #endif
  31. #include "bignum.h"
  32. #include "ecp.h"
  33. #include "ssl_ciphersuites.h"
  34. #if defined(MBEDTLS_X509_CRT_PARSE_C)
  35. #include "x509_crt.h"
  36. #include "x509_crl.h"
  37. #endif
  38. #if defined(MBEDTLS_DHM_C)
  39. #include "dhm.h"
  40. #endif
  41. #if defined(MBEDTLS_ECDH_C)
  42. #include "ecdh.h"
  43. #endif
  44. #if defined(MBEDTLS_ZLIB_SUPPORT)
  45. #include "zlib.h"
  46. #endif
  47. #if defined(MBEDTLS_HAVE_TIME)
  48. #include "mbedtls/platform_time.h"
  49. #endif
  50. /*
  51. * SSL Error codes
  52. */
  53. #define MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE -0x7080 /**< The requested feature is not available. */
  54. #define MBEDTLS_ERR_SSL_BAD_INPUT_DATA -0x7100 /**< Bad input parameters to function. */
  55. #define MBEDTLS_ERR_SSL_INVALID_MAC -0x7180 /**< Verification of the message MAC failed. */
  56. #define MBEDTLS_ERR_SSL_INVALID_RECORD -0x7200 /**< An invalid SSL record was received. */
  57. #define MBEDTLS_ERR_SSL_CONN_EOF -0x7280 /**< The connection indicated an EOF. */
  58. #define MBEDTLS_ERR_SSL_UNKNOWN_CIPHER -0x7300 /**< An unknown cipher was received. */
  59. #define MBEDTLS_ERR_SSL_NO_CIPHER_CHOSEN -0x7380 /**< The server has no ciphersuites in common with the client. */
  60. #define MBEDTLS_ERR_SSL_NO_RNG -0x7400 /**< No RNG was provided to the SSL module. */
  61. #define MBEDTLS_ERR_SSL_NO_CLIENT_CERTIFICATE -0x7480 /**< No client certification received from the client, but required by the authentication mode. */
  62. #define MBEDTLS_ERR_SSL_CERTIFICATE_TOO_LARGE -0x7500 /**< Our own certificate(s) is/are too large to send in an SSL message. */
  63. #define MBEDTLS_ERR_SSL_CERTIFICATE_REQUIRED -0x7580 /**< The own certificate is not set, but needed by the server. */
  64. #define MBEDTLS_ERR_SSL_PRIVATE_KEY_REQUIRED -0x7600 /**< The own private key or pre-shared key is not set, but needed. */
  65. #define MBEDTLS_ERR_SSL_CA_CHAIN_REQUIRED -0x7680 /**< No CA Chain is set, but required to operate. */
  66. #define MBEDTLS_ERR_SSL_UNEXPECTED_MESSAGE -0x7700 /**< An unexpected message was received from our peer. */
  67. #define MBEDTLS_ERR_SSL_FATAL_ALERT_MESSAGE -0x7780 /**< A fatal alert message was received from our peer. */
  68. #define MBEDTLS_ERR_SSL_PEER_VERIFY_FAILED -0x7800 /**< Verification of our peer failed. */
  69. #define MBEDTLS_ERR_SSL_PEER_CLOSE_NOTIFY -0x7880 /**< The peer notified us that the connection is going to be closed. */
  70. #define MBEDTLS_ERR_SSL_BAD_HS_CLIENT_HELLO -0x7900 /**< Processing of the ClientHello handshake message failed. */
  71. #define MBEDTLS_ERR_SSL_BAD_HS_SERVER_HELLO -0x7980 /**< Processing of the ServerHello handshake message failed. */
  72. #define MBEDTLS_ERR_SSL_BAD_HS_CERTIFICATE -0x7A00 /**< Processing of the Certificate handshake message failed. */
  73. #define MBEDTLS_ERR_SSL_BAD_HS_CERTIFICATE_REQUEST -0x7A80 /**< Processing of the CertificateRequest handshake message failed. */
  74. #define MBEDTLS_ERR_SSL_BAD_HS_SERVER_KEY_EXCHANGE -0x7B00 /**< Processing of the ServerKeyExchange handshake message failed. */
  75. #define MBEDTLS_ERR_SSL_BAD_HS_SERVER_HELLO_DONE -0x7B80 /**< Processing of the ServerHelloDone handshake message failed. */
  76. #define MBEDTLS_ERR_SSL_BAD_HS_CLIENT_KEY_EXCHANGE -0x7C00 /**< Processing of the ClientKeyExchange handshake message failed. */
  77. #define MBEDTLS_ERR_SSL_BAD_HS_CLIENT_KEY_EXCHANGE_RP -0x7C80 /**< Processing of the ClientKeyExchange handshake message failed in DHM / ECDH Read Public. */
  78. #define MBEDTLS_ERR_SSL_BAD_HS_CLIENT_KEY_EXCHANGE_CS -0x7D00 /**< Processing of the ClientKeyExchange handshake message failed in DHM / ECDH Calculate Secret. */
  79. #define MBEDTLS_ERR_SSL_BAD_HS_CERTIFICATE_VERIFY -0x7D80 /**< Processing of the CertificateVerify handshake message failed. */
  80. #define MBEDTLS_ERR_SSL_BAD_HS_CHANGE_CIPHER_SPEC -0x7E00 /**< Processing of the ChangeCipherSpec handshake message failed. */
  81. #define MBEDTLS_ERR_SSL_BAD_HS_FINISHED -0x7E80 /**< Processing of the Finished handshake message failed. */
  82. #define MBEDTLS_ERR_SSL_ALLOC_FAILED -0x7F00 /**< Memory allocation failed */
  83. #define MBEDTLS_ERR_SSL_HW_ACCEL_FAILED -0x7F80 /**< Hardware acceleration function returned with error */
  84. #define MBEDTLS_ERR_SSL_HW_ACCEL_FALLTHROUGH -0x6F80 /**< Hardware acceleration function skipped / left alone data */
  85. #define MBEDTLS_ERR_SSL_COMPRESSION_FAILED -0x6F00 /**< Processing of the compression / decompression failed */
  86. #define MBEDTLS_ERR_SSL_BAD_HS_PROTOCOL_VERSION -0x6E80 /**< Handshake protocol not within min/max boundaries */
  87. #define MBEDTLS_ERR_SSL_BAD_HS_NEW_SESSION_TICKET -0x6E00 /**< Processing of the NewSessionTicket handshake message failed. */
  88. #define MBEDTLS_ERR_SSL_SESSION_TICKET_EXPIRED -0x6D80 /**< Session ticket has expired. */
  89. #define MBEDTLS_ERR_SSL_PK_TYPE_MISMATCH -0x6D00 /**< Public key type mismatch (eg, asked for RSA key exchange and presented EC key) */
  90. #define MBEDTLS_ERR_SSL_UNKNOWN_IDENTITY -0x6C80 /**< Unknown identity received (eg, PSK identity) */
  91. #define MBEDTLS_ERR_SSL_INTERNAL_ERROR -0x6C00 /**< Internal error (eg, unexpected failure in lower-level module) */
  92. #define MBEDTLS_ERR_SSL_COUNTER_WRAPPING -0x6B80 /**< A counter would wrap (eg, too many messages exchanged). */
  93. #define MBEDTLS_ERR_SSL_WAITING_SERVER_HELLO_RENEGO -0x6B00 /**< Unexpected message at ServerHello in renegotiation. */
  94. #define MBEDTLS_ERR_SSL_HELLO_VERIFY_REQUIRED -0x6A80 /**< DTLS client must retry for hello verification */
  95. #define MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL -0x6A00 /**< A buffer is too small to receive or write a message */
  96. #define MBEDTLS_ERR_SSL_NO_USABLE_CIPHERSUITE -0x6980 /**< None of the common ciphersuites is usable (eg, no suitable certificate, see debug messages). */
  97. #define MBEDTLS_ERR_SSL_WANT_READ -0x6900 /**< Connection requires a read call. */
  98. #define MBEDTLS_ERR_SSL_WANT_WRITE -0x6880 /**< Connection requires a write call. */
  99. #define MBEDTLS_ERR_SSL_TIMEOUT -0x6800 /**< The operation timed out. */
  100. #define MBEDTLS_ERR_SSL_CLIENT_RECONNECT -0x6780 /**< The client initiated a reconnect from the same port. */
  101. #define MBEDTLS_ERR_SSL_UNEXPECTED_RECORD -0x6700 /**< Record header looks valid but is not expected. */
  102. #define MBEDTLS_ERR_SSL_NON_FATAL -0x6680 /**< The alert message received indicates a non-fatal error. */
  103. #define MBEDTLS_ERR_SSL_INVALID_VERIFY_HASH -0x6600 /**< Couldn't set the hash for verifying CertificateVerify */
  104. /*
  105. * Various constants
  106. */
  107. #define MBEDTLS_SSL_MAJOR_VERSION_3 3
  108. #define MBEDTLS_SSL_MINOR_VERSION_0 0 /*!< SSL v3.0 */
  109. #define MBEDTLS_SSL_MINOR_VERSION_1 1 /*!< TLS v1.0 */
  110. #define MBEDTLS_SSL_MINOR_VERSION_2 2 /*!< TLS v1.1 */
  111. #define MBEDTLS_SSL_MINOR_VERSION_3 3 /*!< TLS v1.2 */
  112. #define MBEDTLS_SSL_TRANSPORT_STREAM 0 /*!< TLS */
  113. #define MBEDTLS_SSL_TRANSPORT_DATAGRAM 1 /*!< DTLS */
  114. #define MBEDTLS_SSL_MAX_HOST_NAME_LEN 255 /*!< Maximum host name defined in RFC 1035 */
  115. /* RFC 6066 section 4, see also mfl_code_to_length in ssl_tls.c
  116. * NONE must be zero so that memset()ing structure to zero works */
  117. #define MBEDTLS_SSL_MAX_FRAG_LEN_NONE 0 /*!< don't use this extension */
  118. #define MBEDTLS_SSL_MAX_FRAG_LEN_512 1 /*!< MaxFragmentLength 2^9 */
  119. #define MBEDTLS_SSL_MAX_FRAG_LEN_1024 2 /*!< MaxFragmentLength 2^10 */
  120. #define MBEDTLS_SSL_MAX_FRAG_LEN_2048 3 /*!< MaxFragmentLength 2^11 */
  121. #define MBEDTLS_SSL_MAX_FRAG_LEN_4096 4 /*!< MaxFragmentLength 2^12 */
  122. #define MBEDTLS_SSL_MAX_FRAG_LEN_INVALID 5 /*!< first invalid value */
  123. #define MBEDTLS_SSL_IS_CLIENT 0
  124. #define MBEDTLS_SSL_IS_SERVER 1
  125. #define MBEDTLS_SSL_IS_NOT_FALLBACK 0
  126. #define MBEDTLS_SSL_IS_FALLBACK 1
  127. #define MBEDTLS_SSL_EXTENDED_MS_DISABLED 0
  128. #define MBEDTLS_SSL_EXTENDED_MS_ENABLED 1
  129. #define MBEDTLS_SSL_ETM_DISABLED 0
  130. #define MBEDTLS_SSL_ETM_ENABLED 1
  131. #define MBEDTLS_SSL_COMPRESS_NULL 0
  132. #define MBEDTLS_SSL_COMPRESS_DEFLATE 1
  133. #define MBEDTLS_SSL_VERIFY_NONE 0
  134. #define MBEDTLS_SSL_VERIFY_OPTIONAL 1
  135. #define MBEDTLS_SSL_VERIFY_REQUIRED 2
  136. #define MBEDTLS_SSL_VERIFY_UNSET 3 /* Used only for sni_authmode */
  137. #define MBEDTLS_SSL_LEGACY_RENEGOTIATION 0
  138. #define MBEDTLS_SSL_SECURE_RENEGOTIATION 1
  139. #define MBEDTLS_SSL_RENEGOTIATION_DISABLED 0
  140. #define MBEDTLS_SSL_RENEGOTIATION_ENABLED 1
  141. #define MBEDTLS_SSL_ANTI_REPLAY_DISABLED 0
  142. #define MBEDTLS_SSL_ANTI_REPLAY_ENABLED 1
  143. #define MBEDTLS_SSL_RENEGOTIATION_NOT_ENFORCED -1
  144. #define MBEDTLS_SSL_RENEGO_MAX_RECORDS_DEFAULT 16
  145. #define MBEDTLS_SSL_LEGACY_NO_RENEGOTIATION 0
  146. #define MBEDTLS_SSL_LEGACY_ALLOW_RENEGOTIATION 1
  147. #define MBEDTLS_SSL_LEGACY_BREAK_HANDSHAKE 2
  148. #define MBEDTLS_SSL_TRUNC_HMAC_DISABLED 0
  149. #define MBEDTLS_SSL_TRUNC_HMAC_ENABLED 1
  150. #define MBEDTLS_SSL_TRUNCATED_HMAC_LEN 10 /* 80 bits, rfc 6066 section 7 */
  151. #define MBEDTLS_SSL_SESSION_TICKETS_DISABLED 0
  152. #define MBEDTLS_SSL_SESSION_TICKETS_ENABLED 1
  153. #define MBEDTLS_SSL_CBC_RECORD_SPLITTING_DISABLED 0
  154. #define MBEDTLS_SSL_CBC_RECORD_SPLITTING_ENABLED 1
  155. #define MBEDTLS_SSL_ARC4_ENABLED 0
  156. #define MBEDTLS_SSL_ARC4_DISABLED 1
  157. #define MBEDTLS_SSL_PRESET_DEFAULT 0
  158. #define MBEDTLS_SSL_PRESET_SUITEB 2
  159. #define MBEDTLS_SSL_CERT_REQ_CA_LIST_ENABLED 1
  160. #define MBEDTLS_SSL_CERT_REQ_CA_LIST_DISABLED 0
  161. /*
  162. * Default range for DTLS retransmission timer value, in milliseconds.
  163. * RFC 6347 4.2.4.1 says from 1 second to 60 seconds.
  164. */
  165. #define MBEDTLS_SSL_DTLS_TIMEOUT_DFL_MIN 1000
  166. #define MBEDTLS_SSL_DTLS_TIMEOUT_DFL_MAX 60000
  167. /**
  168. * \name SECTION: Module settings
  169. *
  170. * The configuration options you can set for this module are in this section.
  171. * Either change them in config.h or define them on the compiler command line.
  172. * \{
  173. */
  174. #if !defined(MBEDTLS_SSL_DEFAULT_TICKET_LIFETIME)
  175. #define MBEDTLS_SSL_DEFAULT_TICKET_LIFETIME 86400 /**< Lifetime of session tickets (if enabled) */
  176. #endif
  177. /*
  178. * Maxium fragment length in bytes,
  179. * determines the size of each of the two internal I/O buffers.
  180. *
  181. * Note: the RFC defines the default size of SSL / TLS messages. If you
  182. * change the value here, other clients / servers may not be able to
  183. * communicate with you anymore. Only change this value if you control
  184. * both sides of the connection and have it reduced at both sides, or
  185. * if you're using the Max Fragment Length extension and you know all your
  186. * peers are using it too!
  187. */
  188. #if !defined(MBEDTLS_SSL_MAX_CONTENT_LEN)
  189. #define MBEDTLS_SSL_MAX_CONTENT_LEN 16384 /**< Size of the input / output buffer */
  190. #endif
  191. /* \} name SECTION: Module settings */
  192. /*
  193. * Length of the verify data for secure renegotiation
  194. */
  195. #if defined(MBEDTLS_SSL_PROTO_SSL3)
  196. #define MBEDTLS_SSL_VERIFY_DATA_MAX_LEN 36
  197. #else
  198. #define MBEDTLS_SSL_VERIFY_DATA_MAX_LEN 12
  199. #endif
  200. /*
  201. * Signaling ciphersuite values (SCSV)
  202. */
  203. #define MBEDTLS_SSL_EMPTY_RENEGOTIATION_INFO 0xFF /**< renegotiation info ext */
  204. #define MBEDTLS_SSL_FALLBACK_SCSV_VALUE 0x5600 /**< RFC 7507 section 2 */
  205. /*
  206. * Supported Signature and Hash algorithms (For TLS 1.2)
  207. * RFC 5246 section 7.4.1.4.1
  208. */
  209. #define MBEDTLS_SSL_HASH_NONE 0
  210. #define MBEDTLS_SSL_HASH_MD5 1
  211. #define MBEDTLS_SSL_HASH_SHA1 2
  212. #define MBEDTLS_SSL_HASH_SHA224 3
  213. #define MBEDTLS_SSL_HASH_SHA256 4
  214. #define MBEDTLS_SSL_HASH_SHA384 5
  215. #define MBEDTLS_SSL_HASH_SHA512 6
  216. #define MBEDTLS_SSL_SIG_ANON 0
  217. #define MBEDTLS_SSL_SIG_RSA 1
  218. #define MBEDTLS_SSL_SIG_ECDSA 3
  219. /*
  220. * Client Certificate Types
  221. * RFC 5246 section 7.4.4 plus RFC 4492 section 5.5
  222. */
  223. #define MBEDTLS_SSL_CERT_TYPE_RSA_SIGN 1
  224. #define MBEDTLS_SSL_CERT_TYPE_ECDSA_SIGN 64
  225. /*
  226. * Message, alert and handshake types
  227. */
  228. #define MBEDTLS_SSL_MSG_CHANGE_CIPHER_SPEC 20
  229. #define MBEDTLS_SSL_MSG_ALERT 21
  230. #define MBEDTLS_SSL_MSG_HANDSHAKE 22
  231. #define MBEDTLS_SSL_MSG_APPLICATION_DATA 23
  232. #define MBEDTLS_SSL_ALERT_LEVEL_WARNING 1
  233. #define MBEDTLS_SSL_ALERT_LEVEL_FATAL 2
  234. #define MBEDTLS_SSL_ALERT_MSG_CLOSE_NOTIFY 0 /* 0x00 */
  235. #define MBEDTLS_SSL_ALERT_MSG_UNEXPECTED_MESSAGE 10 /* 0x0A */
  236. #define MBEDTLS_SSL_ALERT_MSG_BAD_RECORD_MAC 20 /* 0x14 */
  237. #define MBEDTLS_SSL_ALERT_MSG_DECRYPTION_FAILED 21 /* 0x15 */
  238. #define MBEDTLS_SSL_ALERT_MSG_RECORD_OVERFLOW 22 /* 0x16 */
  239. #define MBEDTLS_SSL_ALERT_MSG_DECOMPRESSION_FAILURE 30 /* 0x1E */
  240. #define MBEDTLS_SSL_ALERT_MSG_HANDSHAKE_FAILURE 40 /* 0x28 */
  241. #define MBEDTLS_SSL_ALERT_MSG_NO_CERT 41 /* 0x29 */
  242. #define MBEDTLS_SSL_ALERT_MSG_BAD_CERT 42 /* 0x2A */
  243. #define MBEDTLS_SSL_ALERT_MSG_UNSUPPORTED_CERT 43 /* 0x2B */
  244. #define MBEDTLS_SSL_ALERT_MSG_CERT_REVOKED 44 /* 0x2C */
  245. #define MBEDTLS_SSL_ALERT_MSG_CERT_EXPIRED 45 /* 0x2D */
  246. #define MBEDTLS_SSL_ALERT_MSG_CERT_UNKNOWN 46 /* 0x2E */
  247. #define MBEDTLS_SSL_ALERT_MSG_ILLEGAL_PARAMETER 47 /* 0x2F */
  248. #define MBEDTLS_SSL_ALERT_MSG_UNKNOWN_CA 48 /* 0x30 */
  249. #define MBEDTLS_SSL_ALERT_MSG_ACCESS_DENIED 49 /* 0x31 */
  250. #define MBEDTLS_SSL_ALERT_MSG_DECODE_ERROR 50 /* 0x32 */
  251. #define MBEDTLS_SSL_ALERT_MSG_DECRYPT_ERROR 51 /* 0x33 */
  252. #define MBEDTLS_SSL_ALERT_MSG_EXPORT_RESTRICTION 60 /* 0x3C */
  253. #define MBEDTLS_SSL_ALERT_MSG_PROTOCOL_VERSION 70 /* 0x46 */
  254. #define MBEDTLS_SSL_ALERT_MSG_INSUFFICIENT_SECURITY 71 /* 0x47 */
  255. #define MBEDTLS_SSL_ALERT_MSG_INTERNAL_ERROR 80 /* 0x50 */
  256. #define MBEDTLS_SSL_ALERT_MSG_INAPROPRIATE_FALLBACK 86 /* 0x56 */
  257. #define MBEDTLS_SSL_ALERT_MSG_USER_CANCELED 90 /* 0x5A */
  258. #define MBEDTLS_SSL_ALERT_MSG_NO_RENEGOTIATION 100 /* 0x64 */
  259. #define MBEDTLS_SSL_ALERT_MSG_UNSUPPORTED_EXT 110 /* 0x6E */
  260. #define MBEDTLS_SSL_ALERT_MSG_UNRECOGNIZED_NAME 112 /* 0x70 */
  261. #define MBEDTLS_SSL_ALERT_MSG_UNKNOWN_PSK_IDENTITY 115 /* 0x73 */
  262. #define MBEDTLS_SSL_ALERT_MSG_NO_APPLICATION_PROTOCOL 120 /* 0x78 */
  263. #define MBEDTLS_SSL_HS_HELLO_REQUEST 0
  264. #define MBEDTLS_SSL_HS_CLIENT_HELLO 1
  265. #define MBEDTLS_SSL_HS_SERVER_HELLO 2
  266. #define MBEDTLS_SSL_HS_HELLO_VERIFY_REQUEST 3
  267. #define MBEDTLS_SSL_HS_NEW_SESSION_TICKET 4
  268. #define MBEDTLS_SSL_HS_CERTIFICATE 11
  269. #define MBEDTLS_SSL_HS_SERVER_KEY_EXCHANGE 12
  270. #define MBEDTLS_SSL_HS_CERTIFICATE_REQUEST 13
  271. #define MBEDTLS_SSL_HS_SERVER_HELLO_DONE 14
  272. #define MBEDTLS_SSL_HS_CERTIFICATE_VERIFY 15
  273. #define MBEDTLS_SSL_HS_CLIENT_KEY_EXCHANGE 16
  274. #define MBEDTLS_SSL_HS_FINISHED 20
  275. /*
  276. * TLS extensions
  277. */
  278. #define MBEDTLS_TLS_EXT_SERVERNAME 0
  279. #define MBEDTLS_TLS_EXT_SERVERNAME_HOSTNAME 0
  280. #define MBEDTLS_TLS_EXT_MAX_FRAGMENT_LENGTH 1
  281. #define MBEDTLS_TLS_EXT_TRUNCATED_HMAC 4
  282. #define MBEDTLS_TLS_EXT_SUPPORTED_ELLIPTIC_CURVES 10
  283. #define MBEDTLS_TLS_EXT_SUPPORTED_POINT_FORMATS 11
  284. #define MBEDTLS_TLS_EXT_SIG_ALG 13
  285. #define MBEDTLS_TLS_EXT_ALPN 16
  286. #define MBEDTLS_TLS_EXT_ENCRYPT_THEN_MAC 22 /* 0x16 */
  287. #define MBEDTLS_TLS_EXT_EXTENDED_MASTER_SECRET 0x0017 /* 23 */
  288. #define MBEDTLS_TLS_EXT_SESSION_TICKET 35
  289. #define MBEDTLS_TLS_EXT_ECJPAKE_KKPP 256 /* experimental */
  290. #define MBEDTLS_TLS_EXT_RENEGOTIATION_INFO 0xFF01
  291. /*
  292. * Size defines
  293. */
  294. #if !defined(MBEDTLS_PSK_MAX_LEN)
  295. #define MBEDTLS_PSK_MAX_LEN 32 /* 256 bits */
  296. #endif
  297. /* Dummy type used only for its size */
  298. union mbedtls_ssl_premaster_secret
  299. {
  300. #if defined(MBEDTLS_KEY_EXCHANGE_RSA_ENABLED)
  301. unsigned char _pms_rsa[48]; /* RFC 5246 8.1.1 */
  302. #endif
  303. #if defined(MBEDTLS_KEY_EXCHANGE_DHE_RSA_ENABLED)
  304. unsigned char _pms_dhm[MBEDTLS_MPI_MAX_SIZE]; /* RFC 5246 8.1.2 */
  305. #endif
  306. #if defined(MBEDTLS_KEY_EXCHANGE_ECDHE_RSA_ENABLED) || \
  307. defined(MBEDTLS_KEY_EXCHANGE_ECDHE_ECDSA_ENABLED) || \
  308. defined(MBEDTLS_KEY_EXCHANGE_ECDH_RSA_ENABLED) || \
  309. defined(MBEDTLS_KEY_EXCHANGE_ECDH_ECDSA_ENABLED)
  310. unsigned char _pms_ecdh[MBEDTLS_ECP_MAX_BYTES]; /* RFC 4492 5.10 */
  311. #endif
  312. #if defined(MBEDTLS_KEY_EXCHANGE_PSK_ENABLED)
  313. unsigned char _pms_psk[4 + 2 * MBEDTLS_PSK_MAX_LEN]; /* RFC 4279 2 */
  314. #endif
  315. #if defined(MBEDTLS_KEY_EXCHANGE_DHE_PSK_ENABLED)
  316. unsigned char _pms_dhe_psk[4 + MBEDTLS_MPI_MAX_SIZE
  317. + MBEDTLS_PSK_MAX_LEN]; /* RFC 4279 3 */
  318. #endif
  319. #if defined(MBEDTLS_KEY_EXCHANGE_RSA_PSK_ENABLED)
  320. unsigned char _pms_rsa_psk[52 + MBEDTLS_PSK_MAX_LEN]; /* RFC 4279 4 */
  321. #endif
  322. #if defined(MBEDTLS_KEY_EXCHANGE_ECDHE_PSK_ENABLED)
  323. unsigned char _pms_ecdhe_psk[4 + MBEDTLS_ECP_MAX_BYTES
  324. + MBEDTLS_PSK_MAX_LEN]; /* RFC 5489 2 */
  325. #endif
  326. #if defined(MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED)
  327. unsigned char _pms_ecjpake[32]; /* Thread spec: SHA-256 output */
  328. #endif
  329. };
  330. #define MBEDTLS_PREMASTER_SIZE sizeof( union mbedtls_ssl_premaster_secret )
  331. #ifdef __cplusplus
  332. extern "C" {
  333. #endif
  334. /*
  335. * SSL state machine
  336. */
  337. typedef enum
  338. {
  339. MBEDTLS_SSL_HELLO_REQUEST,
  340. MBEDTLS_SSL_CLIENT_HELLO,
  341. MBEDTLS_SSL_SERVER_HELLO,
  342. MBEDTLS_SSL_SERVER_CERTIFICATE,
  343. MBEDTLS_SSL_SERVER_KEY_EXCHANGE,
  344. MBEDTLS_SSL_CERTIFICATE_REQUEST,
  345. MBEDTLS_SSL_SERVER_HELLO_DONE,
  346. MBEDTLS_SSL_CLIENT_CERTIFICATE,
  347. MBEDTLS_SSL_CLIENT_KEY_EXCHANGE,
  348. MBEDTLS_SSL_CERTIFICATE_VERIFY,
  349. MBEDTLS_SSL_CLIENT_CHANGE_CIPHER_SPEC,
  350. MBEDTLS_SSL_CLIENT_FINISHED,
  351. MBEDTLS_SSL_SERVER_CHANGE_CIPHER_SPEC,
  352. MBEDTLS_SSL_SERVER_FINISHED,
  353. MBEDTLS_SSL_FLUSH_BUFFERS,
  354. MBEDTLS_SSL_HANDSHAKE_WRAPUP,
  355. MBEDTLS_SSL_HANDSHAKE_OVER,
  356. MBEDTLS_SSL_SERVER_NEW_SESSION_TICKET,
  357. MBEDTLS_SSL_SERVER_HELLO_VERIFY_REQUEST_SENT,
  358. }
  359. mbedtls_ssl_states;
  360. /**
  361. * \brief Callback type: send data on the network.
  362. *
  363. * \note That callback may be either blocking or non-blocking.
  364. *
  365. * \param ctx Context for the send callback (typically a file descriptor)
  366. * \param buf Buffer holding the data to send
  367. * \param len Length of the data to send
  368. *
  369. * \return The callback must return the number of bytes sent if any,
  370. * or a non-zero error code.
  371. * If performing non-blocking I/O, \c MBEDTLS_ERR_SSL_WANT_WRITE
  372. * must be returned when the operation would block.
  373. *
  374. * \note The callback is allowed to send fewer bytes than requested.
  375. * It must always return the number of bytes actually sent.
  376. */
  377. typedef int mbedtls_ssl_send_t( void *ctx,
  378. const unsigned char *buf,
  379. size_t len );
  380. /**
  381. * \brief Callback type: receive data from the network.
  382. *
  383. * \note That callback may be either blocking or non-blocking.
  384. *
  385. * \param ctx Context for the receive callback (typically a file
  386. * descriptor)
  387. * \param buf Buffer to write the received data to
  388. * \param len Length of the receive buffer
  389. *
  390. * \return The callback must return the number of bytes received,
  391. * or a non-zero error code.
  392. * If performing non-blocking I/O, \c MBEDTLS_ERR_SSL_WANT_READ
  393. * must be returned when the operation would block.
  394. *
  395. * \note The callback may receive fewer bytes than the length of the
  396. * buffer. It must always return the number of bytes actually
  397. * received and written to the buffer.
  398. */
  399. typedef int mbedtls_ssl_recv_t( void *ctx,
  400. unsigned char *buf,
  401. size_t len );
  402. /**
  403. * \brief Callback type: receive data from the network, with timeout
  404. *
  405. * \note That callback must block until data is received, or the
  406. * timeout delay expires, or the operation is interrupted by a
  407. * signal.
  408. *
  409. * \param ctx Context for the receive callback (typically a file descriptor)
  410. * \param buf Buffer to write the received data to
  411. * \param len Length of the receive buffer
  412. * \param timeout Maximum nomber of millisecondes to wait for data
  413. * 0 means no timeout (potentially waiting forever)
  414. *
  415. * \return The callback must return the number of bytes received,
  416. * or a non-zero error code:
  417. * \c MBEDTLS_ERR_SSL_TIMEOUT if the operation timed out,
  418. * \c MBEDTLS_ERR_SSL_WANT_READ if interrupted by a signal.
  419. *
  420. * \note The callback may receive fewer bytes than the length of the
  421. * buffer. It must always return the number of bytes actually
  422. * received and written to the buffer.
  423. */
  424. typedef int mbedtls_ssl_recv_timeout_t( void *ctx,
  425. unsigned char *buf,
  426. size_t len,
  427. uint32_t timeout );
  428. /**
  429. * \brief Callback type: set a pair of timers/delays to watch
  430. *
  431. * \param ctx Context pointer
  432. * \param int_ms Intermediate delay in milliseconds
  433. * \param fin_ms Final delay in milliseconds
  434. * 0 cancels the current timer.
  435. *
  436. * \note This callback must at least store the necessary information
  437. * for the associated \c mbedtls_ssl_get_timer_t callback to
  438. * return correct information.
  439. *
  440. * \note If using a event-driven style of programming, an event must
  441. * be generated when the final delay is passed. The event must
  442. * cause a call to \c mbedtls_ssl_handshake() with the proper
  443. * SSL context to be scheduled. Care must be taken to ensure
  444. * that at most one such call happens at a time.
  445. *
  446. * \note Only one timer at a time must be running. Calling this
  447. * function while a timer is running must cancel it. Cancelled
  448. * timers must not generate any event.
  449. */
  450. typedef void mbedtls_ssl_set_timer_t( void * ctx,
  451. uint32_t int_ms,
  452. uint32_t fin_ms );
  453. /**
  454. * \brief Callback type: get status of timers/delays
  455. *
  456. * \param ctx Context pointer
  457. *
  458. * \return This callback must return:
  459. * -1 if cancelled (fin_ms == 0),
  460. * 0 if none of the delays have passed,
  461. * 1 if only the intermediate delay has passed,
  462. * 2 if the final delay has passed.
  463. */
  464. typedef int mbedtls_ssl_get_timer_t( void * ctx );
  465. /* Defined below */
  466. typedef struct mbedtls_ssl_session mbedtls_ssl_session;
  467. typedef struct mbedtls_ssl_context mbedtls_ssl_context;
  468. typedef struct mbedtls_ssl_config mbedtls_ssl_config;
  469. /* Defined in ssl_internal.h */
  470. typedef struct mbedtls_ssl_transform mbedtls_ssl_transform;
  471. typedef struct mbedtls_ssl_handshake_params mbedtls_ssl_handshake_params;
  472. typedef struct mbedtls_ssl_sig_hash_set_t mbedtls_ssl_sig_hash_set_t;
  473. #if defined(MBEDTLS_X509_CRT_PARSE_C)
  474. typedef struct mbedtls_ssl_key_cert mbedtls_ssl_key_cert;
  475. #endif
  476. #if defined(MBEDTLS_SSL_PROTO_DTLS)
  477. typedef struct mbedtls_ssl_flight_item mbedtls_ssl_flight_item;
  478. #endif
  479. /*
  480. * This structure is used for storing current session data.
  481. */
  482. struct mbedtls_ssl_session
  483. {
  484. #if defined(MBEDTLS_HAVE_TIME)
  485. mbedtls_time_t start; /*!< starting time */
  486. #endif
  487. int ciphersuite; /*!< chosen ciphersuite */
  488. int compression; /*!< chosen compression */
  489. size_t id_len; /*!< session id length */
  490. unsigned char id[32]; /*!< session identifier */
  491. unsigned char master[48]; /*!< the master secret */
  492. #if defined(MBEDTLS_X509_CRT_PARSE_C)
  493. mbedtls_x509_crt *peer_cert; /*!< peer X.509 cert chain */
  494. #endif /* MBEDTLS_X509_CRT_PARSE_C */
  495. uint32_t verify_result; /*!< verification result */
  496. #if defined(MBEDTLS_SSL_SESSION_TICKETS) && defined(MBEDTLS_SSL_CLI_C)
  497. unsigned char *ticket; /*!< RFC 5077 session ticket */
  498. size_t ticket_len; /*!< session ticket length */
  499. uint32_t ticket_lifetime; /*!< ticket lifetime hint */
  500. #endif /* MBEDTLS_SSL_SESSION_TICKETS && MBEDTLS_SSL_CLI_C */
  501. #if defined(MBEDTLS_SSL_MAX_FRAGMENT_LENGTH)
  502. unsigned char mfl_code; /*!< MaxFragmentLength negotiated by peer */
  503. #endif /* MBEDTLS_SSL_MAX_FRAGMENT_LENGTH */
  504. #if defined(MBEDTLS_SSL_TRUNCATED_HMAC)
  505. int trunc_hmac; /*!< flag for truncated hmac activation */
  506. #endif /* MBEDTLS_SSL_TRUNCATED_HMAC */
  507. #if defined(MBEDTLS_SSL_ENCRYPT_THEN_MAC)
  508. int encrypt_then_mac; /*!< flag for EtM activation */
  509. #endif
  510. };
  511. /**
  512. * SSL/TLS configuration to be shared between mbedtls_ssl_context structures.
  513. */
  514. struct mbedtls_ssl_config
  515. {
  516. /* Group items by size (largest first) to minimize padding overhead */
  517. /*
  518. * Pointers
  519. */
  520. const int *ciphersuite_list[4]; /*!< allowed ciphersuites per version */
  521. /** Callback for printing debug output */
  522. void (*f_dbg)(void *, int, const char *, int, const char *);
  523. void *p_dbg; /*!< context for the debug function */
  524. /** Callback for getting (pseudo-)random numbers */
  525. int (*f_rng)(void *, unsigned char *, size_t);
  526. void *p_rng; /*!< context for the RNG function */
  527. /** Callback to retrieve a session from the cache */
  528. int (*f_get_cache)(void *, mbedtls_ssl_session *);
  529. /** Callback to store a session into the cache */
  530. int (*f_set_cache)(void *, const mbedtls_ssl_session *);
  531. void *p_cache; /*!< context for cache callbacks */
  532. #if defined(MBEDTLS_SSL_SERVER_NAME_INDICATION)
  533. /** Callback for setting cert according to SNI extension */
  534. int (*f_sni)(void *, mbedtls_ssl_context *, const unsigned char *, size_t);
  535. void *p_sni; /*!< context for SNI callback */
  536. #endif
  537. #if defined(MBEDTLS_X509_CRT_PARSE_C)
  538. /** Callback to customize X.509 certificate chain verification */
  539. int (*f_vrfy)(void *, mbedtls_x509_crt *, int, uint32_t *);
  540. void *p_vrfy; /*!< context for X.509 verify calllback */
  541. #endif
  542. #if defined(MBEDTLS_KEY_EXCHANGE__SOME__PSK_ENABLED)
  543. /** Callback to retrieve PSK key from identity */
  544. int (*f_psk)(void *, mbedtls_ssl_context *, const unsigned char *, size_t);
  545. void *p_psk; /*!< context for PSK callback */
  546. #endif
  547. #if defined(MBEDTLS_SSL_DTLS_HELLO_VERIFY) && defined(MBEDTLS_SSL_SRV_C)
  548. /** Callback to create & write a cookie for ClientHello veirifcation */
  549. int (*f_cookie_write)( void *, unsigned char **, unsigned char *,
  550. const unsigned char *, size_t );
  551. /** Callback to verify validity of a ClientHello cookie */
  552. int (*f_cookie_check)( void *, const unsigned char *, size_t,
  553. const unsigned char *, size_t );
  554. void *p_cookie; /*!< context for the cookie callbacks */
  555. #endif
  556. #if defined(MBEDTLS_SSL_SESSION_TICKETS) && defined(MBEDTLS_SSL_SRV_C)
  557. /** Callback to create & write a session ticket */
  558. int (*f_ticket_write)( void *, const mbedtls_ssl_session *,
  559. unsigned char *, const unsigned char *, size_t *, uint32_t * );
  560. /** Callback to parse a session ticket into a session structure */
  561. int (*f_ticket_parse)( void *, mbedtls_ssl_session *, unsigned char *, size_t);
  562. void *p_ticket; /*!< context for the ticket callbacks */
  563. #endif /* MBEDTLS_SSL_SESSION_TICKETS && MBEDTLS_SSL_SRV_C */
  564. #if defined(MBEDTLS_SSL_EXPORT_KEYS)
  565. /** Callback to export key block and master secret */
  566. int (*f_export_keys)( void *, const unsigned char *,
  567. const unsigned char *, size_t, size_t, size_t );
  568. void *p_export_keys; /*!< context for key export callback */
  569. #endif
  570. #if defined(MBEDTLS_X509_CRT_PARSE_C)
  571. const mbedtls_x509_crt_profile *cert_profile; /*!< verification profile */
  572. mbedtls_ssl_key_cert *key_cert; /*!< own certificate/key pair(s) */
  573. mbedtls_x509_crt *ca_chain; /*!< trusted CAs */
  574. mbedtls_x509_crl *ca_crl; /*!< trusted CAs CRLs */
  575. #endif /* MBEDTLS_X509_CRT_PARSE_C */
  576. #if defined(MBEDTLS_KEY_EXCHANGE__WITH_CERT__ENABLED)
  577. const int *sig_hashes; /*!< allowed signature hashes */
  578. #endif
  579. #if defined(MBEDTLS_ECP_C)
  580. const mbedtls_ecp_group_id *curve_list; /*!< allowed curves */
  581. #endif
  582. #if defined(MBEDTLS_DHM_C)
  583. mbedtls_mpi dhm_P; /*!< prime modulus for DHM */
  584. mbedtls_mpi dhm_G; /*!< generator for DHM */
  585. #endif
  586. #if defined(MBEDTLS_KEY_EXCHANGE__SOME__PSK_ENABLED)
  587. unsigned char *psk; /*!< pre-shared key */
  588. size_t psk_len; /*!< length of the pre-shared key */
  589. unsigned char *psk_identity; /*!< identity for PSK negotiation */
  590. size_t psk_identity_len;/*!< length of identity */
  591. #endif
  592. #if defined(MBEDTLS_SSL_ALPN)
  593. const char **alpn_list; /*!< ordered list of protocols */
  594. #endif
  595. /*
  596. * Numerical settings (int then char)
  597. */
  598. uint32_t read_timeout; /*!< timeout for mbedtls_ssl_read (ms) */
  599. #if defined(MBEDTLS_SSL_PROTO_DTLS)
  600. uint32_t hs_timeout_min; /*!< initial value of the handshake
  601. retransmission timeout (ms) */
  602. uint32_t hs_timeout_max; /*!< maximum value of the handshake
  603. retransmission timeout (ms) */
  604. #endif
  605. #if defined(MBEDTLS_SSL_RENEGOTIATION)
  606. int renego_max_records; /*!< grace period for renegotiation */
  607. unsigned char renego_period[8]; /*!< value of the record counters
  608. that triggers renegotiation */
  609. #endif
  610. #if defined(MBEDTLS_SSL_DTLS_BADMAC_LIMIT)
  611. unsigned int badmac_limit; /*!< limit of records with a bad MAC */
  612. #endif
  613. #if defined(MBEDTLS_DHM_C) && defined(MBEDTLS_SSL_CLI_C)
  614. unsigned int dhm_min_bitlen; /*!< min. bit length of the DHM prime */
  615. #endif
  616. unsigned char max_major_ver; /*!< max. major version used */
  617. unsigned char max_minor_ver; /*!< max. minor version used */
  618. unsigned char min_major_ver; /*!< min. major version used */
  619. unsigned char min_minor_ver; /*!< min. minor version used */
  620. /*
  621. * Flags (bitfields)
  622. */
  623. unsigned int endpoint : 1; /*!< 0: client, 1: server */
  624. unsigned int transport : 1; /*!< stream (TLS) or datagram (DTLS) */
  625. unsigned int authmode : 2; /*!< MBEDTLS_SSL_VERIFY_XXX */
  626. /* needed even with renego disabled for LEGACY_BREAK_HANDSHAKE */
  627. unsigned int allow_legacy_renegotiation : 2 ; /*!< MBEDTLS_LEGACY_XXX */
  628. #if defined(MBEDTLS_ARC4_C)
  629. unsigned int arc4_disabled : 1; /*!< blacklist RC4 ciphersuites? */
  630. #endif
  631. #if defined(MBEDTLS_SSL_MAX_FRAGMENT_LENGTH)
  632. unsigned int mfl_code : 3; /*!< desired fragment length */
  633. #endif
  634. #if defined(MBEDTLS_SSL_ENCRYPT_THEN_MAC)
  635. unsigned int encrypt_then_mac : 1 ; /*!< negotiate encrypt-then-mac? */
  636. #endif
  637. #if defined(MBEDTLS_SSL_EXTENDED_MASTER_SECRET)
  638. unsigned int extended_ms : 1; /*!< negotiate extended master secret? */
  639. #endif
  640. #if defined(MBEDTLS_SSL_DTLS_ANTI_REPLAY)
  641. unsigned int anti_replay : 1; /*!< detect and prevent replay? */
  642. #endif
  643. #if defined(MBEDTLS_SSL_CBC_RECORD_SPLITTING)
  644. unsigned int cbc_record_splitting : 1; /*!< do cbc record splitting */
  645. #endif
  646. #if defined(MBEDTLS_SSL_RENEGOTIATION)
  647. unsigned int disable_renegotiation : 1; /*!< disable renegotiation? */
  648. #endif
  649. #if defined(MBEDTLS_SSL_TRUNCATED_HMAC)
  650. unsigned int trunc_hmac : 1; /*!< negotiate truncated hmac? */
  651. #endif
  652. #if defined(MBEDTLS_SSL_SESSION_TICKETS)
  653. unsigned int session_tickets : 1; /*!< use session tickets? */
  654. #endif
  655. #if defined(MBEDTLS_SSL_FALLBACK_SCSV) && defined(MBEDTLS_SSL_CLI_C)
  656. unsigned int fallback : 1; /*!< is this a fallback? */
  657. #endif
  658. #if defined(MBEDTLS_SSL_SRV_C)
  659. unsigned int cert_req_ca_list : 1; /*!< enable sending CA list in
  660. Certificate Request messages? */
  661. #endif
  662. };
  663. struct mbedtls_ssl_context
  664. {
  665. const mbedtls_ssl_config *conf; /*!< configuration information */
  666. /*
  667. * Miscellaneous
  668. */
  669. int state; /*!< SSL handshake: current state */
  670. #if defined(MBEDTLS_SSL_RENEGOTIATION)
  671. int renego_status; /*!< Initial, in progress, pending? */
  672. int renego_records_seen; /*!< Records since renego request, or with DTLS,
  673. number of retransmissions of request if
  674. renego_max_records is < 0 */
  675. #endif
  676. int major_ver; /*!< equal to MBEDTLS_SSL_MAJOR_VERSION_3 */
  677. int minor_ver; /*!< either 0 (SSL3) or 1 (TLS1.0) */
  678. #if defined(MBEDTLS_SSL_DTLS_BADMAC_LIMIT)
  679. unsigned badmac_seen; /*!< records with a bad MAC received */
  680. #endif
  681. mbedtls_ssl_send_t *f_send; /*!< Callback for network send */
  682. mbedtls_ssl_recv_t *f_recv; /*!< Callback for network receive */
  683. mbedtls_ssl_recv_timeout_t *f_recv_timeout;
  684. /*!< Callback for network receive with timeout */
  685. void *p_bio; /*!< context for I/O operations */
  686. /*
  687. * Session layer
  688. */
  689. mbedtls_ssl_session *session_in; /*!< current session data (in) */
  690. mbedtls_ssl_session *session_out; /*!< current session data (out) */
  691. mbedtls_ssl_session *session; /*!< negotiated session data */
  692. mbedtls_ssl_session *session_negotiate; /*!< session data in negotiation */
  693. mbedtls_ssl_handshake_params *handshake; /*!< params required only during
  694. the handshake process */
  695. /*
  696. * Record layer transformations
  697. */
  698. mbedtls_ssl_transform *transform_in; /*!< current transform params (in) */
  699. mbedtls_ssl_transform *transform_out; /*!< current transform params (in) */
  700. mbedtls_ssl_transform *transform; /*!< negotiated transform params */
  701. mbedtls_ssl_transform *transform_negotiate; /*!< transform params in negotiation */
  702. /*
  703. * Timers
  704. */
  705. void *p_timer; /*!< context for the timer callbacks */
  706. mbedtls_ssl_set_timer_t *f_set_timer; /*!< set timer callback */
  707. mbedtls_ssl_get_timer_t *f_get_timer; /*!< get timer callback */
  708. /*
  709. * Record layer (incoming data)
  710. */
  711. unsigned char *in_buf; /*!< input buffer */
  712. unsigned char *in_ctr; /*!< 64-bit incoming message counter
  713. TLS: maintained by us
  714. DTLS: read from peer */
  715. unsigned char *in_hdr; /*!< start of record header */
  716. unsigned char *in_len; /*!< two-bytes message length field */
  717. unsigned char *in_iv; /*!< ivlen-byte IV */
  718. unsigned char *in_msg; /*!< message contents (in_iv+ivlen) */
  719. unsigned char *in_offt; /*!< read offset in application data */
  720. int in_msgtype; /*!< record header: message type */
  721. size_t in_msglen; /*!< record header: message length */
  722. size_t in_left; /*!< amount of data read so far */
  723. #if defined(MBEDTLS_SSL_PROTO_DTLS)
  724. uint16_t in_epoch; /*!< DTLS epoch for incoming records */
  725. size_t next_record_offset; /*!< offset of the next record in datagram
  726. (equal to in_left if none) */
  727. #endif
  728. #if defined(MBEDTLS_SSL_DTLS_ANTI_REPLAY)
  729. uint64_t in_window_top; /*!< last validated record seq_num */
  730. uint64_t in_window; /*!< bitmask for replay detection */
  731. #endif
  732. size_t in_hslen; /*!< current handshake message length,
  733. including the handshake header */
  734. int nb_zero; /*!< # of 0-length encrypted messages */
  735. int keep_current_message; /*!< drop or reuse current message
  736. on next call to record layer? */
  737. /*
  738. * Record layer (outgoing data)
  739. */
  740. unsigned char *out_buf; /*!< output buffer */
  741. unsigned char *out_ctr; /*!< 64-bit outgoing message counter */
  742. unsigned char *out_hdr; /*!< start of record header */
  743. unsigned char *out_len; /*!< two-bytes message length field */
  744. unsigned char *out_iv; /*!< ivlen-byte IV */
  745. unsigned char *out_msg; /*!< message contents (out_iv+ivlen) */
  746. int out_msgtype; /*!< record header: message type */
  747. size_t out_msglen; /*!< record header: message length */
  748. size_t out_left; /*!< amount of data not yet written */
  749. #if defined(MBEDTLS_ZLIB_SUPPORT)
  750. unsigned char *compress_buf; /*!< zlib data buffer */
  751. #endif
  752. #if defined(MBEDTLS_SSL_CBC_RECORD_SPLITTING)
  753. signed char split_done; /*!< current record already splitted? */
  754. #endif
  755. /*
  756. * PKI layer
  757. */
  758. int client_auth; /*!< flag for client auth. */
  759. /*
  760. * User settings
  761. */
  762. #if defined(MBEDTLS_X509_CRT_PARSE_C)
  763. char *hostname; /*!< expected peer CN for verification
  764. (and SNI if available) */
  765. #endif
  766. #if defined(MBEDTLS_SSL_ALPN)
  767. const char *alpn_chosen; /*!< negotiated protocol */
  768. #endif
  769. /*
  770. * Information for DTLS hello verify
  771. */
  772. #if defined(MBEDTLS_SSL_DTLS_HELLO_VERIFY) && defined(MBEDTLS_SSL_SRV_C)
  773. unsigned char *cli_id; /*!< transport-level ID of the client */
  774. size_t cli_id_len; /*!< length of cli_id */
  775. #endif
  776. /*
  777. * Secure renegotiation
  778. */
  779. /* needed to know when to send extension on server */
  780. int secure_renegotiation; /*!< does peer support legacy or
  781. secure renegotiation */
  782. #if defined(MBEDTLS_SSL_RENEGOTIATION)
  783. size_t verify_data_len; /*!< length of verify data stored */
  784. char own_verify_data[MBEDTLS_SSL_VERIFY_DATA_MAX_LEN]; /*!< previous handshake verify data */
  785. char peer_verify_data[MBEDTLS_SSL_VERIFY_DATA_MAX_LEN]; /*!< previous handshake verify data */
  786. #endif
  787. };
  788. #if defined(MBEDTLS_SSL_HW_RECORD_ACCEL)
  789. #define MBEDTLS_SSL_CHANNEL_OUTBOUND 0
  790. #define MBEDTLS_SSL_CHANNEL_INBOUND 1
  791. extern int (*mbedtls_ssl_hw_record_init)(mbedtls_ssl_context *ssl,
  792. const unsigned char *key_enc, const unsigned char *key_dec,
  793. size_t keylen,
  794. const unsigned char *iv_enc, const unsigned char *iv_dec,
  795. size_t ivlen,
  796. const unsigned char *mac_enc, const unsigned char *mac_dec,
  797. size_t maclen);
  798. extern int (*mbedtls_ssl_hw_record_activate)(mbedtls_ssl_context *ssl, int direction);
  799. extern int (*mbedtls_ssl_hw_record_reset)(mbedtls_ssl_context *ssl);
  800. extern int (*mbedtls_ssl_hw_record_write)(mbedtls_ssl_context *ssl);
  801. extern int (*mbedtls_ssl_hw_record_read)(mbedtls_ssl_context *ssl);
  802. extern int (*mbedtls_ssl_hw_record_finish)(mbedtls_ssl_context *ssl);
  803. #endif /* MBEDTLS_SSL_HW_RECORD_ACCEL */
  804. /**
  805. * \brief Returns the list of ciphersuites supported by the SSL/TLS module.
  806. *
  807. * \return a statically allocated array of ciphersuites, the last
  808. * entry is 0.
  809. */
  810. const int *mbedtls_ssl_list_ciphersuites( void );
  811. /**
  812. * \brief Return the name of the ciphersuite associated with the
  813. * given ID
  814. *
  815. * \param ciphersuite_id SSL ciphersuite ID
  816. *
  817. * \return a string containing the ciphersuite name
  818. */
  819. const char *mbedtls_ssl_get_ciphersuite_name( const int ciphersuite_id );
  820. /**
  821. * \brief Return the ID of the ciphersuite associated with the
  822. * given name
  823. *
  824. * \param ciphersuite_name SSL ciphersuite name
  825. *
  826. * \return the ID with the ciphersuite or 0 if not found
  827. */
  828. int mbedtls_ssl_get_ciphersuite_id( const char *ciphersuite_name );
  829. /**
  830. * \brief Initialize an SSL context
  831. * Just makes the context ready for mbedtls_ssl_setup() or
  832. * mbedtls_ssl_free()
  833. *
  834. * \param ssl SSL context
  835. */
  836. void mbedtls_ssl_init( mbedtls_ssl_context *ssl );
  837. /**
  838. * \brief Set up an SSL context for use
  839. *
  840. * \note No copy of the configuration context is made, it can be
  841. * shared by many mbedtls_ssl_context structures.
  842. *
  843. * \warning Modifying the conf structure after it has been used in this
  844. * function is unsupported!
  845. *
  846. * \param ssl SSL context
  847. * \param conf SSL configuration to use
  848. *
  849. * \return 0 if successful, or MBEDTLS_ERR_SSL_ALLOC_FAILED if
  850. * memory allocation failed
  851. */
  852. int mbedtls_ssl_setup( mbedtls_ssl_context *ssl,
  853. const mbedtls_ssl_config *conf );
  854. /**
  855. * \brief Reset an already initialized SSL context for re-use
  856. * while retaining application-set variables, function
  857. * pointers and data.
  858. *
  859. * \param ssl SSL context
  860. * \return 0 if successful, or MBEDTLS_ERR_SSL_ALLOC_FAILED,
  861. MBEDTLS_ERR_SSL_HW_ACCEL_FAILED or
  862. * MBEDTLS_ERR_SSL_COMPRESSION_FAILED
  863. */
  864. int mbedtls_ssl_session_reset( mbedtls_ssl_context *ssl );
  865. /**
  866. * \brief Set the current endpoint type
  867. *
  868. * \param conf SSL configuration
  869. * \param endpoint must be MBEDTLS_SSL_IS_CLIENT or MBEDTLS_SSL_IS_SERVER
  870. */
  871. void mbedtls_ssl_conf_endpoint( mbedtls_ssl_config *conf, int endpoint );
  872. /**
  873. * \brief Set the transport type (TLS or DTLS).
  874. * Default: TLS
  875. *
  876. * \note For DTLS, you must either provide a recv callback that
  877. * doesn't block, or one that handles timeouts, see
  878. * \c mbedtls_ssl_set_bio(). You also need to provide timer
  879. * callbacks with \c mbedtls_ssl_set_timer_cb().
  880. *
  881. * \param conf SSL configuration
  882. * \param transport transport type:
  883. * MBEDTLS_SSL_TRANSPORT_STREAM for TLS,
  884. * MBEDTLS_SSL_TRANSPORT_DATAGRAM for DTLS.
  885. */
  886. void mbedtls_ssl_conf_transport( mbedtls_ssl_config *conf, int transport );
  887. /**
  888. * \brief Set the certificate verification mode
  889. * Default: NONE on server, REQUIRED on client
  890. *
  891. * \param conf SSL configuration
  892. * \param authmode can be:
  893. *
  894. * MBEDTLS_SSL_VERIFY_NONE: peer certificate is not checked
  895. * (default on server)
  896. * (insecure on client)
  897. *
  898. * MBEDTLS_SSL_VERIFY_OPTIONAL: peer certificate is checked, however the
  899. * handshake continues even if verification failed;
  900. * mbedtls_ssl_get_verify_result() can be called after the
  901. * handshake is complete.
  902. *
  903. * MBEDTLS_SSL_VERIFY_REQUIRED: peer *must* present a valid certificate,
  904. * handshake is aborted if verification failed.
  905. * (default on client)
  906. *
  907. * \note On client, MBEDTLS_SSL_VERIFY_REQUIRED is the recommended mode.
  908. * With MBEDTLS_SSL_VERIFY_OPTIONAL, the user needs to call mbedtls_ssl_get_verify_result() at
  909. * the right time(s), which may not be obvious, while REQUIRED always perform
  910. * the verification as soon as possible. For example, REQUIRED was protecting
  911. * against the "triple handshake" attack even before it was found.
  912. */
  913. void mbedtls_ssl_conf_authmode( mbedtls_ssl_config *conf, int authmode );
  914. #if defined(MBEDTLS_X509_CRT_PARSE_C)
  915. /**
  916. * \brief Set the verification callback (Optional).
  917. *
  918. * If set, the verify callback is called for each
  919. * certificate in the chain. For implementation
  920. * information, please see \c mbedtls_x509_crt_verify()
  921. *
  922. * \param conf SSL configuration
  923. * \param f_vrfy verification function
  924. * \param p_vrfy verification parameter
  925. */
  926. void mbedtls_ssl_conf_verify( mbedtls_ssl_config *conf,
  927. int (*f_vrfy)(void *, mbedtls_x509_crt *, int, uint32_t *),
  928. void *p_vrfy );
  929. #endif /* MBEDTLS_X509_CRT_PARSE_C */
  930. /**
  931. * \brief Set the random number generator callback
  932. *
  933. * \param conf SSL configuration
  934. * \param f_rng RNG function
  935. * \param p_rng RNG parameter
  936. */
  937. void mbedtls_ssl_conf_rng( mbedtls_ssl_config *conf,
  938. int (*f_rng)(void *, unsigned char *, size_t),
  939. void *p_rng );
  940. /**
  941. * \brief Set the debug callback
  942. *
  943. * The callback has the following argument:
  944. * void * opaque context for the callback
  945. * int debug level
  946. * const char * file name
  947. * int line number
  948. * const char * message
  949. *
  950. * \param conf SSL configuration
  951. * \param f_dbg debug function
  952. * \param p_dbg debug parameter
  953. */
  954. void mbedtls_ssl_conf_dbg( mbedtls_ssl_config *conf,
  955. void (*f_dbg)(void *, int, const char *, int, const char *),
  956. void *p_dbg );
  957. /**
  958. * \brief Set the underlying BIO callbacks for write, read and
  959. * read-with-timeout.
  960. *
  961. * \param ssl SSL context
  962. * \param p_bio parameter (context) shared by BIO callbacks
  963. * \param f_send write callback
  964. * \param f_recv read callback
  965. * \param f_recv_timeout blocking read callback with timeout.
  966. *
  967. * \note One of f_recv or f_recv_timeout can be NULL, in which case
  968. * the other is used. If both are non-NULL, f_recv_timeout is
  969. * used and f_recv is ignored (as if it were NULL).
  970. *
  971. * \note The two most common use cases are:
  972. * - non-blocking I/O, f_recv != NULL, f_recv_timeout == NULL
  973. * - blocking I/O, f_recv == NULL, f_recv_timout != NULL
  974. *
  975. * \note For DTLS, you need to provide either a non-NULL
  976. * f_recv_timeout callback, or a f_recv that doesn't block.
  977. *
  978. * \note See the documentations of \c mbedtls_ssl_sent_t,
  979. * \c mbedtls_ssl_recv_t and \c mbedtls_ssl_recv_timeout_t for
  980. * the conventions those callbacks must follow.
  981. *
  982. * \note On some platforms, net_sockets.c provides
  983. * \c mbedtls_net_send(), \c mbedtls_net_recv() and
  984. * \c mbedtls_net_recv_timeout() that are suitable to be used
  985. * here.
  986. */
  987. void mbedtls_ssl_set_bio( mbedtls_ssl_context *ssl,
  988. void *p_bio,
  989. mbedtls_ssl_send_t *f_send,
  990. mbedtls_ssl_recv_t *f_recv,
  991. mbedtls_ssl_recv_timeout_t *f_recv_timeout );
  992. /**
  993. * \brief Set the timeout period for mbedtls_ssl_read()
  994. * (Default: no timeout.)
  995. *
  996. * \param conf SSL configuration context
  997. * \param timeout Timeout value in milliseconds.
  998. * Use 0 for no timeout (default).
  999. *
  1000. * \note With blocking I/O, this will only work if a non-NULL
  1001. * \c f_recv_timeout was set with \c mbedtls_ssl_set_bio().
  1002. * With non-blocking I/O, this will only work if timer
  1003. * callbacks were set with \c mbedtls_ssl_set_timer_cb().
  1004. *
  1005. * \note With non-blocking I/O, you may also skip this function
  1006. * altogether and handle timeouts at the application layer.
  1007. */
  1008. void mbedtls_ssl_conf_read_timeout( mbedtls_ssl_config *conf, uint32_t timeout );
  1009. /**
  1010. * \brief Set the timer callbacks (Mandatory for DTLS.)
  1011. *
  1012. * \param ssl SSL context
  1013. * \param p_timer parameter (context) shared by timer callbacks
  1014. * \param f_set_timer set timer callback
  1015. * \param f_get_timer get timer callback. Must return:
  1016. *
  1017. * \note See the documentation of \c mbedtls_ssl_set_timer_t and
  1018. * \c mbedtls_ssl_get_timer_t for the conventions this pair of
  1019. * callbacks must follow.
  1020. *
  1021. * \note On some platforms, timing.c provides
  1022. * \c mbedtls_timing_set_delay() and
  1023. * \c mbedtls_timing_get_delay() that are suitable for using
  1024. * here, except if using an event-driven style.
  1025. *
  1026. * \note See also the "DTLS tutorial" article in our knowledge base.
  1027. * https://tls.mbed.org/kb/how-to/dtls-tutorial
  1028. */
  1029. void mbedtls_ssl_set_timer_cb( mbedtls_ssl_context *ssl,
  1030. void *p_timer,
  1031. mbedtls_ssl_set_timer_t *f_set_timer,
  1032. mbedtls_ssl_get_timer_t *f_get_timer );
  1033. /**
  1034. * \brief Callback type: generate and write session ticket
  1035. *
  1036. * \note This describes what a callback implementation should do.
  1037. * This callback should generate an encrypted and
  1038. * authenticated ticket for the session and write it to the
  1039. * output buffer. Here, ticket means the opaque ticket part
  1040. * of the NewSessionTicket structure of RFC 5077.
  1041. *
  1042. * \param p_ticket Context for the callback
  1043. * \param session SSL session to be written in the ticket
  1044. * \param start Start of the output buffer
  1045. * \param end End of the output buffer
  1046. * \param tlen On exit, holds the length written
  1047. * \param lifetime On exit, holds the lifetime of the ticket in seconds
  1048. *
  1049. * \return 0 if successful, or
  1050. * a specific MBEDTLS_ERR_XXX code.
  1051. */
  1052. typedef int mbedtls_ssl_ticket_write_t( void *p_ticket,
  1053. const mbedtls_ssl_session *session,
  1054. unsigned char *start,
  1055. const unsigned char *end,
  1056. size_t *tlen,
  1057. uint32_t *lifetime );
  1058. #if defined(MBEDTLS_SSL_EXPORT_KEYS)
  1059. /**
  1060. * \brief Callback type: Export key block and master secret
  1061. *
  1062. * \note This is required for certain uses of TLS, e.g. EAP-TLS
  1063. * (RFC 5216) and Thread. The key pointers are ephemeral and
  1064. * therefore must not be stored. The master secret and keys
  1065. * should not be used directly except as an input to a key
  1066. * derivation function.
  1067. *
  1068. * \param p_expkey Context for the callback
  1069. * \param ms Pointer to master secret (fixed length: 48 bytes)
  1070. * \param kb Pointer to key block, see RFC 5246 section 6.3
  1071. * (variable length: 2 * maclen + 2 * keylen + 2 * ivlen).
  1072. * \param maclen MAC length
  1073. * \param keylen Key length
  1074. * \param ivlen IV length
  1075. *
  1076. * \return 0 if successful, or
  1077. * a specific MBEDTLS_ERR_XXX code.
  1078. */
  1079. typedef int mbedtls_ssl_export_keys_t( void *p_expkey,
  1080. const unsigned char *ms,
  1081. const unsigned char *kb,
  1082. size_t maclen,
  1083. size_t keylen,
  1084. size_t ivlen );
  1085. #endif /* MBEDTLS_SSL_EXPORT_KEYS */
  1086. /**
  1087. * \brief Callback type: parse and load session ticket
  1088. *
  1089. * \note This describes what a callback implementation should do.
  1090. * This callback should parse a session ticket as generated
  1091. * by the corresponding mbedtls_ssl_ticket_write_t function,
  1092. * and, if the ticket is authentic and valid, load the
  1093. * session.
  1094. *
  1095. * \note The implementation is allowed to modify the first len
  1096. * bytes of the input buffer, eg to use it as a temporary
  1097. * area for the decrypted ticket contents.
  1098. *
  1099. * \param p_ticket Context for the callback
  1100. * \param session SSL session to be loaded
  1101. * \param buf Start of the buffer containing the ticket
  1102. * \param len Length of the ticket.
  1103. *
  1104. * \return 0 if successful, or
  1105. * MBEDTLS_ERR_SSL_INVALID_MAC if not authentic, or
  1106. * MBEDTLS_ERR_SSL_SESSION_TICKET_EXPIRED if expired, or
  1107. * any other non-zero code for other failures.
  1108. */
  1109. typedef int mbedtls_ssl_ticket_parse_t( void *p_ticket,
  1110. mbedtls_ssl_session *session,
  1111. unsigned char *buf,
  1112. size_t len );
  1113. #if defined(MBEDTLS_SSL_SESSION_TICKETS) && defined(MBEDTLS_SSL_SRV_C)
  1114. /**
  1115. * \brief Configure SSL session ticket callbacks (server only).
  1116. * (Default: none.)
  1117. *
  1118. * \note On server, session tickets are enabled by providing
  1119. * non-NULL callbacks.
  1120. *
  1121. * \note On client, use \c mbedtls_ssl_conf_session_tickets().
  1122. *
  1123. * \param conf SSL configuration context
  1124. * \param f_ticket_write Callback for writing a ticket
  1125. * \param f_ticket_parse Callback for parsing a ticket
  1126. * \param p_ticket Context shared by the two callbacks
  1127. */
  1128. void mbedtls_ssl_conf_session_tickets_cb( mbedtls_ssl_config *conf,
  1129. mbedtls_ssl_ticket_write_t *f_ticket_write,
  1130. mbedtls_ssl_ticket_parse_t *f_ticket_parse,
  1131. void *p_ticket );
  1132. #endif /* MBEDTLS_SSL_SESSION_TICKETS && MBEDTLS_SSL_SRV_C */
  1133. #if defined(MBEDTLS_SSL_EXPORT_KEYS)
  1134. /**
  1135. * \brief Configure key export callback.
  1136. * (Default: none.)
  1137. *
  1138. * \note See \c mbedtls_ssl_export_keys_t.
  1139. *
  1140. * \param conf SSL configuration context
  1141. * \param f_export_keys Callback for exporting keys
  1142. * \param p_export_keys Context for the callback
  1143. */
  1144. void mbedtls_ssl_conf_export_keys_cb( mbedtls_ssl_config *conf,
  1145. mbedtls_ssl_export_keys_t *f_export_keys,
  1146. void *p_export_keys );
  1147. #endif /* MBEDTLS_SSL_EXPORT_KEYS */
  1148. /**
  1149. * \brief Callback type: generate a cookie
  1150. *
  1151. * \param ctx Context for the callback
  1152. * \param p Buffer to write to,
  1153. * must be updated to point right after the cookie
  1154. * \param end Pointer to one past the end of the output buffer
  1155. * \param info Client ID info that was passed to
  1156. * \c mbedtls_ssl_set_client_transport_id()
  1157. * \param ilen Length of info in bytes
  1158. *
  1159. * \return The callback must return 0 on success,
  1160. * or a negative error code.
  1161. */
  1162. typedef int mbedtls_ssl_cookie_write_t( void *ctx,
  1163. unsigned char **p, unsigned char *end,
  1164. const unsigned char *info, size_t ilen );
  1165. /**
  1166. * \brief Callback type: verify a cookie
  1167. *
  1168. * \param ctx Context for the callback
  1169. * \param cookie Cookie to verify
  1170. * \param clen Length of cookie
  1171. * \param info Client ID info that was passed to
  1172. * \c mbedtls_ssl_set_client_transport_id()
  1173. * \param ilen Length of info in bytes
  1174. *
  1175. * \return The callback must return 0 if cookie is valid,
  1176. * or a negative error code.
  1177. */
  1178. typedef int mbedtls_ssl_cookie_check_t( void *ctx,
  1179. const unsigned char *cookie, size_t clen,
  1180. const unsigned char *info, size_t ilen );
  1181. #if defined(MBEDTLS_SSL_DTLS_HELLO_VERIFY) && defined(MBEDTLS_SSL_SRV_C)
  1182. /**
  1183. * \brief Register callbacks for DTLS cookies
  1184. * (Server only. DTLS only.)
  1185. *
  1186. * Default: dummy callbacks that fail, in order to force you to
  1187. * register working callbacks (and initialize their context).
  1188. *
  1189. * To disable HelloVerifyRequest, register NULL callbacks.
  1190. *
  1191. * \warning Disabling hello verification allows your server to be used
  1192. * for amplification in DoS attacks against other hosts.
  1193. * Only disable if you known this can't happen in your
  1194. * particular environment.
  1195. *
  1196. * \note See comments on \c mbedtls_ssl_handshake() about handling
  1197. * the MBEDTLS_ERR_SSL_HELLO_VERIFY_REQUIRED that is expected
  1198. * on the first handshake attempt when this is enabled.
  1199. *
  1200. * \note This is also necessary to handle client reconnection from
  1201. * the same port as described in RFC 6347 section 4.2.8 (only
  1202. * the variant with cookies is supported currently). See
  1203. * comments on \c mbedtls_ssl_read() for details.
  1204. *
  1205. * \param conf SSL configuration
  1206. * \param f_cookie_write Cookie write callback
  1207. * \param f_cookie_check Cookie check callback
  1208. * \param p_cookie Context for both callbacks
  1209. */
  1210. void mbedtls_ssl_conf_dtls_cookies( mbedtls_ssl_config *conf,
  1211. mbedtls_ssl_cookie_write_t *f_cookie_write,
  1212. mbedtls_ssl_cookie_check_t *f_cookie_check,
  1213. void *p_cookie );
  1214. /**
  1215. * \brief Set client's transport-level identification info.
  1216. * (Server only. DTLS only.)
  1217. *
  1218. * This is usually the IP address (and port), but could be
  1219. * anything identify the client depending on the underlying
  1220. * network stack. Used for HelloVerifyRequest with DTLS.
  1221. * This is *not* used to route the actual packets.
  1222. *
  1223. * \param ssl SSL context
  1224. * \param info Transport-level info identifying the client (eg IP + port)
  1225. * \param ilen Length of info in bytes
  1226. *
  1227. * \note An internal copy is made, so the info buffer can be reused.
  1228. *
  1229. * \return 0 on success,
  1230. * MBEDTLS_ERR_SSL_BAD_INPUT_DATA if used on client,
  1231. * MBEDTLS_ERR_SSL_ALLOC_FAILED if out of memory.
  1232. */
  1233. int mbedtls_ssl_set_client_transport_id( mbedtls_ssl_context *ssl,
  1234. const unsigned char *info,
  1235. size_t ilen );
  1236. #endif /* MBEDTLS_SSL_DTLS_HELLO_VERIFY && MBEDTLS_SSL_SRV_C */
  1237. #if defined(MBEDTLS_SSL_DTLS_ANTI_REPLAY)
  1238. /**
  1239. * \brief Enable or disable anti-replay protection for DTLS.
  1240. * (DTLS only, no effect on TLS.)
  1241. * Default: enabled.
  1242. *
  1243. * \param conf SSL configuration
  1244. * \param mode MBEDTLS_SSL_ANTI_REPLAY_ENABLED or MBEDTLS_SSL_ANTI_REPLAY_DISABLED.
  1245. *
  1246. * \warning Disabling this is a security risk unless the application
  1247. * protocol handles duplicated packets in a safe way. You
  1248. * should not disable this without careful consideration.
  1249. * However, if your application already detects duplicated
  1250. * packets and needs information about them to adjust its
  1251. * transmission strategy, then you'll want to disable this.
  1252. */
  1253. void mbedtls_ssl_conf_dtls_anti_replay( mbedtls_ssl_config *conf, char mode );
  1254. #endif /* MBEDTLS_SSL_DTLS_ANTI_REPLAY */
  1255. #if defined(MBEDTLS_SSL_DTLS_BADMAC_LIMIT)
  1256. /**
  1257. * \brief Set a limit on the number of records with a bad MAC
  1258. * before terminating the connection.
  1259. * (DTLS only, no effect on TLS.)
  1260. * Default: 0 (disabled).
  1261. *
  1262. * \param conf SSL configuration
  1263. * \param limit Limit, or 0 to disable.
  1264. *
  1265. * \note If the limit is N, then the connection is terminated when
  1266. * the Nth non-authentic record is seen.
  1267. *
  1268. * \note Records with an invalid header are not counted, only the
  1269. * ones going through the authentication-decryption phase.
  1270. *
  1271. * \note This is a security trade-off related to the fact that it's
  1272. * often relatively easy for an active attacker ot inject UDP
  1273. * datagrams. On one hand, setting a low limit here makes it
  1274. * easier for such an attacker to forcibly terminated a
  1275. * connection. On the other hand, a high limit or no limit
  1276. * might make us waste resources checking authentication on
  1277. * many bogus packets.
  1278. */
  1279. void mbedtls_ssl_conf_dtls_badmac_limit( mbedtls_ssl_config *conf, unsigned limit );
  1280. #endif /* MBEDTLS_SSL_DTLS_BADMAC_LIMIT */
  1281. #if defined(MBEDTLS_SSL_PROTO_DTLS)
  1282. /**
  1283. * \brief Set retransmit timeout values for the DTLS handshake.
  1284. * (DTLS only, no effect on TLS.)
  1285. *
  1286. * \param conf SSL configuration
  1287. * \param min Initial timeout value in milliseconds.
  1288. * Default: 1000 (1 second).
  1289. * \param max Maximum timeout value in milliseconds.
  1290. * Default: 60000 (60 seconds).
  1291. *
  1292. * \note Default values are from RFC 6347 section 4.2.4.1.
  1293. *
  1294. * \note The 'min' value should typically be slightly above the
  1295. * expected round-trip time to your peer, plus whatever time
  1296. * it takes for the peer to process the message. For example,
  1297. * if your RTT is about 600ms and you peer needs up to 1s to
  1298. * do the cryptographic operations in the handshake, then you
  1299. * should set 'min' slightly above 1600. Lower values of 'min'
  1300. * might cause spurious resends which waste network resources,
  1301. * while larger value of 'min' will increase overall latency
  1302. * on unreliable network links.
  1303. *
  1304. * \note The more unreliable your network connection is, the larger
  1305. * your max / min ratio needs to be in order to achieve
  1306. * reliable handshakes.
  1307. *
  1308. * \note Messages are retransmitted up to log2(ceil(max/min)) times.
  1309. * For example, if min = 1s and max = 5s, the retransmit plan
  1310. * goes: send ... 1s -> resend ... 2s -> resend ... 4s ->
  1311. * resend ... 5s -> give up and return a timeout error.
  1312. */
  1313. void mbedtls_ssl_conf_handshake_timeout( mbedtls_ssl_config *conf, uint32_t min, uint32_t max );
  1314. #endif /* MBEDTLS_SSL_PROTO_DTLS */
  1315. #if defined(MBEDTLS_SSL_SRV_C)
  1316. /**
  1317. * \brief Set the session cache callbacks (server-side only)
  1318. * If not set, no session resuming is done (except if session
  1319. * tickets are enabled too).
  1320. *
  1321. * The session cache has the responsibility to check for stale
  1322. * entries based on timeout. See RFC 5246 for recommendations.
  1323. *
  1324. * Warning: session.peer_cert is cleared by the SSL/TLS layer on
  1325. * connection shutdown, so do not cache the pointer! Either set
  1326. * it to NULL or make a full copy of the certificate.
  1327. *
  1328. * The get callback is called once during the initial handshake
  1329. * to enable session resuming. The get function has the
  1330. * following parameters: (void *parameter, mbedtls_ssl_session *session)
  1331. * If a valid entry is found, it should fill the master of
  1332. * the session object with the cached values and return 0,
  1333. * return 1 otherwise. Optionally peer_cert can be set as well
  1334. * if it is properly present in cache entry.
  1335. *
  1336. * The set callback is called once during the initial handshake
  1337. * to enable session resuming after the entire handshake has
  1338. * been finished. The set function has the following parameters:
  1339. * (void *parameter, const mbedtls_ssl_session *session). The function
  1340. * should create a cache entry for future retrieval based on
  1341. * the data in the session structure and should keep in mind
  1342. * that the mbedtls_ssl_session object presented (and all its referenced
  1343. * data) is cleared by the SSL/TLS layer when the connection is
  1344. * terminated. It is recommended to add metadata to determine if
  1345. * an entry is still valid in the future. Return 0 if
  1346. * successfully cached, return 1 otherwise.
  1347. *
  1348. * \param conf SSL configuration
  1349. * \param p_cache parmater (context) for both callbacks
  1350. * \param f_get_cache session get callback
  1351. * \param f_set_cache session set callback
  1352. */
  1353. void mbedtls_ssl_conf_session_cache( mbedtls_ssl_config *conf,
  1354. void *p_cache,
  1355. int (*f_get_cache)(void *, mbedtls_ssl_session *),
  1356. int (*f_set_cache)(void *, const mbedtls_ssl_session *) );
  1357. #endif /* MBEDTLS_SSL_SRV_C */
  1358. #if defined(MBEDTLS_SSL_CLI_C)
  1359. /**
  1360. * \brief Request resumption of session (client-side only)
  1361. * Session data is copied from presented session structure.
  1362. *
  1363. * \param ssl SSL context
  1364. * \param session session context
  1365. *
  1366. * \return 0 if successful,
  1367. * MBEDTLS_ERR_SSL_ALLOC_FAILED if memory allocation failed,
  1368. * MBEDTLS_ERR_SSL_BAD_INPUT_DATA if used server-side or
  1369. * arguments are otherwise invalid
  1370. *
  1371. * \sa mbedtls_ssl_get_session()
  1372. */
  1373. int mbedtls_ssl_set_session( mbedtls_ssl_context *ssl, const mbedtls_ssl_session *session );
  1374. #endif /* MBEDTLS_SSL_CLI_C */
  1375. /**
  1376. * \brief Set the list of allowed ciphersuites and the preference
  1377. * order. First in the list has the highest preference.
  1378. * (Overrides all version-specific lists)
  1379. *
  1380. * The ciphersuites array is not copied, and must remain
  1381. * valid for the lifetime of the ssl_config.
  1382. *
  1383. * Note: The server uses its own preferences
  1384. * over the preference of the client unless
  1385. * MBEDTLS_SSL_SRV_RESPECT_CLIENT_PREFERENCE is defined!
  1386. *
  1387. * \param conf SSL configuration
  1388. * \param ciphersuites 0-terminated list of allowed ciphersuites
  1389. */
  1390. void mbedtls_ssl_conf_ciphersuites( mbedtls_ssl_config *conf,
  1391. const int *ciphersuites );
  1392. /**
  1393. * \brief Set the list of allowed ciphersuites and the
  1394. * preference order for a specific version of the protocol.
  1395. * (Only useful on the server side)
  1396. *
  1397. * The ciphersuites array is not copied, and must remain
  1398. * valid for the lifetime of the ssl_config.
  1399. *
  1400. * \param conf SSL configuration
  1401. * \param ciphersuites 0-terminated list of allowed ciphersuites
  1402. * \param major Major version number (only MBEDTLS_SSL_MAJOR_VERSION_3
  1403. * supported)
  1404. * \param minor Minor version number (MBEDTLS_SSL_MINOR_VERSION_0,
  1405. * MBEDTLS_SSL_MINOR_VERSION_1 and MBEDTLS_SSL_MINOR_VERSION_2,
  1406. * MBEDTLS_SSL_MINOR_VERSION_3 supported)
  1407. *
  1408. * \note With DTLS, use MBEDTLS_SSL_MINOR_VERSION_2 for DTLS 1.0
  1409. * and MBEDTLS_SSL_MINOR_VERSION_3 for DTLS 1.2
  1410. */
  1411. void mbedtls_ssl_conf_ciphersuites_for_version( mbedtls_ssl_config *conf,
  1412. const int *ciphersuites,
  1413. int major, int minor );
  1414. #if defined(MBEDTLS_X509_CRT_PARSE_C)
  1415. /**
  1416. * \brief Set the X.509 security profile used for verification
  1417. *
  1418. * \note The restrictions are enforced for all certificates in the
  1419. * chain. However, signatures in the handshake are not covered
  1420. * by this setting but by \b mbedtls_ssl_conf_sig_hashes().
  1421. *
  1422. * \param conf SSL configuration
  1423. * \param profile Profile to use
  1424. */
  1425. void mbedtls_ssl_conf_cert_profile( mbedtls_ssl_config *conf,
  1426. const mbedtls_x509_crt_profile *profile );
  1427. /**
  1428. * \brief Set the data required to verify peer certificate
  1429. *
  1430. * \param conf SSL configuration
  1431. * \param ca_chain trusted CA chain (meaning all fully trusted top-level CAs)
  1432. * \param ca_crl trusted CA CRLs
  1433. */
  1434. void mbedtls_ssl_conf_ca_chain( mbedtls_ssl_config *conf,
  1435. mbedtls_x509_crt *ca_chain,
  1436. mbedtls_x509_crl *ca_crl );
  1437. /**
  1438. * \brief Set own certificate chain and private key
  1439. *
  1440. * \note own_cert should contain in order from the bottom up your
  1441. * certificate chain. The top certificate (self-signed)
  1442. * can be omitted.
  1443. *
  1444. * \note On server, this function can be called multiple times to
  1445. * provision more than one cert/key pair (eg one ECDSA, one
  1446. * RSA with SHA-256, one RSA with SHA-1). An adequate
  1447. * certificate will be selected according to the client's
  1448. * advertised capabilities. In case mutliple certificates are
  1449. * adequate, preference is given to the one set by the first
  1450. * call to this function, then second, etc.
  1451. *
  1452. * \note On client, only the first call has any effect. That is,
  1453. * only one client certificate can be provisioned. The
  1454. * server's preferences in its CertficateRequest message will
  1455. * be ignored and our only cert will be sent regardless of
  1456. * whether it matches those preferences - the server can then
  1457. * decide what it wants to do with it.
  1458. *
  1459. * \param conf SSL configuration
  1460. * \param own_cert own public certificate chain
  1461. * \param pk_key own private key
  1462. *
  1463. * \return 0 on success or MBEDTLS_ERR_SSL_ALLOC_FAILED
  1464. */
  1465. int mbedtls_ssl_conf_own_cert( mbedtls_ssl_config *conf,
  1466. mbedtls_x509_crt *own_cert,
  1467. mbedtls_pk_context *pk_key );
  1468. #endif /* MBEDTLS_X509_CRT_PARSE_C */
  1469. #if defined(MBEDTLS_KEY_EXCHANGE__SOME__PSK_ENABLED)
  1470. /**
  1471. * \brief Set the Pre Shared Key (PSK) and the expected identity name
  1472. *
  1473. * \note This is mainly useful for clients. Servers will usually
  1474. * want to use \c mbedtls_ssl_conf_psk_cb() instead.
  1475. *
  1476. * \note Currently clients can only register one pre-shared key.
  1477. * In other words, the servers' identity hint is ignored.
  1478. * Support for setting multiple PSKs on clients and selecting
  1479. * one based on the identity hint is not a planned feature but
  1480. * feedback is welcomed.
  1481. *
  1482. * \param conf SSL configuration
  1483. * \param psk pointer to the pre-shared key
  1484. * \param psk_len pre-shared key length
  1485. * \param psk_identity pointer to the pre-shared key identity
  1486. * \param psk_identity_len identity key length
  1487. *
  1488. * \return 0 if successful or MBEDTLS_ERR_SSL_ALLOC_FAILED
  1489. */
  1490. int mbedtls_ssl_conf_psk( mbedtls_ssl_config *conf,
  1491. const unsigned char *psk, size_t psk_len,
  1492. const unsigned char *psk_identity, size_t psk_identity_len );
  1493. /**
  1494. * \brief Set the Pre Shared Key (PSK) for the current handshake
  1495. *
  1496. * \note This should only be called inside the PSK callback,
  1497. * ie the function passed to \c mbedtls_ssl_conf_psk_cb().
  1498. *
  1499. * \param ssl SSL context
  1500. * \param psk pointer to the pre-shared key
  1501. * \param psk_len pre-shared key length
  1502. *
  1503. * \return 0 if successful or MBEDTLS_ERR_SSL_ALLOC_FAILED
  1504. */
  1505. int mbedtls_ssl_set_hs_psk( mbedtls_ssl_context *ssl,
  1506. const unsigned char *psk, size_t psk_len );
  1507. /**
  1508. * \brief Set the PSK callback (server-side only).
  1509. *
  1510. * If set, the PSK callback is called for each
  1511. * handshake where a PSK ciphersuite was negotiated.
  1512. * The caller provides the identity received and wants to
  1513. * receive the actual PSK data and length.
  1514. *
  1515. * The callback has the following parameters: (void *parameter,
  1516. * mbedtls_ssl_context *ssl, const unsigned char *psk_identity,
  1517. * size_t identity_len)
  1518. * If a valid PSK identity is found, the callback should use
  1519. * \c mbedtls_ssl_set_hs_psk() on the ssl context to set the
  1520. * correct PSK and return 0.
  1521. * Any other return value will result in a denied PSK identity.
  1522. *
  1523. * \note If you set a PSK callback using this function, then you
  1524. * don't need to set a PSK key and identity using
  1525. * \c mbedtls_ssl_conf_psk().
  1526. *
  1527. * \param conf SSL configuration
  1528. * \param f_psk PSK identity function
  1529. * \param p_psk PSK identity parameter
  1530. */
  1531. void mbedtls_ssl_conf_psk_cb( mbedtls_ssl_config *conf,
  1532. int (*f_psk)(void *, mbedtls_ssl_context *, const unsigned char *,
  1533. size_t),
  1534. void *p_psk );
  1535. #endif /* MBEDTLS_KEY_EXCHANGE__SOME__PSK_ENABLED */
  1536. #if defined(MBEDTLS_DHM_C) && defined(MBEDTLS_SSL_SRV_C)
  1537. #if !defined(MBEDTLS_DEPRECATED_REMOVED)
  1538. #if defined(MBEDTLS_DEPRECATED_WARNING)
  1539. #define MBEDTLS_DEPRECATED __attribute__((deprecated))
  1540. #else
  1541. #define MBEDTLS_DEPRECATED
  1542. #endif
  1543. /**
  1544. * \brief Set the Diffie-Hellman public P and G values,
  1545. * read as hexadecimal strings (server-side only)
  1546. * (Default values: MBEDTLS_DHM_RFC3526_MODP_2048_[PG])
  1547. *
  1548. * \param conf SSL configuration
  1549. * \param dhm_P Diffie-Hellman-Merkle modulus
  1550. * \param dhm_G Diffie-Hellman-Merkle generator
  1551. *
  1552. * \deprecated Superseded by \c mbedtls_ssl_conf_dh_param_bin.
  1553. *
  1554. * \return 0 if successful
  1555. */
  1556. MBEDTLS_DEPRECATED int mbedtls_ssl_conf_dh_param( mbedtls_ssl_config *conf,
  1557. const char *dhm_P,
  1558. const char *dhm_G );
  1559. #endif /* MBEDTLS_DEPRECATED_REMOVED */
  1560. /**
  1561. * \brief Set the Diffie-Hellman public P and G values
  1562. * from big-endian binary presentations.
  1563. * (Default values: MBEDTLS_DHM_RFC3526_MODP_2048_[PG]_BIN)
  1564. *
  1565. * \param conf SSL configuration
  1566. * \param dhm_P Diffie-Hellman-Merkle modulus in big-endian binary form
  1567. * \param P_len Length of DHM modulus
  1568. * \param dhm_G Diffie-Hellman-Merkle generator in big-endian binary form
  1569. * \param G_len Length of DHM generator
  1570. *
  1571. * \return 0 if successful
  1572. */
  1573. int mbedtls_ssl_conf_dh_param_bin( mbedtls_ssl_config *conf,
  1574. const unsigned char *dhm_P, size_t P_len,
  1575. const unsigned char *dhm_G, size_t G_len );
  1576. /**
  1577. * \brief Set the Diffie-Hellman public P and G values,
  1578. * read from existing context (server-side only)
  1579. *
  1580. * \param conf SSL configuration
  1581. * \param dhm_ctx Diffie-Hellman-Merkle context
  1582. *
  1583. * \return 0 if successful
  1584. */
  1585. int mbedtls_ssl_conf_dh_param_ctx( mbedtls_ssl_config *conf, mbedtls_dhm_context *dhm_ctx );
  1586. #endif /* MBEDTLS_DHM_C && defined(MBEDTLS_SSL_SRV_C) */
  1587. #if defined(MBEDTLS_DHM_C) && defined(MBEDTLS_SSL_CLI_C)
  1588. /**
  1589. * \brief Set the minimum length for Diffie-Hellman parameters.
  1590. * (Client-side only.)
  1591. * (Default: 1024 bits.)
  1592. *
  1593. * \param conf SSL configuration
  1594. * \param bitlen Minimum bit length of the DHM prime
  1595. */
  1596. void mbedtls_ssl_conf_dhm_min_bitlen( mbedtls_ssl_config *conf,
  1597. unsigned int bitlen );
  1598. #endif /* MBEDTLS_DHM_C && MBEDTLS_SSL_CLI_C */
  1599. #if defined(MBEDTLS_ECP_C)
  1600. /**
  1601. * \brief Set the allowed curves in order of preference.
  1602. * (Default: all defined curves.)
  1603. *
  1604. * On server: this only affects selection of the ECDHE curve;
  1605. * the curves used for ECDH and ECDSA are determined by the
  1606. * list of available certificates instead.
  1607. *
  1608. * On client: this affects the list of curves offered for any
  1609. * use. The server can override our preference order.
  1610. *
  1611. * Both sides: limits the set of curves accepted for use in
  1612. * ECDHE and in the peer's end-entity certificate.
  1613. *
  1614. * \note This has no influence on which curves are allowed inside the
  1615. * certificate chains, see \c mbedtls_ssl_conf_cert_profile()
  1616. * for that. For the end-entity certificate however, the key
  1617. * will be accepted only if it is allowed both by this list
  1618. * and by the cert profile.
  1619. *
  1620. * \note This list should be ordered by decreasing preference
  1621. * (preferred curve first).
  1622. *
  1623. * \param conf SSL configuration
  1624. * \param curves Ordered list of allowed curves,
  1625. * terminated by MBEDTLS_ECP_DP_NONE.
  1626. */
  1627. void mbedtls_ssl_conf_curves( mbedtls_ssl_config *conf,
  1628. const mbedtls_ecp_group_id *curves );
  1629. #endif /* MBEDTLS_ECP_C */
  1630. #if defined(MBEDTLS_KEY_EXCHANGE__WITH_CERT__ENABLED)
  1631. /**
  1632. * \brief Set the allowed hashes for signatures during the handshake.
  1633. * (Default: all available hashes except MD5.)
  1634. *
  1635. * \note This only affects which hashes are offered and can be used
  1636. * for signatures during the handshake. Hashes for message
  1637. * authentication and the TLS PRF are controlled by the
  1638. * ciphersuite, see \c mbedtls_ssl_conf_ciphersuites(). Hashes
  1639. * used for certificate signature are controlled by the
  1640. * verification profile, see \c mbedtls_ssl_conf_cert_profile().
  1641. *
  1642. * \note This list should be ordered by decreasing preference
  1643. * (preferred hash first).
  1644. *
  1645. * \param conf SSL configuration
  1646. * \param hashes Ordered list of allowed signature hashes,
  1647. * terminated by \c MBEDTLS_MD_NONE.
  1648. */
  1649. void mbedtls_ssl_conf_sig_hashes( mbedtls_ssl_config *conf,
  1650. const int *hashes );
  1651. #endif /* MBEDTLS_KEY_EXCHANGE__WITH_CERT__ENABLED */
  1652. #if defined(MBEDTLS_X509_CRT_PARSE_C)
  1653. /**
  1654. * \brief Set or reset the hostname to check against the received
  1655. * server certificate. It sets the ServerName TLS extension,
  1656. * too, if that extension is enabled. (client-side only)
  1657. *
  1658. * \param ssl SSL context
  1659. * \param hostname the server hostname, may be NULL to clear hostname
  1660. * \note Maximum hostname length MBEDTLS_SSL_MAX_HOST_NAME_LEN.
  1661. *
  1662. * \return 0 if successful, MBEDTLS_ERR_SSL_ALLOC_FAILED on
  1663. * allocation failure, MBEDTLS_ERR_SSL_BAD_INPUT_DATA on
  1664. * too long input hostname.
  1665. *
  1666. * Hostname set to the one provided on success (cleared
  1667. * when NULL). On allocation failure hostname is cleared.
  1668. * On too long input failure, old hostname is unchanged.
  1669. */
  1670. int mbedtls_ssl_set_hostname( mbedtls_ssl_context *ssl, const char *hostname );
  1671. #endif /* MBEDTLS_X509_CRT_PARSE_C */
  1672. #if defined(MBEDTLS_SSL_SERVER_NAME_INDICATION)
  1673. /**
  1674. * \brief Set own certificate and key for the current handshake
  1675. *
  1676. * \note Same as \c mbedtls_ssl_conf_own_cert() but for use within
  1677. * the SNI callback.
  1678. *
  1679. * \param ssl SSL context
  1680. * \param own_cert own public certificate chain
  1681. * \param pk_key own private key
  1682. *
  1683. * \return 0 on success or MBEDTLS_ERR_SSL_ALLOC_FAILED
  1684. */
  1685. int mbedtls_ssl_set_hs_own_cert( mbedtls_ssl_context *ssl,
  1686. mbedtls_x509_crt *own_cert,
  1687. mbedtls_pk_context *pk_key );
  1688. /**
  1689. * \brief Set the data required to verify peer certificate for the
  1690. * current handshake
  1691. *
  1692. * \note Same as \c mbedtls_ssl_conf_ca_chain() but for use within
  1693. * the SNI callback.
  1694. *
  1695. * \param ssl SSL context
  1696. * \param ca_chain trusted CA chain (meaning all fully trusted top-level CAs)
  1697. * \param ca_crl trusted CA CRLs
  1698. */
  1699. void mbedtls_ssl_set_hs_ca_chain( mbedtls_ssl_context *ssl,
  1700. mbedtls_x509_crt *ca_chain,
  1701. mbedtls_x509_crl *ca_crl );
  1702. /**
  1703. * \brief Set authmode for the current handshake.
  1704. *
  1705. * \note Same as \c mbedtls_ssl_conf_authmode() but for use within
  1706. * the SNI callback.
  1707. *
  1708. * \param ssl SSL context
  1709. * \param authmode MBEDTLS_SSL_VERIFY_NONE, MBEDTLS_SSL_VERIFY_OPTIONAL or
  1710. * MBEDTLS_SSL_VERIFY_REQUIRED
  1711. */
  1712. void mbedtls_ssl_set_hs_authmode( mbedtls_ssl_context *ssl,
  1713. int authmode );
  1714. /**
  1715. * \brief Set server side ServerName TLS extension callback
  1716. * (optional, server-side only).
  1717. *
  1718. * If set, the ServerName callback is called whenever the
  1719. * server receives a ServerName TLS extension from the client
  1720. * during a handshake. The ServerName callback has the
  1721. * following parameters: (void *parameter, mbedtls_ssl_context *ssl,
  1722. * const unsigned char *hostname, size_t len). If a suitable
  1723. * certificate is found, the callback must set the
  1724. * certificate(s) and key(s) to use with \c
  1725. * mbedtls_ssl_set_hs_own_cert() (can be called repeatedly),
  1726. * and may optionally adjust the CA and associated CRL with \c
  1727. * mbedtls_ssl_set_hs_ca_chain() as well as the client
  1728. * authentication mode with \c mbedtls_ssl_set_hs_authmode(),
  1729. * then must return 0. If no matching name is found, the
  1730. * callback must either set a default cert, or
  1731. * return non-zero to abort the handshake at this point.
  1732. *
  1733. * \param conf SSL configuration
  1734. * \param f_sni verification function
  1735. * \param p_sni verification parameter
  1736. */
  1737. void mbedtls_ssl_conf_sni( mbedtls_ssl_config *conf,
  1738. int (*f_sni)(void *, mbedtls_ssl_context *, const unsigned char *,
  1739. size_t),
  1740. void *p_sni );
  1741. #endif /* MBEDTLS_SSL_SERVER_NAME_INDICATION */
  1742. #if defined(MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED)
  1743. /**
  1744. * \brief Set the EC J-PAKE password for current handshake.
  1745. *
  1746. * \note An internal copy is made, and destroyed as soon as the
  1747. * handshake is completed, or when the SSL context is reset or
  1748. * freed.
  1749. *
  1750. * \note The SSL context needs to be already set up. The right place
  1751. * to call this function is between \c mbedtls_ssl_setup() or
  1752. * \c mbedtls_ssl_reset() and \c mbedtls_ssl_handshake().
  1753. *
  1754. * \param ssl SSL context
  1755. * \param pw EC J-PAKE password (pre-shared secret)
  1756. * \param pw_len length of pw in bytes
  1757. *
  1758. * \return 0 on success, or a negative error code.
  1759. */
  1760. int mbedtls_ssl_set_hs_ecjpake_password( mbedtls_ssl_context *ssl,
  1761. const unsigned char *pw,
  1762. size_t pw_len );
  1763. #endif /*MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED */
  1764. #if defined(MBEDTLS_SSL_ALPN)
  1765. /**
  1766. * \brief Set the supported Application Layer Protocols.
  1767. *
  1768. * \param conf SSL configuration
  1769. * \param protos Pointer to a NULL-terminated list of supported protocols,
  1770. * in decreasing preference order. The pointer to the list is
  1771. * recorded by the library for later reference as required, so
  1772. * the lifetime of the table must be atleast as long as the
  1773. * lifetime of the SSL configuration structure.
  1774. *
  1775. * \return 0 on success, or MBEDTLS_ERR_SSL_BAD_INPUT_DATA.
  1776. */
  1777. int mbedtls_ssl_conf_alpn_protocols( mbedtls_ssl_config *conf, const char **protos );
  1778. /**
  1779. * \brief Get the name of the negotiated Application Layer Protocol.
  1780. * This function should be called after the handshake is
  1781. * completed.
  1782. *
  1783. * \param ssl SSL context
  1784. *
  1785. * \return Protcol name, or NULL if no protocol was negotiated.
  1786. */
  1787. const char *mbedtls_ssl_get_alpn_protocol( const mbedtls_ssl_context *ssl );
  1788. #endif /* MBEDTLS_SSL_ALPN */
  1789. /**
  1790. * \brief Set the maximum supported version sent from the client side
  1791. * and/or accepted at the server side
  1792. * (Default: MBEDTLS_SSL_MAX_MAJOR_VERSION, MBEDTLS_SSL_MAX_MINOR_VERSION)
  1793. *
  1794. * \note This ignores ciphersuites from higher versions.
  1795. *
  1796. * \note With DTLS, use MBEDTLS_SSL_MINOR_VERSION_2 for DTLS 1.0 and
  1797. * MBEDTLS_SSL_MINOR_VERSION_3 for DTLS 1.2
  1798. *
  1799. * \param conf SSL configuration
  1800. * \param major Major version number (only MBEDTLS_SSL_MAJOR_VERSION_3 supported)
  1801. * \param minor Minor version number (MBEDTLS_SSL_MINOR_VERSION_0,
  1802. * MBEDTLS_SSL_MINOR_VERSION_1 and MBEDTLS_SSL_MINOR_VERSION_2,
  1803. * MBEDTLS_SSL_MINOR_VERSION_3 supported)
  1804. */
  1805. void mbedtls_ssl_conf_max_version( mbedtls_ssl_config *conf, int major, int minor );
  1806. /**
  1807. * \brief Set the minimum accepted SSL/TLS protocol version
  1808. * (Default: TLS 1.0)
  1809. *
  1810. * \note Input outside of the SSL_MAX_XXXXX_VERSION and
  1811. * SSL_MIN_XXXXX_VERSION range is ignored.
  1812. *
  1813. * \note MBEDTLS_SSL_MINOR_VERSION_0 (SSL v3) should be avoided.
  1814. *
  1815. * \note With DTLS, use MBEDTLS_SSL_MINOR_VERSION_2 for DTLS 1.0 and
  1816. * MBEDTLS_SSL_MINOR_VERSION_3 for DTLS 1.2
  1817. *
  1818. * \param conf SSL configuration
  1819. * \param major Major version number (only MBEDTLS_SSL_MAJOR_VERSION_3 supported)
  1820. * \param minor Minor version number (MBEDTLS_SSL_MINOR_VERSION_0,
  1821. * MBEDTLS_SSL_MINOR_VERSION_1 and MBEDTLS_SSL_MINOR_VERSION_2,
  1822. * MBEDTLS_SSL_MINOR_VERSION_3 supported)
  1823. */
  1824. void mbedtls_ssl_conf_min_version( mbedtls_ssl_config *conf, int major, int minor );
  1825. #if defined(MBEDTLS_SSL_FALLBACK_SCSV) && defined(MBEDTLS_SSL_CLI_C)
  1826. /**
  1827. * \brief Set the fallback flag (client-side only).
  1828. * (Default: MBEDTLS_SSL_IS_NOT_FALLBACK).
  1829. *
  1830. * \note Set to MBEDTLS_SSL_IS_FALLBACK when preparing a fallback
  1831. * connection, that is a connection with max_version set to a
  1832. * lower value than the value you're willing to use. Such
  1833. * fallback connections are not recommended but are sometimes
  1834. * necessary to interoperate with buggy (version-intolerant)
  1835. * servers.
  1836. *
  1837. * \warning You should NOT set this to MBEDTLS_SSL_IS_FALLBACK for
  1838. * non-fallback connections! This would appear to work for a
  1839. * while, then cause failures when the server is upgraded to
  1840. * support a newer TLS version.
  1841. *
  1842. * \param conf SSL configuration
  1843. * \param fallback MBEDTLS_SSL_IS_NOT_FALLBACK or MBEDTLS_SSL_IS_FALLBACK
  1844. */
  1845. void mbedtls_ssl_conf_fallback( mbedtls_ssl_config *conf, char fallback );
  1846. #endif /* MBEDTLS_SSL_FALLBACK_SCSV && MBEDTLS_SSL_CLI_C */
  1847. #if defined(MBEDTLS_SSL_ENCRYPT_THEN_MAC)
  1848. /**
  1849. * \brief Enable or disable Encrypt-then-MAC
  1850. * (Default: MBEDTLS_SSL_ETM_ENABLED)
  1851. *
  1852. * \note This should always be enabled, it is a security
  1853. * improvement, and should not cause any interoperability
  1854. * issue (used only if the peer supports it too).
  1855. *
  1856. * \param conf SSL configuration
  1857. * \param etm MBEDTLS_SSL_ETM_ENABLED or MBEDTLS_SSL_ETM_DISABLED
  1858. */
  1859. void mbedtls_ssl_conf_encrypt_then_mac( mbedtls_ssl_config *conf, char etm );
  1860. #endif /* MBEDTLS_SSL_ENCRYPT_THEN_MAC */
  1861. #if defined(MBEDTLS_SSL_EXTENDED_MASTER_SECRET)
  1862. /**
  1863. * \brief Enable or disable Extended Master Secret negotiation.
  1864. * (Default: MBEDTLS_SSL_EXTENDED_MS_ENABLED)
  1865. *
  1866. * \note This should always be enabled, it is a security fix to the
  1867. * protocol, and should not cause any interoperability issue
  1868. * (used only if the peer supports it too).
  1869. *
  1870. * \param conf SSL configuration
  1871. * \param ems MBEDTLS_SSL_EXTENDED_MS_ENABLED or MBEDTLS_SSL_EXTENDED_MS_DISABLED
  1872. */
  1873. void mbedtls_ssl_conf_extended_master_secret( mbedtls_ssl_config *conf, char ems );
  1874. #endif /* MBEDTLS_SSL_EXTENDED_MASTER_SECRET */
  1875. #if defined(MBEDTLS_ARC4_C)
  1876. /**
  1877. * \brief Disable or enable support for RC4
  1878. * (Default: MBEDTLS_SSL_ARC4_DISABLED)
  1879. *
  1880. * \warning Use of RC4 in DTLS/TLS has been prohibited by RFC 7465
  1881. * for security reasons. Use at your own risk.
  1882. *
  1883. * \note This function is deprecated and will likely be removed in
  1884. * a future version of the library.
  1885. * RC4 is disabled by default at compile time and needs to be
  1886. * actively enabled for use with legacy systems.
  1887. *
  1888. * \param conf SSL configuration
  1889. * \param arc4 MBEDTLS_SSL_ARC4_ENABLED or MBEDTLS_SSL_ARC4_DISABLED
  1890. */
  1891. void mbedtls_ssl_conf_arc4_support( mbedtls_ssl_config *conf, char arc4 );
  1892. #endif /* MBEDTLS_ARC4_C */
  1893. #if defined(MBEDTLS_SSL_SRV_C)
  1894. /**
  1895. * \brief Whether to send a list of acceptable CAs in
  1896. * CertificateRequest messages.
  1897. * (Default: do send)
  1898. *
  1899. * \param conf SSL configuration
  1900. * \param cert_req_ca_list MBEDTLS_SSL_CERT_REQ_CA_LIST_ENABLED or
  1901. * MBEDTLS_SSL_CERT_REQ_CA_LIST_DISABLED
  1902. */
  1903. void mbedtls_ssl_conf_cert_req_ca_list( mbedtls_ssl_config *conf,
  1904. char cert_req_ca_list );
  1905. #endif /* MBEDTLS_SSL_SRV_C */
  1906. #if defined(MBEDTLS_SSL_MAX_FRAGMENT_LENGTH)
  1907. /**
  1908. * \brief Set the maximum fragment length to emit and/or negotiate
  1909. * (Default: MBEDTLS_SSL_MAX_CONTENT_LEN, usually 2^14 bytes)
  1910. * (Server: set maximum fragment length to emit,
  1911. * usually negotiated by the client during handshake
  1912. * (Client: set maximum fragment length to emit *and*
  1913. * negotiate with the server during handshake)
  1914. *
  1915. * \param conf SSL configuration
  1916. * \param mfl_code Code for maximum fragment length (allowed values:
  1917. * MBEDTLS_SSL_MAX_FRAG_LEN_512, MBEDTLS_SSL_MAX_FRAG_LEN_1024,
  1918. * MBEDTLS_SSL_MAX_FRAG_LEN_2048, MBEDTLS_SSL_MAX_FRAG_LEN_4096)
  1919. *
  1920. * \return 0 if successful or MBEDTLS_ERR_SSL_BAD_INPUT_DATA
  1921. */
  1922. int mbedtls_ssl_conf_max_frag_len( mbedtls_ssl_config *conf, unsigned char mfl_code );
  1923. #endif /* MBEDTLS_SSL_MAX_FRAGMENT_LENGTH */
  1924. #if defined(MBEDTLS_SSL_TRUNCATED_HMAC)
  1925. /**
  1926. * \brief Activate negotiation of truncated HMAC
  1927. * (Default: MBEDTLS_SSL_TRUNC_HMAC_DISABLED)
  1928. *
  1929. * \param conf SSL configuration
  1930. * \param truncate Enable or disable (MBEDTLS_SSL_TRUNC_HMAC_ENABLED or
  1931. * MBEDTLS_SSL_TRUNC_HMAC_DISABLED)
  1932. */
  1933. void mbedtls_ssl_conf_truncated_hmac( mbedtls_ssl_config *conf, int truncate );
  1934. #endif /* MBEDTLS_SSL_TRUNCATED_HMAC */
  1935. #if defined(MBEDTLS_SSL_CBC_RECORD_SPLITTING)
  1936. /**
  1937. * \brief Enable / Disable 1/n-1 record splitting
  1938. * (Default: MBEDTLS_SSL_CBC_RECORD_SPLITTING_ENABLED)
  1939. *
  1940. * \note Only affects SSLv3 and TLS 1.0, not higher versions.
  1941. * Does not affect non-CBC ciphersuites in any version.
  1942. *
  1943. * \param conf SSL configuration
  1944. * \param split MBEDTLS_SSL_CBC_RECORD_SPLITTING_ENABLED or
  1945. * MBEDTLS_SSL_CBC_RECORD_SPLITTING_DISABLED
  1946. */
  1947. void mbedtls_ssl_conf_cbc_record_splitting( mbedtls_ssl_config *conf, char split );
  1948. #endif /* MBEDTLS_SSL_CBC_RECORD_SPLITTING */
  1949. #if defined(MBEDTLS_SSL_SESSION_TICKETS) && defined(MBEDTLS_SSL_CLI_C)
  1950. /**
  1951. * \brief Enable / Disable session tickets (client only).
  1952. * (Default: MBEDTLS_SSL_SESSION_TICKETS_ENABLED.)
  1953. *
  1954. * \note On server, use \c mbedtls_ssl_conf_session_tickets_cb().
  1955. *
  1956. * \param conf SSL configuration
  1957. * \param use_tickets Enable or disable (MBEDTLS_SSL_SESSION_TICKETS_ENABLED or
  1958. * MBEDTLS_SSL_SESSION_TICKETS_DISABLED)
  1959. */
  1960. void mbedtls_ssl_conf_session_tickets( mbedtls_ssl_config *conf, int use_tickets );
  1961. #endif /* MBEDTLS_SSL_SESSION_TICKETS && MBEDTLS_SSL_CLI_C */
  1962. #if defined(MBEDTLS_SSL_RENEGOTIATION)
  1963. /**
  1964. * \brief Enable / Disable renegotiation support for connection when
  1965. * initiated by peer
  1966. * (Default: MBEDTLS_SSL_RENEGOTIATION_DISABLED)
  1967. *
  1968. * \warning It is recommended to always disable renegotation unless you
  1969. * know you need it and you know what you're doing. In the
  1970. * past, there have been several issues associated with
  1971. * renegotiation or a poor understanding of its properties.
  1972. *
  1973. * \note Server-side, enabling renegotiation also makes the server
  1974. * susceptible to a resource DoS by a malicious client.
  1975. *
  1976. * \param conf SSL configuration
  1977. * \param renegotiation Enable or disable (MBEDTLS_SSL_RENEGOTIATION_ENABLED or
  1978. * MBEDTLS_SSL_RENEGOTIATION_DISABLED)
  1979. */
  1980. void mbedtls_ssl_conf_renegotiation( mbedtls_ssl_config *conf, int renegotiation );
  1981. #endif /* MBEDTLS_SSL_RENEGOTIATION */
  1982. /**
  1983. * \brief Prevent or allow legacy renegotiation.
  1984. * (Default: MBEDTLS_SSL_LEGACY_NO_RENEGOTIATION)
  1985. *
  1986. * MBEDTLS_SSL_LEGACY_NO_RENEGOTIATION allows connections to
  1987. * be established even if the peer does not support
  1988. * secure renegotiation, but does not allow renegotiation
  1989. * to take place if not secure.
  1990. * (Interoperable and secure option)
  1991. *
  1992. * MBEDTLS_SSL_LEGACY_ALLOW_RENEGOTIATION allows renegotiations
  1993. * with non-upgraded peers. Allowing legacy renegotiation
  1994. * makes the connection vulnerable to specific man in the
  1995. * middle attacks. (See RFC 5746)
  1996. * (Most interoperable and least secure option)
  1997. *
  1998. * MBEDTLS_SSL_LEGACY_BREAK_HANDSHAKE breaks off connections
  1999. * if peer does not support secure renegotiation. Results
  2000. * in interoperability issues with non-upgraded peers
  2001. * that do not support renegotiation altogether.
  2002. * (Most secure option, interoperability issues)
  2003. *
  2004. * \param conf SSL configuration
  2005. * \param allow_legacy Prevent or allow (SSL_NO_LEGACY_RENEGOTIATION,
  2006. * SSL_ALLOW_LEGACY_RENEGOTIATION or
  2007. * MBEDTLS_SSL_LEGACY_BREAK_HANDSHAKE)
  2008. */
  2009. void mbedtls_ssl_conf_legacy_renegotiation( mbedtls_ssl_config *conf, int allow_legacy );
  2010. #if defined(MBEDTLS_SSL_RENEGOTIATION)
  2011. /**
  2012. * \brief Enforce renegotiation requests.
  2013. * (Default: enforced, max_records = 16)
  2014. *
  2015. * When we request a renegotiation, the peer can comply or
  2016. * ignore the request. This function allows us to decide
  2017. * whether to enforce our renegotiation requests by closing
  2018. * the connection if the peer doesn't comply.
  2019. *
  2020. * However, records could already be in transit from the peer
  2021. * when the request is emitted. In order to increase
  2022. * reliability, we can accept a number of records before the
  2023. * expected handshake records.
  2024. *
  2025. * The optimal value is highly dependent on the specific usage
  2026. * scenario.
  2027. *
  2028. * \note With DTLS and server-initiated renegotiation, the
  2029. * HelloRequest is retransmited every time mbedtls_ssl_read() times
  2030. * out or receives Application Data, until:
  2031. * - max_records records have beens seen, if it is >= 0, or
  2032. * - the number of retransmits that would happen during an
  2033. * actual handshake has been reached.
  2034. * Please remember the request might be lost a few times
  2035. * if you consider setting max_records to a really low value.
  2036. *
  2037. * \warning On client, the grace period can only happen during
  2038. * mbedtls_ssl_read(), as opposed to mbedtls_ssl_write() and mbedtls_ssl_renegotiate()
  2039. * which always behave as if max_record was 0. The reason is,
  2040. * if we receive application data from the server, we need a
  2041. * place to write it, which only happens during mbedtls_ssl_read().
  2042. *
  2043. * \param conf SSL configuration
  2044. * \param max_records Use MBEDTLS_SSL_RENEGOTIATION_NOT_ENFORCED if you don't want to
  2045. * enforce renegotiation, or a non-negative value to enforce
  2046. * it but allow for a grace period of max_records records.
  2047. */
  2048. void mbedtls_ssl_conf_renegotiation_enforced( mbedtls_ssl_config *conf, int max_records );
  2049. /**
  2050. * \brief Set record counter threshold for periodic renegotiation.
  2051. * (Default: 2^48 - 1)
  2052. *
  2053. * Renegotiation is automatically triggered when a record
  2054. * counter (outgoing or ingoing) crosses the defined
  2055. * threshold. The default value is meant to prevent the
  2056. * connection from being closed when the counter is about to
  2057. * reached its maximal value (it is not allowed to wrap).
  2058. *
  2059. * Lower values can be used to enforce policies such as "keys
  2060. * must be refreshed every N packets with cipher X".
  2061. *
  2062. * The renegotiation period can be disabled by setting
  2063. * conf->disable_renegotiation to
  2064. * MBEDTLS_SSL_RENEGOTIATION_DISABLED.
  2065. *
  2066. * \note When the configured transport is
  2067. * MBEDTLS_SSL_TRANSPORT_DATAGRAM the maximum renegotiation
  2068. * period is 2^48 - 1, and for MBEDTLS_SSL_TRANSPORT_STREAM,
  2069. * the maximum renegotiation period is 2^64 - 1.
  2070. *
  2071. * \param conf SSL configuration
  2072. * \param period The threshold value: a big-endian 64-bit number.
  2073. */
  2074. void mbedtls_ssl_conf_renegotiation_period( mbedtls_ssl_config *conf,
  2075. const unsigned char period[8] );
  2076. #endif /* MBEDTLS_SSL_RENEGOTIATION */
  2077. /**
  2078. * \brief Return the number of data bytes available to read
  2079. *
  2080. * \param ssl SSL context
  2081. *
  2082. * \return how many bytes are available in the read buffer
  2083. */
  2084. size_t mbedtls_ssl_get_bytes_avail( const mbedtls_ssl_context *ssl );
  2085. /**
  2086. * \brief Return the result of the certificate verification
  2087. *
  2088. * \param ssl SSL context
  2089. *
  2090. * \return 0 if successful,
  2091. * -1 if result is not available (eg because the handshake was
  2092. * aborted too early), or
  2093. * a combination of BADCERT_xxx and BADCRL_xxx flags, see
  2094. * x509.h
  2095. */
  2096. uint32_t mbedtls_ssl_get_verify_result( const mbedtls_ssl_context *ssl );
  2097. /**
  2098. * \brief Return the name of the current ciphersuite
  2099. *
  2100. * \param ssl SSL context
  2101. *
  2102. * \return a string containing the ciphersuite name
  2103. */
  2104. const char *mbedtls_ssl_get_ciphersuite( const mbedtls_ssl_context *ssl );
  2105. /**
  2106. * \brief Return the current SSL version (SSLv3/TLSv1/etc)
  2107. *
  2108. * \param ssl SSL context
  2109. *
  2110. * \return a string containing the SSL version
  2111. */
  2112. const char *mbedtls_ssl_get_version( const mbedtls_ssl_context *ssl );
  2113. /**
  2114. * \brief Return the (maximum) number of bytes added by the record
  2115. * layer: header + encryption/MAC overhead (inc. padding)
  2116. *
  2117. * \param ssl SSL context
  2118. *
  2119. * \return Current maximum record expansion in bytes, or
  2120. * MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE if compression is
  2121. * enabled, which makes expansion much less predictable
  2122. */
  2123. int mbedtls_ssl_get_record_expansion( const mbedtls_ssl_context *ssl );
  2124. #if defined(MBEDTLS_SSL_MAX_FRAGMENT_LENGTH)
  2125. /**
  2126. * \brief Return the maximum fragment length (payload, in bytes).
  2127. * This is the value negotiated with peer if any,
  2128. * or the locally configured value.
  2129. *
  2130. * \note With DTLS, \c mbedtls_ssl_write() will return an error if
  2131. * called with a larger length value.
  2132. * With TLS, \c mbedtls_ssl_write() will fragment the input if
  2133. * necessary and return the number of bytes written; it is up
  2134. * to the caller to call \c mbedtls_ssl_write() again in
  2135. * order to send the remaining bytes if any.
  2136. *
  2137. * \param ssl SSL context
  2138. *
  2139. * \return Current maximum fragment length.
  2140. */
  2141. size_t mbedtls_ssl_get_max_frag_len( const mbedtls_ssl_context *ssl );
  2142. #endif /* MBEDTLS_SSL_MAX_FRAGMENT_LENGTH */
  2143. #if defined(MBEDTLS_X509_CRT_PARSE_C)
  2144. /**
  2145. * \brief Return the peer certificate from the current connection
  2146. *
  2147. * Note: Can be NULL in case no certificate was sent during
  2148. * the handshake. Different calls for the same connection can
  2149. * return the same or different pointers for the same
  2150. * certificate and even a different certificate altogether.
  2151. * The peer cert CAN change in a single connection if
  2152. * renegotiation is performed.
  2153. *
  2154. * \param ssl SSL context
  2155. *
  2156. * \return the current peer certificate
  2157. */
  2158. const mbedtls_x509_crt *mbedtls_ssl_get_peer_cert( const mbedtls_ssl_context *ssl );
  2159. #endif /* MBEDTLS_X509_CRT_PARSE_C */
  2160. #if defined(MBEDTLS_SSL_CLI_C)
  2161. /**
  2162. * \brief Save session in order to resume it later (client-side only)
  2163. * Session data is copied to presented session structure.
  2164. *
  2165. * \warning Currently, peer certificate is lost in the operation.
  2166. *
  2167. * \param ssl SSL context
  2168. * \param session session context
  2169. *
  2170. * \return 0 if successful,
  2171. * MBEDTLS_ERR_SSL_ALLOC_FAILED if memory allocation failed,
  2172. * MBEDTLS_ERR_SSL_BAD_INPUT_DATA if used server-side or
  2173. * arguments are otherwise invalid
  2174. *
  2175. * \sa mbedtls_ssl_set_session()
  2176. */
  2177. int mbedtls_ssl_get_session( const mbedtls_ssl_context *ssl, mbedtls_ssl_session *session );
  2178. #endif /* MBEDTLS_SSL_CLI_C */
  2179. /**
  2180. * \brief Perform the SSL handshake
  2181. *
  2182. * \param ssl SSL context
  2183. *
  2184. * \return 0 if successful, or
  2185. * MBEDTLS_ERR_SSL_WANT_READ or MBEDTLS_ERR_SSL_WANT_WRITE, or
  2186. * MBEDTLS_ERR_SSL_HELLO_VERIFY_REQUIRED (see below), or
  2187. * a specific SSL error code.
  2188. *
  2189. * \note If this function returns something other than 0 or
  2190. * MBEDTLS_ERR_SSL_WANT_READ/WRITE, then the ssl context
  2191. * becomes unusable, and you should either free it or call
  2192. * \c mbedtls_ssl_session_reset() on it before re-using it for
  2193. * a new connection; the current connection must be closed.
  2194. *
  2195. * \note If DTLS is in use, then you may choose to handle
  2196. * MBEDTLS_ERR_SSL_HELLO_VERIFY_REQUIRED specially for logging
  2197. * purposes, as it is an expected return value rather than an
  2198. * actual error, but you still need to reset/free the context.
  2199. */
  2200. int mbedtls_ssl_handshake( mbedtls_ssl_context *ssl );
  2201. /**
  2202. * \brief Perform a single step of the SSL handshake
  2203. *
  2204. * \note The state of the context (ssl->state) will be at
  2205. * the next state after execution of this function. Do not
  2206. * call this function if state is MBEDTLS_SSL_HANDSHAKE_OVER.
  2207. *
  2208. * \note If this function returns something other than 0 or
  2209. * MBEDTLS_ERR_SSL_WANT_READ/WRITE, then the ssl context
  2210. * becomes unusable, and you should either free it or call
  2211. * \c mbedtls_ssl_session_reset() on it before re-using it for
  2212. * a new connection; the current connection must be closed.
  2213. *
  2214. * \param ssl SSL context
  2215. *
  2216. * \return 0 if successful, or
  2217. * MBEDTLS_ERR_SSL_WANT_READ or MBEDTLS_ERR_SSL_WANT_WRITE, or
  2218. * a specific SSL error code.
  2219. */
  2220. int mbedtls_ssl_handshake_step( mbedtls_ssl_context *ssl );
  2221. #if defined(MBEDTLS_SSL_RENEGOTIATION)
  2222. /**
  2223. * \brief Initiate an SSL renegotiation on the running connection.
  2224. * Client: perform the renegotiation right now.
  2225. * Server: request renegotiation, which will be performed
  2226. * during the next call to mbedtls_ssl_read() if honored by
  2227. * client.
  2228. *
  2229. * \param ssl SSL context
  2230. *
  2231. * \return 0 if successful, or any mbedtls_ssl_handshake() return
  2232. * value.
  2233. *
  2234. * \note If this function returns something other than 0 or
  2235. * MBEDTLS_ERR_SSL_WANT_READ/WRITE, then the ssl context
  2236. * becomes unusable, and you should either free it or call
  2237. * \c mbedtls_ssl_session_reset() on it before re-using it for
  2238. * a new connection; the current connection must be closed.
  2239. */
  2240. int mbedtls_ssl_renegotiate( mbedtls_ssl_context *ssl );
  2241. #endif /* MBEDTLS_SSL_RENEGOTIATION */
  2242. /**
  2243. * \brief Read at most 'len' application data bytes
  2244. *
  2245. * \param ssl SSL context
  2246. * \param buf buffer that will hold the data
  2247. * \param len maximum number of bytes to read
  2248. *
  2249. * \return the number of bytes read, or
  2250. * 0 for EOF, or
  2251. * MBEDTLS_ERR_SSL_WANT_READ or MBEDTLS_ERR_SSL_WANT_WRITE, or
  2252. * MBEDTLS_ERR_SSL_CLIENT_RECONNECT (see below), or
  2253. * another negative error code.
  2254. *
  2255. * \note If this function returns something other than a positive
  2256. * value or MBEDTLS_ERR_SSL_WANT_READ/WRITE or
  2257. * MBEDTLS_ERR_SSL_CLIENT_RECONNECT, then the ssl context
  2258. * becomes unusable, and you should either free it or call
  2259. * \c mbedtls_ssl_session_reset() on it before re-using it for
  2260. * a new connection; the current connection must be closed.
  2261. *
  2262. * \note When this function return MBEDTLS_ERR_SSL_CLIENT_RECONNECT
  2263. * (which can only happen server-side), it means that a client
  2264. * is initiating a new connection using the same source port.
  2265. * You can either treat that as a connection close and wait
  2266. * for the client to resend a ClientHello, or directly
  2267. * continue with \c mbedtls_ssl_handshake() with the same
  2268. * context (as it has beeen reset internally). Either way, you
  2269. * should make sure this is seen by the application as a new
  2270. * connection: application state, if any, should be reset, and
  2271. * most importantly the identity of the client must be checked
  2272. * again. WARNING: not validating the identity of the client
  2273. * again, or not transmitting the new identity to the
  2274. * application layer, would allow authentication bypass!
  2275. */
  2276. int mbedtls_ssl_read( mbedtls_ssl_context *ssl, unsigned char *buf, size_t len );
  2277. /**
  2278. * \brief Try to write exactly 'len' application data bytes
  2279. *
  2280. * \warning This function will do partial writes in some cases. If the
  2281. * return value is non-negative but less than length, the
  2282. * function must be called again with updated arguments:
  2283. * buf + ret, len - ret (if ret is the return value) until
  2284. * it returns a value equal to the last 'len' argument.
  2285. *
  2286. * \param ssl SSL context
  2287. * \param buf buffer holding the data
  2288. * \param len how many bytes must be written
  2289. *
  2290. * \return the number of bytes actually written (may be less than len),
  2291. * or MBEDTLS_ERR_SSL_WANT_WRITE or MBEDTLS_ERR_SSL_WANT_READ,
  2292. * or another negative error code.
  2293. *
  2294. * \note If this function returns something other than a positive
  2295. * value or MBEDTLS_ERR_SSL_WANT_READ/WRITE, the ssl context
  2296. * becomes unusable, and you should either free it or call
  2297. * \c mbedtls_ssl_session_reset() on it before re-using it for
  2298. * a new connection; the current connection must be closed.
  2299. *
  2300. * \note When this function returns MBEDTLS_ERR_SSL_WANT_WRITE/READ,
  2301. * it must be called later with the *same* arguments,
  2302. * until it returns a positive value.
  2303. *
  2304. * \note If the requested length is greater than the maximum
  2305. * fragment length (either the built-in limit or the one set
  2306. * or negotiated with the peer), then:
  2307. * - with TLS, less bytes than requested are written.
  2308. * - with DTLS, MBEDTLS_ERR_SSL_BAD_INPUT_DATA is returned.
  2309. * \c mbedtls_ssl_get_max_frag_len() may be used to query the
  2310. * active maximum fragment length.
  2311. */
  2312. int mbedtls_ssl_write( mbedtls_ssl_context *ssl, const unsigned char *buf, size_t len );
  2313. /**
  2314. * \brief Send an alert message
  2315. *
  2316. * \param ssl SSL context
  2317. * \param level The alert level of the message
  2318. * (MBEDTLS_SSL_ALERT_LEVEL_WARNING or MBEDTLS_SSL_ALERT_LEVEL_FATAL)
  2319. * \param message The alert message (SSL_ALERT_MSG_*)
  2320. *
  2321. * \return 0 if successful, or a specific SSL error code.
  2322. *
  2323. * \note If this function returns something other than 0 or
  2324. * MBEDTLS_ERR_SSL_WANT_READ/WRITE, then the ssl context
  2325. * becomes unusable, and you should either free it or call
  2326. * \c mbedtls_ssl_session_reset() on it before re-using it for
  2327. * a new connection; the current connection must be closed.
  2328. */
  2329. int mbedtls_ssl_send_alert_message( mbedtls_ssl_context *ssl,
  2330. unsigned char level,
  2331. unsigned char message );
  2332. /**
  2333. * \brief Notify the peer that the connection is being closed
  2334. *
  2335. * \param ssl SSL context
  2336. *
  2337. * \return 0 if successful, or a specific SSL error code.
  2338. *
  2339. * \note If this function returns something other than 0 or
  2340. * MBEDTLS_ERR_SSL_WANT_READ/WRITE, then the ssl context
  2341. * becomes unusable, and you should either free it or call
  2342. * \c mbedtls_ssl_session_reset() on it before re-using it for
  2343. * a new connection; the current connection must be closed.
  2344. */
  2345. int mbedtls_ssl_close_notify( mbedtls_ssl_context *ssl );
  2346. /**
  2347. * \brief Free referenced items in an SSL context and clear memory
  2348. *
  2349. * \param ssl SSL context
  2350. */
  2351. void mbedtls_ssl_free( mbedtls_ssl_context *ssl );
  2352. /**
  2353. * \brief Initialize an SSL configuration context
  2354. * Just makes the context ready for
  2355. * mbedtls_ssl_config_defaults() or mbedtls_ssl_config_free().
  2356. *
  2357. * \note You need to call mbedtls_ssl_config_defaults() unless you
  2358. * manually set all of the relevent fields yourself.
  2359. *
  2360. * \param conf SSL configuration context
  2361. */
  2362. void mbedtls_ssl_config_init( mbedtls_ssl_config *conf );
  2363. /**
  2364. * \brief Load reasonnable default SSL configuration values.
  2365. * (You need to call mbedtls_ssl_config_init() first.)
  2366. *
  2367. * \param conf SSL configuration context
  2368. * \param endpoint MBEDTLS_SSL_IS_CLIENT or MBEDTLS_SSL_IS_SERVER
  2369. * \param transport MBEDTLS_SSL_TRANSPORT_STREAM for TLS, or
  2370. * MBEDTLS_SSL_TRANSPORT_DATAGRAM for DTLS
  2371. * \param preset a MBEDTLS_SSL_PRESET_XXX value
  2372. *
  2373. * \note See \c mbedtls_ssl_conf_transport() for notes on DTLS.
  2374. *
  2375. * \return 0 if successful, or
  2376. * MBEDTLS_ERR_XXX_ALLOC_FAILED on memory allocation error.
  2377. */
  2378. int mbedtls_ssl_config_defaults( mbedtls_ssl_config *conf,
  2379. int endpoint, int transport, int preset );
  2380. /**
  2381. * \brief Free an SSL configuration context
  2382. *
  2383. * \param conf SSL configuration context
  2384. */
  2385. void mbedtls_ssl_config_free( mbedtls_ssl_config *conf );
  2386. /**
  2387. * \brief Initialize SSL session structure
  2388. *
  2389. * \param session SSL session
  2390. */
  2391. void mbedtls_ssl_session_init( mbedtls_ssl_session *session );
  2392. /**
  2393. * \brief Free referenced items in an SSL session including the
  2394. * peer certificate and clear memory
  2395. *
  2396. * \param session SSL session
  2397. */
  2398. void mbedtls_ssl_session_free( mbedtls_ssl_session *session );
  2399. #ifdef __cplusplus
  2400. }
  2401. #endif
  2402. #endif /* ssl.h */