ssl.h 115 KB

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