1 /** 2 * \file ssl.h 3 * 4 * \brief SSL/TLS functions. 5 */ 6 /* 7 * Copyright The Mbed TLS Contributors 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 #ifndef MBEDTLS_SSL_H 23 #define MBEDTLS_SSL_H 24 #include "mbedtls/platform_util.h" 25 #include "mbedtls/private_access.h" 26 27 #include "mbedtls/build_info.h" 28 29 #include "mbedtls/bignum.h" 30 #include "mbedtls/ecp.h" 31 32 #include "mbedtls/ssl_ciphersuites.h" 33 34 #if defined(MBEDTLS_X509_CRT_PARSE_C) 35 #include "mbedtls/x509_crt.h" 36 #include "mbedtls/x509_crl.h" 37 #endif 38 39 #if defined(MBEDTLS_DHM_C) 40 #include "mbedtls/dhm.h" 41 #endif 42 43 /* Adding guard for MBEDTLS_ECDSA_C to ensure no compile errors due 44 * to guards also being in ssl_srv.c and ssl_cli.c. There is a gap 45 * in functionality that access to ecdh_ctx structure is needed for 46 * MBEDTLS_ECDSA_C which does not seem correct. 47 */ 48 #if defined(MBEDTLS_ECDH_C) || defined(MBEDTLS_ECDSA_C) 49 #include "mbedtls/ecdh.h" 50 #endif 51 52 #if defined(MBEDTLS_HAVE_TIME) 53 #include "mbedtls/platform_time.h" 54 #endif 55 56 #if defined(MBEDTLS_USE_PSA_CRYPTO) 57 #include "psa/crypto.h" 58 #endif /* MBEDTLS_USE_PSA_CRYPTO */ 59 60 /* 61 * SSL Error codes 62 */ 63 /** A cryptographic operation is in progress. Try again later. */ 64 #define MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS -0x7000 65 /** The requested feature is not available. */ 66 #define MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE -0x7080 67 /** Bad input parameters to function. */ 68 #define MBEDTLS_ERR_SSL_BAD_INPUT_DATA -0x7100 69 /** Verification of the message MAC failed. */ 70 #define MBEDTLS_ERR_SSL_INVALID_MAC -0x7180 71 /** An invalid SSL record was received. */ 72 #define MBEDTLS_ERR_SSL_INVALID_RECORD -0x7200 73 /** The connection indicated an EOF. */ 74 #define MBEDTLS_ERR_SSL_CONN_EOF -0x7280 75 /** A message could not be parsed due to a syntactic error. */ 76 #define MBEDTLS_ERR_SSL_DECODE_ERROR -0x7300 77 /* Error space gap */ 78 /** No RNG was provided to the SSL module. */ 79 #define MBEDTLS_ERR_SSL_NO_RNG -0x7400 80 /** No client certification received from the client, but required by the authentication mode. */ 81 #define MBEDTLS_ERR_SSL_NO_CLIENT_CERTIFICATE -0x7480 82 /** Client received an extended server hello containing an unsupported extension */ 83 #define MBEDTLS_ERR_SSL_UNSUPPORTED_EXTENSION -0x7500 84 /** No ALPN protocols supported that the client advertises */ 85 #define MBEDTLS_ERR_SSL_NO_APPLICATION_PROTOCOL -0x7580 86 /** The own private key or pre-shared key is not set, but needed. */ 87 #define MBEDTLS_ERR_SSL_PRIVATE_KEY_REQUIRED -0x7600 88 /** No CA Chain is set, but required to operate. */ 89 #define MBEDTLS_ERR_SSL_CA_CHAIN_REQUIRED -0x7680 90 /** An unexpected message was received from our peer. */ 91 #define MBEDTLS_ERR_SSL_UNEXPECTED_MESSAGE -0x7700 92 /** A fatal alert message was received from our peer. */ 93 #define MBEDTLS_ERR_SSL_FATAL_ALERT_MESSAGE -0x7780 94 /** No server could be identified matching the client's SNI. */ 95 #define MBEDTLS_ERR_SSL_UNRECOGNIZED_NAME -0x7800 96 /** The peer notified us that the connection is going to be closed. */ 97 #define MBEDTLS_ERR_SSL_PEER_CLOSE_NOTIFY -0x7880 98 /* Error space gap */ 99 /* Error space gap */ 100 /** Processing of the Certificate handshake message failed. */ 101 #define MBEDTLS_ERR_SSL_BAD_CERTIFICATE -0x7A00 102 /* Error space gap */ 103 /* Error space gap */ 104 /* Error space gap */ 105 /* Error space gap */ 106 /* Error space gap */ 107 /* Error space gap */ 108 /* Error space gap */ 109 /* Error space gap */ 110 /* Error space gap */ 111 /** Memory allocation failed */ 112 #define MBEDTLS_ERR_SSL_ALLOC_FAILED -0x7F00 113 /** Hardware acceleration function returned with error */ 114 #define MBEDTLS_ERR_SSL_HW_ACCEL_FAILED -0x7F80 115 /** Hardware acceleration function skipped / left alone data */ 116 #define MBEDTLS_ERR_SSL_HW_ACCEL_FALLTHROUGH -0x6F80 117 /** Handshake protocol not within min/max boundaries */ 118 #define MBEDTLS_ERR_SSL_BAD_PROTOCOL_VERSION -0x6E80 119 /** The handshake negotiation failed. */ 120 #define MBEDTLS_ERR_SSL_HANDSHAKE_FAILURE -0x6E00 121 /** Session ticket has expired. */ 122 #define MBEDTLS_ERR_SSL_SESSION_TICKET_EXPIRED -0x6D80 123 /** Public key type mismatch (eg, asked for RSA key exchange and presented EC key) */ 124 #define MBEDTLS_ERR_SSL_PK_TYPE_MISMATCH -0x6D00 125 /** Unknown identity received (eg, PSK identity) */ 126 #define MBEDTLS_ERR_SSL_UNKNOWN_IDENTITY -0x6C80 127 /** Internal error (eg, unexpected failure in lower-level module) */ 128 #define MBEDTLS_ERR_SSL_INTERNAL_ERROR -0x6C00 129 /** A counter would wrap (eg, too many messages exchanged). */ 130 #define MBEDTLS_ERR_SSL_COUNTER_WRAPPING -0x6B80 131 /** Unexpected message at ServerHello in renegotiation. */ 132 #define MBEDTLS_ERR_SSL_WAITING_SERVER_HELLO_RENEGO -0x6B00 133 /** DTLS client must retry for hello verification */ 134 #define MBEDTLS_ERR_SSL_HELLO_VERIFY_REQUIRED -0x6A80 135 /** A buffer is too small to receive or write a message */ 136 #define MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL -0x6A00 137 /* Error space gap */ 138 /** No data of requested type currently available on underlying transport. */ 139 #define MBEDTLS_ERR_SSL_WANT_READ -0x6900 140 /** Connection requires a write call. */ 141 #define MBEDTLS_ERR_SSL_WANT_WRITE -0x6880 142 /** The operation timed out. */ 143 #define MBEDTLS_ERR_SSL_TIMEOUT -0x6800 144 /** The client initiated a reconnect from the same port. */ 145 #define MBEDTLS_ERR_SSL_CLIENT_RECONNECT -0x6780 146 /** Record header looks valid but is not expected. */ 147 #define MBEDTLS_ERR_SSL_UNEXPECTED_RECORD -0x6700 148 /** The alert message received indicates a non-fatal error. */ 149 #define MBEDTLS_ERR_SSL_NON_FATAL -0x6680 150 /** A field in a message was incorrect or inconsistent with other fields. */ 151 #define MBEDTLS_ERR_SSL_ILLEGAL_PARAMETER -0x6600 152 /** Internal-only message signaling that further message-processing should be done */ 153 #define MBEDTLS_ERR_SSL_CONTINUE_PROCESSING -0x6580 154 /** The asynchronous operation is not completed yet. */ 155 #define MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS -0x6500 156 /** Internal-only message signaling that a message arrived early. */ 157 #define MBEDTLS_ERR_SSL_EARLY_MESSAGE -0x6480 158 /* Error space gap */ 159 /* Error space gap */ 160 /* Error space gap */ 161 /* Error space gap */ 162 /* Error space gap */ 163 /* Error space gap */ 164 /* Error space gap */ 165 /* Error space gap */ 166 /** An encrypted DTLS-frame with an unexpected CID was received. */ 167 #define MBEDTLS_ERR_SSL_UNEXPECTED_CID -0x6000 168 /** An operation failed due to an unexpected version or configuration. */ 169 #define MBEDTLS_ERR_SSL_VERSION_MISMATCH -0x5F00 170 /** Invalid value in SSL config */ 171 #define MBEDTLS_ERR_SSL_BAD_CONFIG -0x5E80 172 173 /* 174 * TLS 1.3 NamedGroup values 175 * 176 * From RF 8446 177 * enum { 178 * // Elliptic Curve Groups (ECDHE) 179 * secp256r1(0x0017), secp384r1(0x0018), secp521r1(0x0019), 180 * x25519(0x001D), x448(0x001E), 181 * // Finite Field Groups (DHE) 182 * ffdhe2048(0x0100), ffdhe3072(0x0101), ffdhe4096(0x0102), 183 * ffdhe6144(0x0103), ffdhe8192(0x0104), 184 * // Reserved Code Points 185 * ffdhe_private_use(0x01FC..0x01FF), 186 * ecdhe_private_use(0xFE00..0xFEFF), 187 * (0xFFFF) 188 * } NamedGroup; 189 * 190 */ 191 192 /* Elliptic Curve Groups (ECDHE) */ 193 #define MBEDTLS_SSL_IANA_TLS_GROUP_NONE 0 194 #define MBEDTLS_SSL_IANA_TLS_GROUP_SECP192K1 0x0012 195 #define MBEDTLS_SSL_IANA_TLS_GROUP_SECP192R1 0x0013 196 #define MBEDTLS_SSL_IANA_TLS_GROUP_SECP224K1 0x0014 197 #define MBEDTLS_SSL_IANA_TLS_GROUP_SECP224R1 0x0015 198 #define MBEDTLS_SSL_IANA_TLS_GROUP_SECP256K1 0x0016 199 #define MBEDTLS_SSL_IANA_TLS_GROUP_SECP256R1 0x0017 200 #define MBEDTLS_SSL_IANA_TLS_GROUP_SECP384R1 0x0018 201 #define MBEDTLS_SSL_IANA_TLS_GROUP_SECP521R1 0x0019 202 #define MBEDTLS_SSL_IANA_TLS_GROUP_BP256R1 0x001A 203 #define MBEDTLS_SSL_IANA_TLS_GROUP_BP384R1 0x001B 204 #define MBEDTLS_SSL_IANA_TLS_GROUP_BP512R1 0x001C 205 #define MBEDTLS_SSL_IANA_TLS_GROUP_X25519 0x001D 206 #define MBEDTLS_SSL_IANA_TLS_GROUP_X448 0x001E 207 /* Finite Field Groups (DHE) */ 208 #define MBEDTLS_SSL_IANA_TLS_GROUP_FFDHE2048 0x0100 209 #define MBEDTLS_SSL_IANA_TLS_GROUP_FFDHE3072 0x0101 210 #define MBEDTLS_SSL_IANA_TLS_GROUP_FFDHE4096 0x0102 211 #define MBEDTLS_SSL_IANA_TLS_GROUP_FFDHE6144 0x0103 212 #define MBEDTLS_SSL_IANA_TLS_GROUP_FFDHE8192 0x0104 213 214 /* 215 * TLS 1.3 Key Exchange Modes 216 * 217 * Mbed TLS internal identifiers for use with the SSL configuration API 218 * mbedtls_ssl_conf_tls13_key_exchange_modes(). 219 */ 220 221 #define MBEDTLS_SSL_TLS13_KEY_EXCHANGE_MODE_PSK ( 1u << 0 ) /*!< Pure-PSK TLS 1.3 key exchange, 222 * encompassing both externally agreed PSKs 223 * as well as resumption PSKs. */ 224 #define MBEDTLS_SSL_TLS13_KEY_EXCHANGE_MODE_EPHEMERAL ( 1u << 1 ) /*!< Pure-Ephemeral TLS 1.3 key exchanges, 225 * including for example ECDHE and DHE 226 * key exchanges. */ 227 #define MBEDTLS_SSL_TLS13_KEY_EXCHANGE_MODE_PSK_EPHEMERAL ( 1u << 2 ) /*!< PSK-Ephemeral TLS 1.3 key exchanges, 228 * using both a PSK and an ephemeral 229 * key exchange. */ 230 231 /* Convenience macros for sets of key exchanges. */ 232 #define MBEDTLS_SSL_TLS13_KEY_EXCHANGE_MODE_ALL \ 233 ( MBEDTLS_SSL_TLS13_KEY_EXCHANGE_MODE_PSK | \ 234 MBEDTLS_SSL_TLS13_KEY_EXCHANGE_MODE_PSK_EPHEMERAL | \ 235 MBEDTLS_SSL_TLS13_KEY_EXCHANGE_MODE_EPHEMERAL ) /*!< All TLS 1.3 key exchanges */ 236 #define MBEDTLS_SSL_TLS13_KEY_EXCHANGE_MODE_PSK_ALL \ 237 ( MBEDTLS_SSL_TLS13_KEY_EXCHANGE_MODE_PSK | \ 238 MBEDTLS_SSL_TLS13_KEY_EXCHANGE_MODE_PSK_EPHEMERAL ) /*!< All PSK-based TLS 1.3 key exchanges */ 239 #define MBEDTLS_SSL_TLS13_KEY_EXCHANGE_MODE_EPHEMERAL_ALL \ 240 ( MBEDTLS_SSL_TLS13_KEY_EXCHANGE_MODE_EPHEMERAL | \ 241 MBEDTLS_SSL_TLS13_KEY_EXCHANGE_MODE_PSK_EPHEMERAL ) /*!< All ephemeral TLS 1.3 key exchanges */ 242 243 /* 244 * Various constants 245 */ 246 247 /* These are the high an low bytes of ProtocolVersion as defined by: 248 * - RFC 5246: ProtocolVersion version = { 3, 3 }; // TLS v1.2 249 * - RFC 8446: see section 4.2.1 250 */ 251 #define MBEDTLS_SSL_MAJOR_VERSION_3 3 252 #define MBEDTLS_SSL_MINOR_VERSION_3 3 /*!< TLS v1.2 */ 253 #define MBEDTLS_SSL_MINOR_VERSION_4 4 /*!< TLS v1.3 (experimental) */ 254 255 #define MBEDTLS_SSL_TRANSPORT_STREAM 0 /*!< TLS */ 256 #define MBEDTLS_SSL_TRANSPORT_DATAGRAM 1 /*!< DTLS */ 257 258 #define MBEDTLS_SSL_MAX_HOST_NAME_LEN 255 /*!< Maximum host name defined in RFC 1035 */ 259 #define MBEDTLS_SSL_MAX_ALPN_NAME_LEN 255 /*!< Maximum size in bytes of a protocol name in alpn ext., RFC 7301 */ 260 261 #define MBEDTLS_SSL_MAX_ALPN_LIST_LEN 65535 /*!< Maximum size in bytes of list in alpn ext., RFC 7301 */ 262 263 /* RFC 6066 section 4, see also mfl_code_to_length in ssl_tls.c 264 * NONE must be zero so that memset()ing structure to zero works */ 265 #define MBEDTLS_SSL_MAX_FRAG_LEN_NONE 0 /*!< don't use this extension */ 266 #define MBEDTLS_SSL_MAX_FRAG_LEN_512 1 /*!< MaxFragmentLength 2^9 */ 267 #define MBEDTLS_SSL_MAX_FRAG_LEN_1024 2 /*!< MaxFragmentLength 2^10 */ 268 #define MBEDTLS_SSL_MAX_FRAG_LEN_2048 3 /*!< MaxFragmentLength 2^11 */ 269 #define MBEDTLS_SSL_MAX_FRAG_LEN_4096 4 /*!< MaxFragmentLength 2^12 */ 270 #define MBEDTLS_SSL_MAX_FRAG_LEN_INVALID 5 /*!< first invalid value */ 271 272 #define MBEDTLS_SSL_IS_CLIENT 0 273 #define MBEDTLS_SSL_IS_SERVER 1 274 275 #define MBEDTLS_SSL_EXTENDED_MS_DISABLED 0 276 #define MBEDTLS_SSL_EXTENDED_MS_ENABLED 1 277 278 #define MBEDTLS_SSL_CID_DISABLED 0 279 #define MBEDTLS_SSL_CID_ENABLED 1 280 281 #define MBEDTLS_SSL_ETM_DISABLED 0 282 #define MBEDTLS_SSL_ETM_ENABLED 1 283 284 #define MBEDTLS_SSL_COMPRESS_NULL 0 285 286 #define MBEDTLS_SSL_VERIFY_NONE 0 287 #define MBEDTLS_SSL_VERIFY_OPTIONAL 1 288 #define MBEDTLS_SSL_VERIFY_REQUIRED 2 289 #define MBEDTLS_SSL_VERIFY_UNSET 3 /* Used only for sni_authmode */ 290 291 #define MBEDTLS_SSL_LEGACY_RENEGOTIATION 0 292 #define MBEDTLS_SSL_SECURE_RENEGOTIATION 1 293 294 #define MBEDTLS_SSL_RENEGOTIATION_DISABLED 0 295 #define MBEDTLS_SSL_RENEGOTIATION_ENABLED 1 296 297 #define MBEDTLS_SSL_ANTI_REPLAY_DISABLED 0 298 #define MBEDTLS_SSL_ANTI_REPLAY_ENABLED 1 299 300 #define MBEDTLS_SSL_RENEGOTIATION_NOT_ENFORCED -1 301 #define MBEDTLS_SSL_RENEGO_MAX_RECORDS_DEFAULT 16 302 303 #define MBEDTLS_SSL_LEGACY_NO_RENEGOTIATION 0 304 #define MBEDTLS_SSL_LEGACY_ALLOW_RENEGOTIATION 1 305 #define MBEDTLS_SSL_LEGACY_BREAK_HANDSHAKE 2 306 307 #define MBEDTLS_SSL_TRUNC_HMAC_DISABLED 0 308 #define MBEDTLS_SSL_TRUNC_HMAC_ENABLED 1 309 #define MBEDTLS_SSL_TRUNCATED_HMAC_LEN 10 /* 80 bits, rfc 6066 section 7 */ 310 311 #define MBEDTLS_SSL_SESSION_TICKETS_DISABLED 0 312 #define MBEDTLS_SSL_SESSION_TICKETS_ENABLED 1 313 314 #define MBEDTLS_SSL_PRESET_DEFAULT 0 315 #define MBEDTLS_SSL_PRESET_SUITEB 2 316 317 #define MBEDTLS_SSL_CERT_REQ_CA_LIST_ENABLED 1 318 #define MBEDTLS_SSL_CERT_REQ_CA_LIST_DISABLED 0 319 320 #define MBEDTLS_SSL_DTLS_SRTP_MKI_UNSUPPORTED 0 321 #define MBEDTLS_SSL_DTLS_SRTP_MKI_SUPPORTED 1 322 323 #define MBEDTLS_SSL_SRV_CIPHERSUITE_ORDER_CLIENT 1 324 #define MBEDTLS_SSL_SRV_CIPHERSUITE_ORDER_SERVER 0 325 326 /* 327 * Default range for DTLS retransmission timer value, in milliseconds. 328 * RFC 6347 4.2.4.1 says from 1 second to 60 seconds. 329 */ 330 #define MBEDTLS_SSL_DTLS_TIMEOUT_DFL_MIN 1000 331 #define MBEDTLS_SSL_DTLS_TIMEOUT_DFL_MAX 60000 332 333 /** 334 * \name SECTION: Module settings 335 * 336 * The configuration options you can set for this module are in this section. 337 * Either change them in mbedtls_config.h or define them on the compiler command line. 338 * \{ 339 */ 340 341 /* 342 * Maximum fragment length in bytes, 343 * determines the size of each of the two internal I/O buffers. 344 * 345 * Note: the RFC defines the default size of SSL / TLS messages. If you 346 * change the value here, other clients / servers may not be able to 347 * communicate with you anymore. Only change this value if you control 348 * both sides of the connection and have it reduced at both sides, or 349 * if you're using the Max Fragment Length extension and you know all your 350 * peers are using it too! 351 */ 352 #if !defined(MBEDTLS_SSL_IN_CONTENT_LEN) 353 #define MBEDTLS_SSL_IN_CONTENT_LEN 16384 354 #endif 355 356 #if !defined(MBEDTLS_SSL_OUT_CONTENT_LEN) 357 #define MBEDTLS_SSL_OUT_CONTENT_LEN 16384 358 #endif 359 360 /* 361 * Maximum number of heap-allocated bytes for the purpose of 362 * DTLS handshake message reassembly and future message buffering. 363 */ 364 #if !defined(MBEDTLS_SSL_DTLS_MAX_BUFFERING) 365 #define MBEDTLS_SSL_DTLS_MAX_BUFFERING 32768 366 #endif 367 368 /* 369 * Maximum length of CIDs for incoming and outgoing messages. 370 */ 371 #if !defined(MBEDTLS_SSL_CID_IN_LEN_MAX) 372 #define MBEDTLS_SSL_CID_IN_LEN_MAX 32 373 #endif 374 375 #if !defined(MBEDTLS_SSL_CID_OUT_LEN_MAX) 376 #define MBEDTLS_SSL_CID_OUT_LEN_MAX 32 377 #endif 378 379 #if !defined(MBEDTLS_SSL_CID_TLS1_3_PADDING_GRANULARITY) 380 #define MBEDTLS_SSL_CID_TLS1_3_PADDING_GRANULARITY 16 381 #endif 382 383 /* \} name SECTION: Module settings */ 384 385 /* 386 * Length of the verify data for secure renegotiation 387 */ 388 #define MBEDTLS_SSL_VERIFY_DATA_MAX_LEN 12 389 390 /* 391 * Signaling ciphersuite values (SCSV) 392 */ 393 #define MBEDTLS_SSL_EMPTY_RENEGOTIATION_INFO 0xFF /**< renegotiation info ext */ 394 395 /* 396 * Supported Signature and Hash algorithms (For TLS 1.2) 397 * RFC 5246 section 7.4.1.4.1 398 */ 399 #define MBEDTLS_SSL_HASH_NONE 0 400 #define MBEDTLS_SSL_HASH_MD5 1 401 #define MBEDTLS_SSL_HASH_SHA1 2 402 #define MBEDTLS_SSL_HASH_SHA224 3 403 #define MBEDTLS_SSL_HASH_SHA256 4 404 #define MBEDTLS_SSL_HASH_SHA384 5 405 #define MBEDTLS_SSL_HASH_SHA512 6 406 407 #define MBEDTLS_SSL_SIG_ANON 0 408 #define MBEDTLS_SSL_SIG_RSA 1 409 #define MBEDTLS_SSL_SIG_ECDSA 3 410 411 /* 412 * TLS 1.3 signature algorithms 413 * RFC 8446, Section 4.2.2 414 */ 415 416 /* RSASSA-PKCS1-v1_5 algorithms */ 417 #define MBEDTLS_TLS13_SIG_RSA_PKCS1_SHA256 0x0401 418 #define MBEDTLS_TLS13_SIG_RSA_PKCS1_SHA384 0x0501 419 #define MBEDTLS_TLS13_SIG_RSA_PKCS1_SHA512 0x0601 420 421 /* ECDSA algorithms */ 422 #define MBEDTLS_TLS13_SIG_ECDSA_SECP256R1_SHA256 0x0403 423 #define MBEDTLS_TLS13_SIG_ECDSA_SECP384R1_SHA384 0x0503 424 #define MBEDTLS_TLS13_SIG_ECDSA_SECP521R1_SHA512 0x0603 425 426 /* RSASSA-PSS algorithms with public key OID rsaEncryption */ 427 #define MBEDTLS_TLS13_SIG_RSA_PSS_RSAE_SHA256 0x0804 428 #define MBEDTLS_TLS13_SIG_RSA_PSS_RSAE_SHA384 0x0805 429 #define MBEDTLS_TLS13_SIG_RSA_PSS_RSAE_SHA512 0x0806 430 431 /* EdDSA algorithms */ 432 #define MBEDTLS_TLS13_SIG_ED25519 0x0807 433 #define MBEDTLS_TLS13_SIG_ED448 0x0808 434 435 /* RSASSA-PSS algorithms with public key OID RSASSA-PSS */ 436 #define MBEDTLS_TLS13_SIG_RSA_PSS_PSS_SHA256 0x0809 437 #define MBEDTLS_TLS13_SIG_RSA_PSS_PSS_SHA384 0x080A 438 #define MBEDTLS_TLS13_SIG_RSA_PSS_PSS_SHA512 0x080B 439 440 /* LEGACY ALGORITHMS */ 441 #define MBEDTLS_TLS13_SIG_RSA_PKCS1_SHA1 0x0201 442 #define MBEDTLS_TLS13_SIG_ECDSA_SHA1 0x0203 443 444 #define MBEDTLS_TLS13_SIG_NONE 0x0 445 446 /* 447 * Client Certificate Types 448 * RFC 5246 section 7.4.4 plus RFC 4492 section 5.5 449 */ 450 #define MBEDTLS_SSL_CERT_TYPE_RSA_SIGN 1 451 #define MBEDTLS_SSL_CERT_TYPE_ECDSA_SIGN 64 452 453 /* 454 * Message, alert and handshake types 455 */ 456 #define MBEDTLS_SSL_MSG_CHANGE_CIPHER_SPEC 20 457 #define MBEDTLS_SSL_MSG_ALERT 21 458 #define MBEDTLS_SSL_MSG_HANDSHAKE 22 459 #define MBEDTLS_SSL_MSG_APPLICATION_DATA 23 460 #define MBEDTLS_SSL_MSG_CID 25 461 462 #define MBEDTLS_SSL_ALERT_LEVEL_WARNING 1 463 #define MBEDTLS_SSL_ALERT_LEVEL_FATAL 2 464 465 #define MBEDTLS_SSL_ALERT_MSG_CLOSE_NOTIFY 0 /* 0x00 */ 466 #define MBEDTLS_SSL_ALERT_MSG_UNEXPECTED_MESSAGE 10 /* 0x0A */ 467 #define MBEDTLS_SSL_ALERT_MSG_BAD_RECORD_MAC 20 /* 0x14 */ 468 #define MBEDTLS_SSL_ALERT_MSG_DECRYPTION_FAILED 21 /* 0x15 */ 469 #define MBEDTLS_SSL_ALERT_MSG_RECORD_OVERFLOW 22 /* 0x16 */ 470 #define MBEDTLS_SSL_ALERT_MSG_DECOMPRESSION_FAILURE 30 /* 0x1E */ 471 #define MBEDTLS_SSL_ALERT_MSG_HANDSHAKE_FAILURE 40 /* 0x28 */ 472 #define MBEDTLS_SSL_ALERT_MSG_NO_CERT 41 /* 0x29 */ 473 #define MBEDTLS_SSL_ALERT_MSG_BAD_CERT 42 /* 0x2A */ 474 #define MBEDTLS_SSL_ALERT_MSG_UNSUPPORTED_CERT 43 /* 0x2B */ 475 #define MBEDTLS_SSL_ALERT_MSG_CERT_REVOKED 44 /* 0x2C */ 476 #define MBEDTLS_SSL_ALERT_MSG_CERT_EXPIRED 45 /* 0x2D */ 477 #define MBEDTLS_SSL_ALERT_MSG_CERT_UNKNOWN 46 /* 0x2E */ 478 #define MBEDTLS_SSL_ALERT_MSG_ILLEGAL_PARAMETER 47 /* 0x2F */ 479 #define MBEDTLS_SSL_ALERT_MSG_UNKNOWN_CA 48 /* 0x30 */ 480 #define MBEDTLS_SSL_ALERT_MSG_ACCESS_DENIED 49 /* 0x31 */ 481 #define MBEDTLS_SSL_ALERT_MSG_DECODE_ERROR 50 /* 0x32 */ 482 #define MBEDTLS_SSL_ALERT_MSG_DECRYPT_ERROR 51 /* 0x33 */ 483 #define MBEDTLS_SSL_ALERT_MSG_EXPORT_RESTRICTION 60 /* 0x3C */ 484 #define MBEDTLS_SSL_ALERT_MSG_PROTOCOL_VERSION 70 /* 0x46 */ 485 #define MBEDTLS_SSL_ALERT_MSG_INSUFFICIENT_SECURITY 71 /* 0x47 */ 486 #define MBEDTLS_SSL_ALERT_MSG_INTERNAL_ERROR 80 /* 0x50 */ 487 #define MBEDTLS_SSL_ALERT_MSG_INAPROPRIATE_FALLBACK 86 /* 0x56 */ 488 #define MBEDTLS_SSL_ALERT_MSG_USER_CANCELED 90 /* 0x5A */ 489 #define MBEDTLS_SSL_ALERT_MSG_NO_RENEGOTIATION 100 /* 0x64 */ 490 #define MBEDTLS_SSL_ALERT_MSG_UNSUPPORTED_EXT 110 /* 0x6E */ 491 #define MBEDTLS_SSL_ALERT_MSG_UNRECOGNIZED_NAME 112 /* 0x70 */ 492 #define MBEDTLS_SSL_ALERT_MSG_UNKNOWN_PSK_IDENTITY 115 /* 0x73 */ 493 #define MBEDTLS_SSL_ALERT_MSG_NO_APPLICATION_PROTOCOL 120 /* 0x78 */ 494 495 #define MBEDTLS_SSL_HS_HELLO_REQUEST 0 496 #define MBEDTLS_SSL_HS_CLIENT_HELLO 1 497 #define MBEDTLS_SSL_HS_SERVER_HELLO 2 498 #define MBEDTLS_SSL_HS_HELLO_VERIFY_REQUEST 3 499 #define MBEDTLS_SSL_HS_NEW_SESSION_TICKET 4 500 #define MBEDTLS_SSL_HS_ENCRYPTED_EXTENSIONS 8 // NEW IN TLS 1.3 501 #define MBEDTLS_SSL_HS_CERTIFICATE 11 502 #define MBEDTLS_SSL_HS_SERVER_KEY_EXCHANGE 12 503 #define MBEDTLS_SSL_HS_CERTIFICATE_REQUEST 13 504 #define MBEDTLS_SSL_HS_SERVER_HELLO_DONE 14 505 #define MBEDTLS_SSL_HS_CERTIFICATE_VERIFY 15 506 #define MBEDTLS_SSL_HS_CLIENT_KEY_EXCHANGE 16 507 #define MBEDTLS_SSL_HS_FINISHED 20 508 509 /* 510 * TLS extensions 511 */ 512 #define MBEDTLS_TLS_EXT_SERVERNAME 0 513 #define MBEDTLS_TLS_EXT_SERVERNAME_HOSTNAME 0 514 515 #define MBEDTLS_TLS_EXT_MAX_FRAGMENT_LENGTH 1 516 517 #define MBEDTLS_TLS_EXT_TRUNCATED_HMAC 4 518 #define MBEDTLS_TLS_EXT_STATUS_REQUEST 5 /* RFC 6066 TLS 1.2 and 1.3 */ 519 520 #define MBEDTLS_TLS_EXT_SUPPORTED_ELLIPTIC_CURVES 10 521 #define MBEDTLS_TLS_EXT_SUPPORTED_GROUPS 10 /* RFC 8422,7919 TLS 1.2 and 1.3 */ 522 #define MBEDTLS_TLS_EXT_SUPPORTED_POINT_FORMATS 11 523 524 #define MBEDTLS_TLS_EXT_SIG_ALG 13 /* RFC 8446 TLS 1.3 */ 525 #define MBEDTLS_TLS_EXT_USE_SRTP 14 526 #define MBEDTLS_TLS_EXT_HEARTBEAT 15 /* RFC 6520 TLS 1.2 and 1.3 */ 527 #define MBEDTLS_TLS_EXT_ALPN 16 528 529 #define MBEDTLS_TLS_EXT_SCT 18 /* RFC 6962 TLS 1.2 and 1.3 */ 530 #define MBEDTLS_TLS_EXT_CLI_CERT_TYPE 19 /* RFC 7250 TLS 1.2 and 1.3 */ 531 #define MBEDTLS_TLS_EXT_SERV_CERT_TYPE 20 /* RFC 7250 TLS 1.2 and 1.3 */ 532 #define MBEDTLS_TLS_EXT_PADDING 21 /* RFC 7685 TLS 1.2 and 1.3 */ 533 #define MBEDTLS_TLS_EXT_ENCRYPT_THEN_MAC 22 /* 0x16 */ 534 #define MBEDTLS_TLS_EXT_EXTENDED_MASTER_SECRET 0x0017 /* 23 */ 535 536 #define MBEDTLS_TLS_EXT_SESSION_TICKET 35 537 538 #define MBEDTLS_TLS_EXT_PRE_SHARED_KEY 41 /* RFC 8446 TLS 1.3 */ 539 #define MBEDTLS_TLS_EXT_EARLY_DATA 42 /* RFC 8446 TLS 1.3 */ 540 #define MBEDTLS_TLS_EXT_SUPPORTED_VERSIONS 43 /* RFC 8446 TLS 1.3 */ 541 #define MBEDTLS_TLS_EXT_COOKIE 44 /* RFC 8446 TLS 1.3 */ 542 #define MBEDTLS_TLS_EXT_PSK_KEY_EXCHANGE_MODES 45 /* RFC 8446 TLS 1.3 */ 543 544 #define MBEDTLS_TLS_EXT_CERT_AUTH 47 /* RFC 8446 TLS 1.3 */ 545 #define MBEDTLS_TLS_EXT_OID_FILTERS 48 /* RFC 8446 TLS 1.3 */ 546 #define MBEDTLS_TLS_EXT_POST_HANDSHAKE_AUTH 49 /* RFC 8446 TLS 1.3 */ 547 #define MBEDTLS_TLS_EXT_SIG_ALG_CERT 50 /* RFC 8446 TLS 1.3 */ 548 #define MBEDTLS_TLS_EXT_KEY_SHARE 51 /* RFC 8446 TLS 1.3 */ 549 550 /* The value of the CID extension is still TBD as of 551 * draft-ietf-tls-dtls-connection-id-05 552 * (https://tools.ietf.org/html/draft-ietf-tls-dtls-connection-id-05). 553 * 554 * A future minor revision of Mbed TLS may change the default value of 555 * this option to match evolving standards and usage. 556 */ 557 #if !defined(MBEDTLS_TLS_EXT_CID) 558 #define MBEDTLS_TLS_EXT_CID 254 /* TBD */ 559 #endif 560 561 #define MBEDTLS_TLS_EXT_ECJPAKE_KKPP 256 /* experimental */ 562 563 #define MBEDTLS_TLS_EXT_RENEGOTIATION_INFO 0xFF01 564 565 /* 566 * Size defines 567 */ 568 #if !defined(MBEDTLS_PSK_MAX_LEN) 569 #define MBEDTLS_PSK_MAX_LEN 32 /* 256 bits */ 570 #endif 571 572 /* Dummy type used only for its size */ 573 union mbedtls_ssl_premaster_secret 574 { 575 #if defined(MBEDTLS_KEY_EXCHANGE_RSA_ENABLED) 576 unsigned char _pms_rsa[48]; /* RFC 5246 8.1.1 */ 577 #endif 578 #if defined(MBEDTLS_KEY_EXCHANGE_DHE_RSA_ENABLED) 579 unsigned char _pms_dhm[MBEDTLS_MPI_MAX_SIZE]; /* RFC 5246 8.1.2 */ 580 #endif 581 #if defined(MBEDTLS_KEY_EXCHANGE_ECDHE_RSA_ENABLED) || \ 582 defined(MBEDTLS_KEY_EXCHANGE_ECDHE_ECDSA_ENABLED) || \ 583 defined(MBEDTLS_KEY_EXCHANGE_ECDH_RSA_ENABLED) || \ 584 defined(MBEDTLS_KEY_EXCHANGE_ECDH_ECDSA_ENABLED) 585 unsigned char _pms_ecdh[MBEDTLS_ECP_MAX_BYTES]; /* RFC 4492 5.10 */ 586 #endif 587 #if defined(MBEDTLS_KEY_EXCHANGE_PSK_ENABLED) 588 unsigned char _pms_psk[4 + 2 * MBEDTLS_PSK_MAX_LEN]; /* RFC 4279 2 */ 589 #endif 590 #if defined(MBEDTLS_KEY_EXCHANGE_DHE_PSK_ENABLED) 591 unsigned char _pms_dhe_psk[4 + MBEDTLS_MPI_MAX_SIZE 592 + MBEDTLS_PSK_MAX_LEN]; /* RFC 4279 3 */ 593 #endif 594 #if defined(MBEDTLS_KEY_EXCHANGE_RSA_PSK_ENABLED) 595 unsigned char _pms_rsa_psk[52 + MBEDTLS_PSK_MAX_LEN]; /* RFC 4279 4 */ 596 #endif 597 #if defined(MBEDTLS_KEY_EXCHANGE_ECDHE_PSK_ENABLED) 598 unsigned char _pms_ecdhe_psk[4 + MBEDTLS_ECP_MAX_BYTES 599 + MBEDTLS_PSK_MAX_LEN]; /* RFC 5489 2 */ 600 #endif 601 #if defined(MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED) 602 unsigned char _pms_ecjpake[32]; /* Thread spec: SHA-256 output */ 603 #endif 604 }; 605 606 #define MBEDTLS_PREMASTER_SIZE sizeof( union mbedtls_ssl_premaster_secret ) 607 608 #define MBEDTLS_TLS1_3_MD_MAX_SIZE MBEDTLS_MD_MAX_SIZE 609 610 /* Length in number of bytes of the TLS sequence number */ 611 #define MBEDTLS_SSL_SEQUENCE_NUMBER_LEN 8 612 613 #ifdef __cplusplus 614 extern "C" { 615 #endif 616 617 /* 618 * SSL state machine 619 */ 620 typedef enum 621 { 622 MBEDTLS_SSL_HELLO_REQUEST, 623 MBEDTLS_SSL_CLIENT_HELLO, 624 MBEDTLS_SSL_SERVER_HELLO, 625 MBEDTLS_SSL_SERVER_CERTIFICATE, 626 MBEDTLS_SSL_SERVER_KEY_EXCHANGE, 627 MBEDTLS_SSL_CERTIFICATE_REQUEST, 628 MBEDTLS_SSL_SERVER_HELLO_DONE, 629 MBEDTLS_SSL_CLIENT_CERTIFICATE, 630 MBEDTLS_SSL_CLIENT_KEY_EXCHANGE, 631 MBEDTLS_SSL_CERTIFICATE_VERIFY, 632 MBEDTLS_SSL_CLIENT_CHANGE_CIPHER_SPEC, 633 MBEDTLS_SSL_CLIENT_FINISHED, 634 MBEDTLS_SSL_SERVER_CHANGE_CIPHER_SPEC, 635 MBEDTLS_SSL_SERVER_FINISHED, 636 MBEDTLS_SSL_FLUSH_BUFFERS, 637 MBEDTLS_SSL_HANDSHAKE_WRAPUP, 638 MBEDTLS_SSL_HANDSHAKE_OVER, 639 MBEDTLS_SSL_SERVER_NEW_SESSION_TICKET, 640 MBEDTLS_SSL_SERVER_HELLO_VERIFY_REQUEST_SENT, 641 #if defined(MBEDTLS_SSL_PROTO_TLS1_3_EXPERIMENTAL) 642 MBEDTLS_SSL_ENCRYPTED_EXTENSIONS, 643 MBEDTLS_SSL_CLIENT_CERTIFICATE_VERIFY, 644 #endif /* MBEDTLS_SSL_PROTO_TLS1_3_EXPERIMENTAL */ 645 } 646 mbedtls_ssl_states; 647 648 /** 649 * \brief Callback type: send data on the network. 650 * 651 * \note That callback may be either blocking or non-blocking. 652 * 653 * \param ctx Context for the send callback (typically a file descriptor) 654 * \param buf Buffer holding the data to send 655 * \param len Length of the data to send 656 * 657 * \return The callback must return the number of bytes sent if any, 658 * or a non-zero error code. 659 * If performing non-blocking I/O, \c MBEDTLS_ERR_SSL_WANT_WRITE 660 * must be returned when the operation would block. 661 * 662 * \note The callback is allowed to send fewer bytes than requested. 663 * It must always return the number of bytes actually sent. 664 */ 665 typedef int mbedtls_ssl_send_t( void *ctx, 666 const unsigned char *buf, 667 size_t len ); 668 669 /** 670 * \brief Callback type: receive data from the network. 671 * 672 * \note That callback may be either blocking or non-blocking. 673 * 674 * \param ctx Context for the receive callback (typically a file 675 * descriptor) 676 * \param buf Buffer to write the received data to 677 * \param len Length of the receive buffer 678 * 679 * \returns If data has been received, the positive number of bytes received. 680 * \returns \c 0 if the connection has been closed. 681 * \returns If performing non-blocking I/O, \c MBEDTLS_ERR_SSL_WANT_READ 682 * must be returned when the operation would block. 683 * \returns Another negative error code on other kinds of failures. 684 * 685 * \note The callback may receive fewer bytes than the length of the 686 * buffer. It must always return the number of bytes actually 687 * received and written to the buffer. 688 */ 689 typedef int mbedtls_ssl_recv_t( void *ctx, 690 unsigned char *buf, 691 size_t len ); 692 693 /** 694 * \brief Callback type: receive data from the network, with timeout 695 * 696 * \note That callback must block until data is received, or the 697 * timeout delay expires, or the operation is interrupted by a 698 * signal. 699 * 700 * \param ctx Context for the receive callback (typically a file descriptor) 701 * \param buf Buffer to write the received data to 702 * \param len Length of the receive buffer 703 * \param timeout Maximum number of milliseconds to wait for data 704 * 0 means no timeout (potentially waiting forever) 705 * 706 * \return The callback must return the number of bytes received, 707 * or a non-zero error code: 708 * \c MBEDTLS_ERR_SSL_TIMEOUT if the operation timed out, 709 * \c MBEDTLS_ERR_SSL_WANT_READ if interrupted by a signal. 710 * 711 * \note The callback may receive fewer bytes than the length of the 712 * buffer. It must always return the number of bytes actually 713 * received and written to the buffer. 714 */ 715 typedef int mbedtls_ssl_recv_timeout_t( void *ctx, 716 unsigned char *buf, 717 size_t len, 718 uint32_t timeout ); 719 /** 720 * \brief Callback type: set a pair of timers/delays to watch 721 * 722 * \param ctx Context pointer 723 * \param int_ms Intermediate delay in milliseconds 724 * \param fin_ms Final delay in milliseconds 725 * 0 cancels the current timer. 726 * 727 * \note This callback must at least store the necessary information 728 * for the associated \c mbedtls_ssl_get_timer_t callback to 729 * return correct information. 730 * 731 * \note If using a event-driven style of programming, an event must 732 * be generated when the final delay is passed. The event must 733 * cause a call to \c mbedtls_ssl_handshake() with the proper 734 * SSL context to be scheduled. Care must be taken to ensure 735 * that at most one such call happens at a time. 736 * 737 * \note Only one timer at a time must be running. Calling this 738 * function while a timer is running must cancel it. Cancelled 739 * timers must not generate any event. 740 */ 741 typedef void mbedtls_ssl_set_timer_t( void * ctx, 742 uint32_t int_ms, 743 uint32_t fin_ms ); 744 745 /** 746 * \brief Callback type: get status of timers/delays 747 * 748 * \param ctx Context pointer 749 * 750 * \return This callback must return: 751 * -1 if cancelled (fin_ms == 0), 752 * 0 if none of the delays have passed, 753 * 1 if only the intermediate delay has passed, 754 * 2 if the final delay has passed. 755 */ 756 typedef int mbedtls_ssl_get_timer_t( void * ctx ); 757 758 /* Defined below */ 759 typedef struct mbedtls_ssl_session mbedtls_ssl_session; 760 typedef struct mbedtls_ssl_context mbedtls_ssl_context; 761 typedef struct mbedtls_ssl_config mbedtls_ssl_config; 762 763 /* Defined in library/ssl_misc.h */ 764 typedef struct mbedtls_ssl_transform mbedtls_ssl_transform; 765 typedef struct mbedtls_ssl_handshake_params mbedtls_ssl_handshake_params; 766 typedef struct mbedtls_ssl_sig_hash_set_t mbedtls_ssl_sig_hash_set_t; 767 #if defined(MBEDTLS_X509_CRT_PARSE_C) 768 typedef struct mbedtls_ssl_key_cert mbedtls_ssl_key_cert; 769 #endif 770 #if defined(MBEDTLS_SSL_PROTO_DTLS) 771 typedef struct mbedtls_ssl_flight_item mbedtls_ssl_flight_item; 772 #endif 773 774 /** 775 * \brief Callback type: server-side session cache getter 776 * 777 * The session cache is logically a key value store, with 778 * keys being session IDs and values being instances of 779 * mbedtls_ssl_session. 780 * 781 * This callback retrieves an entry in this key-value store. 782 * 783 * \param data The address of the session cache structure to query. 784 * \param session_id The buffer holding the session ID to query. 785 * \param session_id_len The length of \p session_id in Bytes. 786 * \param session The address of the session structure to populate. 787 * It is initialized with mbdtls_ssl_session_init(), 788 * and the callback must always leave it in a state 789 * where it can safely be freed via 790 * mbedtls_ssl_session_free() independent of the 791 * return code of this function. 792 * 793 * \return \c 0 on success 794 * \return A non-zero return value on failure. 795 * 796 */ 797 typedef int mbedtls_ssl_cache_get_t( void *data, 798 unsigned char const *session_id, 799 size_t session_id_len, 800 mbedtls_ssl_session *session ); 801 /** 802 * \brief Callback type: server-side session cache setter 803 * 804 * The session cache is logically a key value store, with 805 * keys being session IDs and values being instances of 806 * mbedtls_ssl_session. 807 * 808 * This callback sets an entry in this key-value store. 809 * 810 * \param data The address of the session cache structure to modify. 811 * \param session_id The buffer holding the session ID to query. 812 * \param session_id_len The length of \p session_id in Bytes. 813 * \param session The address of the session to be stored in the 814 * session cache. 815 * 816 * \return \c 0 on success 817 * \return A non-zero return value on failure. 818 */ 819 typedef int mbedtls_ssl_cache_set_t( void *data, 820 unsigned char const *session_id, 821 size_t session_id_len, 822 const mbedtls_ssl_session *session ); 823 824 #if defined(MBEDTLS_SSL_ASYNC_PRIVATE) 825 #if defined(MBEDTLS_X509_CRT_PARSE_C) 826 /** 827 * \brief Callback type: start external signature operation. 828 * 829 * This callback is called during an SSL handshake to start 830 * a signature decryption operation using an 831 * external processor. The parameter \p cert contains 832 * the public key; it is up to the callback function to 833 * determine how to access the associated private key. 834 * 835 * This function typically sends or enqueues a request, and 836 * does not wait for the operation to complete. This allows 837 * the handshake step to be non-blocking. 838 * 839 * The parameters \p ssl and \p cert are guaranteed to remain 840 * valid throughout the handshake. On the other hand, this 841 * function must save the contents of \p hash if the value 842 * is needed for later processing, because the \p hash buffer 843 * is no longer valid after this function returns. 844 * 845 * This function may call mbedtls_ssl_set_async_operation_data() 846 * to store an operation context for later retrieval 847 * by the resume or cancel callback. 848 * 849 * \note For RSA signatures, this function must produce output 850 * that is consistent with PKCS#1 v1.5 in the same way as 851 * mbedtls_rsa_pkcs1_sign(). Before the private key operation, 852 * apply the padding steps described in RFC 8017, section 9.2 853 * "EMSA-PKCS1-v1_5" as follows. 854 * - If \p md_alg is #MBEDTLS_MD_NONE, apply the PKCS#1 v1.5 855 * encoding, treating \p hash as the DigestInfo to be 856 * padded. In other words, apply EMSA-PKCS1-v1_5 starting 857 * from step 3, with `T = hash` and `tLen = hash_len`. 858 * - If `md_alg != MBEDTLS_MD_NONE`, apply the PKCS#1 v1.5 859 * encoding, treating \p hash as the hash to be encoded and 860 * padded. In other words, apply EMSA-PKCS1-v1_5 starting 861 * from step 2, with `digestAlgorithm` obtained by calling 862 * mbedtls_oid_get_oid_by_md() on \p md_alg. 863 * 864 * \note For ECDSA signatures, the output format is the DER encoding 865 * `Ecdsa-Sig-Value` defined in 866 * [RFC 4492 section 5.4](https://tools.ietf.org/html/rfc4492#section-5.4). 867 * 868 * \param ssl The SSL connection instance. It should not be 869 * modified other than via 870 * mbedtls_ssl_set_async_operation_data(). 871 * \param cert Certificate containing the public key. 872 * In simple cases, this is one of the pointers passed to 873 * mbedtls_ssl_conf_own_cert() when configuring the SSL 874 * connection. However, if other callbacks are used, this 875 * property may not hold. For example, if an SNI callback 876 * is registered with mbedtls_ssl_conf_sni(), then 877 * this callback determines what certificate is used. 878 * \param md_alg Hash algorithm. 879 * \param hash Buffer containing the hash. This buffer is 880 * no longer valid when the function returns. 881 * \param hash_len Size of the \c hash buffer in bytes. 882 * 883 * \return 0 if the operation was started successfully and the SSL 884 * stack should call the resume callback immediately. 885 * \return #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS if the operation 886 * was started successfully and the SSL stack should return 887 * immediately without calling the resume callback yet. 888 * \return #MBEDTLS_ERR_SSL_HW_ACCEL_FALLTHROUGH if the external 889 * processor does not support this key. The SSL stack will 890 * use the private key object instead. 891 * \return Any other error indicates a fatal failure and is 892 * propagated up the call chain. The callback should 893 * use \c MBEDTLS_ERR_PK_xxx error codes, and <b>must not</b> 894 * use \c MBEDTLS_ERR_SSL_xxx error codes except as 895 * directed in the documentation of this callback. 896 */ 897 typedef int mbedtls_ssl_async_sign_t( mbedtls_ssl_context *ssl, 898 mbedtls_x509_crt *cert, 899 mbedtls_md_type_t md_alg, 900 const unsigned char *hash, 901 size_t hash_len ); 902 903 /** 904 * \brief Callback type: start external decryption operation. 905 * 906 * This callback is called during an SSL handshake to start 907 * an RSA decryption operation using an 908 * external processor. The parameter \p cert contains 909 * the public key; it is up to the callback function to 910 * determine how to access the associated private key. 911 * 912 * This function typically sends or enqueues a request, and 913 * does not wait for the operation to complete. This allows 914 * the handshake step to be non-blocking. 915 * 916 * The parameters \p ssl and \p cert are guaranteed to remain 917 * valid throughout the handshake. On the other hand, this 918 * function must save the contents of \p input if the value 919 * is needed for later processing, because the \p input buffer 920 * is no longer valid after this function returns. 921 * 922 * This function may call mbedtls_ssl_set_async_operation_data() 923 * to store an operation context for later retrieval 924 * by the resume or cancel callback. 925 * 926 * \warning RSA decryption as used in TLS is subject to a potential 927 * timing side channel attack first discovered by Bleichenbacher 928 * in 1998. This attack can be remotely exploitable 929 * in practice. To avoid this attack, you must ensure that 930 * if the callback performs an RSA decryption, the time it 931 * takes to execute and return the result does not depend 932 * on whether the RSA decryption succeeded or reported 933 * invalid padding. 934 * 935 * \param ssl The SSL connection instance. It should not be 936 * modified other than via 937 * mbedtls_ssl_set_async_operation_data(). 938 * \param cert Certificate containing the public key. 939 * In simple cases, this is one of the pointers passed to 940 * mbedtls_ssl_conf_own_cert() when configuring the SSL 941 * connection. However, if other callbacks are used, this 942 * property may not hold. For example, if an SNI callback 943 * is registered with mbedtls_ssl_conf_sni(), then 944 * this callback determines what certificate is used. 945 * \param input Buffer containing the input ciphertext. This buffer 946 * is no longer valid when the function returns. 947 * \param input_len Size of the \p input buffer in bytes. 948 * 949 * \return 0 if the operation was started successfully and the SSL 950 * stack should call the resume callback immediately. 951 * \return #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS if the operation 952 * was started successfully and the SSL stack should return 953 * immediately without calling the resume callback yet. 954 * \return #MBEDTLS_ERR_SSL_HW_ACCEL_FALLTHROUGH if the external 955 * processor does not support this key. The SSL stack will 956 * use the private key object instead. 957 * \return Any other error indicates a fatal failure and is 958 * propagated up the call chain. The callback should 959 * use \c MBEDTLS_ERR_PK_xxx error codes, and <b>must not</b> 960 * use \c MBEDTLS_ERR_SSL_xxx error codes except as 961 * directed in the documentation of this callback. 962 */ 963 typedef int mbedtls_ssl_async_decrypt_t( mbedtls_ssl_context *ssl, 964 mbedtls_x509_crt *cert, 965 const unsigned char *input, 966 size_t input_len ); 967 #endif /* MBEDTLS_X509_CRT_PARSE_C */ 968 969 /** 970 * \brief Callback type: resume external operation. 971 * 972 * This callback is called during an SSL handshake to resume 973 * an external operation started by the 974 * ::mbedtls_ssl_async_sign_t or 975 * ::mbedtls_ssl_async_decrypt_t callback. 976 * 977 * This function typically checks the status of a pending 978 * request or causes the request queue to make progress, and 979 * does not wait for the operation to complete. This allows 980 * the handshake step to be non-blocking. 981 * 982 * This function may call mbedtls_ssl_get_async_operation_data() 983 * to retrieve an operation context set by the start callback. 984 * It may call mbedtls_ssl_set_async_operation_data() to modify 985 * this context. 986 * 987 * Note that when this function returns a status other than 988 * #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS, it must free any 989 * resources associated with the operation. 990 * 991 * \param ssl The SSL connection instance. It should not be 992 * modified other than via 993 * mbedtls_ssl_set_async_operation_data(). 994 * \param output Buffer containing the output (signature or decrypted 995 * data) on success. 996 * \param output_len On success, number of bytes written to \p output. 997 * \param output_size Size of the \p output buffer in bytes. 998 * 999 * \return 0 if output of the operation is available in the 1000 * \p output buffer. 1001 * \return #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS if the operation 1002 * is still in progress. Subsequent requests for progress 1003 * on the SSL connection will call the resume callback 1004 * again. 1005 * \return Any other error means that the operation is aborted. 1006 * The SSL handshake is aborted. The callback should 1007 * use \c MBEDTLS_ERR_PK_xxx error codes, and <b>must not</b> 1008 * use \c MBEDTLS_ERR_SSL_xxx error codes except as 1009 * directed in the documentation of this callback. 1010 */ 1011 typedef int mbedtls_ssl_async_resume_t( mbedtls_ssl_context *ssl, 1012 unsigned char *output, 1013 size_t *output_len, 1014 size_t output_size ); 1015 1016 /** 1017 * \brief Callback type: cancel external operation. 1018 * 1019 * This callback is called if an SSL connection is closed 1020 * while an asynchronous operation is in progress. Note that 1021 * this callback is not called if the 1022 * ::mbedtls_ssl_async_resume_t callback has run and has 1023 * returned a value other than 1024 * #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS, since in that case 1025 * the asynchronous operation has already completed. 1026 * 1027 * This function may call mbedtls_ssl_get_async_operation_data() 1028 * to retrieve an operation context set by the start callback. 1029 * 1030 * \param ssl The SSL connection instance. It should not be 1031 * modified. 1032 */ 1033 typedef void mbedtls_ssl_async_cancel_t( mbedtls_ssl_context *ssl ); 1034 #endif /* MBEDTLS_SSL_ASYNC_PRIVATE */ 1035 1036 #if defined(MBEDTLS_KEY_EXCHANGE_WITH_CERT_ENABLED) && \ 1037 !defined(MBEDTLS_SSL_KEEP_PEER_CERTIFICATE) 1038 #define MBEDTLS_SSL_PEER_CERT_DIGEST_MAX_LEN 48 1039 #if defined(MBEDTLS_SHA256_C) 1040 #define MBEDTLS_SSL_PEER_CERT_DIGEST_DFL_TYPE MBEDTLS_MD_SHA256 1041 #define MBEDTLS_SSL_PEER_CERT_DIGEST_DFL_LEN 32 1042 #elif defined(MBEDTLS_SHA384_C) 1043 #define MBEDTLS_SSL_PEER_CERT_DIGEST_DFL_TYPE MBEDTLS_MD_SHA384 1044 #define MBEDTLS_SSL_PEER_CERT_DIGEST_DFL_LEN 48 1045 #elif defined(MBEDTLS_SHA1_C) 1046 #define MBEDTLS_SSL_PEER_CERT_DIGEST_DFL_TYPE MBEDTLS_MD_SHA1 1047 #define MBEDTLS_SSL_PEER_CERT_DIGEST_DFL_LEN 20 1048 #else 1049 /* This is already checked in check_config.h, but be sure. */ 1050 #error "Bad configuration - need SHA-1, SHA-256 or SHA-512 enabled to compute digest of peer CRT." 1051 #endif 1052 #endif /* MBEDTLS_KEY_EXCHANGE_WITH_CERT_ENABLED && 1053 !MBEDTLS_SSL_KEEP_PEER_CERTIFICATE */ 1054 1055 typedef struct 1056 { 1057 unsigned char client_application_traffic_secret_N[ MBEDTLS_TLS1_3_MD_MAX_SIZE ]; 1058 unsigned char server_application_traffic_secret_N[ MBEDTLS_TLS1_3_MD_MAX_SIZE ]; 1059 unsigned char exporter_master_secret [ MBEDTLS_TLS1_3_MD_MAX_SIZE ]; 1060 unsigned char resumption_master_secret [ MBEDTLS_TLS1_3_MD_MAX_SIZE ]; 1061 } mbedtls_ssl_tls1_3_application_secrets; 1062 1063 #if defined(MBEDTLS_SSL_DTLS_SRTP) 1064 1065 #define MBEDTLS_TLS_SRTP_MAX_MKI_LENGTH 255 1066 #define MBEDTLS_TLS_SRTP_MAX_PROFILE_LIST_LENGTH 4 1067 /* 1068 * For code readability use a typedef for DTLS-SRTP profiles 1069 * 1070 * Use_srtp extension protection profiles values as defined in 1071 * http://www.iana.org/assignments/srtp-protection/srtp-protection.xhtml 1072 * 1073 * Reminder: if this list is expanded mbedtls_ssl_check_srtp_profile_value 1074 * must be updated too. 1075 */ 1076 #define MBEDTLS_TLS_SRTP_AES128_CM_HMAC_SHA1_80 ( (uint16_t) 0x0001) 1077 #define MBEDTLS_TLS_SRTP_AES128_CM_HMAC_SHA1_32 ( (uint16_t) 0x0002) 1078 #define MBEDTLS_TLS_SRTP_NULL_HMAC_SHA1_80 ( (uint16_t) 0x0005) 1079 #define MBEDTLS_TLS_SRTP_NULL_HMAC_SHA1_32 ( (uint16_t) 0x0006) 1080 /* This one is not iana defined, but for code readability. */ 1081 #define MBEDTLS_TLS_SRTP_UNSET ( (uint16_t) 0x0000) 1082 1083 typedef uint16_t mbedtls_ssl_srtp_profile; 1084 1085 typedef struct mbedtls_dtls_srtp_info_t 1086 { 1087 /*! The SRTP profile that was negotiated. */ 1088 mbedtls_ssl_srtp_profile MBEDTLS_PRIVATE(chosen_dtls_srtp_profile); 1089 /*! The length of mki_value. */ 1090 uint16_t MBEDTLS_PRIVATE(mki_len); 1091 /*! The mki_value used, with max size of 256 bytes. */ 1092 unsigned char MBEDTLS_PRIVATE(mki_value)[MBEDTLS_TLS_SRTP_MAX_MKI_LENGTH]; 1093 } 1094 mbedtls_dtls_srtp_info; 1095 1096 #endif /* MBEDTLS_SSL_DTLS_SRTP */ 1097 1098 /* 1099 * This structure is used for storing current session data. 1100 * 1101 * Note: when changing this definition, we need to check and update: 1102 * - in tests/suites/test_suite_ssl.function: 1103 * ssl_populate_session() and ssl_serialize_session_save_load() 1104 * - in library/ssl_tls.c: 1105 * mbedtls_ssl_session_init() and mbedtls_ssl_session_free() 1106 * mbedtls_ssl_session_save() and ssl_session_load() 1107 * ssl_session_copy() 1108 */ 1109 struct mbedtls_ssl_session 1110 { 1111 #if defined(MBEDTLS_HAVE_TIME) 1112 mbedtls_time_t MBEDTLS_PRIVATE(start); /*!< starting time */ 1113 #endif 1114 int MBEDTLS_PRIVATE(ciphersuite); /*!< chosen ciphersuite */ 1115 int MBEDTLS_PRIVATE(compression); /*!< chosen compression */ 1116 size_t MBEDTLS_PRIVATE(id_len); /*!< session id length */ 1117 unsigned char MBEDTLS_PRIVATE(id)[32]; /*!< session identifier */ 1118 unsigned char MBEDTLS_PRIVATE(master)[48]; /*!< the master secret */ 1119 1120 unsigned char MBEDTLS_PRIVATE(exported); 1121 1122 /* This field is temporarily duplicated with mbedtls_ssl_context.minor_ver. 1123 * Once runtime negotiation of TLS 1.2 and TLS 1.3 is implemented, it needs 1124 * to be studied whether one of them can be removed. */ 1125 unsigned char MBEDTLS_PRIVATE(minor_ver); /*!< The TLS version used in the session. */ 1126 1127 #if defined(MBEDTLS_X509_CRT_PARSE_C) 1128 #if defined(MBEDTLS_SSL_KEEP_PEER_CERTIFICATE) 1129 mbedtls_x509_crt *MBEDTLS_PRIVATE(peer_cert); /*!< peer X.509 cert chain */ 1130 #else /* MBEDTLS_SSL_KEEP_PEER_CERTIFICATE */ 1131 /*! The digest of the peer's end-CRT. This must be kept to detect CRT 1132 * changes during renegotiation, mitigating the triple handshake attack. */ 1133 unsigned char *MBEDTLS_PRIVATE(peer_cert_digest); 1134 size_t MBEDTLS_PRIVATE(peer_cert_digest_len); 1135 mbedtls_md_type_t MBEDTLS_PRIVATE(peer_cert_digest_type); 1136 #endif /* !MBEDTLS_SSL_KEEP_PEER_CERTIFICATE */ 1137 #endif /* MBEDTLS_X509_CRT_PARSE_C */ 1138 uint32_t MBEDTLS_PRIVATE(verify_result); /*!< verification result */ 1139 1140 #if defined(MBEDTLS_SSL_SESSION_TICKETS) && defined(MBEDTLS_SSL_CLI_C) 1141 unsigned char *MBEDTLS_PRIVATE(ticket); /*!< RFC 5077 session ticket */ 1142 size_t MBEDTLS_PRIVATE(ticket_len); /*!< session ticket length */ 1143 uint32_t MBEDTLS_PRIVATE(ticket_lifetime); /*!< ticket lifetime hint */ 1144 #endif /* MBEDTLS_SSL_SESSION_TICKETS && MBEDTLS_SSL_CLI_C */ 1145 1146 #if defined(MBEDTLS_SSL_MAX_FRAGMENT_LENGTH) 1147 unsigned char MBEDTLS_PRIVATE(mfl_code); /*!< MaxFragmentLength negotiated by peer */ 1148 #endif /* MBEDTLS_SSL_MAX_FRAGMENT_LENGTH */ 1149 1150 #if defined(MBEDTLS_SSL_ENCRYPT_THEN_MAC) 1151 int MBEDTLS_PRIVATE(encrypt_then_mac); /*!< flag for EtM activation */ 1152 #endif 1153 1154 #if defined(MBEDTLS_SSL_PROTO_TLS1_3_EXPERIMENTAL) 1155 mbedtls_ssl_tls1_3_application_secrets MBEDTLS_PRIVATE(app_secrets); 1156 #endif 1157 }; 1158 1159 /* 1160 * Identifiers for PRFs used in various versions of TLS. 1161 */ 1162 typedef enum 1163 { 1164 MBEDTLS_SSL_TLS_PRF_NONE, 1165 MBEDTLS_SSL_TLS_PRF_SHA384, 1166 MBEDTLS_SSL_TLS_PRF_SHA256, 1167 MBEDTLS_SSL_HKDF_EXPAND_SHA384, 1168 MBEDTLS_SSL_HKDF_EXPAND_SHA256 1169 } 1170 mbedtls_tls_prf_types; 1171 1172 typedef enum 1173 { 1174 MBEDTLS_SSL_KEY_EXPORT_TLS12_MASTER_SECRET = 0, 1175 #if defined(MBEDTLS_SSL_PROTO_TLS1_3_EXPERIMENTAL) 1176 MBEDTLS_SSL_KEY_EXPORT_TLS13_CLIENT_EARLY_SECRET, 1177 MBEDTLS_SSL_KEY_EXPORT_TLS13_EARLY_EXPORTER_SECRET, 1178 MBEDTLS_SSL_KEY_EXPORT_TLS13_CLIENT_HANDSHAKE_TRAFFIC_SECRET, 1179 MBEDTLS_SSL_KEY_EXPORT_TLS13_SERVER_HANDSHAKE_TRAFFIC_SECRET, 1180 MBEDTLS_SSL_KEY_EXPORT_TLS13_CLIENT_APPLICATION_TRAFFIC_SECRET, 1181 MBEDTLS_SSL_KEY_EXPORT_TLS13_SERVER_APPLICATION_TRAFFIC_SECRET, 1182 #endif /* MBEDTLS_SSL_PROTO_TLS1_3_EXPERIMENTAL */ 1183 } mbedtls_ssl_key_export_type; 1184 1185 /** 1186 * \brief Callback type: Export key alongside random values for 1187 * session identification, and PRF for 1188 * implementation of TLS key exporters. 1189 * 1190 * \param p_expkey Context for the callback. 1191 * \param type The type of the key that is being exported. 1192 * \param secret The address of the buffer holding the secret 1193 * that's being exporterd. 1194 * \param secret_len The length of \p secret in bytes. 1195 * \param client_random The client random bytes. 1196 * \param server_random The server random bytes. 1197 * \param tls_prf_type The identifier for the PRF used in the handshake 1198 * to which the key belongs. 1199 */ 1200 typedef void mbedtls_ssl_export_keys_t( void *p_expkey, 1201 mbedtls_ssl_key_export_type type, 1202 const unsigned char *secret, 1203 size_t secret_len, 1204 const unsigned char client_random[32], 1205 const unsigned char server_random[32], 1206 mbedtls_tls_prf_types tls_prf_type ); 1207 1208 /** 1209 * SSL/TLS configuration to be shared between mbedtls_ssl_context structures. 1210 */ 1211 struct mbedtls_ssl_config 1212 { 1213 /* Group items by size (largest first) to minimize padding overhead */ 1214 1215 /* 1216 * Pointers 1217 */ 1218 1219 /** Allowed ciphersuites for (D)TLS 1.2 (0-terminated) */ 1220 const int *MBEDTLS_PRIVATE(ciphersuite_list); 1221 1222 #if defined(MBEDTLS_SSL_PROTO_TLS1_3_EXPERIMENTAL) 1223 /** Allowed TLS 1.3 key exchange modes. */ 1224 int MBEDTLS_PRIVATE(tls13_kex_modes); 1225 #endif /* MBEDTLS_SSL_PROTO_TLS1_3_EXPERIMENTAL */ 1226 1227 /** Callback for printing debug output */ 1228 void (*MBEDTLS_PRIVATE(f_dbg))(void *, int, const char *, int, const char *); 1229 void *MBEDTLS_PRIVATE(p_dbg); /*!< context for the debug function */ 1230 1231 /** Callback for getting (pseudo-)random numbers */ 1232 int (*MBEDTLS_PRIVATE(f_rng))(void *, unsigned char *, size_t); 1233 void *MBEDTLS_PRIVATE(p_rng); /*!< context for the RNG function */ 1234 1235 /** Callback to retrieve a session from the cache */ 1236 mbedtls_ssl_cache_get_t *MBEDTLS_PRIVATE(f_get_cache); 1237 /** Callback to store a session into the cache */ 1238 mbedtls_ssl_cache_set_t *MBEDTLS_PRIVATE(f_set_cache); 1239 void *MBEDTLS_PRIVATE(p_cache); /*!< context for cache callbacks */ 1240 1241 #if defined(MBEDTLS_SSL_SERVER_NAME_INDICATION) 1242 /** Callback for setting cert according to SNI extension */ 1243 int (*MBEDTLS_PRIVATE(f_sni))(void *, mbedtls_ssl_context *, const unsigned char *, size_t); 1244 void *MBEDTLS_PRIVATE(p_sni); /*!< context for SNI callback */ 1245 #endif 1246 1247 #if defined(MBEDTLS_X509_CRT_PARSE_C) 1248 /** Callback to customize X.509 certificate chain verification */ 1249 int (*MBEDTLS_PRIVATE(f_vrfy))(void *, mbedtls_x509_crt *, int, uint32_t *); 1250 void *MBEDTLS_PRIVATE(p_vrfy); /*!< context for X.509 verify calllback */ 1251 #endif 1252 1253 #if defined(MBEDTLS_KEY_EXCHANGE_SOME_PSK_ENABLED) 1254 /** Callback to retrieve PSK key from identity */ 1255 int (*MBEDTLS_PRIVATE(f_psk))(void *, mbedtls_ssl_context *, const unsigned char *, size_t); 1256 void *MBEDTLS_PRIVATE(p_psk); /*!< context for PSK callback */ 1257 #endif 1258 1259 #if defined(MBEDTLS_SSL_DTLS_HELLO_VERIFY) && defined(MBEDTLS_SSL_SRV_C) 1260 /** Callback to create & write a cookie for ClientHello veirifcation */ 1261 int (*MBEDTLS_PRIVATE(f_cookie_write))( void *, unsigned char **, unsigned char *, 1262 const unsigned char *, size_t ); 1263 /** Callback to verify validity of a ClientHello cookie */ 1264 int (*MBEDTLS_PRIVATE(f_cookie_check))( void *, const unsigned char *, size_t, 1265 const unsigned char *, size_t ); 1266 void *MBEDTLS_PRIVATE(p_cookie); /*!< context for the cookie callbacks */ 1267 #endif 1268 1269 #if defined(MBEDTLS_SSL_SESSION_TICKETS) && defined(MBEDTLS_SSL_SRV_C) 1270 /** Callback to create & write a session ticket */ 1271 int (*MBEDTLS_PRIVATE(f_ticket_write))( void *, const mbedtls_ssl_session *, 1272 unsigned char *, const unsigned char *, size_t *, uint32_t * ); 1273 /** Callback to parse a session ticket into a session structure */ 1274 int (*MBEDTLS_PRIVATE(f_ticket_parse))( void *, mbedtls_ssl_session *, unsigned char *, size_t); 1275 void *MBEDTLS_PRIVATE(p_ticket); /*!< context for the ticket callbacks */ 1276 #endif /* MBEDTLS_SSL_SESSION_TICKETS && MBEDTLS_SSL_SRV_C */ 1277 1278 #if defined(MBEDTLS_SSL_DTLS_CONNECTION_ID) 1279 size_t MBEDTLS_PRIVATE(cid_len); /*!< The length of CIDs for incoming DTLS records. */ 1280 #endif /* MBEDTLS_SSL_DTLS_CONNECTION_ID */ 1281 1282 #if defined(MBEDTLS_X509_CRT_PARSE_C) 1283 const mbedtls_x509_crt_profile *MBEDTLS_PRIVATE(cert_profile); /*!< verification profile */ 1284 mbedtls_ssl_key_cert *MBEDTLS_PRIVATE(key_cert); /*!< own certificate/key pair(s) */ 1285 mbedtls_x509_crt *MBEDTLS_PRIVATE(ca_chain); /*!< trusted CAs */ 1286 mbedtls_x509_crl *MBEDTLS_PRIVATE(ca_crl); /*!< trusted CAs CRLs */ 1287 #if defined(MBEDTLS_X509_TRUSTED_CERTIFICATE_CALLBACK) 1288 mbedtls_x509_crt_ca_cb_t MBEDTLS_PRIVATE(f_ca_cb); 1289 void *MBEDTLS_PRIVATE(p_ca_cb); 1290 #endif /* MBEDTLS_X509_TRUSTED_CERTIFICATE_CALLBACK */ 1291 #endif /* MBEDTLS_X509_CRT_PARSE_C */ 1292 1293 #if defined(MBEDTLS_SSL_ASYNC_PRIVATE) 1294 #if defined(MBEDTLS_X509_CRT_PARSE_C) 1295 mbedtls_ssl_async_sign_t *MBEDTLS_PRIVATE(f_async_sign_start); /*!< start asynchronous signature operation */ 1296 mbedtls_ssl_async_decrypt_t *MBEDTLS_PRIVATE(f_async_decrypt_start); /*!< start asynchronous decryption operation */ 1297 #endif /* MBEDTLS_X509_CRT_PARSE_C */ 1298 mbedtls_ssl_async_resume_t *MBEDTLS_PRIVATE(f_async_resume); /*!< resume asynchronous operation */ 1299 mbedtls_ssl_async_cancel_t *MBEDTLS_PRIVATE(f_async_cancel); /*!< cancel asynchronous operation */ 1300 void *MBEDTLS_PRIVATE(p_async_config_data); /*!< Configuration data set by mbedtls_ssl_conf_async_private_cb(). */ 1301 #endif /* MBEDTLS_SSL_ASYNC_PRIVATE */ 1302 1303 #if defined(MBEDTLS_KEY_EXCHANGE_WITH_CERT_ENABLED) 1304 const int *MBEDTLS_PRIVATE(sig_hashes); /*!< allowed signature hashes */ 1305 1306 #if defined(MBEDTLS_SSL_PROTO_TLS1_3_EXPERIMENTAL) 1307 const uint16_t *MBEDTLS_PRIVATE(tls13_sig_algs); /*!< allowed signature algorithms for TLS 1.3 */ 1308 #endif /* MBEDTLS_SSL_PROTO_TLS1_3_EXPERIMENTAL */ 1309 #endif 1310 1311 #if defined(MBEDTLS_ECP_C) && !defined(MBEDTLS_DEPRECATED_REMOVED) 1312 const mbedtls_ecp_group_id *MBEDTLS_PRIVATE(curve_list); /*!< allowed curves */ 1313 #endif 1314 1315 const uint16_t *MBEDTLS_PRIVATE(group_list); /*!< allowed IANA NamedGroups */ 1316 1317 #if defined(MBEDTLS_DHM_C) 1318 mbedtls_mpi MBEDTLS_PRIVATE(dhm_P); /*!< prime modulus for DHM */ 1319 mbedtls_mpi MBEDTLS_PRIVATE(dhm_G); /*!< generator for DHM */ 1320 #endif 1321 1322 #if defined(MBEDTLS_KEY_EXCHANGE_SOME_PSK_ENABLED) 1323 1324 #if defined(MBEDTLS_USE_PSA_CRYPTO) 1325 psa_key_id_t MBEDTLS_PRIVATE(psk_opaque); /*!< PSA key slot holding opaque PSK. This field 1326 * should only be set via 1327 * mbedtls_ssl_conf_psk_opaque(). 1328 * If either no PSK or a raw PSK have been 1329 * configured, this has value \c 0. 1330 */ 1331 #endif /* MBEDTLS_USE_PSA_CRYPTO */ 1332 1333 unsigned char *MBEDTLS_PRIVATE(psk); /*!< The raw pre-shared key. This field should 1334 * only be set via mbedtls_ssl_conf_psk(). 1335 * If either no PSK or an opaque PSK 1336 * have been configured, this has value NULL. */ 1337 size_t MBEDTLS_PRIVATE(psk_len); /*!< The length of the raw pre-shared key. 1338 * This field should only be set via 1339 * mbedtls_ssl_conf_psk(). 1340 * Its value is non-zero if and only if 1341 * \c psk is not \c NULL. */ 1342 1343 unsigned char *MBEDTLS_PRIVATE(psk_identity); /*!< The PSK identity for PSK negotiation. 1344 * This field should only be set via 1345 * mbedtls_ssl_conf_psk(). 1346 * This is set if and only if either 1347 * \c psk or \c psk_opaque are set. */ 1348 size_t MBEDTLS_PRIVATE(psk_identity_len);/*!< The length of PSK identity. 1349 * This field should only be set via 1350 * mbedtls_ssl_conf_psk(). 1351 * Its value is non-zero if and only if 1352 * \c psk is not \c NULL or \c psk_opaque 1353 * is not \c 0. */ 1354 #endif /* MBEDTLS_KEY_EXCHANGE_SOME_PSK_ENABLED */ 1355 1356 #if defined(MBEDTLS_SSL_ALPN) 1357 const char **MBEDTLS_PRIVATE(alpn_list); /*!< ordered list of protocols */ 1358 #endif 1359 1360 #if defined(MBEDTLS_SSL_DTLS_SRTP) 1361 /*! ordered list of supported srtp profile */ 1362 const mbedtls_ssl_srtp_profile *MBEDTLS_PRIVATE(dtls_srtp_profile_list); 1363 /*! number of supported profiles */ 1364 size_t MBEDTLS_PRIVATE(dtls_srtp_profile_list_len); 1365 #endif /* MBEDTLS_SSL_DTLS_SRTP */ 1366 1367 /* 1368 * Numerical settings (int then char) 1369 */ 1370 1371 uint32_t MBEDTLS_PRIVATE(read_timeout); /*!< timeout for mbedtls_ssl_read (ms) */ 1372 1373 #if defined(MBEDTLS_SSL_PROTO_DTLS) 1374 uint32_t MBEDTLS_PRIVATE(hs_timeout_min); /*!< initial value of the handshake 1375 retransmission timeout (ms) */ 1376 uint32_t MBEDTLS_PRIVATE(hs_timeout_max); /*!< maximum value of the handshake 1377 retransmission timeout (ms) */ 1378 #endif 1379 1380 #if defined(MBEDTLS_SSL_RENEGOTIATION) 1381 int MBEDTLS_PRIVATE(renego_max_records); /*!< grace period for renegotiation */ 1382 unsigned char MBEDTLS_PRIVATE(renego_period)[8]; /*!< value of the record counters 1383 that triggers renegotiation */ 1384 #endif 1385 1386 unsigned int MBEDTLS_PRIVATE(badmac_limit); /*!< limit of records with a bad MAC */ 1387 1388 #if defined(MBEDTLS_DHM_C) && defined(MBEDTLS_SSL_CLI_C) 1389 unsigned int MBEDTLS_PRIVATE(dhm_min_bitlen); /*!< min. bit length of the DHM prime */ 1390 #endif 1391 1392 unsigned char MBEDTLS_PRIVATE(max_major_ver); /*!< max. major version used */ 1393 unsigned char MBEDTLS_PRIVATE(max_minor_ver); /*!< max. minor version used */ 1394 unsigned char MBEDTLS_PRIVATE(min_major_ver); /*!< min. major version used */ 1395 unsigned char MBEDTLS_PRIVATE(min_minor_ver); /*!< min. minor version used */ 1396 1397 /* 1398 * Flags (bitfields) 1399 */ 1400 1401 unsigned int MBEDTLS_PRIVATE(endpoint) : 1; /*!< 0: client, 1: server */ 1402 unsigned int MBEDTLS_PRIVATE(transport) : 1; /*!< stream (TLS) or datagram (DTLS) */ 1403 unsigned int MBEDTLS_PRIVATE(authmode) : 2; /*!< MBEDTLS_SSL_VERIFY_XXX */ 1404 /* needed even with renego disabled for LEGACY_BREAK_HANDSHAKE */ 1405 unsigned int MBEDTLS_PRIVATE(allow_legacy_renegotiation) : 2 ; /*!< MBEDTLS_LEGACY_XXX */ 1406 #if defined(MBEDTLS_SSL_MAX_FRAGMENT_LENGTH) 1407 unsigned int MBEDTLS_PRIVATE(mfl_code) : 3; /*!< desired fragment length */ 1408 #endif 1409 #if defined(MBEDTLS_SSL_ENCRYPT_THEN_MAC) 1410 unsigned int MBEDTLS_PRIVATE(encrypt_then_mac) : 1 ; /*!< negotiate encrypt-then-mac? */ 1411 #endif 1412 #if defined(MBEDTLS_SSL_EXTENDED_MASTER_SECRET) 1413 unsigned int MBEDTLS_PRIVATE(extended_ms) : 1; /*!< negotiate extended master secret? */ 1414 #endif 1415 #if defined(MBEDTLS_SSL_DTLS_ANTI_REPLAY) 1416 unsigned int MBEDTLS_PRIVATE(anti_replay) : 1; /*!< detect and prevent replay? */ 1417 #endif 1418 #if defined(MBEDTLS_SSL_RENEGOTIATION) 1419 unsigned int MBEDTLS_PRIVATE(disable_renegotiation) : 1; /*!< disable renegotiation? */ 1420 #endif 1421 #if defined(MBEDTLS_SSL_SESSION_TICKETS) 1422 unsigned int MBEDTLS_PRIVATE(session_tickets) : 1; /*!< use session tickets? */ 1423 #endif 1424 #if defined(MBEDTLS_SSL_SRV_C) 1425 unsigned int MBEDTLS_PRIVATE(cert_req_ca_list) : 1; /*!< enable sending CA list in 1426 Certificate Request messages? */ 1427 unsigned int MBEDTLS_PRIVATE(respect_cli_pref) : 1; /*!< pick the ciphersuite according to 1428 the client's preferences rather 1429 than ours */ 1430 #endif 1431 #if defined(MBEDTLS_SSL_DTLS_CONNECTION_ID) 1432 unsigned int MBEDTLS_PRIVATE(ignore_unexpected_cid) : 1; /*!< Determines whether DTLS 1433 * record with unexpected CID 1434 * should lead to failure. */ 1435 #endif /* MBEDTLS_SSL_DTLS_CONNECTION_ID */ 1436 #if defined(MBEDTLS_SSL_DTLS_SRTP) 1437 unsigned int MBEDTLS_PRIVATE(dtls_srtp_mki_support) : 1; /* support having mki_value 1438 in the use_srtp extension */ 1439 #endif 1440 }; 1441 1442 struct mbedtls_ssl_context 1443 { 1444 const mbedtls_ssl_config *MBEDTLS_PRIVATE(conf); /*!< configuration information */ 1445 1446 /* 1447 * Miscellaneous 1448 */ 1449 int MBEDTLS_PRIVATE(state); /*!< SSL handshake: current state */ 1450 #if defined(MBEDTLS_SSL_RENEGOTIATION) 1451 int MBEDTLS_PRIVATE(renego_status); /*!< Initial, in progress, pending? */ 1452 int MBEDTLS_PRIVATE(renego_records_seen); /*!< Records since renego request, or with DTLS, 1453 number of retransmissions of request if 1454 renego_max_records is < 0 */ 1455 #endif /* MBEDTLS_SSL_RENEGOTIATION */ 1456 1457 int MBEDTLS_PRIVATE(major_ver); /*!< equal to MBEDTLS_SSL_MAJOR_VERSION_3 */ 1458 1459 /* This field is temporarily duplicated with mbedtls_ssl_context.minor_ver. 1460 * Once runtime negotiation of TLS 1.2 and TLS 1.3 is implemented, it needs 1461 * to be studied whether one of them can be removed. */ 1462 int MBEDTLS_PRIVATE(minor_ver); /*!< one of MBEDTLS_SSL_MINOR_VERSION_x macros */ 1463 unsigned MBEDTLS_PRIVATE(badmac_seen); /*!< records with a bad MAC received */ 1464 1465 #if defined(MBEDTLS_X509_CRT_PARSE_C) 1466 /** Callback to customize X.509 certificate chain verification */ 1467 int (*MBEDTLS_PRIVATE(f_vrfy))(void *, mbedtls_x509_crt *, int, uint32_t *); 1468 void *MBEDTLS_PRIVATE(p_vrfy); /*!< context for X.509 verify callback */ 1469 #endif 1470 1471 mbedtls_ssl_send_t *MBEDTLS_PRIVATE(f_send); /*!< Callback for network send */ 1472 mbedtls_ssl_recv_t *MBEDTLS_PRIVATE(f_recv); /*!< Callback for network receive */ 1473 mbedtls_ssl_recv_timeout_t *MBEDTLS_PRIVATE(f_recv_timeout); 1474 /*!< Callback for network receive with timeout */ 1475 1476 void *MBEDTLS_PRIVATE(p_bio); /*!< context for I/O operations */ 1477 1478 /* 1479 * Session layer 1480 */ 1481 mbedtls_ssl_session *MBEDTLS_PRIVATE(session_in); /*!< current session data (in) */ 1482 mbedtls_ssl_session *MBEDTLS_PRIVATE(session_out); /*!< current session data (out) */ 1483 mbedtls_ssl_session *MBEDTLS_PRIVATE(session); /*!< negotiated session data */ 1484 mbedtls_ssl_session *MBEDTLS_PRIVATE(session_negotiate); /*!< session data in negotiation */ 1485 1486 mbedtls_ssl_handshake_params *MBEDTLS_PRIVATE(handshake); /*!< params required only during 1487 the handshake process */ 1488 1489 /* 1490 * Record layer transformations 1491 */ 1492 mbedtls_ssl_transform *MBEDTLS_PRIVATE(transform_in); /*!< current transform params (in) 1493 * This is always a reference, 1494 * never an owning pointer. */ 1495 mbedtls_ssl_transform *MBEDTLS_PRIVATE(transform_out); /*!< current transform params (out) 1496 * This is always a reference, 1497 * never an owning pointer. */ 1498 mbedtls_ssl_transform *MBEDTLS_PRIVATE(transform); /*!< negotiated transform params 1499 * This pointer owns the transform 1500 * it references. */ 1501 mbedtls_ssl_transform *MBEDTLS_PRIVATE(transform_negotiate); /*!< transform params in negotiation 1502 * This pointer owns the transform 1503 * it references. */ 1504 1505 #if defined(MBEDTLS_SSL_PROTO_TLS1_3_EXPERIMENTAL) 1506 /*! The application data transform in TLS 1.3. 1507 * This pointer owns the transform it references. */ 1508 mbedtls_ssl_transform *MBEDTLS_PRIVATE(transform_application); 1509 #endif /* MBEDTLS_SSL_PROTO_TLS1_3_EXPERIMENTAL */ 1510 1511 /* 1512 * Timers 1513 */ 1514 void *MBEDTLS_PRIVATE(p_timer); /*!< context for the timer callbacks */ 1515 1516 mbedtls_ssl_set_timer_t *MBEDTLS_PRIVATE(f_set_timer); /*!< set timer callback */ 1517 mbedtls_ssl_get_timer_t *MBEDTLS_PRIVATE(f_get_timer); /*!< get timer callback */ 1518 1519 /* 1520 * Record layer (incoming data) 1521 */ 1522 unsigned char *MBEDTLS_PRIVATE(in_buf); /*!< input buffer */ 1523 unsigned char *MBEDTLS_PRIVATE(in_ctr); /*!< 64-bit incoming message counter 1524 TLS: maintained by us 1525 DTLS: read from peer */ 1526 unsigned char *MBEDTLS_PRIVATE(in_hdr); /*!< start of record header */ 1527 #if defined(MBEDTLS_SSL_DTLS_CONNECTION_ID) 1528 unsigned char *MBEDTLS_PRIVATE(in_cid); /*!< The start of the CID; 1529 * (the end is marked by in_len). */ 1530 #endif /* MBEDTLS_SSL_DTLS_CONNECTION_ID */ 1531 unsigned char *MBEDTLS_PRIVATE(in_len); /*!< two-bytes message length field */ 1532 unsigned char *MBEDTLS_PRIVATE(in_iv); /*!< ivlen-byte IV */ 1533 unsigned char *MBEDTLS_PRIVATE(in_msg); /*!< message contents (in_iv+ivlen) */ 1534 unsigned char *MBEDTLS_PRIVATE(in_offt); /*!< read offset in application data */ 1535 1536 int MBEDTLS_PRIVATE(in_msgtype); /*!< record header: message type */ 1537 size_t MBEDTLS_PRIVATE(in_msglen); /*!< record header: message length */ 1538 size_t MBEDTLS_PRIVATE(in_left); /*!< amount of data read so far */ 1539 #if defined(MBEDTLS_SSL_VARIABLE_BUFFER_LENGTH) 1540 size_t MBEDTLS_PRIVATE(in_buf_len); /*!< length of input buffer */ 1541 #endif 1542 #if defined(MBEDTLS_SSL_PROTO_DTLS) 1543 uint16_t MBEDTLS_PRIVATE(in_epoch); /*!< DTLS epoch for incoming records */ 1544 size_t MBEDTLS_PRIVATE(next_record_offset); /*!< offset of the next record in datagram 1545 (equal to in_left if none) */ 1546 #endif /* MBEDTLS_SSL_PROTO_DTLS */ 1547 #if defined(MBEDTLS_SSL_DTLS_ANTI_REPLAY) 1548 uint64_t MBEDTLS_PRIVATE(in_window_top); /*!< last validated record seq_num */ 1549 uint64_t MBEDTLS_PRIVATE(in_window); /*!< bitmask for replay detection */ 1550 #endif /* MBEDTLS_SSL_DTLS_ANTI_REPLAY */ 1551 1552 size_t MBEDTLS_PRIVATE(in_hslen); /*!< current handshake message length, 1553 including the handshake header */ 1554 int MBEDTLS_PRIVATE(nb_zero); /*!< # of 0-length encrypted messages */ 1555 1556 int MBEDTLS_PRIVATE(keep_current_message); /*!< drop or reuse current message 1557 on next call to record layer? */ 1558 1559 /* The following three variables indicate if and, if yes, 1560 * what kind of alert is pending to be sent. 1561 */ 1562 unsigned char MBEDTLS_PRIVATE(send_alert); /*!< Determines if a fatal alert 1563 should be sent. Values: 1564 - \c 0 , no alert is to be sent. 1565 - \c 1 , alert is to be sent. */ 1566 unsigned char MBEDTLS_PRIVATE(alert_type); /*!< Type of alert if send_alert 1567 != 0 */ 1568 int MBEDTLS_PRIVATE(alert_reason); /*!< The error code to be returned 1569 to the user once the fatal alert 1570 has been sent. */ 1571 1572 #if defined(MBEDTLS_SSL_PROTO_DTLS) 1573 uint8_t MBEDTLS_PRIVATE(disable_datagram_packing); /*!< Disable packing multiple records 1574 * within a single datagram. */ 1575 #endif /* MBEDTLS_SSL_PROTO_DTLS */ 1576 1577 /* 1578 * Record layer (outgoing data) 1579 */ 1580 unsigned char *MBEDTLS_PRIVATE(out_buf); /*!< output buffer */ 1581 unsigned char *MBEDTLS_PRIVATE(out_ctr); /*!< 64-bit outgoing message counter */ 1582 unsigned char *MBEDTLS_PRIVATE(out_hdr); /*!< start of record header */ 1583 #if defined(MBEDTLS_SSL_DTLS_CONNECTION_ID) 1584 unsigned char *MBEDTLS_PRIVATE(out_cid); /*!< The start of the CID; 1585 * (the end is marked by in_len). */ 1586 #endif /* MBEDTLS_SSL_DTLS_CONNECTION_ID */ 1587 unsigned char *MBEDTLS_PRIVATE(out_len); /*!< two-bytes message length field */ 1588 unsigned char *MBEDTLS_PRIVATE(out_iv); /*!< ivlen-byte IV */ 1589 unsigned char *MBEDTLS_PRIVATE(out_msg); /*!< message contents (out_iv+ivlen) */ 1590 1591 int MBEDTLS_PRIVATE(out_msgtype); /*!< record header: message type */ 1592 size_t MBEDTLS_PRIVATE(out_msglen); /*!< record header: message length */ 1593 size_t MBEDTLS_PRIVATE(out_left); /*!< amount of data not yet written */ 1594 #if defined(MBEDTLS_SSL_VARIABLE_BUFFER_LENGTH) 1595 size_t MBEDTLS_PRIVATE(out_buf_len); /*!< length of output buffer */ 1596 #endif 1597 1598 unsigned char MBEDTLS_PRIVATE(cur_out_ctr)[MBEDTLS_SSL_SEQUENCE_NUMBER_LEN]; /*!< Outgoing record sequence number. */ 1599 1600 #if defined(MBEDTLS_SSL_PROTO_DTLS) 1601 uint16_t MBEDTLS_PRIVATE(mtu); /*!< path mtu, used to fragment outgoing messages */ 1602 #endif /* MBEDTLS_SSL_PROTO_DTLS */ 1603 1604 /* 1605 * PKI layer 1606 */ 1607 int MBEDTLS_PRIVATE(client_auth); /*!< flag for client auth. */ 1608 1609 /* 1610 * User settings 1611 */ 1612 #if defined(MBEDTLS_X509_CRT_PARSE_C) 1613 char *MBEDTLS_PRIVATE(hostname); /*!< expected peer CN for verification 1614 (and SNI if available) */ 1615 #endif /* MBEDTLS_X509_CRT_PARSE_C */ 1616 1617 #if defined(MBEDTLS_SSL_ALPN) 1618 const char *MBEDTLS_PRIVATE(alpn_chosen); /*!< negotiated protocol */ 1619 #endif /* MBEDTLS_SSL_ALPN */ 1620 1621 #if defined(MBEDTLS_SSL_DTLS_SRTP) 1622 /* 1623 * use_srtp extension 1624 */ 1625 mbedtls_dtls_srtp_info MBEDTLS_PRIVATE(dtls_srtp_info); 1626 #endif /* MBEDTLS_SSL_DTLS_SRTP */ 1627 1628 /* 1629 * Information for DTLS hello verify 1630 */ 1631 #if defined(MBEDTLS_SSL_DTLS_HELLO_VERIFY) && defined(MBEDTLS_SSL_SRV_C) 1632 unsigned char *MBEDTLS_PRIVATE(cli_id); /*!< transport-level ID of the client */ 1633 size_t MBEDTLS_PRIVATE(cli_id_len); /*!< length of cli_id */ 1634 #endif /* MBEDTLS_SSL_DTLS_HELLO_VERIFY && MBEDTLS_SSL_SRV_C */ 1635 1636 /* 1637 * Secure renegotiation 1638 */ 1639 /* needed to know when to send extension on server */ 1640 int MBEDTLS_PRIVATE(secure_renegotiation); /*!< does peer support legacy or 1641 secure renegotiation */ 1642 #if defined(MBEDTLS_SSL_RENEGOTIATION) 1643 size_t MBEDTLS_PRIVATE(verify_data_len); /*!< length of verify data stored */ 1644 char MBEDTLS_PRIVATE(own_verify_data)[MBEDTLS_SSL_VERIFY_DATA_MAX_LEN]; /*!< previous handshake verify data */ 1645 char MBEDTLS_PRIVATE(peer_verify_data)[MBEDTLS_SSL_VERIFY_DATA_MAX_LEN]; /*!< previous handshake verify data */ 1646 #endif /* MBEDTLS_SSL_RENEGOTIATION */ 1647 1648 #if defined(MBEDTLS_SSL_DTLS_CONNECTION_ID) 1649 /* CID configuration to use in subsequent handshakes. */ 1650 1651 /*! The next incoming CID, chosen by the user and applying to 1652 * all subsequent handshakes. This may be different from the 1653 * CID currently used in case the user has re-configured the CID 1654 * after an initial handshake. */ 1655 unsigned char MBEDTLS_PRIVATE(own_cid)[ MBEDTLS_SSL_CID_IN_LEN_MAX ]; 1656 uint8_t MBEDTLS_PRIVATE(own_cid_len); /*!< The length of \c own_cid. */ 1657 uint8_t MBEDTLS_PRIVATE(negotiate_cid); /*!< This indicates whether the CID extension should 1658 * be negotiated in the next handshake or not. 1659 * Possible values are #MBEDTLS_SSL_CID_ENABLED 1660 * and #MBEDTLS_SSL_CID_DISABLED. */ 1661 #endif /* MBEDTLS_SSL_DTLS_CONNECTION_ID */ 1662 1663 /** Callback to export key block and master secret */ 1664 mbedtls_ssl_export_keys_t *MBEDTLS_PRIVATE(f_export_keys); 1665 void *MBEDTLS_PRIVATE(p_export_keys); /*!< context for key export callback */ 1666 }; 1667 1668 /** 1669 * \brief Return the name of the ciphersuite associated with the 1670 * given ID 1671 * 1672 * \param ciphersuite_id SSL ciphersuite ID 1673 * 1674 * \return a string containing the ciphersuite name 1675 */ 1676 const char *mbedtls_ssl_get_ciphersuite_name( const int ciphersuite_id ); 1677 1678 /** 1679 * \brief Return the ID of the ciphersuite associated with the 1680 * given name 1681 * 1682 * \param ciphersuite_name SSL ciphersuite name 1683 * 1684 * \return the ID with the ciphersuite or 0 if not found 1685 */ 1686 int mbedtls_ssl_get_ciphersuite_id( const char *ciphersuite_name ); 1687 1688 /** 1689 * \brief Initialize an SSL context 1690 * Just makes the context ready for mbedtls_ssl_setup() or 1691 * mbedtls_ssl_free() 1692 * 1693 * \param ssl SSL context 1694 */ 1695 void mbedtls_ssl_init( mbedtls_ssl_context *ssl ); 1696 1697 /** 1698 * \brief Set up an SSL context for use 1699 * 1700 * \note No copy of the configuration context is made, it can be 1701 * shared by many mbedtls_ssl_context structures. 1702 * 1703 * \warning The conf structure will be accessed during the session. 1704 * It must not be modified or freed as long as the session 1705 * is active. 1706 * 1707 * \warning This function must be called exactly once per context. 1708 * Calling mbedtls_ssl_setup again is not supported, even 1709 * if no session is active. 1710 * 1711 * \param ssl SSL context 1712 * \param conf SSL configuration to use 1713 * 1714 * \return 0 if successful, or MBEDTLS_ERR_SSL_ALLOC_FAILED if 1715 * memory allocation failed 1716 */ 1717 int mbedtls_ssl_setup( mbedtls_ssl_context *ssl, 1718 const mbedtls_ssl_config *conf ); 1719 1720 /** 1721 * \brief Reset an already initialized SSL context for re-use 1722 * while retaining application-set variables, function 1723 * pointers and data. 1724 * 1725 * \param ssl SSL context 1726 * \return 0 if successful, or MBEDTLS_ERR_SSL_ALLOC_FAILED or 1727 MBEDTLS_ERR_SSL_HW_ACCEL_FAILED 1728 */ 1729 int mbedtls_ssl_session_reset( mbedtls_ssl_context *ssl ); 1730 1731 /** 1732 * \brief Set the current endpoint type 1733 * 1734 * \param conf SSL configuration 1735 * \param endpoint must be MBEDTLS_SSL_IS_CLIENT or MBEDTLS_SSL_IS_SERVER 1736 */ 1737 void mbedtls_ssl_conf_endpoint( mbedtls_ssl_config *conf, int endpoint ); 1738 1739 /** 1740 * \brief Set the transport type (TLS or DTLS). 1741 * Default: TLS 1742 * 1743 * \note For DTLS, you must either provide a recv callback that 1744 * doesn't block, or one that handles timeouts, see 1745 * \c mbedtls_ssl_set_bio(). You also need to provide timer 1746 * callbacks with \c mbedtls_ssl_set_timer_cb(). 1747 * 1748 * \param conf SSL configuration 1749 * \param transport transport type: 1750 * MBEDTLS_SSL_TRANSPORT_STREAM for TLS, 1751 * MBEDTLS_SSL_TRANSPORT_DATAGRAM for DTLS. 1752 */ 1753 void mbedtls_ssl_conf_transport( mbedtls_ssl_config *conf, int transport ); 1754 1755 /** 1756 * \brief Set the certificate verification mode 1757 * Default: NONE on server, REQUIRED on client 1758 * 1759 * \param conf SSL configuration 1760 * \param authmode can be: 1761 * 1762 * MBEDTLS_SSL_VERIFY_NONE: peer certificate is not checked 1763 * (default on server) 1764 * (insecure on client) 1765 * 1766 * MBEDTLS_SSL_VERIFY_OPTIONAL: peer certificate is checked, however the 1767 * handshake continues even if verification failed; 1768 * mbedtls_ssl_get_verify_result() can be called after the 1769 * handshake is complete. 1770 * 1771 * MBEDTLS_SSL_VERIFY_REQUIRED: peer *must* present a valid certificate, 1772 * handshake is aborted if verification failed. 1773 * (default on client) 1774 * 1775 * \note On client, MBEDTLS_SSL_VERIFY_REQUIRED is the recommended mode. 1776 * With MBEDTLS_SSL_VERIFY_OPTIONAL, the user needs to call mbedtls_ssl_get_verify_result() at 1777 * the right time(s), which may not be obvious, while REQUIRED always perform 1778 * the verification as soon as possible. For example, REQUIRED was protecting 1779 * against the "triple handshake" attack even before it was found. 1780 */ 1781 void mbedtls_ssl_conf_authmode( mbedtls_ssl_config *conf, int authmode ); 1782 1783 #if defined(MBEDTLS_X509_CRT_PARSE_C) 1784 /** 1785 * \brief Set the verification callback (Optional). 1786 * 1787 * If set, the provided verify callback is called for each 1788 * certificate in the peer's CRT chain, including the trusted 1789 * root. For more information, please see the documentation of 1790 * \c mbedtls_x509_crt_verify(). 1791 * 1792 * \note For per context callbacks and contexts, please use 1793 * mbedtls_ssl_set_verify() instead. 1794 * 1795 * \param conf The SSL configuration to use. 1796 * \param f_vrfy The verification callback to use during CRT verification. 1797 * \param p_vrfy The opaque context to be passed to the callback. 1798 */ 1799 void mbedtls_ssl_conf_verify( mbedtls_ssl_config *conf, 1800 int (*f_vrfy)(void *, mbedtls_x509_crt *, int, uint32_t *), 1801 void *p_vrfy ); 1802 #endif /* MBEDTLS_X509_CRT_PARSE_C */ 1803 1804 /** 1805 * \brief Set the random number generator callback 1806 * 1807 * \param conf SSL configuration 1808 * \param f_rng RNG function (mandatory) 1809 * \param p_rng RNG parameter 1810 */ 1811 void mbedtls_ssl_conf_rng( mbedtls_ssl_config *conf, 1812 int (*f_rng)(void *, unsigned char *, size_t), 1813 void *p_rng ); 1814 1815 /** 1816 * \brief Set the debug callback 1817 * 1818 * The callback has the following argument: 1819 * void * opaque context for the callback 1820 * int debug level 1821 * const char * file name 1822 * int line number 1823 * const char * message 1824 * 1825 * \param conf SSL configuration 1826 * \param f_dbg debug function 1827 * \param p_dbg debug parameter 1828 */ 1829 void mbedtls_ssl_conf_dbg( mbedtls_ssl_config *conf, 1830 void (*f_dbg)(void *, int, const char *, int, const char *), 1831 void *p_dbg ); 1832 1833 /** 1834 * \brief Set the underlying BIO callbacks for write, read and 1835 * read-with-timeout. 1836 * 1837 * \param ssl SSL context 1838 * \param p_bio parameter (context) shared by BIO callbacks 1839 * \param f_send write callback 1840 * \param f_recv read callback 1841 * \param f_recv_timeout blocking read callback with timeout. 1842 * 1843 * \note One of f_recv or f_recv_timeout can be NULL, in which case 1844 * the other is used. If both are non-NULL, f_recv_timeout is 1845 * used and f_recv is ignored (as if it were NULL). 1846 * 1847 * \note The two most common use cases are: 1848 * - non-blocking I/O, f_recv != NULL, f_recv_timeout == NULL 1849 * - blocking I/O, f_recv == NULL, f_recv_timout != NULL 1850 * 1851 * \note For DTLS, you need to provide either a non-NULL 1852 * f_recv_timeout callback, or a f_recv that doesn't block. 1853 * 1854 * \note See the documentations of \c mbedtls_ssl_send_t, 1855 * \c mbedtls_ssl_recv_t and \c mbedtls_ssl_recv_timeout_t for 1856 * the conventions those callbacks must follow. 1857 * 1858 * \note On some platforms, net_sockets.c provides 1859 * \c mbedtls_net_send(), \c mbedtls_net_recv() and 1860 * \c mbedtls_net_recv_timeout() that are suitable to be used 1861 * here. 1862 */ 1863 void mbedtls_ssl_set_bio( mbedtls_ssl_context *ssl, 1864 void *p_bio, 1865 mbedtls_ssl_send_t *f_send, 1866 mbedtls_ssl_recv_t *f_recv, 1867 mbedtls_ssl_recv_timeout_t *f_recv_timeout ); 1868 1869 #if defined(MBEDTLS_SSL_PROTO_DTLS) 1870 1871 #if defined(MBEDTLS_SSL_DTLS_CONNECTION_ID) 1872 1873 1874 /** 1875 * \brief Configure the use of the Connection ID (CID) 1876 * extension in the next handshake. 1877 * 1878 * Reference: draft-ietf-tls-dtls-connection-id-05 1879 * https://tools.ietf.org/html/draft-ietf-tls-dtls-connection-id-05 1880 * 1881 * The DTLS CID extension allows the reliable association of 1882 * DTLS records to DTLS connections across changes in the 1883 * underlying transport (changed IP and Port metadata) by 1884 * adding explicit connection identifiers (CIDs) to the 1885 * headers of encrypted DTLS records. The desired CIDs are 1886 * configured by the application layer and are exchanged in 1887 * new `ClientHello` / `ServerHello` extensions during the 1888 * handshake, where each side indicates the CID it wants the 1889 * peer to use when writing encrypted messages. The CIDs are 1890 * put to use once records get encrypted: the stack discards 1891 * any incoming records that don't include the configured CID 1892 * in their header, and adds the peer's requested CID to the 1893 * headers of outgoing messages. 1894 * 1895 * This API enables or disables the use of the CID extension 1896 * in the next handshake and sets the value of the CID to 1897 * be used for incoming messages. 1898 * 1899 * \param ssl The SSL context to configure. This must be initialized. 1900 * \param enable This value determines whether the CID extension should 1901 * be used or not. Possible values are: 1902 * - MBEDTLS_SSL_CID_ENABLED to enable the use of the CID. 1903 * - MBEDTLS_SSL_CID_DISABLED (default) to disable the use 1904 * of the CID. 1905 * \param own_cid The address of the readable buffer holding the CID we want 1906 * the peer to use when sending encrypted messages to us. 1907 * This may be \c NULL if \p own_cid_len is \c 0. 1908 * This parameter is unused if \p enabled is set to 1909 * MBEDTLS_SSL_CID_DISABLED. 1910 * \param own_cid_len The length of \p own_cid. 1911 * This parameter is unused if \p enabled is set to 1912 * MBEDTLS_SSL_CID_DISABLED. 1913 * 1914 * \note The value of \p own_cid_len must match the value of the 1915 * \c len parameter passed to mbedtls_ssl_conf_cid() 1916 * when configuring the ::mbedtls_ssl_config that \p ssl 1917 * is bound to. 1918 * 1919 * \note This CID configuration applies to subsequent handshakes 1920 * performed on the SSL context \p ssl, but does not trigger 1921 * one. You still have to call `mbedtls_ssl_handshake()` 1922 * (for the initial handshake) or `mbedtls_ssl_renegotiate()` 1923 * (for a renegotiation handshake) explicitly after a 1924 * successful call to this function to run the handshake. 1925 * 1926 * \note This call cannot guarantee that the use of the CID 1927 * will be successfully negotiated in the next handshake, 1928 * because the peer might not support it. Specifically: 1929 * - On the Client, enabling the use of the CID through 1930 * this call implies that the `ClientHello` in the next 1931 * handshake will include the CID extension, thereby 1932 * offering the use of the CID to the server. Only if 1933 * the `ServerHello` contains the CID extension, too, 1934 * the CID extension will actually be put to use. 1935 * - On the Server, enabling the use of the CID through 1936 * this call implies that that the server will look for 1937 * the CID extension in a `ClientHello` from the client, 1938 * and, if present, reply with a CID extension in its 1939 * `ServerHello`. 1940 * 1941 * \note To check whether the use of the CID was negotiated 1942 * after the subsequent handshake has completed, please 1943 * use the API mbedtls_ssl_get_peer_cid(). 1944 * 1945 * \warning If the use of the CID extension is enabled in this call 1946 * and the subsequent handshake negotiates its use, Mbed TLS 1947 * will silently drop every packet whose CID does not match 1948 * the CID configured in \p own_cid. It is the responsibility 1949 * of the user to adapt the underlying transport to take care 1950 * of CID-based demultiplexing before handing datagrams to 1951 * Mbed TLS. 1952 * 1953 * \return \c 0 on success. In this case, the CID configuration 1954 * applies to the next handshake. 1955 * \return A negative error code on failure. 1956 */ 1957 int mbedtls_ssl_set_cid( mbedtls_ssl_context *ssl, 1958 int enable, 1959 unsigned char const *own_cid, 1960 size_t own_cid_len ); 1961 1962 /** 1963 * \brief Get information about the use of the CID extension 1964 * in the current connection. 1965 * 1966 * \param ssl The SSL context to query. 1967 * \param enabled The address at which to store whether the CID extension 1968 * is currently in use or not. If the CID is in use, 1969 * `*enabled` is set to MBEDTLS_SSL_CID_ENABLED; 1970 * otherwise, it is set to MBEDTLS_SSL_CID_DISABLED. 1971 * \param peer_cid The address of the buffer in which to store the CID 1972 * chosen by the peer (if the CID extension is used). 1973 * This may be \c NULL in case the value of peer CID 1974 * isn't needed. If it is not \c NULL, \p peer_cid_len 1975 * must not be \c NULL. 1976 * \param peer_cid_len The address at which to store the size of the CID 1977 * chosen by the peer (if the CID extension is used). 1978 * This is also the number of Bytes in \p peer_cid that 1979 * have been written. 1980 * This may be \c NULL in case the length of the peer CID 1981 * isn't needed. If it is \c NULL, \p peer_cid must be 1982 * \c NULL, too. 1983 * 1984 * \note This applies to the state of the CID negotiated in 1985 * the last complete handshake. If a handshake is in 1986 * progress, this function will attempt to complete 1987 * the handshake first. 1988 * 1989 * \note If CID extensions have been exchanged but both client 1990 * and server chose to use an empty CID, this function 1991 * sets `*enabled` to #MBEDTLS_SSL_CID_DISABLED 1992 * (the rationale for this is that the resulting 1993 * communication is the same as if the CID extensions 1994 * hadn't been used). 1995 * 1996 * \return \c 0 on success. 1997 * \return A negative error code on failure. 1998 */ 1999 int mbedtls_ssl_get_peer_cid( mbedtls_ssl_context *ssl, 2000 int *enabled, 2001 unsigned char peer_cid[ MBEDTLS_SSL_CID_OUT_LEN_MAX ], 2002 size_t *peer_cid_len ); 2003 2004 #endif /* MBEDTLS_SSL_DTLS_CONNECTION_ID */ 2005 2006 /** 2007 * \brief Set the Maximum Tranport Unit (MTU). 2008 * Special value: 0 means unset (no limit). 2009 * This represents the maximum size of a datagram payload 2010 * handled by the transport layer (usually UDP) as determined 2011 * by the network link and stack. In practice, this controls 2012 * the maximum size datagram the DTLS layer will pass to the 2013 * \c f_send() callback set using \c mbedtls_ssl_set_bio(). 2014 * 2015 * \note The limit on datagram size is converted to a limit on 2016 * record payload by subtracting the current overhead of 2017 * encapsulation and encryption/authentication if any. 2018 * 2019 * \note This can be called at any point during the connection, for 2020 * example when a Path Maximum Transfer Unit (PMTU) 2021 * estimate becomes available from other sources, 2022 * such as lower (or higher) protocol layers. 2023 * 2024 * \note This setting only controls the size of the packets we send, 2025 * and does not restrict the size of the datagrams we're 2026 * willing to receive. Client-side, you can request the 2027 * server to use smaller records with \c 2028 * mbedtls_ssl_conf_max_frag_len(). 2029 * 2030 * \note If both a MTU and a maximum fragment length have been 2031 * configured (or negotiated with the peer), the resulting 2032 * lower limit on record payload (see first note) is used. 2033 * 2034 * \note This can only be used to decrease the maximum size 2035 * of datagrams (hence records, see first note) sent. It 2036 * cannot be used to increase the maximum size of records over 2037 * the limit set by #MBEDTLS_SSL_OUT_CONTENT_LEN. 2038 * 2039 * \note Values lower than the current record layer expansion will 2040 * result in an error when trying to send data. 2041 * 2042 * \param ssl SSL context 2043 * \param mtu Value of the path MTU in bytes 2044 */ 2045 void mbedtls_ssl_set_mtu( mbedtls_ssl_context *ssl, uint16_t mtu ); 2046 #endif /* MBEDTLS_SSL_PROTO_DTLS */ 2047 2048 #if defined(MBEDTLS_X509_CRT_PARSE_C) 2049 /** 2050 * \brief Set a connection-specific verification callback (optional). 2051 * 2052 * If set, the provided verify callback is called for each 2053 * certificate in the peer's CRT chain, including the trusted 2054 * root. For more information, please see the documentation of 2055 * \c mbedtls_x509_crt_verify(). 2056 * 2057 * \note This call is analogous to mbedtls_ssl_conf_verify() but 2058 * binds the verification callback and context to an SSL context 2059 * as opposed to an SSL configuration. 2060 * If mbedtls_ssl_conf_verify() and mbedtls_ssl_set_verify() 2061 * are both used, mbedtls_ssl_set_verify() takes precedence. 2062 * 2063 * \param ssl The SSL context to use. 2064 * \param f_vrfy The verification callback to use during CRT verification. 2065 * \param p_vrfy The opaque context to be passed to the callback. 2066 */ 2067 void mbedtls_ssl_set_verify( mbedtls_ssl_context *ssl, 2068 int (*f_vrfy)(void *, mbedtls_x509_crt *, int, uint32_t *), 2069 void *p_vrfy ); 2070 #endif /* MBEDTLS_X509_CRT_PARSE_C */ 2071 2072 /** 2073 * \brief Set the timeout period for mbedtls_ssl_read() 2074 * (Default: no timeout.) 2075 * 2076 * \param conf SSL configuration context 2077 * \param timeout Timeout value in milliseconds. 2078 * Use 0 for no timeout (default). 2079 * 2080 * \note With blocking I/O, this will only work if a non-NULL 2081 * \c f_recv_timeout was set with \c mbedtls_ssl_set_bio(). 2082 * With non-blocking I/O, this will only work if timer 2083 * callbacks were set with \c mbedtls_ssl_set_timer_cb(). 2084 * 2085 * \note With non-blocking I/O, you may also skip this function 2086 * altogether and handle timeouts at the application layer. 2087 */ 2088 void mbedtls_ssl_conf_read_timeout( mbedtls_ssl_config *conf, uint32_t timeout ); 2089 2090 /** 2091 * \brief Check whether a buffer contains a valid and authentic record 2092 * that has not been seen before. (DTLS only). 2093 * 2094 * This function does not change the user-visible state 2095 * of the SSL context. Its sole purpose is to provide 2096 * an indication of the legitimacy of an incoming record. 2097 * 2098 * This can be useful e.g. in distributed server environments 2099 * using the DTLS Connection ID feature, in which connections 2100 * might need to be passed between service instances on a change 2101 * of peer address, but where such disruptive operations should 2102 * only happen after the validity of incoming records has been 2103 * confirmed. 2104 * 2105 * \param ssl The SSL context to use. 2106 * \param buf The address of the buffer holding the record to be checked. 2107 * This must be a read/write buffer of length \p buflen Bytes. 2108 * \param buflen The length of \p buf in Bytes. 2109 * 2110 * \note This routine only checks whether the provided buffer begins 2111 * with a valid and authentic record that has not been seen 2112 * before, but does not check potential data following the 2113 * initial record. In particular, it is possible to pass DTLS 2114 * datagrams containing multiple records, in which case only 2115 * the first record is checked. 2116 * 2117 * \note This function modifies the input buffer \p buf. If you need 2118 * to preserve the original record, you have to maintain a copy. 2119 * 2120 * \return \c 0 if the record is valid and authentic and has not been 2121 * seen before. 2122 * \return MBEDTLS_ERR_SSL_INVALID_MAC if the check completed 2123 * successfully but the record was found to be not authentic. 2124 * \return MBEDTLS_ERR_SSL_INVALID_RECORD if the check completed 2125 * successfully but the record was found to be invalid for 2126 * a reason different from authenticity checking. 2127 * \return MBEDTLS_ERR_SSL_UNEXPECTED_RECORD if the check completed 2128 * successfully but the record was found to be unexpected 2129 * in the state of the SSL context, including replayed records. 2130 * \return Another negative error code on different kinds of failure. 2131 * In this case, the SSL context becomes unusable and needs 2132 * to be freed or reset before reuse. 2133 */ 2134 int mbedtls_ssl_check_record( mbedtls_ssl_context const *ssl, 2135 unsigned char *buf, 2136 size_t buflen ); 2137 2138 /** 2139 * \brief Set the timer callbacks (Mandatory for DTLS.) 2140 * 2141 * \param ssl SSL context 2142 * \param p_timer parameter (context) shared by timer callbacks 2143 * \param f_set_timer set timer callback 2144 * \param f_get_timer get timer callback. Must return: 2145 * 2146 * \note See the documentation of \c mbedtls_ssl_set_timer_t and 2147 * \c mbedtls_ssl_get_timer_t for the conventions this pair of 2148 * callbacks must follow. 2149 * 2150 * \note On some platforms, timing.c provides 2151 * \c mbedtls_timing_set_delay() and 2152 * \c mbedtls_timing_get_delay() that are suitable for using 2153 * here, except if using an event-driven style. 2154 * 2155 * \note See also the "DTLS tutorial" article in our knowledge base. 2156 * https://tls.mbed.org/kb/how-to/dtls-tutorial 2157 */ 2158 void mbedtls_ssl_set_timer_cb( mbedtls_ssl_context *ssl, 2159 void *p_timer, 2160 mbedtls_ssl_set_timer_t *f_set_timer, 2161 mbedtls_ssl_get_timer_t *f_get_timer ); 2162 2163 /** 2164 * \brief Callback type: generate and write session ticket 2165 * 2166 * \note This describes what a callback implementation should do. 2167 * This callback should generate an encrypted and 2168 * authenticated ticket for the session and write it to the 2169 * output buffer. Here, ticket means the opaque ticket part 2170 * of the NewSessionTicket structure of RFC 5077. 2171 * 2172 * \param p_ticket Context for the callback 2173 * \param session SSL session to be written in the ticket 2174 * \param start Start of the output buffer 2175 * \param end End of the output buffer 2176 * \param tlen On exit, holds the length written 2177 * \param lifetime On exit, holds the lifetime of the ticket in seconds 2178 * 2179 * \return 0 if successful, or 2180 * a specific MBEDTLS_ERR_XXX code. 2181 */ 2182 typedef int mbedtls_ssl_ticket_write_t( void *p_ticket, 2183 const mbedtls_ssl_session *session, 2184 unsigned char *start, 2185 const unsigned char *end, 2186 size_t *tlen, 2187 uint32_t *lifetime ); 2188 2189 /** 2190 * \brief Callback type: parse and load session ticket 2191 * 2192 * \note This describes what a callback implementation should do. 2193 * This callback should parse a session ticket as generated 2194 * by the corresponding mbedtls_ssl_ticket_write_t function, 2195 * and, if the ticket is authentic and valid, load the 2196 * session. 2197 * 2198 * \note The implementation is allowed to modify the first len 2199 * bytes of the input buffer, eg to use it as a temporary 2200 * area for the decrypted ticket contents. 2201 * 2202 * \param p_ticket Context for the callback 2203 * \param session SSL session to be loaded 2204 * \param buf Start of the buffer containing the ticket 2205 * \param len Length of the ticket. 2206 * 2207 * \return 0 if successful, or 2208 * MBEDTLS_ERR_SSL_INVALID_MAC if not authentic, or 2209 * MBEDTLS_ERR_SSL_SESSION_TICKET_EXPIRED if expired, or 2210 * any other non-zero code for other failures. 2211 */ 2212 typedef int mbedtls_ssl_ticket_parse_t( void *p_ticket, 2213 mbedtls_ssl_session *session, 2214 unsigned char *buf, 2215 size_t len ); 2216 2217 #if defined(MBEDTLS_SSL_SESSION_TICKETS) && defined(MBEDTLS_SSL_SRV_C) 2218 /** 2219 * \brief Configure SSL session ticket callbacks (server only). 2220 * (Default: none.) 2221 * 2222 * \note On server, session tickets are enabled by providing 2223 * non-NULL callbacks. 2224 * 2225 * \note On client, use \c mbedtls_ssl_conf_session_tickets(). 2226 * 2227 * \param conf SSL configuration context 2228 * \param f_ticket_write Callback for writing a ticket 2229 * \param f_ticket_parse Callback for parsing a ticket 2230 * \param p_ticket Context shared by the two callbacks 2231 */ 2232 void mbedtls_ssl_conf_session_tickets_cb( mbedtls_ssl_config *conf, 2233 mbedtls_ssl_ticket_write_t *f_ticket_write, 2234 mbedtls_ssl_ticket_parse_t *f_ticket_parse, 2235 void *p_ticket ); 2236 #endif /* MBEDTLS_SSL_SESSION_TICKETS && MBEDTLS_SSL_SRV_C */ 2237 2238 /** 2239 * \brief Configure a key export callback. 2240 * (Default: none.) 2241 * 2242 * This API can be used for two purposes: 2243 * - Debugging: Use this API to e.g. generate an NSSKeylog 2244 * file and use it to inspect encrypted traffic in tools 2245 * such as Wireshark. 2246 * - Application-specific export: Use this API to implement 2247 * key exporters, e.g. for EAP-TLS or DTLS-SRTP. 2248 * 2249 * 2250 * \param ssl The SSL context to which the export 2251 * callback should be attached. 2252 * \param f_export_keys The callback for the key export. 2253 * \param p_export_keys The opaque context pointer to be passed to the 2254 * callback \p f_export_keys. 2255 */ 2256 void mbedtls_ssl_set_export_keys_cb( mbedtls_ssl_context *ssl, 2257 mbedtls_ssl_export_keys_t *f_export_keys, 2258 void *p_export_keys ); 2259 2260 #if defined(MBEDTLS_SSL_ASYNC_PRIVATE) 2261 /** 2262 * \brief Configure asynchronous private key operation callbacks. 2263 * 2264 * \param conf SSL configuration context 2265 * \param f_async_sign Callback to start a signature operation. See 2266 * the description of ::mbedtls_ssl_async_sign_t 2267 * for more information. This may be \c NULL if the 2268 * external processor does not support any signature 2269 * operation; in this case the private key object 2270 * associated with the certificate will be used. 2271 * \param f_async_decrypt Callback to start a decryption operation. See 2272 * the description of ::mbedtls_ssl_async_decrypt_t 2273 * for more information. This may be \c NULL if the 2274 * external processor does not support any decryption 2275 * operation; in this case the private key object 2276 * associated with the certificate will be used. 2277 * \param f_async_resume Callback to resume an asynchronous operation. See 2278 * the description of ::mbedtls_ssl_async_resume_t 2279 * for more information. This may not be \c NULL unless 2280 * \p f_async_sign and \p f_async_decrypt are both 2281 * \c NULL. 2282 * \param f_async_cancel Callback to cancel an asynchronous operation. See 2283 * the description of ::mbedtls_ssl_async_cancel_t 2284 * for more information. This may be \c NULL if 2285 * no cleanup is needed. 2286 * \param config_data A pointer to configuration data which can be 2287 * retrieved with 2288 * mbedtls_ssl_conf_get_async_config_data(). The 2289 * library stores this value without dereferencing it. 2290 */ 2291 void mbedtls_ssl_conf_async_private_cb( mbedtls_ssl_config *conf, 2292 mbedtls_ssl_async_sign_t *f_async_sign, 2293 mbedtls_ssl_async_decrypt_t *f_async_decrypt, 2294 mbedtls_ssl_async_resume_t *f_async_resume, 2295 mbedtls_ssl_async_cancel_t *f_async_cancel, 2296 void *config_data ); 2297 2298 /** 2299 * \brief Retrieve the configuration data set by 2300 * mbedtls_ssl_conf_async_private_cb(). 2301 * 2302 * \param conf SSL configuration context 2303 * \return The configuration data set by 2304 * mbedtls_ssl_conf_async_private_cb(). 2305 */ 2306 void *mbedtls_ssl_conf_get_async_config_data( const mbedtls_ssl_config *conf ); 2307 2308 /** 2309 * \brief Retrieve the asynchronous operation user context. 2310 * 2311 * \note This function may only be called while a handshake 2312 * is in progress. 2313 * 2314 * \param ssl The SSL context to access. 2315 * 2316 * \return The asynchronous operation user context that was last 2317 * set during the current handshake. If 2318 * mbedtls_ssl_set_async_operation_data() has not yet been 2319 * called during the current handshake, this function returns 2320 * \c NULL. 2321 */ 2322 void *mbedtls_ssl_get_async_operation_data( const mbedtls_ssl_context *ssl ); 2323 2324 /** 2325 * \brief Retrieve the asynchronous operation user context. 2326 * 2327 * \note This function may only be called while a handshake 2328 * is in progress. 2329 * 2330 * \param ssl The SSL context to access. 2331 * \param ctx The new value of the asynchronous operation user context. 2332 * Call mbedtls_ssl_get_async_operation_data() later during the 2333 * same handshake to retrieve this value. 2334 */ 2335 void mbedtls_ssl_set_async_operation_data( mbedtls_ssl_context *ssl, 2336 void *ctx ); 2337 #endif /* MBEDTLS_SSL_ASYNC_PRIVATE */ 2338 2339 /** 2340 * \brief Callback type: generate a cookie 2341 * 2342 * \param ctx Context for the callback 2343 * \param p Buffer to write to, 2344 * must be updated to point right after the cookie 2345 * \param end Pointer to one past the end of the output buffer 2346 * \param info Client ID info that was passed to 2347 * \c mbedtls_ssl_set_client_transport_id() 2348 * \param ilen Length of info in bytes 2349 * 2350 * \return The callback must return 0 on success, 2351 * or a negative error code. 2352 */ 2353 typedef int mbedtls_ssl_cookie_write_t( void *ctx, 2354 unsigned char **p, unsigned char *end, 2355 const unsigned char *info, size_t ilen ); 2356 2357 /** 2358 * \brief Callback type: verify a cookie 2359 * 2360 * \param ctx Context for the callback 2361 * \param cookie Cookie to verify 2362 * \param clen Length of cookie 2363 * \param info Client ID info that was passed to 2364 * \c mbedtls_ssl_set_client_transport_id() 2365 * \param ilen Length of info in bytes 2366 * 2367 * \return The callback must return 0 if cookie is valid, 2368 * or a negative error code. 2369 */ 2370 typedef int mbedtls_ssl_cookie_check_t( void *ctx, 2371 const unsigned char *cookie, size_t clen, 2372 const unsigned char *info, size_t ilen ); 2373 2374 #if defined(MBEDTLS_SSL_DTLS_HELLO_VERIFY) && defined(MBEDTLS_SSL_SRV_C) 2375 /** 2376 * \brief Register callbacks for DTLS cookies 2377 * (Server only. DTLS only.) 2378 * 2379 * Default: dummy callbacks that fail, in order to force you to 2380 * register working callbacks (and initialize their context). 2381 * 2382 * To disable HelloVerifyRequest, register NULL callbacks. 2383 * 2384 * \warning Disabling hello verification allows your server to be used 2385 * for amplification in DoS attacks against other hosts. 2386 * Only disable if you known this can't happen in your 2387 * particular environment. 2388 * 2389 * \note See comments on \c mbedtls_ssl_handshake() about handling 2390 * the MBEDTLS_ERR_SSL_HELLO_VERIFY_REQUIRED that is expected 2391 * on the first handshake attempt when this is enabled. 2392 * 2393 * \note This is also necessary to handle client reconnection from 2394 * the same port as described in RFC 6347 section 4.2.8 (only 2395 * the variant with cookies is supported currently). See 2396 * comments on \c mbedtls_ssl_read() for details. 2397 * 2398 * \param conf SSL configuration 2399 * \param f_cookie_write Cookie write callback 2400 * \param f_cookie_check Cookie check callback 2401 * \param p_cookie Context for both callbacks 2402 */ 2403 void mbedtls_ssl_conf_dtls_cookies( mbedtls_ssl_config *conf, 2404 mbedtls_ssl_cookie_write_t *f_cookie_write, 2405 mbedtls_ssl_cookie_check_t *f_cookie_check, 2406 void *p_cookie ); 2407 2408 /** 2409 * \brief Set client's transport-level identification info. 2410 * (Server only. DTLS only.) 2411 * 2412 * This is usually the IP address (and port), but could be 2413 * anything identify the client depending on the underlying 2414 * network stack. Used for HelloVerifyRequest with DTLS. 2415 * This is *not* used to route the actual packets. 2416 * 2417 * \param ssl SSL context 2418 * \param info Transport-level info identifying the client (eg IP + port) 2419 * \param ilen Length of info in bytes 2420 * 2421 * \note An internal copy is made, so the info buffer can be reused. 2422 * 2423 * \return 0 on success, 2424 * MBEDTLS_ERR_SSL_BAD_INPUT_DATA if used on client, 2425 * MBEDTLS_ERR_SSL_ALLOC_FAILED if out of memory. 2426 */ 2427 int mbedtls_ssl_set_client_transport_id( mbedtls_ssl_context *ssl, 2428 const unsigned char *info, 2429 size_t ilen ); 2430 2431 #endif /* MBEDTLS_SSL_DTLS_HELLO_VERIFY && MBEDTLS_SSL_SRV_C */ 2432 2433 #if defined(MBEDTLS_SSL_DTLS_ANTI_REPLAY) 2434 /** 2435 * \brief Enable or disable anti-replay protection for DTLS. 2436 * (DTLS only, no effect on TLS.) 2437 * Default: enabled. 2438 * 2439 * \param conf SSL configuration 2440 * \param mode MBEDTLS_SSL_ANTI_REPLAY_ENABLED or MBEDTLS_SSL_ANTI_REPLAY_DISABLED. 2441 * 2442 * \warning Disabling this is a security risk unless the application 2443 * protocol handles duplicated packets in a safe way. You 2444 * should not disable this without careful consideration. 2445 * However, if your application already detects duplicated 2446 * packets and needs information about them to adjust its 2447 * transmission strategy, then you'll want to disable this. 2448 */ 2449 void mbedtls_ssl_conf_dtls_anti_replay( mbedtls_ssl_config *conf, char mode ); 2450 #endif /* MBEDTLS_SSL_DTLS_ANTI_REPLAY */ 2451 2452 /** 2453 * \brief Set a limit on the number of records with a bad MAC 2454 * before terminating the connection. 2455 * (DTLS only, no effect on TLS.) 2456 * Default: 0 (disabled). 2457 * 2458 * \param conf SSL configuration 2459 * \param limit Limit, or 0 to disable. 2460 * 2461 * \note If the limit is N, then the connection is terminated when 2462 * the Nth non-authentic record is seen. 2463 * 2464 * \note Records with an invalid header are not counted, only the 2465 * ones going through the authentication-decryption phase. 2466 * 2467 * \note This is a security trade-off related to the fact that it's 2468 * often relatively easy for an active attacker ot inject UDP 2469 * datagrams. On one hand, setting a low limit here makes it 2470 * easier for such an attacker to forcibly terminated a 2471 * connection. On the other hand, a high limit or no limit 2472 * might make us waste resources checking authentication on 2473 * many bogus packets. 2474 */ 2475 void mbedtls_ssl_conf_dtls_badmac_limit( mbedtls_ssl_config *conf, unsigned limit ); 2476 2477 #if defined(MBEDTLS_SSL_PROTO_DTLS) 2478 2479 /** 2480 * \brief Allow or disallow packing of multiple handshake records 2481 * within a single datagram. 2482 * 2483 * \param ssl The SSL context to configure. 2484 * \param allow_packing This determines whether datagram packing may 2485 * be used or not. A value of \c 0 means that every 2486 * record will be sent in a separate datagram; a 2487 * value of \c 1 means that, if space permits, 2488 * multiple handshake messages (including CCS) belonging to 2489 * a single flight may be packed within a single datagram. 2490 * 2491 * \note This is enabled by default and should only be disabled 2492 * for test purposes, or if datagram packing causes 2493 * interoperability issues with peers that don't support it. 2494 * 2495 * \note Allowing datagram packing reduces the network load since 2496 * there's less overhead if multiple messages share the same 2497 * datagram. Also, it increases the handshake efficiency 2498 * since messages belonging to a single datagram will not 2499 * be reordered in transit, and so future message buffering 2500 * or flight retransmission (if no buffering is used) as 2501 * means to deal with reordering are needed less frequently. 2502 * 2503 * \note Application records are not affected by this option and 2504 * are currently always sent in separate datagrams. 2505 * 2506 */ 2507 void mbedtls_ssl_set_datagram_packing( mbedtls_ssl_context *ssl, 2508 unsigned allow_packing ); 2509 2510 /** 2511 * \brief Set retransmit timeout values for the DTLS handshake. 2512 * (DTLS only, no effect on TLS.) 2513 * 2514 * \param conf SSL configuration 2515 * \param min Initial timeout value in milliseconds. 2516 * Default: 1000 (1 second). 2517 * \param max Maximum timeout value in milliseconds. 2518 * Default: 60000 (60 seconds). 2519 * 2520 * \note Default values are from RFC 6347 section 4.2.4.1. 2521 * 2522 * \note The 'min' value should typically be slightly above the 2523 * expected round-trip time to your peer, plus whatever time 2524 * it takes for the peer to process the message. For example, 2525 * if your RTT is about 600ms and you peer needs up to 1s to 2526 * do the cryptographic operations in the handshake, then you 2527 * should set 'min' slightly above 1600. Lower values of 'min' 2528 * might cause spurious resends which waste network resources, 2529 * while larger value of 'min' will increase overall latency 2530 * on unreliable network links. 2531 * 2532 * \note The more unreliable your network connection is, the larger 2533 * your max / min ratio needs to be in order to achieve 2534 * reliable handshakes. 2535 * 2536 * \note Messages are retransmitted up to log2(ceil(max/min)) times. 2537 * For example, if min = 1s and max = 5s, the retransmit plan 2538 * goes: send ... 1s -> resend ... 2s -> resend ... 4s -> 2539 * resend ... 5s -> give up and return a timeout error. 2540 */ 2541 void mbedtls_ssl_conf_handshake_timeout( mbedtls_ssl_config *conf, uint32_t min, uint32_t max ); 2542 #endif /* MBEDTLS_SSL_PROTO_DTLS */ 2543 2544 #if defined(MBEDTLS_SSL_SRV_C) 2545 /** 2546 * \brief Set the session cache callbacks (server-side only) 2547 * If not set, no session resuming is done (except if session 2548 * tickets are enabled too). 2549 * 2550 * The session cache has the responsibility to check for stale 2551 * entries based on timeout. See RFC 5246 for recommendations. 2552 * 2553 * Warning: session.peer_cert is cleared by the SSL/TLS layer on 2554 * connection shutdown, so do not cache the pointer! Either set 2555 * it to NULL or make a full copy of the certificate. 2556 * 2557 * The get callback is called once during the initial handshake 2558 * to enable session resuming. The get function has the 2559 * following parameters: (void *parameter, mbedtls_ssl_session *session) 2560 * If a valid entry is found, it should fill the master of 2561 * the session object with the cached values and return 0, 2562 * return 1 otherwise. Optionally peer_cert can be set as well 2563 * if it is properly present in cache entry. 2564 * 2565 * The set callback is called once during the initial handshake 2566 * to enable session resuming after the entire handshake has 2567 * been finished. The set function has the following parameters: 2568 * (void *parameter, const mbedtls_ssl_session *session). The function 2569 * should create a cache entry for future retrieval based on 2570 * the data in the session structure and should keep in mind 2571 * that the mbedtls_ssl_session object presented (and all its referenced 2572 * data) is cleared by the SSL/TLS layer when the connection is 2573 * terminated. It is recommended to add metadata to determine if 2574 * an entry is still valid in the future. Return 0 if 2575 * successfully cached, return 1 otherwise. 2576 * 2577 * \param conf SSL configuration 2578 * \param p_cache parmater (context) for both callbacks 2579 * \param f_get_cache session get callback 2580 * \param f_set_cache session set callback 2581 */ 2582 void mbedtls_ssl_conf_session_cache( mbedtls_ssl_config *conf, 2583 void *p_cache, 2584 mbedtls_ssl_cache_get_t *f_get_cache, 2585 mbedtls_ssl_cache_set_t *f_set_cache ); 2586 #endif /* MBEDTLS_SSL_SRV_C */ 2587 2588 #if defined(MBEDTLS_SSL_CLI_C) 2589 /** 2590 * \brief Load a session for session resumption. 2591 * 2592 * Sessions loaded through this call will be considered 2593 * for session resumption in the next handshake. 2594 * 2595 * \note Even if this call succeeds, it is not guaranteed that 2596 * the next handshake will indeed be shortened through the 2597 * use of session resumption: The server is always free 2598 * to reject any attempt for resumption and fall back to 2599 * a full handshake. 2600 * 2601 * \note This function can handle a variety of mechanisms for session 2602 * resumption: For TLS 1.2, both session ID-based resumption and 2603 * ticket-based resumption will be considered. For TLS 1.3, 2604 * once implemented, sessions equate to tickets, and loading 2605 * one or more sessions via this call will lead to their 2606 * corresponding tickets being advertised as resumption PSKs 2607 * by the client. 2608 * 2609 * \note Calling this function multiple times will only be useful 2610 * once TLS 1.3 is supported. For TLS 1.2 connections, this 2611 * function should be called at most once. 2612 * 2613 * \param ssl The SSL context representing the connection which should 2614 * be attempted to be setup using session resumption. This 2615 * must be initialized via mbedtls_ssl_init() and bound to 2616 * an SSL configuration via mbedtls_ssl_setup(), but 2617 * the handshake must not yet have been started. 2618 * \param session The session to be considered for session resumption. 2619 * This must be a session previously exported via 2620 * mbedtls_ssl_get_session(), and potentially serialized and 2621 * deserialized through mbedtls_ssl_session_save() and 2622 * mbedtls_ssl_session_load() in the meantime. 2623 * 2624 * \return \c 0 if successful. 2625 * \return \c MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE if the session 2626 * could not be loaded because of an implementation limitation. 2627 * This error is non-fatal, and has no observable effect on 2628 * the SSL context or the session that was attempted to be loaded. 2629 * \return Another negative error code on other kinds of failure. 2630 * 2631 * \sa mbedtls_ssl_get_session() 2632 * \sa mbedtls_ssl_session_load() 2633 */ 2634 int mbedtls_ssl_set_session( mbedtls_ssl_context *ssl, const mbedtls_ssl_session *session ); 2635 #endif /* MBEDTLS_SSL_CLI_C */ 2636 2637 /** 2638 * \brief Load serialized session data into a session structure. 2639 * On client, this can be used for loading saved sessions 2640 * before resuming them with mbedstls_ssl_set_session(). 2641 * On server, this can be used for alternative implementations 2642 * of session cache or session tickets. 2643 * 2644 * \warning If a peer certificate chain is associated with the session, 2645 * the serialized state will only contain the peer's 2646 * end-entity certificate and the result of the chain 2647 * verification (unless verification was disabled), but not 2648 * the rest of the chain. 2649 * 2650 * \see mbedtls_ssl_session_save() 2651 * \see mbedtls_ssl_set_session() 2652 * 2653 * \param session The session structure to be populated. It must have been 2654 * initialised with mbedtls_ssl_session_init() but not 2655 * populated yet. 2656 * \param buf The buffer holding the serialized session data. It must be a 2657 * readable buffer of at least \p len bytes. 2658 * \param len The size of the serialized data in bytes. 2659 * 2660 * \return \c 0 if successful. 2661 * \return #MBEDTLS_ERR_SSL_ALLOC_FAILED if memory allocation failed. 2662 * \return #MBEDTLS_ERR_SSL_BAD_INPUT_DATA if input data is invalid. 2663 * \return #MBEDTLS_ERR_SSL_VERSION_MISMATCH if the serialized data 2664 * was generated in a different version or configuration of 2665 * Mbed TLS. 2666 * \return Another negative value for other kinds of errors (for 2667 * example, unsupported features in the embedded certificate). 2668 */ 2669 int mbedtls_ssl_session_load( mbedtls_ssl_session *session, 2670 const unsigned char *buf, 2671 size_t len ); 2672 2673 /** 2674 * \brief Save session structure as serialized data in a buffer. 2675 * On client, this can be used for saving session data, 2676 * potentially in non-volatile storage, for resuming later. 2677 * On server, this can be used for alternative implementations 2678 * of session cache or session tickets. 2679 * 2680 * \see mbedtls_ssl_session_load() 2681 * 2682 * \param session The session structure to be saved. 2683 * \param buf The buffer to write the serialized data to. It must be a 2684 * writeable buffer of at least \p len bytes, or may be \c 2685 * NULL if \p len is \c 0. 2686 * \param buf_len The number of bytes available for writing in \p buf. 2687 * \param olen The size in bytes of the data that has been or would have 2688 * been written. It must point to a valid \c size_t. 2689 * 2690 * \note \p olen is updated to the correct value regardless of 2691 * whether \p buf_len was large enough. This makes it possible 2692 * to determine the necessary size by calling this function 2693 * with \p buf set to \c NULL and \p buf_len to \c 0. 2694 * 2695 * \return \c 0 if successful. 2696 * \return #MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL if \p buf is too small. 2697 */ 2698 int mbedtls_ssl_session_save( const mbedtls_ssl_session *session, 2699 unsigned char *buf, 2700 size_t buf_len, 2701 size_t *olen ); 2702 2703 /** 2704 * \brief Set the list of allowed ciphersuites and the preference 2705 * order. First in the list has the highest preference. 2706 * 2707 * For TLS 1.2, the notion of ciphersuite determines both 2708 * the key exchange mechanism and the suite of symmetric 2709 * algorithms to be used during and after the handshake. 2710 * 2711 * For TLS 1.3 (in development), the notion of ciphersuite 2712 * only determines the suite of symmetric algorithms to be 2713 * used during and after the handshake, while key exchange 2714 * mechanisms are configured separately. 2715 * 2716 * In Mbed TLS, ciphersuites for both TLS 1.2 and TLS 1.3 2717 * are configured via this function. For users of TLS 1.3, 2718 * there will be separate API for the configuration of key 2719 * exchange mechanisms. 2720 * 2721 * The list of ciphersuites passed to this function may 2722 * contain a mixture of TLS 1.2 and TLS 1.3 ciphersuite 2723 * identifiers. This is useful if negotiation of TLS 1.3 2724 * should be attempted, but a fallback to TLS 1.2 would 2725 * be tolerated. 2726 * 2727 * \note By default, the server chooses its preferred 2728 * ciphersuite among those that the client supports. If 2729 * mbedtls_ssl_conf_preference_order() is called to prefer 2730 * the client's preferences, the server instead chooses 2731 * the client's preferred ciphersuite among those that 2732 * the server supports. 2733 * 2734 * \warning The ciphersuites array \p ciphersuites is not copied. 2735 * It must remain valid for the lifetime of the SSL 2736 * configuration \p conf. 2737 * 2738 * \param conf The SSL configuration to modify. 2739 * \param ciphersuites A 0-terminated list of IANA identifiers of supported 2740 * ciphersuites, accessible through \c MBEDTLS_TLS_XXX 2741 * and \c MBEDTLS_TLS1_3_XXX macros defined in 2742 * ssl_ciphersuites.h. 2743 */ 2744 void mbedtls_ssl_conf_ciphersuites( mbedtls_ssl_config *conf, 2745 const int *ciphersuites ); 2746 2747 #if defined(MBEDTLS_SSL_PROTO_TLS1_3_EXPERIMENTAL) 2748 /** 2749 * \brief Set the supported key exchange modes for TLS 1.3 connections. 2750 * 2751 * In contrast to TLS 1.2, the ciphersuite concept in TLS 1.3 does not 2752 * include the choice of key exchange mechanism. It is therefore not 2753 * covered by the API mbedtls_ssl_conf_ciphersuites(). See the 2754 * documentation of mbedtls_ssl_conf_ciphersuites() for more 2755 * information on the ciphersuite concept in TLS 1.2 and TLS 1.3. 2756 * 2757 * The present function is specific to TLS 1.3 and allows users to 2758 * configure the set of supported key exchange mechanisms in TLS 1.3. 2759 * 2760 * \param conf The SSL configuration the change should apply to. 2761 * \param kex_modes A bitwise combination of one or more of the following: 2762 * - MBEDTLS_SSL_TLS13_KEY_EXCHANGE_MODE_PSK 2763 * This flag enables pure-PSK key exchanges. 2764 * - MBEDTLS_SSL_TLS13_KEY_EXCHANGE_MODE_PSK_EPHEMERAL 2765 * This flag enables combined PSK-ephemeral key exchanges. 2766 * - MBEDTLS_SSL_TLS13_KEY_EXCHANGE_MODE_EPHEMERAL 2767 * This flag enables pure-ephemeral key exchanges. 2768 * For convenience, the following pre-defined macros are 2769 * available for combinations of the above: 2770 * - MBEDTLS_SSL_TLS13_KEY_EXCHANGE_MODE_ALL 2771 * Includes all of pure-PSK, PSK-ephemeral and pure-ephemeral. 2772 * - MBEDTLS_SSL_TLS13_KEY_EXCHANGE_MODE_PSK_ALL 2773 * Includes both pure-PSK and combined PSK-ephemeral 2774 * key exchanges, but excludes pure-ephemeral key exchanges. 2775 * - MBEDTLS_SSL_TLS13_KEY_EXCHANGE_MODE_EPHEMERAL_ALL 2776 * Includes both pure-ephemeral and combined PSK-ephemeral 2777 * key exchanges. 2778 * 2779 * \note If a PSK-based key exchange mode shall be supported, applications 2780 * must also use the APIs mbedtls_ssl_conf_psk() or 2781 * mbedtls_ssl_conf_psk_cb() or mbedtls_ssl_conf_psk_opaque() 2782 * to configure the PSKs to be used. 2783 * 2784 * \note If a pure-ephemeral key exchange mode shall be supported, 2785 * server-side applications must also provide a certificate via 2786 * mbedtls_ssl_conf_own_cert(). 2787 * 2788 */ 2789 2790 void mbedtls_ssl_conf_tls13_key_exchange_modes( mbedtls_ssl_config* conf, 2791 const int kex_modes ); 2792 #endif /* MBEDTLS_SSL_PROTO_TLS1_3_EXPERIMENTAL */ 2793 2794 #if defined(MBEDTLS_SSL_DTLS_CONNECTION_ID) 2795 #define MBEDTLS_SSL_UNEXPECTED_CID_IGNORE 0 2796 #define MBEDTLS_SSL_UNEXPECTED_CID_FAIL 1 2797 /** 2798 * \brief Specify the length of Connection IDs for incoming 2799 * encrypted DTLS records, as well as the behaviour 2800 * on unexpected CIDs. 2801 * 2802 * By default, the CID length is set to \c 0, 2803 * and unexpected CIDs are silently ignored. 2804 * 2805 * \param conf The SSL configuration to modify. 2806 * \param len The length in Bytes of the CID fields in encrypted 2807 * DTLS records using the CID mechanism. This must 2808 * not be larger than #MBEDTLS_SSL_CID_OUT_LEN_MAX. 2809 * \param ignore_other_cids This determines the stack's behaviour when 2810 * receiving a record with an unexpected CID. 2811 * Possible values are: 2812 * - #MBEDTLS_SSL_UNEXPECTED_CID_IGNORE 2813 * In this case, the record is silently ignored. 2814 * - #MBEDTLS_SSL_UNEXPECTED_CID_FAIL 2815 * In this case, the stack fails with the specific 2816 * error code #MBEDTLS_ERR_SSL_UNEXPECTED_CID. 2817 * 2818 * \note The CID specification allows implementations to either 2819 * use a common length for all incoming connection IDs or 2820 * allow variable-length incoming IDs. Mbed TLS currently 2821 * requires a common length for all connections sharing the 2822 * same SSL configuration; this allows simpler parsing of 2823 * record headers. 2824 * 2825 * \return \c 0 on success. 2826 * \return #MBEDTLS_ERR_SSL_BAD_INPUT_DATA if \p own_cid_len 2827 * is too large. 2828 */ 2829 int mbedtls_ssl_conf_cid( mbedtls_ssl_config *conf, size_t len, 2830 int ignore_other_cids ); 2831 #endif /* MBEDTLS_SSL_DTLS_CONNECTION_ID */ 2832 2833 #if defined(MBEDTLS_X509_CRT_PARSE_C) 2834 /** 2835 * \brief Set the X.509 security profile used for verification 2836 * 2837 * \note The restrictions are enforced for all certificates in the 2838 * chain. However, signatures in the handshake are not covered 2839 * by this setting but by \b mbedtls_ssl_conf_sig_hashes(). 2840 * 2841 * \param conf SSL configuration 2842 * \param profile Profile to use 2843 */ 2844 void mbedtls_ssl_conf_cert_profile( mbedtls_ssl_config *conf, 2845 const mbedtls_x509_crt_profile *profile ); 2846 2847 /** 2848 * \brief Set the data required to verify peer certificate 2849 * 2850 * \note See \c mbedtls_x509_crt_verify() for notes regarding the 2851 * parameters ca_chain (maps to trust_ca for that function) 2852 * and ca_crl. 2853 * 2854 * \param conf SSL configuration 2855 * \param ca_chain trusted CA chain (meaning all fully trusted top-level CAs) 2856 * \param ca_crl trusted CA CRLs 2857 */ 2858 void mbedtls_ssl_conf_ca_chain( mbedtls_ssl_config *conf, 2859 mbedtls_x509_crt *ca_chain, 2860 mbedtls_x509_crl *ca_crl ); 2861 2862 #if defined(MBEDTLS_X509_TRUSTED_CERTIFICATE_CALLBACK) 2863 /** 2864 * \brief Set the trusted certificate callback. 2865 * 2866 * This API allows to register the set of trusted certificates 2867 * through a callback, instead of a linked list as configured 2868 * by mbedtls_ssl_conf_ca_chain(). 2869 * 2870 * This is useful for example in contexts where a large number 2871 * of CAs are used, and the inefficiency of maintaining them 2872 * in a linked list cannot be tolerated. It is also useful when 2873 * the set of trusted CAs needs to be modified frequently. 2874 * 2875 * See the documentation of `mbedtls_x509_crt_ca_cb_t` for 2876 * more information. 2877 * 2878 * \param conf The SSL configuration to register the callback with. 2879 * \param f_ca_cb The trusted certificate callback to use when verifying 2880 * certificate chains. 2881 * \param p_ca_cb The context to be passed to \p f_ca_cb (for example, 2882 * a reference to a trusted CA database). 2883 * 2884 * \note This API is incompatible with mbedtls_ssl_conf_ca_chain(): 2885 * Any call to this function overwrites the values set through 2886 * earlier calls to mbedtls_ssl_conf_ca_chain() or 2887 * mbedtls_ssl_conf_ca_cb(). 2888 * 2889 * \note This API is incompatible with CA indication in 2890 * CertificateRequest messages: A server-side SSL context which 2891 * is bound to an SSL configuration that uses a CA callback 2892 * configured via mbedtls_ssl_conf_ca_cb(), and which requires 2893 * client authentication, will send an empty CA list in the 2894 * corresponding CertificateRequest message. 2895 * 2896 * \note This API is incompatible with mbedtls_ssl_set_hs_ca_chain(): 2897 * If an SSL context is bound to an SSL configuration which uses 2898 * CA callbacks configured via mbedtls_ssl_conf_ca_cb(), then 2899 * calls to mbedtls_ssl_set_hs_ca_chain() have no effect. 2900 * 2901 * \note The use of this API disables the use of restartable ECC 2902 * during X.509 CRT signature verification (but doesn't affect 2903 * other uses). 2904 * 2905 * \warning This API is incompatible with the use of CRLs. Any call to 2906 * mbedtls_ssl_conf_ca_cb() unsets CRLs configured through 2907 * earlier calls to mbedtls_ssl_conf_ca_chain(). 2908 * 2909 * \warning In multi-threaded environments, the callback \p f_ca_cb 2910 * must be thread-safe, and it is the user's responsibility 2911 * to guarantee this (for example through a mutex 2912 * contained in the callback context pointed to by \p p_ca_cb). 2913 */ 2914 void mbedtls_ssl_conf_ca_cb( mbedtls_ssl_config *conf, 2915 mbedtls_x509_crt_ca_cb_t f_ca_cb, 2916 void *p_ca_cb ); 2917 #endif /* MBEDTLS_X509_TRUSTED_CERTIFICATE_CALLBACK */ 2918 2919 /** 2920 * \brief Set own certificate chain and private key 2921 * 2922 * \note own_cert should contain in order from the bottom up your 2923 * certificate chain. The top certificate (self-signed) 2924 * can be omitted. 2925 * 2926 * \note On server, this function can be called multiple times to 2927 * provision more than one cert/key pair (eg one ECDSA, one 2928 * RSA with SHA-256, one RSA with SHA-1). An adequate 2929 * certificate will be selected according to the client's 2930 * advertised capabilities. In case multiple certificates are 2931 * adequate, preference is given to the one set by the first 2932 * call to this function, then second, etc. 2933 * 2934 * \note On client, only the first call has any effect. That is, 2935 * only one client certificate can be provisioned. The 2936 * server's preferences in its CertficateRequest message will 2937 * be ignored and our only cert will be sent regardless of 2938 * whether it matches those preferences - the server can then 2939 * decide what it wants to do with it. 2940 * 2941 * \note The provided \p pk_key needs to match the public key in the 2942 * first certificate in \p own_cert, or all handshakes using 2943 * that certificate will fail. It is your responsibility 2944 * to ensure that; this function will not perform any check. 2945 * You may use mbedtls_pk_check_pair() in order to perform 2946 * this check yourself, but be aware that this function can 2947 * be computationally expensive on some key types. 2948 * 2949 * \param conf SSL configuration 2950 * \param own_cert own public certificate chain 2951 * \param pk_key own private key 2952 * 2953 * \return 0 on success or MBEDTLS_ERR_SSL_ALLOC_FAILED 2954 */ 2955 int mbedtls_ssl_conf_own_cert( mbedtls_ssl_config *conf, 2956 mbedtls_x509_crt *own_cert, 2957 mbedtls_pk_context *pk_key ); 2958 #endif /* MBEDTLS_X509_CRT_PARSE_C */ 2959 2960 #if defined(MBEDTLS_KEY_EXCHANGE_SOME_PSK_ENABLED) 2961 /** 2962 * \brief Configure pre-shared keys (PSKs) and their 2963 * identities to be used in PSK-based ciphersuites. 2964 * 2965 * Only one PSK can be registered, through either 2966 * mbedtls_ssl_conf_psk() or mbedtls_ssl_conf_psk_opaque(). 2967 * If you attempt to register more than one PSK, this function 2968 * fails, though this may change in future versions, which 2969 * may add support for multiple PSKs. 2970 * 2971 * \note This is mainly useful for clients. Servers will usually 2972 * want to use \c mbedtls_ssl_conf_psk_cb() instead. 2973 * 2974 * \note A PSK set by \c mbedtls_ssl_set_hs_psk() in the PSK callback 2975 * takes precedence over a PSK configured by this function. 2976 * 2977 * \param conf The SSL configuration to register the PSK with. 2978 * \param psk The pointer to the pre-shared key to use. 2979 * \param psk_len The length of the pre-shared key in bytes. 2980 * \param psk_identity The pointer to the pre-shared key identity. 2981 * \param psk_identity_len The length of the pre-shared key identity 2982 * in bytes. 2983 * 2984 * \note The PSK and its identity are copied internally and 2985 * hence need not be preserved by the caller for the lifetime 2986 * of the SSL configuration. 2987 * 2988 * \return \c 0 if successful. 2989 * \return #MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE if no more PSKs 2990 * can be configured. In this case, the old PSK(s) remain intact. 2991 * \return Another negative error code on other kinds of failure. 2992 */ 2993 int mbedtls_ssl_conf_psk( mbedtls_ssl_config *conf, 2994 const unsigned char *psk, size_t psk_len, 2995 const unsigned char *psk_identity, size_t psk_identity_len ); 2996 2997 #if defined(MBEDTLS_USE_PSA_CRYPTO) 2998 /** 2999 * \brief Configure one or more opaque pre-shared keys (PSKs) and 3000 * their identities to be used in PSK-based ciphersuites. 3001 * 3002 * Only one PSK can be registered, through either 3003 * mbedtls_ssl_conf_psk() or mbedtls_ssl_conf_psk_opaque(). 3004 * If you attempt to register more than one PSK, this function 3005 * fails, though this may change in future versions, which 3006 * may add support for multiple PSKs. 3007 * 3008 * \note This is mainly useful for clients. Servers will usually 3009 * want to use \c mbedtls_ssl_conf_psk_cb() instead. 3010 * 3011 * \note An opaque PSK set by \c mbedtls_ssl_set_hs_psk_opaque() in 3012 * the PSK callback takes precedence over an opaque PSK 3013 * configured by this function. 3014 * 3015 * \param conf The SSL configuration to register the PSK with. 3016 * \param psk The identifier of the key slot holding the PSK. 3017 * Until \p conf is destroyed or this function is successfully 3018 * called again, the key slot \p psk must be populated with a 3019 * key of type PSA_ALG_CATEGORY_KEY_DERIVATION whose policy 3020 * allows its use for the key derivation algorithm applied 3021 * in the handshake. 3022 * \param psk_identity The pointer to the pre-shared key identity. 3023 * \param psk_identity_len The length of the pre-shared key identity 3024 * in bytes. 3025 * 3026 * \note The PSK identity hint is copied internally and hence need 3027 * not be preserved by the caller for the lifetime of the 3028 * SSL configuration. 3029 * 3030 * \return \c 0 if successful. 3031 * \return #MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE if no more PSKs 3032 * can be configured. In this case, the old PSK(s) remain intact. 3033 * \return Another negative error code on other kinds of failure. 3034 */ 3035 int mbedtls_ssl_conf_psk_opaque( mbedtls_ssl_config *conf, 3036 psa_key_id_t psk, 3037 const unsigned char *psk_identity, 3038 size_t psk_identity_len ); 3039 #endif /* MBEDTLS_USE_PSA_CRYPTO */ 3040 3041 /** 3042 * \brief Set the pre-shared Key (PSK) for the current handshake. 3043 * 3044 * \note This should only be called inside the PSK callback, 3045 * i.e. the function passed to \c mbedtls_ssl_conf_psk_cb(). 3046 * 3047 * \note A PSK set by this function takes precedence over a PSK 3048 * configured by \c mbedtls_ssl_conf_psk(). 3049 * 3050 * \param ssl The SSL context to configure a PSK for. 3051 * \param psk The pointer to the pre-shared key. 3052 * \param psk_len The length of the pre-shared key in bytes. 3053 * 3054 * \return \c 0 if successful. 3055 * \return An \c MBEDTLS_ERR_SSL_XXX error code on failure. 3056 */ 3057 int mbedtls_ssl_set_hs_psk( mbedtls_ssl_context *ssl, 3058 const unsigned char *psk, size_t psk_len ); 3059 3060 #if defined(MBEDTLS_USE_PSA_CRYPTO) 3061 /** 3062 * \brief Set an opaque pre-shared Key (PSK) for the current handshake. 3063 * 3064 * \note This should only be called inside the PSK callback, 3065 * i.e. the function passed to \c mbedtls_ssl_conf_psk_cb(). 3066 * 3067 * \note An opaque PSK set by this function takes precedence over an 3068 * opaque PSK configured by \c mbedtls_ssl_conf_psk_opaque(). 3069 * 3070 * \param ssl The SSL context to configure a PSK for. 3071 * \param psk The identifier of the key slot holding the PSK. 3072 * For the duration of the current handshake, the key slot 3073 * must be populated with a key of type 3074 * PSA_ALG_CATEGORY_KEY_DERIVATION whose policy allows its 3075 * use for the key derivation algorithm 3076 * applied in the handshake. 3077 * 3078 * \return \c 0 if successful. 3079 * \return An \c MBEDTLS_ERR_SSL_XXX error code on failure. 3080 */ 3081 int mbedtls_ssl_set_hs_psk_opaque( mbedtls_ssl_context *ssl, 3082 psa_key_id_t psk ); 3083 #endif /* MBEDTLS_USE_PSA_CRYPTO */ 3084 3085 /** 3086 * \brief Set the PSK callback (server-side only). 3087 * 3088 * If set, the PSK callback is called for each 3089 * handshake where a PSK-based ciphersuite was negotiated. 3090 * The caller provides the identity received and wants to 3091 * receive the actual PSK data and length. 3092 * 3093 * The callback has the following parameters: 3094 * - \c void*: The opaque pointer \p p_psk. 3095 * - \c mbedtls_ssl_context*: The SSL context to which 3096 * the operation applies. 3097 * - \c const unsigned char*: The PSK identity 3098 * selected by the client. 3099 * - \c size_t: The length of the PSK identity 3100 * selected by the client. 3101 * 3102 * If a valid PSK identity is found, the callback should use 3103 * \c mbedtls_ssl_set_hs_psk() or 3104 * \c mbedtls_ssl_set_hs_psk_opaque() 3105 * on the SSL context to set the correct PSK and return \c 0. 3106 * Any other return value will result in a denied PSK identity. 3107 * 3108 * \note A dynamic PSK (i.e. set by the PSK callback) takes 3109 * precedence over a static PSK (i.e. set by 3110 * \c mbedtls_ssl_conf_psk() or 3111 * \c mbedtls_ssl_conf_psk_opaque()). 3112 * This means that if you set a PSK callback using this 3113 * function, you don't need to set a PSK using 3114 * \c mbedtls_ssl_conf_psk() or 3115 * \c mbedtls_ssl_conf_psk_opaque()). 3116 * 3117 * \param conf The SSL configuration to register the callback with. 3118 * \param f_psk The callback for selecting and setting the PSK based 3119 * in the PSK identity chosen by the client. 3120 * \param p_psk A pointer to an opaque structure to be passed to 3121 * the callback, for example a PSK store. 3122 */ 3123 void mbedtls_ssl_conf_psk_cb( mbedtls_ssl_config *conf, 3124 int (*f_psk)(void *, mbedtls_ssl_context *, const unsigned char *, 3125 size_t), 3126 void *p_psk ); 3127 #endif /* MBEDTLS_KEY_EXCHANGE_SOME_PSK_ENABLED */ 3128 3129 #if defined(MBEDTLS_DHM_C) && defined(MBEDTLS_SSL_SRV_C) 3130 /** 3131 * \brief Set the Diffie-Hellman public P and G values 3132 * from big-endian binary presentations. 3133 * (Default values: MBEDTLS_DHM_RFC3526_MODP_2048_[PG]_BIN) 3134 * 3135 * \param conf SSL configuration 3136 * \param dhm_P Diffie-Hellman-Merkle modulus in big-endian binary form 3137 * \param P_len Length of DHM modulus 3138 * \param dhm_G Diffie-Hellman-Merkle generator in big-endian binary form 3139 * \param G_len Length of DHM generator 3140 * 3141 * \return 0 if successful 3142 */ 3143 int mbedtls_ssl_conf_dh_param_bin( mbedtls_ssl_config *conf, 3144 const unsigned char *dhm_P, size_t P_len, 3145 const unsigned char *dhm_G, size_t G_len ); 3146 3147 /** 3148 * \brief Set the Diffie-Hellman public P and G values, 3149 * read from existing context (server-side only) 3150 * 3151 * \param conf SSL configuration 3152 * \param dhm_ctx Diffie-Hellman-Merkle context 3153 * 3154 * \return 0 if successful 3155 */ 3156 int mbedtls_ssl_conf_dh_param_ctx( mbedtls_ssl_config *conf, mbedtls_dhm_context *dhm_ctx ); 3157 #endif /* MBEDTLS_DHM_C && defined(MBEDTLS_SSL_SRV_C) */ 3158 3159 #if defined(MBEDTLS_DHM_C) && defined(MBEDTLS_SSL_CLI_C) 3160 /** 3161 * \brief Set the minimum length for Diffie-Hellman parameters. 3162 * (Client-side only.) 3163 * (Default: 1024 bits.) 3164 * 3165 * \param conf SSL configuration 3166 * \param bitlen Minimum bit length of the DHM prime 3167 */ 3168 void mbedtls_ssl_conf_dhm_min_bitlen( mbedtls_ssl_config *conf, 3169 unsigned int bitlen ); 3170 #endif /* MBEDTLS_DHM_C && MBEDTLS_SSL_CLI_C */ 3171 3172 #if defined(MBEDTLS_ECP_C) 3173 #if !defined(MBEDTLS_DEPRECATED_REMOVED) 3174 /** 3175 * \brief Set the allowed curves in order of preference. 3176 * 3177 * On server: this only affects selection of the ECDHE curve; 3178 * the curves used for ECDH and ECDSA are determined by the 3179 * list of available certificates instead. 3180 * 3181 * On client: this affects the list of curves offered for any 3182 * use. The server can override our preference order. 3183 * 3184 * Both sides: limits the set of curves accepted for use in 3185 * ECDHE and in the peer's end-entity certificate. 3186 * 3187 * \deprecated Superseeded by mbedtls_ssl_conf_groups(). 3188 * 3189 * \note This has no influence on which curves are allowed inside the 3190 * certificate chains, see \c mbedtls_ssl_conf_cert_profile() 3191 * for that. For the end-entity certificate however, the key 3192 * will be accepted only if it is allowed both by this list 3193 * and by the cert profile. 3194 * 3195 * \note This list should be ordered by decreasing preference 3196 * (preferred curve first). 3197 * 3198 * \note The default list is the same set of curves that 3199 * #mbedtls_x509_crt_profile_default allows, plus 3200 * ECDHE-only curves selected according to the same criteria. 3201 * The order favors curves with the lowest resource usage. 3202 * 3203 * \note New minor versions of Mbed TLS may extend this list, 3204 * for example if new curves are added to the library. 3205 * New minor versions of Mbed TLS will not remove items 3206 * from this list unless serious security concerns require it. 3207 * New minor versions of Mbed TLS may change the order in 3208 * keeping with the general principle of favoring the lowest 3209 * resource usage. 3210 * 3211 * \param conf SSL configuration 3212 * \param curves Ordered list of allowed curves, 3213 * terminated by MBEDTLS_ECP_DP_NONE. 3214 */ 3215 void MBEDTLS_DEPRECATED mbedtls_ssl_conf_curves( mbedtls_ssl_config *conf, 3216 const mbedtls_ecp_group_id *curves ); 3217 #endif /* MBEDTLS_DEPRECATED_REMOVED */ 3218 #endif /* MBEDTLS_ECP_C */ 3219 3220 /** 3221 * \brief Set the allowed groups in order of preference. 3222 * 3223 * On server: This only affects the choice of key agreement mechanism 3224 * 3225 * On client: this affects the list of groups offered for any 3226 * use. The server can override our preference order. 3227 * 3228 * Both sides: limits the set of groups accepted for use in 3229 * key sharing. 3230 * 3231 * \note This function replaces the deprecated mbedtls_ssl_conf_curves(), 3232 * which only allows ECP curves to be configured. 3233 * 3234 * \note The most recent invocation of either mbedtls_ssl_conf_curves() 3235 * or mbedtls_ssl_conf_groups() nullifies all previous invocations 3236 * of both. 3237 * 3238 * \note This list should be ordered by decreasing preference 3239 * (preferred group first). 3240 * 3241 * \note When this function is not called, a default list is used, 3242 * consisting of all supported curves at 255 bits and above, 3243 * and all supported finite fields at 2048 bits and above. 3244 * The order favors groups with the lowest resource usage. 3245 * 3246 * \note New minor versions of Mbed TLS will not remove items 3247 * from the default list unless serious security concerns require it. 3248 * New minor versions of Mbed TLS may change the order in 3249 * keeping with the general principle of favoring the lowest 3250 * resource usage. 3251 * 3252 * \param conf SSL configuration 3253 * \param groups List of allowed groups ordered by preference, terminated by 0. 3254 * Must contain valid IANA NamedGroup IDs (provided via either an integer 3255 * or using MBEDTLS_TLS13_NAMED_GROUP_XXX macros). 3256 */ 3257 void mbedtls_ssl_conf_groups( mbedtls_ssl_config *conf, 3258 const uint16_t *groups ); 3259 3260 #if defined(MBEDTLS_KEY_EXCHANGE_WITH_CERT_ENABLED) 3261 /** 3262 * \brief Set the allowed hashes for signatures during the handshake. 3263 * 3264 * \note This only affects which hashes are offered and can be used 3265 * for signatures during the handshake. Hashes for message 3266 * authentication and the TLS PRF are controlled by the 3267 * ciphersuite, see \c mbedtls_ssl_conf_ciphersuites(). Hashes 3268 * used for certificate signature are controlled by the 3269 * verification profile, see \c mbedtls_ssl_conf_cert_profile(). 3270 * 3271 * \note This list should be ordered by decreasing preference 3272 * (preferred hash first). 3273 * 3274 * \note By default, all supported hashes whose length is at least 3275 * 256 bits are allowed. This is the same set as the default 3276 * for certificate verification 3277 * (#mbedtls_x509_crt_profile_default). 3278 * The preference order is currently unspecified and may 3279 * change in future versions. 3280 * 3281 * \note New minor versions of Mbed TLS may extend this list, 3282 * for example if new curves are added to the library. 3283 * New minor versions of Mbed TLS will not remove items 3284 * from this list unless serious security concerns require it. 3285 * 3286 * \param conf SSL configuration 3287 * \param hashes Ordered list of allowed signature hashes, 3288 * terminated by \c MBEDTLS_MD_NONE. 3289 */ 3290 void mbedtls_ssl_conf_sig_hashes( mbedtls_ssl_config *conf, 3291 const int *hashes ); 3292 3293 #if defined(MBEDTLS_SSL_PROTO_TLS1_3_EXPERIMENTAL) 3294 /** 3295 * \brief Configure allowed signature algorithms for use in TLS 1.3 3296 * 3297 * \param conf The SSL configuration to use. 3298 * \param sig_algs List of allowed IANA values for TLS 1.3 signature algorithms, 3299 * terminated by \c MBEDTLS_TLS13_SIG_NONE. The list must remain 3300 * available throughout the lifetime of the conf object. Supported 3301 * values are available as \c MBEDTLS_TLS13_SIG_XXXX 3302 */ 3303 void mbedtls_ssl_conf_sig_algs( mbedtls_ssl_config *conf, 3304 const uint16_t* sig_algs ); 3305 #endif /* MBEDTLS_SSL_PROTO_TLS1_3_EXPERIMENTAL */ 3306 #endif /* MBEDTLS_KEY_EXCHANGE_WITH_CERT_ENABLED */ 3307 3308 #if defined(MBEDTLS_X509_CRT_PARSE_C) 3309 /** 3310 * \brief Set or reset the hostname to check against the received 3311 * server certificate. It sets the ServerName TLS extension, 3312 * too, if that extension is enabled. (client-side only) 3313 * 3314 * \param ssl SSL context 3315 * \param hostname the server hostname, may be NULL to clear hostname 3316 3317 * \note Maximum hostname length MBEDTLS_SSL_MAX_HOST_NAME_LEN. 3318 * 3319 * \return 0 if successful, MBEDTLS_ERR_SSL_ALLOC_FAILED on 3320 * allocation failure, MBEDTLS_ERR_SSL_BAD_INPUT_DATA on 3321 * too long input hostname. 3322 * 3323 * Hostname set to the one provided on success (cleared 3324 * when NULL). On allocation failure hostname is cleared. 3325 * On too long input failure, old hostname is unchanged. 3326 */ 3327 int mbedtls_ssl_set_hostname( mbedtls_ssl_context *ssl, const char *hostname ); 3328 #endif /* MBEDTLS_X509_CRT_PARSE_C */ 3329 3330 #if defined(MBEDTLS_SSL_SERVER_NAME_INDICATION) 3331 /** 3332 * \brief Set own certificate and key for the current handshake 3333 * 3334 * \note Same as \c mbedtls_ssl_conf_own_cert() but for use within 3335 * the SNI callback. 3336 * 3337 * \param ssl SSL context 3338 * \param own_cert own public certificate chain 3339 * \param pk_key own private key 3340 * 3341 * \return 0 on success or MBEDTLS_ERR_SSL_ALLOC_FAILED 3342 */ 3343 int mbedtls_ssl_set_hs_own_cert( mbedtls_ssl_context *ssl, 3344 mbedtls_x509_crt *own_cert, 3345 mbedtls_pk_context *pk_key ); 3346 3347 /** 3348 * \brief Set the data required to verify peer certificate for the 3349 * current handshake 3350 * 3351 * \note Same as \c mbedtls_ssl_conf_ca_chain() but for use within 3352 * the SNI callback. 3353 * 3354 * \param ssl SSL context 3355 * \param ca_chain trusted CA chain (meaning all fully trusted top-level CAs) 3356 * \param ca_crl trusted CA CRLs 3357 */ 3358 void mbedtls_ssl_set_hs_ca_chain( mbedtls_ssl_context *ssl, 3359 mbedtls_x509_crt *ca_chain, 3360 mbedtls_x509_crl *ca_crl ); 3361 3362 /** 3363 * \brief Set authmode for the current handshake. 3364 * 3365 * \note Same as \c mbedtls_ssl_conf_authmode() but for use within 3366 * the SNI callback. 3367 * 3368 * \param ssl SSL context 3369 * \param authmode MBEDTLS_SSL_VERIFY_NONE, MBEDTLS_SSL_VERIFY_OPTIONAL or 3370 * MBEDTLS_SSL_VERIFY_REQUIRED 3371 */ 3372 void mbedtls_ssl_set_hs_authmode( mbedtls_ssl_context *ssl, 3373 int authmode ); 3374 3375 /** 3376 * \brief Set server side ServerName TLS extension callback 3377 * (optional, server-side only). 3378 * 3379 * If set, the ServerName callback is called whenever the 3380 * server receives a ServerName TLS extension from the client 3381 * during a handshake. The ServerName callback has the 3382 * following parameters: (void *parameter, mbedtls_ssl_context *ssl, 3383 * const unsigned char *hostname, size_t len). If a suitable 3384 * certificate is found, the callback must set the 3385 * certificate(s) and key(s) to use with \c 3386 * mbedtls_ssl_set_hs_own_cert() (can be called repeatedly), 3387 * and may optionally adjust the CA and associated CRL with \c 3388 * mbedtls_ssl_set_hs_ca_chain() as well as the client 3389 * authentication mode with \c mbedtls_ssl_set_hs_authmode(), 3390 * then must return 0. If no matching name is found, the 3391 * callback must either set a default cert, or 3392 * return non-zero to abort the handshake at this point. 3393 * 3394 * \param conf SSL configuration 3395 * \param f_sni verification function 3396 * \param p_sni verification parameter 3397 */ 3398 void mbedtls_ssl_conf_sni( mbedtls_ssl_config *conf, 3399 int (*f_sni)(void *, mbedtls_ssl_context *, const unsigned char *, 3400 size_t), 3401 void *p_sni ); 3402 #endif /* MBEDTLS_SSL_SERVER_NAME_INDICATION */ 3403 3404 #if defined(MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED) 3405 /** 3406 * \brief Set the EC J-PAKE password for current handshake. 3407 * 3408 * \note An internal copy is made, and destroyed as soon as the 3409 * handshake is completed, or when the SSL context is reset or 3410 * freed. 3411 * 3412 * \note The SSL context needs to be already set up. The right place 3413 * to call this function is between \c mbedtls_ssl_setup() or 3414 * \c mbedtls_ssl_reset() and \c mbedtls_ssl_handshake(). 3415 * 3416 * \param ssl SSL context 3417 * \param pw EC J-PAKE password (pre-shared secret) 3418 * \param pw_len length of pw in bytes 3419 * 3420 * \return 0 on success, or a negative error code. 3421 */ 3422 int mbedtls_ssl_set_hs_ecjpake_password( mbedtls_ssl_context *ssl, 3423 const unsigned char *pw, 3424 size_t pw_len ); 3425 #endif /*MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED */ 3426 3427 #if defined(MBEDTLS_SSL_ALPN) 3428 /** 3429 * \brief Set the supported Application Layer Protocols. 3430 * 3431 * \param conf SSL configuration 3432 * \param protos Pointer to a NULL-terminated list of supported protocols, 3433 * in decreasing preference order. The pointer to the list is 3434 * recorded by the library for later reference as required, so 3435 * the lifetime of the table must be atleast as long as the 3436 * lifetime of the SSL configuration structure. 3437 * 3438 * \return 0 on success, or MBEDTLS_ERR_SSL_BAD_INPUT_DATA. 3439 */ 3440 int mbedtls_ssl_conf_alpn_protocols( mbedtls_ssl_config *conf, const char **protos ); 3441 3442 /** 3443 * \brief Get the name of the negotiated Application Layer Protocol. 3444 * This function should be called after the handshake is 3445 * completed. 3446 * 3447 * \param ssl SSL context 3448 * 3449 * \return Protcol name, or NULL if no protocol was negotiated. 3450 */ 3451 const char *mbedtls_ssl_get_alpn_protocol( const mbedtls_ssl_context *ssl ); 3452 #endif /* MBEDTLS_SSL_ALPN */ 3453 3454 #if defined(MBEDTLS_SSL_DTLS_SRTP) 3455 #if defined(MBEDTLS_DEBUG_C) mbedtls_ssl_get_srtp_profile_as_string(mbedtls_ssl_srtp_profile profile)3456 static inline const char *mbedtls_ssl_get_srtp_profile_as_string( mbedtls_ssl_srtp_profile profile ) 3457 { 3458 switch( profile ) 3459 { 3460 case MBEDTLS_TLS_SRTP_AES128_CM_HMAC_SHA1_80: 3461 return( "MBEDTLS_TLS_SRTP_AES128_CM_HMAC_SHA1_80" ); 3462 case MBEDTLS_TLS_SRTP_AES128_CM_HMAC_SHA1_32: 3463 return( "MBEDTLS_TLS_SRTP_AES128_CM_HMAC_SHA1_32" ); 3464 case MBEDTLS_TLS_SRTP_NULL_HMAC_SHA1_80: 3465 return( "MBEDTLS_TLS_SRTP_NULL_HMAC_SHA1_80" ); 3466 case MBEDTLS_TLS_SRTP_NULL_HMAC_SHA1_32: 3467 return( "MBEDTLS_TLS_SRTP_NULL_HMAC_SHA1_32" ); 3468 default: break; 3469 } 3470 return( "" ); 3471 } 3472 #endif /* MBEDTLS_DEBUG_C */ 3473 /** 3474 * \brief Manage support for mki(master key id) value 3475 * in use_srtp extension. 3476 * MKI is an optional part of SRTP used for key management 3477 * and re-keying. See RFC3711 section 3.1 for details. 3478 * The default value is 3479 * #MBEDTLS_SSL_DTLS_SRTP_MKI_UNSUPPORTED. 3480 * 3481 * \param conf The SSL configuration to manage mki support. 3482 * \param support_mki_value Enable or disable mki usage. Values are 3483 * #MBEDTLS_SSL_DTLS_SRTP_MKI_UNSUPPORTED 3484 * or #MBEDTLS_SSL_DTLS_SRTP_MKI_SUPPORTED. 3485 */ 3486 void mbedtls_ssl_conf_srtp_mki_value_supported( mbedtls_ssl_config *conf, 3487 int support_mki_value ); 3488 3489 /** 3490 * \brief Set the supported DTLS-SRTP protection profiles. 3491 * 3492 * \param conf SSL configuration 3493 * \param profiles Pointer to a List of MBEDTLS_TLS_SRTP_UNSET terminated 3494 * supported protection profiles 3495 * in decreasing preference order. 3496 * The pointer to the list is recorded by the library 3497 * for later reference as required, so the lifetime 3498 * of the table must be at least as long as the lifetime 3499 * of the SSL configuration structure. 3500 * The list must not hold more than 3501 * MBEDTLS_TLS_SRTP_MAX_PROFILE_LIST_LENGTH elements 3502 * (excluding the terminating MBEDTLS_TLS_SRTP_UNSET). 3503 * 3504 * \return 0 on success 3505 * \return #MBEDTLS_ERR_SSL_BAD_INPUT_DATA when the list of 3506 * protection profiles is incorrect. 3507 */ 3508 int mbedtls_ssl_conf_dtls_srtp_protection_profiles 3509 ( mbedtls_ssl_config *conf, 3510 const mbedtls_ssl_srtp_profile *profiles ); 3511 3512 /** 3513 * \brief Set the mki_value for the current DTLS-SRTP session. 3514 * 3515 * \param ssl SSL context to use. 3516 * \param mki_value The MKI value to set. 3517 * \param mki_len The length of the MKI value. 3518 * 3519 * \note This function is relevant on client side only. 3520 * The server discovers the mki value during handshake. 3521 * A mki value set on server side using this function 3522 * is ignored. 3523 * 3524 * \return 0 on success 3525 * \return #MBEDTLS_ERR_SSL_BAD_INPUT_DATA 3526 * \return #MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE 3527 */ 3528 int mbedtls_ssl_dtls_srtp_set_mki_value( mbedtls_ssl_context *ssl, 3529 unsigned char *mki_value, 3530 uint16_t mki_len ); 3531 /** 3532 * \brief Get the negotiated DTLS-SRTP informations: 3533 * Protection profile and MKI value. 3534 * 3535 * \warning This function must be called after the handshake is 3536 * completed. The value returned by this function must 3537 * not be trusted or acted upon before the handshake completes. 3538 * 3539 * \param ssl The SSL context to query. 3540 * \param dtls_srtp_info The negotiated DTLS-SRTP informations: 3541 * - Protection profile in use. 3542 * A direct mapping of the iana defined value for protection 3543 * profile on an uint16_t. 3544 http://www.iana.org/assignments/srtp-protection/srtp-protection.xhtml 3545 * #MBEDTLS_TLS_SRTP_UNSET if the use of SRTP was not negotiated 3546 * or peer's Hello packet was not parsed yet. 3547 * - mki size and value( if size is > 0 ). 3548 */ 3549 void mbedtls_ssl_get_dtls_srtp_negotiation_result( const mbedtls_ssl_context *ssl, 3550 mbedtls_dtls_srtp_info *dtls_srtp_info ); 3551 #endif /* MBEDTLS_SSL_DTLS_SRTP */ 3552 3553 /** 3554 * \brief Set the maximum supported version sent from the client side 3555 * and/or accepted at the server side 3556 * (Default: MBEDTLS_SSL_MAX_MAJOR_VERSION, MBEDTLS_SSL_MAX_MINOR_VERSION) 3557 * 3558 * \note This ignores ciphersuites from higher versions. 3559 * 3560 * \note With DTLS, use MBEDTLS_SSL_MINOR_VERSION_3 for DTLS 1.2 3561 * 3562 * \param conf SSL configuration 3563 * \param major Major version number (only MBEDTLS_SSL_MAJOR_VERSION_3 supported) 3564 * \param minor Minor version number (only MBEDTLS_SSL_MINOR_VERSION_3 supported) 3565 */ 3566 void mbedtls_ssl_conf_max_version( mbedtls_ssl_config *conf, int major, int minor ); 3567 3568 /** 3569 * \brief Set the minimum accepted SSL/TLS protocol version 3570 * (Default: TLS 1.2) 3571 * 3572 * \note Input outside of the SSL_MAX_XXXXX_VERSION and 3573 * SSL_MIN_XXXXX_VERSION range is ignored. 3574 * 3575 * \note With DTLS, use MBEDTLS_SSL_MINOR_VERSION_3 for DTLS 1.2 3576 * 3577 * \param conf SSL configuration 3578 * \param major Major version number (only MBEDTLS_SSL_MAJOR_VERSION_3 supported) 3579 * \param minor Minor version number (only MBEDTLS_SSL_MINOR_VERSION_3 supported) 3580 */ 3581 void mbedtls_ssl_conf_min_version( mbedtls_ssl_config *conf, int major, int minor ); 3582 3583 #if defined(MBEDTLS_SSL_ENCRYPT_THEN_MAC) 3584 /** 3585 * \brief Enable or disable Encrypt-then-MAC 3586 * (Default: MBEDTLS_SSL_ETM_ENABLED) 3587 * 3588 * \note This should always be enabled, it is a security 3589 * improvement, and should not cause any interoperability 3590 * issue (used only if the peer supports it too). 3591 * 3592 * \param conf SSL configuration 3593 * \param etm MBEDTLS_SSL_ETM_ENABLED or MBEDTLS_SSL_ETM_DISABLED 3594 */ 3595 void mbedtls_ssl_conf_encrypt_then_mac( mbedtls_ssl_config *conf, char etm ); 3596 #endif /* MBEDTLS_SSL_ENCRYPT_THEN_MAC */ 3597 3598 #if defined(MBEDTLS_SSL_EXTENDED_MASTER_SECRET) 3599 /** 3600 * \brief Enable or disable Extended Master Secret negotiation. 3601 * (Default: MBEDTLS_SSL_EXTENDED_MS_ENABLED) 3602 * 3603 * \note This should always be enabled, it is a security fix to the 3604 * protocol, and should not cause any interoperability issue 3605 * (used only if the peer supports it too). 3606 * 3607 * \param conf SSL configuration 3608 * \param ems MBEDTLS_SSL_EXTENDED_MS_ENABLED or MBEDTLS_SSL_EXTENDED_MS_DISABLED 3609 */ 3610 void mbedtls_ssl_conf_extended_master_secret( mbedtls_ssl_config *conf, char ems ); 3611 #endif /* MBEDTLS_SSL_EXTENDED_MASTER_SECRET */ 3612 3613 #if defined(MBEDTLS_SSL_SRV_C) 3614 /** 3615 * \brief Whether to send a list of acceptable CAs in 3616 * CertificateRequest messages. 3617 * (Default: do send) 3618 * 3619 * \param conf SSL configuration 3620 * \param cert_req_ca_list MBEDTLS_SSL_CERT_REQ_CA_LIST_ENABLED or 3621 * MBEDTLS_SSL_CERT_REQ_CA_LIST_DISABLED 3622 */ 3623 void mbedtls_ssl_conf_cert_req_ca_list( mbedtls_ssl_config *conf, 3624 char cert_req_ca_list ); 3625 #endif /* MBEDTLS_SSL_SRV_C */ 3626 3627 #if defined(MBEDTLS_SSL_MAX_FRAGMENT_LENGTH) 3628 /** 3629 * \brief Set the maximum fragment length to emit and/or negotiate. 3630 * (Typical: the smaller of #MBEDTLS_SSL_IN_CONTENT_LEN and 3631 * #MBEDTLS_SSL_OUT_CONTENT_LEN, usually `2^14` bytes) 3632 * (Server: set maximum fragment length to emit, 3633 * usually negotiated by the client during handshake) 3634 * (Client: set maximum fragment length to emit *and* 3635 * negotiate with the server during handshake) 3636 * (Default: #MBEDTLS_SSL_MAX_FRAG_LEN_NONE) 3637 * 3638 * \note On the client side, the maximum fragment length extension 3639 * *will not* be used, unless the maximum fragment length has 3640 * been set via this function to a value different than 3641 * #MBEDTLS_SSL_MAX_FRAG_LEN_NONE. 3642 * 3643 * \note With TLS, this currently only affects ApplicationData (sent 3644 * with \c mbedtls_ssl_read()), not handshake messages. 3645 * With DTLS, this affects both ApplicationData and handshake. 3646 * 3647 * \note This sets the maximum length for a record's payload, 3648 * excluding record overhead that will be added to it, see 3649 * \c mbedtls_ssl_get_record_expansion(). 3650 * 3651 * \note For DTLS, it is also possible to set a limit for the total 3652 * size of daragrams passed to the transport layer, including 3653 * record overhead, see \c mbedtls_ssl_set_mtu(). 3654 * 3655 * \param conf SSL configuration 3656 * \param mfl_code Code for maximum fragment length (allowed values: 3657 * MBEDTLS_SSL_MAX_FRAG_LEN_512, MBEDTLS_SSL_MAX_FRAG_LEN_1024, 3658 * MBEDTLS_SSL_MAX_FRAG_LEN_2048, MBEDTLS_SSL_MAX_FRAG_LEN_4096) 3659 * 3660 * \return 0 if successful or MBEDTLS_ERR_SSL_BAD_INPUT_DATA 3661 */ 3662 int mbedtls_ssl_conf_max_frag_len( mbedtls_ssl_config *conf, unsigned char mfl_code ); 3663 #endif /* MBEDTLS_SSL_MAX_FRAGMENT_LENGTH */ 3664 3665 #if defined(MBEDTLS_SSL_SRV_C) 3666 /** 3667 * \brief Pick the ciphersuites order according to the second parameter 3668 * in the SSL Server module (MBEDTLS_SSL_SRV_C). 3669 * (Default, if never called: MBEDTLS_SSL_SRV_CIPHERSUITE_ORDER_SERVER) 3670 * 3671 * \param conf SSL configuration 3672 * \param order Server or client (MBEDTLS_SSL_SRV_CIPHERSUITE_ORDER_SERVER 3673 * or MBEDTLS_SSL_SRV_CIPHERSUITE_ORDER_CLIENT) 3674 */ 3675 void mbedtls_ssl_conf_preference_order( mbedtls_ssl_config *conf, int order ); 3676 #endif /* MBEDTLS_SSL_SRV_C */ 3677 3678 #if defined(MBEDTLS_SSL_SESSION_TICKETS) && defined(MBEDTLS_SSL_CLI_C) 3679 /** 3680 * \brief Enable / Disable session tickets (client only). 3681 * (Default: MBEDTLS_SSL_SESSION_TICKETS_ENABLED.) 3682 * 3683 * \note On server, use \c mbedtls_ssl_conf_session_tickets_cb(). 3684 * 3685 * \param conf SSL configuration 3686 * \param use_tickets Enable or disable (MBEDTLS_SSL_SESSION_TICKETS_ENABLED or 3687 * MBEDTLS_SSL_SESSION_TICKETS_DISABLED) 3688 */ 3689 void mbedtls_ssl_conf_session_tickets( mbedtls_ssl_config *conf, int use_tickets ); 3690 #endif /* MBEDTLS_SSL_SESSION_TICKETS && MBEDTLS_SSL_CLI_C */ 3691 3692 #if defined(MBEDTLS_SSL_RENEGOTIATION) 3693 /** 3694 * \brief Enable / Disable renegotiation support for connection when 3695 * initiated by peer 3696 * (Default: MBEDTLS_SSL_RENEGOTIATION_DISABLED) 3697 * 3698 * \warning It is recommended to always disable renegotation unless you 3699 * know you need it and you know what you're doing. In the 3700 * past, there have been several issues associated with 3701 * renegotiation or a poor understanding of its properties. 3702 * 3703 * \note Server-side, enabling renegotiation also makes the server 3704 * susceptible to a resource DoS by a malicious client. 3705 * 3706 * \param conf SSL configuration 3707 * \param renegotiation Enable or disable (MBEDTLS_SSL_RENEGOTIATION_ENABLED or 3708 * MBEDTLS_SSL_RENEGOTIATION_DISABLED) 3709 */ 3710 void mbedtls_ssl_conf_renegotiation( mbedtls_ssl_config *conf, int renegotiation ); 3711 #endif /* MBEDTLS_SSL_RENEGOTIATION */ 3712 3713 /** 3714 * \brief Prevent or allow legacy renegotiation. 3715 * (Default: MBEDTLS_SSL_LEGACY_NO_RENEGOTIATION) 3716 * 3717 * MBEDTLS_SSL_LEGACY_NO_RENEGOTIATION allows connections to 3718 * be established even if the peer does not support 3719 * secure renegotiation, but does not allow renegotiation 3720 * to take place if not secure. 3721 * (Interoperable and secure option) 3722 * 3723 * MBEDTLS_SSL_LEGACY_ALLOW_RENEGOTIATION allows renegotiations 3724 * with non-upgraded peers. Allowing legacy renegotiation 3725 * makes the connection vulnerable to specific man in the 3726 * middle attacks. (See RFC 5746) 3727 * (Most interoperable and least secure option) 3728 * 3729 * MBEDTLS_SSL_LEGACY_BREAK_HANDSHAKE breaks off connections 3730 * if peer does not support secure renegotiation. Results 3731 * in interoperability issues with non-upgraded peers 3732 * that do not support renegotiation altogether. 3733 * (Most secure option, interoperability issues) 3734 * 3735 * \param conf SSL configuration 3736 * \param allow_legacy Prevent or allow (SSL_NO_LEGACY_RENEGOTIATION, 3737 * SSL_ALLOW_LEGACY_RENEGOTIATION or 3738 * MBEDTLS_SSL_LEGACY_BREAK_HANDSHAKE) 3739 */ 3740 void mbedtls_ssl_conf_legacy_renegotiation( mbedtls_ssl_config *conf, int allow_legacy ); 3741 3742 #if defined(MBEDTLS_SSL_RENEGOTIATION) 3743 /** 3744 * \brief Enforce renegotiation requests. 3745 * (Default: enforced, max_records = 16) 3746 * 3747 * When we request a renegotiation, the peer can comply or 3748 * ignore the request. This function allows us to decide 3749 * whether to enforce our renegotiation requests by closing 3750 * the connection if the peer doesn't comply. 3751 * 3752 * However, records could already be in transit from the peer 3753 * when the request is emitted. In order to increase 3754 * reliability, we can accept a number of records before the 3755 * expected handshake records. 3756 * 3757 * The optimal value is highly dependent on the specific usage 3758 * scenario. 3759 * 3760 * \note With DTLS and server-initiated renegotiation, the 3761 * HelloRequest is retransmited every time mbedtls_ssl_read() times 3762 * out or receives Application Data, until: 3763 * - max_records records have beens seen, if it is >= 0, or 3764 * - the number of retransmits that would happen during an 3765 * actual handshake has been reached. 3766 * Please remember the request might be lost a few times 3767 * if you consider setting max_records to a really low value. 3768 * 3769 * \warning On client, the grace period can only happen during 3770 * mbedtls_ssl_read(), as opposed to mbedtls_ssl_write() and mbedtls_ssl_renegotiate() 3771 * which always behave as if max_record was 0. The reason is, 3772 * if we receive application data from the server, we need a 3773 * place to write it, which only happens during mbedtls_ssl_read(). 3774 * 3775 * \param conf SSL configuration 3776 * \param max_records Use MBEDTLS_SSL_RENEGOTIATION_NOT_ENFORCED if you don't want to 3777 * enforce renegotiation, or a non-negative value to enforce 3778 * it but allow for a grace period of max_records records. 3779 */ 3780 void mbedtls_ssl_conf_renegotiation_enforced( mbedtls_ssl_config *conf, int max_records ); 3781 3782 /** 3783 * \brief Set record counter threshold for periodic renegotiation. 3784 * (Default: 2^48 - 1) 3785 * 3786 * Renegotiation is automatically triggered when a record 3787 * counter (outgoing or incoming) crosses the defined 3788 * threshold. The default value is meant to prevent the 3789 * connection from being closed when the counter is about to 3790 * reached its maximal value (it is not allowed to wrap). 3791 * 3792 * Lower values can be used to enforce policies such as "keys 3793 * must be refreshed every N packets with cipher X". 3794 * 3795 * The renegotiation period can be disabled by setting 3796 * conf->disable_renegotiation to 3797 * MBEDTLS_SSL_RENEGOTIATION_DISABLED. 3798 * 3799 * \note When the configured transport is 3800 * MBEDTLS_SSL_TRANSPORT_DATAGRAM the maximum renegotiation 3801 * period is 2^48 - 1, and for MBEDTLS_SSL_TRANSPORT_STREAM, 3802 * the maximum renegotiation period is 2^64 - 1. 3803 * 3804 * \param conf SSL configuration 3805 * \param period The threshold value: a big-endian 64-bit number. 3806 */ 3807 void mbedtls_ssl_conf_renegotiation_period( mbedtls_ssl_config *conf, 3808 const unsigned char period[8] ); 3809 #endif /* MBEDTLS_SSL_RENEGOTIATION */ 3810 3811 /** 3812 * \brief Check if there is data already read from the 3813 * underlying transport but not yet processed. 3814 * 3815 * \param ssl SSL context 3816 * 3817 * \return 0 if nothing's pending, 1 otherwise. 3818 * 3819 * \note This is different in purpose and behaviour from 3820 * \c mbedtls_ssl_get_bytes_avail in that it considers 3821 * any kind of unprocessed data, not only unread 3822 * application data. If \c mbedtls_ssl_get_bytes 3823 * returns a non-zero value, this function will 3824 * also signal pending data, but the converse does 3825 * not hold. For example, in DTLS there might be 3826 * further records waiting to be processed from 3827 * the current underlying transport's datagram. 3828 * 3829 * \note If this function returns 1 (data pending), this 3830 * does not imply that a subsequent call to 3831 * \c mbedtls_ssl_read will provide any data; 3832 * e.g., the unprocessed data might turn out 3833 * to be an alert or a handshake message. 3834 * 3835 * \note This function is useful in the following situation: 3836 * If the SSL/TLS module successfully returns from an 3837 * operation - e.g. a handshake or an application record 3838 * read - and you're awaiting incoming data next, you 3839 * must not immediately idle on the underlying transport 3840 * to have data ready, but you need to check the value 3841 * of this function first. The reason is that the desired 3842 * data might already be read but not yet processed. 3843 * If, in contrast, a previous call to the SSL/TLS module 3844 * returned MBEDTLS_ERR_SSL_WANT_READ, it is not necessary 3845 * to call this function, as the latter error code entails 3846 * that all internal data has been processed. 3847 * 3848 */ 3849 int mbedtls_ssl_check_pending( const mbedtls_ssl_context *ssl ); 3850 3851 /** 3852 * \brief Return the number of application data bytes 3853 * remaining to be read from the current record. 3854 * 3855 * \param ssl SSL context 3856 * 3857 * \return How many bytes are available in the application 3858 * data record read buffer. 3859 * 3860 * \note When working over a datagram transport, this is 3861 * useful to detect the current datagram's boundary 3862 * in case \c mbedtls_ssl_read has written the maximal 3863 * amount of data fitting into the input buffer. 3864 * 3865 */ 3866 size_t mbedtls_ssl_get_bytes_avail( const mbedtls_ssl_context *ssl ); 3867 3868 /** 3869 * \brief Return the result of the certificate verification 3870 * 3871 * \param ssl The SSL context to use. 3872 * 3873 * \return \c 0 if the certificate verification was successful. 3874 * \return \c -1u if the result is not available. This may happen 3875 * e.g. if the handshake aborts early, or a verification 3876 * callback returned a fatal error. 3877 * \return A bitwise combination of \c MBEDTLS_X509_BADCERT_XXX 3878 * and \c MBEDTLS_X509_BADCRL_XXX failure flags; see x509.h. 3879 */ 3880 uint32_t mbedtls_ssl_get_verify_result( const mbedtls_ssl_context *ssl ); 3881 3882 /** 3883 * \brief Return the name of the current ciphersuite 3884 * 3885 * \param ssl SSL context 3886 * 3887 * \return a string containing the ciphersuite name 3888 */ 3889 const char *mbedtls_ssl_get_ciphersuite( const mbedtls_ssl_context *ssl ); 3890 3891 /** 3892 * \brief Return the current TLS version 3893 * 3894 * \param ssl SSL context 3895 * 3896 * \return a string containing the TLS version 3897 */ 3898 const char *mbedtls_ssl_get_version( const mbedtls_ssl_context *ssl ); 3899 3900 /** 3901 * \brief Return the (maximum) number of bytes added by the record 3902 * layer: header + encryption/MAC overhead (inc. padding) 3903 * 3904 * \param ssl SSL context 3905 * 3906 * \return Current maximum record expansion in bytes 3907 */ 3908 int mbedtls_ssl_get_record_expansion( const mbedtls_ssl_context *ssl ); 3909 3910 /** 3911 * \brief Return the current maximum outgoing record payload in bytes. 3912 * 3913 * \note The logic to determine the maximum outgoing record payload is 3914 * version-specific. It takes into account various factors, such as 3915 * the mbedtls_config.h setting \c MBEDTLS_SSL_OUT_CONTENT_LEN, extensions 3916 * such as the max fragment length or record size limit extension if 3917 * used, and for DTLS the path MTU as configured and current 3918 * record expansion. 3919 * 3920 * \note With DTLS, \c mbedtls_ssl_write() will return an error if 3921 * called with a larger length value. 3922 * With TLS, \c mbedtls_ssl_write() will fragment the input if 3923 * necessary and return the number of bytes written; it is up 3924 * to the caller to call \c mbedtls_ssl_write() again in 3925 * order to send the remaining bytes if any. 3926 * 3927 * \sa mbedtls_ssl_get_max_out_record_payload() 3928 * \sa mbedtls_ssl_get_record_expansion() 3929 * 3930 * \param ssl SSL context 3931 * 3932 * \return Current maximum payload for an outgoing record, 3933 * or a negative error code. 3934 */ 3935 int mbedtls_ssl_get_max_out_record_payload( const mbedtls_ssl_context *ssl ); 3936 3937 /** 3938 * \brief Return the current maximum incoming record payload in bytes. 3939 * 3940 * \note The logic to determine the maximum outgoing record payload is 3941 * version-specific. It takes into account various factors, such as 3942 * the mbedtls_config.h setting \c MBEDTLS_SSL_IN_CONTENT_LEN, extensions 3943 * such as the max fragment length extension or record size limit 3944 * extension if used, and the current record expansion. 3945 * 3946 * \sa mbedtls_ssl_set_mtu() 3947 * \sa mbedtls_ssl_get_max_in_record_payload() 3948 * \sa mbedtls_ssl_get_record_expansion() 3949 * 3950 * \param ssl SSL context 3951 * 3952 * \return Current maximum payload for an outgoing record, 3953 * or a negative error code. 3954 */ 3955 int mbedtls_ssl_get_max_in_record_payload( const mbedtls_ssl_context *ssl ); 3956 3957 #if defined(MBEDTLS_X509_CRT_PARSE_C) 3958 /** 3959 * \brief Return the peer certificate from the current connection. 3960 * 3961 * \param ssl The SSL context to use. This must be initialized and setup. 3962 * 3963 * \return The current peer certificate, if available. 3964 * The returned certificate is owned by the SSL context and 3965 * is valid only until the next call to the SSL API. 3966 * \return \c NULL if no peer certificate is available. This might 3967 * be because the chosen ciphersuite doesn't use CRTs 3968 * (PSK-based ciphersuites, for example), or because 3969 * #MBEDTLS_SSL_KEEP_PEER_CERTIFICATE has been disabled, 3970 * allowing the stack to free the peer's CRT to save memory. 3971 * 3972 * \note For one-time inspection of the peer's certificate during 3973 * the handshake, consider registering an X.509 CRT verification 3974 * callback through mbedtls_ssl_conf_verify() instead of calling 3975 * this function. Using mbedtls_ssl_conf_verify() also comes at 3976 * the benefit of allowing you to influence the verification 3977 * process, for example by masking expected and tolerated 3978 * verification failures. 3979 * 3980 * \warning You must not use the pointer returned by this function 3981 * after any further call to the SSL API, including 3982 * mbedtls_ssl_read() and mbedtls_ssl_write(); this is 3983 * because the pointer might change during renegotiation, 3984 * which happens transparently to the user. 3985 * If you want to use the certificate across API calls, 3986 * you must make a copy. 3987 */ 3988 const mbedtls_x509_crt *mbedtls_ssl_get_peer_cert( const mbedtls_ssl_context *ssl ); 3989 #endif /* MBEDTLS_X509_CRT_PARSE_C */ 3990 3991 #if defined(MBEDTLS_SSL_CLI_C) 3992 /** 3993 * \brief Export a session in order to resume it later. 3994 * 3995 * \param ssl The SSL context representing the connection for which to 3996 * to export a session structure for later resumption. 3997 * \param session The target structure in which to store the exported session. 3998 * This must have been initialized with mbedtls_ssl_init_session() 3999 * but otherwise be unused. 4000 * 4001 * \note This function can handle a variety of mechanisms for session 4002 * resumption: For TLS 1.2, both session ID-based resumption and 4003 * ticket-based resumption will be considered. For TLS 1.3, 4004 * once implemented, sessions equate to tickets, and calling 4005 * this function multiple times will export the available 4006 * tickets one a time until no further tickets are available, 4007 * in which case MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE will 4008 * be returned. 4009 * 4010 * \note Calling this function multiple times will only be useful 4011 * once TLS 1.3 is supported. For TLS 1.2 connections, this 4012 * function should be called at most once. 4013 * 4014 * \return \c 0 if successful. In this case, \p session can be used for 4015 * session resumption by passing it to mbedtls_ssl_set_session(), 4016 * and serialized for storage via mbedtls_ssl_session_save(). 4017 * \return #MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE if no further session 4018 * is available for export. 4019 * This error is a non-fatal, and has no observable effect on 4020 * the SSL context or the destination session. 4021 * \return Another negative error code on other kinds of failure. 4022 * 4023 * \sa mbedtls_ssl_set_session() 4024 * \sa mbedtls_ssl_session_save() 4025 */ 4026 int mbedtls_ssl_get_session( const mbedtls_ssl_context *ssl, 4027 mbedtls_ssl_session *session ); 4028 #endif /* MBEDTLS_SSL_CLI_C */ 4029 4030 /** 4031 * \brief Perform the SSL handshake 4032 * 4033 * \param ssl SSL context 4034 * 4035 * \return \c 0 if successful. 4036 * \return #MBEDTLS_ERR_SSL_WANT_READ or #MBEDTLS_ERR_SSL_WANT_WRITE 4037 * if the handshake is incomplete and waiting for data to 4038 * be available for reading from or writing to the underlying 4039 * transport - in this case you must call this function again 4040 * when the underlying transport is ready for the operation. 4041 * \return #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS if an asynchronous 4042 * operation is in progress (see 4043 * mbedtls_ssl_conf_async_private_cb()) - in this case you 4044 * must call this function again when the operation is ready. 4045 * \return #MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS if a cryptographic 4046 * operation is in progress (see mbedtls_ecp_set_max_ops()) - 4047 * in this case you must call this function again to complete 4048 * the handshake when you're done attending other tasks. 4049 * \return #MBEDTLS_ERR_SSL_HELLO_VERIFY_REQUIRED if DTLS is in use 4050 * and the client did not demonstrate reachability yet - in 4051 * this case you must stop using the context (see below). 4052 * \return Another SSL error code - in this case you must stop using 4053 * the context (see below). 4054 * 4055 * \warning If this function returns something other than 4056 * \c 0, 4057 * #MBEDTLS_ERR_SSL_WANT_READ, 4058 * #MBEDTLS_ERR_SSL_WANT_WRITE, 4059 * #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS or 4060 * #MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS, 4061 * you must stop using the SSL context for reading or writing, 4062 * and either free it or call \c mbedtls_ssl_session_reset() 4063 * on it before re-using it for a new connection; the current 4064 * connection must be closed. 4065 * 4066 * \note If DTLS is in use, then you may choose to handle 4067 * #MBEDTLS_ERR_SSL_HELLO_VERIFY_REQUIRED specially for logging 4068 * purposes, as it is an expected return value rather than an 4069 * actual error, but you still need to reset/free the context. 4070 * 4071 * \note Remarks regarding event-driven DTLS: 4072 * If the function returns #MBEDTLS_ERR_SSL_WANT_READ, no datagram 4073 * from the underlying transport layer is currently being processed, 4074 * and it is safe to idle until the timer or the underlying transport 4075 * signal a new event. This is not true for a successful handshake, 4076 * in which case the datagram of the underlying transport that is 4077 * currently being processed might or might not contain further 4078 * DTLS records. 4079 */ 4080 int mbedtls_ssl_handshake( mbedtls_ssl_context *ssl ); 4081 4082 /** 4083 * \brief Perform a single step of the SSL handshake 4084 * 4085 * \note The state of the context (ssl->state) will be at 4086 * the next state after this function returns \c 0. Do not 4087 * call this function if state is MBEDTLS_SSL_HANDSHAKE_OVER. 4088 * 4089 * \param ssl SSL context 4090 * 4091 * \return See mbedtls_ssl_handshake(). 4092 * 4093 * \warning If this function returns something other than \c 0, 4094 * #MBEDTLS_ERR_SSL_WANT_READ, #MBEDTLS_ERR_SSL_WANT_WRITE, 4095 * #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS or 4096 * #MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS, you must stop using 4097 * the SSL context for reading or writing, and either free it 4098 * or call \c mbedtls_ssl_session_reset() on it before 4099 * re-using it for a new connection; the current connection 4100 * must be closed. 4101 */ 4102 int mbedtls_ssl_handshake_step( mbedtls_ssl_context *ssl ); 4103 4104 #if defined(MBEDTLS_SSL_RENEGOTIATION) 4105 /** 4106 * \brief Initiate an SSL renegotiation on the running connection. 4107 * Client: perform the renegotiation right now. 4108 * Server: request renegotiation, which will be performed 4109 * during the next call to mbedtls_ssl_read() if honored by 4110 * client. 4111 * 4112 * \param ssl SSL context 4113 * 4114 * \return 0 if successful, or any mbedtls_ssl_handshake() return 4115 * value except #MBEDTLS_ERR_SSL_CLIENT_RECONNECT that can't 4116 * happen during a renegotiation. 4117 * 4118 * \warning If this function returns something other than \c 0, 4119 * #MBEDTLS_ERR_SSL_WANT_READ, #MBEDTLS_ERR_SSL_WANT_WRITE, 4120 * #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS or 4121 * #MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS, you must stop using 4122 * the SSL context for reading or writing, and either free it 4123 * or call \c mbedtls_ssl_session_reset() on it before 4124 * re-using it for a new connection; the current connection 4125 * must be closed. 4126 * 4127 */ 4128 int mbedtls_ssl_renegotiate( mbedtls_ssl_context *ssl ); 4129 #endif /* MBEDTLS_SSL_RENEGOTIATION */ 4130 4131 /** 4132 * \brief Read at most 'len' application data bytes 4133 * 4134 * \param ssl SSL context 4135 * \param buf buffer that will hold the data 4136 * \param len maximum number of bytes to read 4137 * 4138 * \return The (positive) number of bytes read if successful. 4139 * \return \c 0 if the read end of the underlying transport was closed 4140 * without sending a CloseNotify beforehand, which might happen 4141 * because of various reasons (internal error of an underlying 4142 * stack, non-conformant peer not sending a CloseNotify and 4143 * such) - in this case you must stop using the context 4144 * (see below). 4145 * \return #MBEDTLS_ERR_SSL_PEER_CLOSE_NOTIFY if the underlying 4146 * transport is still functional, but the peer has 4147 * acknowledged to not send anything anymore. 4148 * \return #MBEDTLS_ERR_SSL_WANT_READ or #MBEDTLS_ERR_SSL_WANT_WRITE 4149 * if the handshake is incomplete and waiting for data to 4150 * be available for reading from or writing to the underlying 4151 * transport - in this case you must call this function again 4152 * when the underlying transport is ready for the operation. 4153 * \return #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS if an asynchronous 4154 * operation is in progress (see 4155 * mbedtls_ssl_conf_async_private_cb()) - in this case you 4156 * must call this function again when the operation is ready. 4157 * \return #MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS if a cryptographic 4158 * operation is in progress (see mbedtls_ecp_set_max_ops()) - 4159 * in this case you must call this function again to complete 4160 * the handshake when you're done attending other tasks. 4161 * \return #MBEDTLS_ERR_SSL_CLIENT_RECONNECT if we're at the server 4162 * side of a DTLS connection and the client is initiating a 4163 * new connection using the same source port. See below. 4164 * \return Another SSL error code - in this case you must stop using 4165 * the context (see below). 4166 * 4167 * \warning If this function returns something other than 4168 * a positive value, 4169 * #MBEDTLS_ERR_SSL_WANT_READ, 4170 * #MBEDTLS_ERR_SSL_WANT_WRITE, 4171 * #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS, 4172 * #MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS or 4173 * #MBEDTLS_ERR_SSL_CLIENT_RECONNECT, 4174 * you must stop using the SSL context for reading or writing, 4175 * and either free it or call \c mbedtls_ssl_session_reset() 4176 * on it before re-using it for a new connection; the current 4177 * connection must be closed. 4178 * 4179 * \note When this function returns #MBEDTLS_ERR_SSL_CLIENT_RECONNECT 4180 * (which can only happen server-side), it means that a client 4181 * is initiating a new connection using the same source port. 4182 * You can either treat that as a connection close and wait 4183 * for the client to resend a ClientHello, or directly 4184 * continue with \c mbedtls_ssl_handshake() with the same 4185 * context (as it has been reset internally). Either way, you 4186 * must make sure this is seen by the application as a new 4187 * connection: application state, if any, should be reset, and 4188 * most importantly the identity of the client must be checked 4189 * again. WARNING: not validating the identity of the client 4190 * again, or not transmitting the new identity to the 4191 * application layer, would allow authentication bypass! 4192 * 4193 * \note Remarks regarding event-driven DTLS: 4194 * - If the function returns #MBEDTLS_ERR_SSL_WANT_READ, no datagram 4195 * from the underlying transport layer is currently being processed, 4196 * and it is safe to idle until the timer or the underlying transport 4197 * signal a new event. 4198 * - This function may return MBEDTLS_ERR_SSL_WANT_READ even if data was 4199 * initially available on the underlying transport, as this data may have 4200 * been only e.g. duplicated messages or a renegotiation request. 4201 * Therefore, you must be prepared to receive MBEDTLS_ERR_SSL_WANT_READ even 4202 * when reacting to an incoming-data event from the underlying transport. 4203 * - On success, the datagram of the underlying transport that is currently 4204 * being processed may contain further DTLS records. You should call 4205 * \c mbedtls_ssl_check_pending to check for remaining records. 4206 * 4207 */ 4208 int mbedtls_ssl_read( mbedtls_ssl_context *ssl, unsigned char *buf, size_t len ); 4209 4210 /** 4211 * \brief Try to write exactly 'len' application data bytes 4212 * 4213 * \warning This function will do partial writes in some cases. If the 4214 * return value is non-negative but less than length, the 4215 * function must be called again with updated arguments: 4216 * buf + ret, len - ret (if ret is the return value) until 4217 * it returns a value equal to the last 'len' argument. 4218 * 4219 * \param ssl SSL context 4220 * \param buf buffer holding the data 4221 * \param len how many bytes must be written 4222 * 4223 * \return The (non-negative) number of bytes actually written if 4224 * successful (may be less than \p len). 4225 * \return #MBEDTLS_ERR_SSL_WANT_READ or #MBEDTLS_ERR_SSL_WANT_WRITE 4226 * if the handshake is incomplete and waiting for data to 4227 * be available for reading from or writing to the underlying 4228 * transport - in this case you must call this function again 4229 * when the underlying transport is ready for the operation. 4230 * \return #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS if an asynchronous 4231 * operation is in progress (see 4232 * mbedtls_ssl_conf_async_private_cb()) - in this case you 4233 * must call this function again when the operation is ready. 4234 * \return #MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS if a cryptographic 4235 * operation is in progress (see mbedtls_ecp_set_max_ops()) - 4236 * in this case you must call this function again to complete 4237 * the handshake when you're done attending other tasks. 4238 * \return Another SSL error code - in this case you must stop using 4239 * the context (see below). 4240 * 4241 * \warning If this function returns something other than 4242 * a non-negative value, 4243 * #MBEDTLS_ERR_SSL_WANT_READ, 4244 * #MBEDTLS_ERR_SSL_WANT_WRITE, 4245 * #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS or 4246 * #MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS, 4247 * you must stop using the SSL context for reading or writing, 4248 * and either free it or call \c mbedtls_ssl_session_reset() 4249 * on it before re-using it for a new connection; the current 4250 * connection must be closed. 4251 * 4252 * \note When this function returns #MBEDTLS_ERR_SSL_WANT_WRITE/READ, 4253 * it must be called later with the *same* arguments, 4254 * until it returns a value greater that or equal to 0. When 4255 * the function returns #MBEDTLS_ERR_SSL_WANT_WRITE there may be 4256 * some partial data in the output buffer, however this is not 4257 * yet sent. 4258 * 4259 * \note If the requested length is greater than the maximum 4260 * fragment length (either the built-in limit or the one set 4261 * or negotiated with the peer), then: 4262 * - with TLS, less bytes than requested are written. 4263 * - with DTLS, MBEDTLS_ERR_SSL_BAD_INPUT_DATA is returned. 4264 * \c mbedtls_ssl_get_max_out_record_payload() may be used to 4265 * query the active maximum fragment length. 4266 * 4267 * \note Attempting to write 0 bytes will result in an empty TLS 4268 * application record being sent. 4269 */ 4270 int mbedtls_ssl_write( mbedtls_ssl_context *ssl, const unsigned char *buf, size_t len ); 4271 4272 /** 4273 * \brief Send an alert message 4274 * 4275 * \param ssl SSL context 4276 * \param level The alert level of the message 4277 * (MBEDTLS_SSL_ALERT_LEVEL_WARNING or MBEDTLS_SSL_ALERT_LEVEL_FATAL) 4278 * \param message The alert message (SSL_ALERT_MSG_*) 4279 * 4280 * \return 0 if successful, or a specific SSL error code. 4281 * 4282 * \note If this function returns something other than 0 or 4283 * MBEDTLS_ERR_SSL_WANT_READ/WRITE, you must stop using 4284 * the SSL context for reading or writing, and either free it or 4285 * call \c mbedtls_ssl_session_reset() on it before re-using it 4286 * for a new connection; the current connection must be closed. 4287 */ 4288 int mbedtls_ssl_send_alert_message( mbedtls_ssl_context *ssl, 4289 unsigned char level, 4290 unsigned char message ); 4291 /** 4292 * \brief Notify the peer that the connection is being closed 4293 * 4294 * \param ssl SSL context 4295 * 4296 * \return 0 if successful, or a specific SSL error code. 4297 * 4298 * \note If this function returns something other than 0 or 4299 * MBEDTLS_ERR_SSL_WANT_READ/WRITE, you must stop using 4300 * the SSL context for reading or writing, and either free it or 4301 * call \c mbedtls_ssl_session_reset() on it before re-using it 4302 * for a new connection; the current connection must be closed. 4303 */ 4304 int mbedtls_ssl_close_notify( mbedtls_ssl_context *ssl ); 4305 4306 /** 4307 * \brief Free referenced items in an SSL context and clear memory 4308 * 4309 * \param ssl SSL context 4310 */ 4311 void mbedtls_ssl_free( mbedtls_ssl_context *ssl ); 4312 4313 #if defined(MBEDTLS_SSL_CONTEXT_SERIALIZATION) 4314 /** 4315 * \brief Save an active connection as serialized data in a buffer. 4316 * This allows the freeing or re-using of the SSL context 4317 * while still picking up the connection later in a way that 4318 * it entirely transparent to the peer. 4319 * 4320 * \see mbedtls_ssl_context_load() 4321 * 4322 * \note This feature is currently only available under certain 4323 * conditions, see the documentation of the return value 4324 * #MBEDTLS_ERR_SSL_BAD_INPUT_DATA for details. 4325 * 4326 * \note When this function succeeds, it calls 4327 * mbedtls_ssl_session_reset() on \p ssl which as a result is 4328 * no longer associated with the connection that has been 4329 * serialized. This avoids creating copies of the connection 4330 * state. You're then free to either re-use the context 4331 * structure for a different connection, or call 4332 * mbedtls_ssl_free() on it. See the documentation of 4333 * mbedtls_ssl_session_reset() for more details. 4334 * 4335 * \param ssl The SSL context to save. On success, it is no longer 4336 * associated with the connection that has been serialized. 4337 * \param buf The buffer to write the serialized data to. It must be a 4338 * writeable buffer of at least \p buf_len bytes, or may be \c 4339 * NULL if \p buf_len is \c 0. 4340 * \param buf_len The number of bytes available for writing in \p buf. 4341 * \param olen The size in bytes of the data that has been or would have 4342 * been written. It must point to a valid \c size_t. 4343 * 4344 * \note \p olen is updated to the correct value regardless of 4345 * whether \p buf_len was large enough. This makes it possible 4346 * to determine the necessary size by calling this function 4347 * with \p buf set to \c NULL and \p buf_len to \c 0. However, 4348 * the value of \p olen is only guaranteed to be correct when 4349 * the function returns #MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL or 4350 * \c 0. If the return value is different, then the value of 4351 * \p olen is undefined. 4352 * 4353 * \return \c 0 if successful. 4354 * \return #MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL if \p buf is too small. 4355 * \return #MBEDTLS_ERR_SSL_ALLOC_FAILED if memory allocation failed 4356 * while reseting the context. 4357 * \return #MBEDTLS_ERR_SSL_BAD_INPUT_DATA if a handshake is in 4358 * progress, or there is pending data for reading or sending, 4359 * or the connection does not use DTLS 1.2 with an AEAD 4360 * ciphersuite, or renegotiation is enabled. 4361 */ 4362 int mbedtls_ssl_context_save( mbedtls_ssl_context *ssl, 4363 unsigned char *buf, 4364 size_t buf_len, 4365 size_t *olen ); 4366 4367 /** 4368 * \brief Load serialized connection data to an SSL context. 4369 * 4370 * \see mbedtls_ssl_context_save() 4371 * 4372 * \warning The same serialized data must never be loaded into more 4373 * that one context. In order to ensure that, after 4374 * successfully loading serialized data to an SSL context, you 4375 * should immediately destroy or invalidate all copies of the 4376 * serialized data that was loaded. Loading the same data in 4377 * more than one context would cause severe security failures 4378 * including but not limited to loss of confidentiality. 4379 * 4380 * \note Before calling this function, the SSL context must be 4381 * prepared in one of the two following ways. The first way is 4382 * to take a context freshly initialised with 4383 * mbedtls_ssl_init() and call mbedtls_ssl_setup() on it with 4384 * the same ::mbedtls_ssl_config structure that was used in 4385 * the original connection. The second way is to 4386 * call mbedtls_ssl_session_reset() on a context that was 4387 * previously prepared as above but used in the meantime. 4388 * Either way, you must not use the context to perform a 4389 * handshake between calling mbedtls_ssl_setup() or 4390 * mbedtls_ssl_session_reset() and calling this function. You 4391 * may however call other setter functions in that time frame 4392 * as indicated in the note below. 4393 * 4394 * \note Before or after calling this function successfully, you 4395 * also need to configure some connection-specific callbacks 4396 * and settings before you can use the connection again 4397 * (unless they were already set before calling 4398 * mbedtls_ssl_session_reset() and the values are suitable for 4399 * the present connection). Specifically, you want to call 4400 * at least mbedtls_ssl_set_bio() and 4401 * mbedtls_ssl_set_timer_cb(). All other SSL setter functions 4402 * are not necessary to call, either because they're only used 4403 * in handshakes, or because the setting is already saved. You 4404 * might choose to call them anyway, for example in order to 4405 * share code between the cases of establishing a new 4406 * connection and the case of loading an already-established 4407 * connection. 4408 * 4409 * \note If you have new information about the path MTU, you want to 4410 * call mbedtls_ssl_set_mtu() after calling this function, as 4411 * otherwise this function would overwrite your 4412 * newly-configured value with the value that was active when 4413 * the context was saved. 4414 * 4415 * \note When this function returns an error code, it calls 4416 * mbedtls_ssl_free() on \p ssl. In this case, you need to 4417 * prepare the context with the usual sequence starting with a 4418 * call to mbedtls_ssl_init() if you want to use it again. 4419 * 4420 * \param ssl The SSL context structure to be populated. It must have 4421 * been prepared as described in the note above. 4422 * \param buf The buffer holding the serialized connection data. It must 4423 * be a readable buffer of at least \p len bytes. 4424 * \param len The size of the serialized data in bytes. 4425 * 4426 * \return \c 0 if successful. 4427 * \return #MBEDTLS_ERR_SSL_ALLOC_FAILED if memory allocation failed. 4428 * \return #MBEDTLS_ERR_SSL_VERSION_MISMATCH if the serialized data 4429 * comes from a different Mbed TLS version or build. 4430 * \return #MBEDTLS_ERR_SSL_BAD_INPUT_DATA if input data is invalid. 4431 */ 4432 int mbedtls_ssl_context_load( mbedtls_ssl_context *ssl, 4433 const unsigned char *buf, 4434 size_t len ); 4435 #endif /* MBEDTLS_SSL_CONTEXT_SERIALIZATION */ 4436 4437 /** 4438 * \brief Initialize an SSL configuration context 4439 * Just makes the context ready for 4440 * mbedtls_ssl_config_defaults() or mbedtls_ssl_config_free(). 4441 * 4442 * \note You need to call mbedtls_ssl_config_defaults() unless you 4443 * manually set all of the relevant fields yourself. 4444 * 4445 * \param conf SSL configuration context 4446 */ 4447 void mbedtls_ssl_config_init( mbedtls_ssl_config *conf ); 4448 4449 /** 4450 * \brief Load reasonnable default SSL configuration values. 4451 * (You need to call mbedtls_ssl_config_init() first.) 4452 * 4453 * \param conf SSL configuration context 4454 * \param endpoint MBEDTLS_SSL_IS_CLIENT or MBEDTLS_SSL_IS_SERVER 4455 * \param transport MBEDTLS_SSL_TRANSPORT_STREAM for TLS, or 4456 * MBEDTLS_SSL_TRANSPORT_DATAGRAM for DTLS 4457 * \param preset a MBEDTLS_SSL_PRESET_XXX value 4458 * 4459 * \note See \c mbedtls_ssl_conf_transport() for notes on DTLS. 4460 * 4461 * \return 0 if successful, or 4462 * MBEDTLS_ERR_XXX_ALLOC_FAILED on memory allocation error. 4463 */ 4464 int mbedtls_ssl_config_defaults( mbedtls_ssl_config *conf, 4465 int endpoint, int transport, int preset ); 4466 4467 /** 4468 * \brief Free an SSL configuration context 4469 * 4470 * \param conf SSL configuration context 4471 */ 4472 void mbedtls_ssl_config_free( mbedtls_ssl_config *conf ); 4473 4474 /** 4475 * \brief Initialize SSL session structure 4476 * 4477 * \param session SSL session 4478 */ 4479 void mbedtls_ssl_session_init( mbedtls_ssl_session *session ); 4480 4481 /** 4482 * \brief Free referenced items in an SSL session including the 4483 * peer certificate and clear memory 4484 * 4485 * \note A session object can be freed even if the SSL context 4486 * that was used to retrieve the session is still in use. 4487 * 4488 * \param session SSL session 4489 */ 4490 void mbedtls_ssl_session_free( mbedtls_ssl_session *session ); 4491 4492 /** 4493 * \brief TLS-PRF function for key derivation. 4494 * 4495 * \param prf The tls_prf type function type to be used. 4496 * \param secret Secret for the key derivation function. 4497 * \param slen Length of the secret. 4498 * \param label String label for the key derivation function, 4499 * terminated with null character. 4500 * \param random Random bytes. 4501 * \param rlen Length of the random bytes buffer. 4502 * \param dstbuf The buffer holding the derived key. 4503 * \param dlen Length of the output buffer. 4504 * 4505 * \return 0 on success. An SSL specific error on failure. 4506 */ 4507 int mbedtls_ssl_tls_prf( const mbedtls_tls_prf_types prf, 4508 const unsigned char *secret, size_t slen, 4509 const char *label, 4510 const unsigned char *random, size_t rlen, 4511 unsigned char *dstbuf, size_t dlen ); 4512 4513 #ifdef __cplusplus 4514 } 4515 #endif 4516 4517 #endif /* ssl.h */ 4518