ssl.h 112 KB

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