ssl.h 103 KB

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