ssl.h 149 KB

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