NCBI C++ ToolKit
ssl.h
Go to the documentation of this file.

Go to the SVN repository for this file.

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 OR GPL-2.0-or-later
9  */
10 #ifndef MBEDTLS_SSL_H
11 #define MBEDTLS_SSL_H
12 #include "mbedtls/platform_util.h"
13 #include "mbedtls/private_access.h"
14 
15 #include "mbedtls/build_info.h"
16 
17 #include "mbedtls/bignum.h"
18 #include "mbedtls/ecp.h"
19 
21 
22 #if defined(MBEDTLS_X509_CRT_PARSE_C)
23 #include "mbedtls/x509_crt.h"
24 #include "mbedtls/x509_crl.h"
25 #endif
26 
27 #if defined(MBEDTLS_DHM_C)
28 #include "mbedtls/dhm.h"
29 #endif
30 
31 #include "mbedtls/md.h"
32 
33 #if defined(MBEDTLS_KEY_EXCHANGE_SOME_ECDH_OR_ECDHE_ANY_ENABLED)
34 #include "mbedtls/ecdh.h"
35 #endif
36 
37 #if defined(MBEDTLS_HAVE_TIME)
38 #include "mbedtls/platform_time.h"
39 #endif
40 
41 #include "psa/crypto.h"
42 
43 /*
44  * SSL Error codes
45  */
46 /** A cryptographic operation is in progress. Try again later. */
47 #define MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS -0x7000
48 /** The requested feature is not available. */
49 #define MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE -0x7080
50 /** Bad input parameters to function. */
51 #define MBEDTLS_ERR_SSL_BAD_INPUT_DATA -0x7100
52 /** Verification of the message MAC failed. */
53 #define MBEDTLS_ERR_SSL_INVALID_MAC -0x7180
54 /** An invalid SSL record was received. */
55 #define MBEDTLS_ERR_SSL_INVALID_RECORD -0x7200
56 /** The connection indicated an EOF. */
57 #define MBEDTLS_ERR_SSL_CONN_EOF -0x7280
58 /** A message could not be parsed due to a syntactic error. */
59 #define MBEDTLS_ERR_SSL_DECODE_ERROR -0x7300
60 /* Error space gap */
61 /** No RNG was provided to the SSL module. */
62 #define MBEDTLS_ERR_SSL_NO_RNG -0x7400
63 /** No client certification received from the client, but required by the authentication mode. */
64 #define MBEDTLS_ERR_SSL_NO_CLIENT_CERTIFICATE -0x7480
65 /** Client received an extended server hello containing an unsupported extension */
66 #define MBEDTLS_ERR_SSL_UNSUPPORTED_EXTENSION -0x7500
67 /** No ALPN protocols supported that the client advertises */
68 #define MBEDTLS_ERR_SSL_NO_APPLICATION_PROTOCOL -0x7580
69 /** The own private key or pre-shared key is not set, but needed. */
70 #define MBEDTLS_ERR_SSL_PRIVATE_KEY_REQUIRED -0x7600
71 /** No CA Chain is set, but required to operate. */
72 #define MBEDTLS_ERR_SSL_CA_CHAIN_REQUIRED -0x7680
73 /** An unexpected message was received from our peer. */
74 #define MBEDTLS_ERR_SSL_UNEXPECTED_MESSAGE -0x7700
75 /** A fatal alert message was received from our peer. */
76 #define MBEDTLS_ERR_SSL_FATAL_ALERT_MESSAGE -0x7780
77 /** No server could be identified matching the client's SNI. */
78 #define MBEDTLS_ERR_SSL_UNRECOGNIZED_NAME -0x7800
79 /** The peer notified us that the connection is going to be closed. */
80 #define MBEDTLS_ERR_SSL_PEER_CLOSE_NOTIFY -0x7880
81 /* Error space gap */
82 /* Error space gap */
83 /** Processing of the Certificate handshake message failed. */
84 #define MBEDTLS_ERR_SSL_BAD_CERTIFICATE -0x7A00
85 /* Error space gap */
86 /**
87  * Received NewSessionTicket Post Handshake Message.
88  * This error code is experimental and may be changed or removed without notice.
89  */
90 #define MBEDTLS_ERR_SSL_RECEIVED_NEW_SESSION_TICKET -0x7B00
91 /** Not possible to read early data */
92 #define MBEDTLS_ERR_SSL_CANNOT_READ_EARLY_DATA -0x7B80
93 /**
94  * Early data has been received as part of an on-going handshake.
95  * This error code can be returned only on server side if and only if early
96  * data has been enabled by means of the mbedtls_ssl_conf_early_data() API.
97  * This error code can then be returned by mbedtls_ssl_handshake(),
98  * mbedtls_ssl_handshake_step(), mbedtls_ssl_read() or mbedtls_ssl_write() if
99  * early data has been received as part of the handshake sequence they
100  * triggered. To read the early data, call mbedtls_ssl_read_early_data().
101  */
102 #define MBEDTLS_ERR_SSL_RECEIVED_EARLY_DATA -0x7C00
103 /** Not possible to write early data */
104 #define MBEDTLS_ERR_SSL_CANNOT_WRITE_EARLY_DATA -0x7C80
105 /* Error space gap */
106 /* Error space gap */
107 /* Error space gap */
108 /* Error space gap */
109 /** Cache entry not found */
110 #define MBEDTLS_ERR_SSL_CACHE_ENTRY_NOT_FOUND -0x7E80
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  * Constants from RFC 8446 for TLS 1.3 PSK modes
175  *
176  * Those are used in the Pre-Shared Key Exchange Modes extension.
177  * See Section 4.2.9 in RFC 8446.
178  */
179 #define MBEDTLS_SSL_TLS1_3_PSK_MODE_PURE 0 /* Pure PSK-based exchange */
180 #define MBEDTLS_SSL_TLS1_3_PSK_MODE_ECDHE 1 /* PSK+ECDHE-based exchange */
181 
182 /*
183  * TLS 1.3 NamedGroup values
184  *
185  * From RF 8446
186  * enum {
187  * // Elliptic Curve Groups (ECDHE)
188  * secp256r1(0x0017), secp384r1(0x0018), secp521r1(0x0019),
189  * x25519(0x001D), x448(0x001E),
190  * // Finite Field Groups (DHE)
191  * ffdhe2048(0x0100), ffdhe3072(0x0101), ffdhe4096(0x0102),
192  * ffdhe6144(0x0103), ffdhe8192(0x0104),
193  * // Reserved Code Points
194  * ffdhe_private_use(0x01FC..0x01FF),
195  * ecdhe_private_use(0xFE00..0xFEFF),
196  * (0xFFFF)
197  * } NamedGroup;
198  *
199  */
200 
201 /* Elliptic Curve Groups (ECDHE) */
202 #define MBEDTLS_SSL_IANA_TLS_GROUP_NONE 0
203 #define MBEDTLS_SSL_IANA_TLS_GROUP_SECP192K1 0x0012
204 #define MBEDTLS_SSL_IANA_TLS_GROUP_SECP192R1 0x0013
205 #define MBEDTLS_SSL_IANA_TLS_GROUP_SECP224K1 0x0014
206 #define MBEDTLS_SSL_IANA_TLS_GROUP_SECP224R1 0x0015
207 #define MBEDTLS_SSL_IANA_TLS_GROUP_SECP256K1 0x0016
208 #define MBEDTLS_SSL_IANA_TLS_GROUP_SECP256R1 0x0017
209 #define MBEDTLS_SSL_IANA_TLS_GROUP_SECP384R1 0x0018
210 #define MBEDTLS_SSL_IANA_TLS_GROUP_SECP521R1 0x0019
211 #define MBEDTLS_SSL_IANA_TLS_GROUP_BP256R1 0x001A
212 #define MBEDTLS_SSL_IANA_TLS_GROUP_BP384R1 0x001B
213 #define MBEDTLS_SSL_IANA_TLS_GROUP_BP512R1 0x001C
214 #define MBEDTLS_SSL_IANA_TLS_GROUP_X25519 0x001D
215 #define MBEDTLS_SSL_IANA_TLS_GROUP_X448 0x001E
216 /* Finite Field Groups (DHE) */
217 #define MBEDTLS_SSL_IANA_TLS_GROUP_FFDHE2048 0x0100
218 #define MBEDTLS_SSL_IANA_TLS_GROUP_FFDHE3072 0x0101
219 #define MBEDTLS_SSL_IANA_TLS_GROUP_FFDHE4096 0x0102
220 #define MBEDTLS_SSL_IANA_TLS_GROUP_FFDHE6144 0x0103
221 #define MBEDTLS_SSL_IANA_TLS_GROUP_FFDHE8192 0x0104
222 
223 /*
224  * TLS 1.3 Key Exchange Modes
225  *
226  * Mbed TLS internal identifiers for use with the SSL configuration API
227  * mbedtls_ssl_conf_tls13_key_exchange_modes().
228  */
229 
230 #define MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK (1u << 0) /*!< Pure-PSK TLS 1.3 key exchange,
231  * encompassing both externally agreed PSKs
232  * as well as resumption PSKs. */
233 #define MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_EPHEMERAL (1u << 1) /*!< Pure-Ephemeral TLS 1.3 key exchanges,
234  * including for example ECDHE and DHE
235  * key exchanges. */
236 #define MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_EPHEMERAL (1u << 2) /*!< PSK-Ephemeral TLS 1.3 key exchanges,
237  * using both a PSK and an ephemeral
238  * key exchange. */
239 
240 /* Convenience macros for sets of key exchanges. */
241 #define MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_ALL \
242  (MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK | \
243  MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_EPHEMERAL | \
244  MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_EPHEMERAL) /*!< All TLS 1.3 key exchanges */
245 #define MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_ALL \
246  (MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK | \
247  MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_EPHEMERAL) /*!< All PSK-based TLS 1.3 key exchanges */
248 #define MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_EPHEMERAL_ALL \
249  (MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_EPHEMERAL | \
250  MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_EPHEMERAL) /*!< All ephemeral TLS 1.3 key exchanges */
251 
252 #define MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_NONE (0)
253 
254 /*
255  * Various constants
256  */
257 
258 #if !defined(MBEDTLS_DEPRECATED_REMOVED)
259 /* These are the high and low bytes of ProtocolVersion as defined by:
260  * - RFC 5246: ProtocolVersion version = { 3, 3 }; // TLS v1.2
261  * - RFC 8446: see section 4.2.1
262  */
263 #define MBEDTLS_SSL_MAJOR_VERSION_3 3
264 #define MBEDTLS_SSL_MINOR_VERSION_3 3 /*!< TLS v1.2 */
265 #define MBEDTLS_SSL_MINOR_VERSION_4 4 /*!< TLS v1.3 */
266 #endif /* MBEDTLS_DEPRECATED_REMOVED */
267 
268 #define MBEDTLS_SSL_TRANSPORT_STREAM 0 /*!< TLS */
269 #define MBEDTLS_SSL_TRANSPORT_DATAGRAM 1 /*!< DTLS */
270 
271 #define MBEDTLS_SSL_MAX_HOST_NAME_LEN 255 /*!< Maximum host name defined in RFC 1035 */
272 #define MBEDTLS_SSL_MAX_ALPN_NAME_LEN 255 /*!< Maximum size in bytes of a protocol name in alpn ext., RFC 7301 */
273 
274 #define MBEDTLS_SSL_MAX_ALPN_LIST_LEN 65535 /*!< Maximum size in bytes of list in alpn ext., RFC 7301 */
275 
276 /* RFC 6066 section 4, see also mfl_code_to_length in ssl_tls.c
277  * NONE must be zero so that memset()ing structure to zero works */
278 #define MBEDTLS_SSL_MAX_FRAG_LEN_NONE 0 /*!< don't use this extension */
279 #define MBEDTLS_SSL_MAX_FRAG_LEN_512 1 /*!< MaxFragmentLength 2^9 */
280 #define MBEDTLS_SSL_MAX_FRAG_LEN_1024 2 /*!< MaxFragmentLength 2^10 */
281 #define MBEDTLS_SSL_MAX_FRAG_LEN_2048 3 /*!< MaxFragmentLength 2^11 */
282 #define MBEDTLS_SSL_MAX_FRAG_LEN_4096 4 /*!< MaxFragmentLength 2^12 */
283 #define MBEDTLS_SSL_MAX_FRAG_LEN_INVALID 5 /*!< first invalid value */
284 
285 #define MBEDTLS_SSL_IS_CLIENT 0
286 #define MBEDTLS_SSL_IS_SERVER 1
287 
288 #define MBEDTLS_SSL_EXTENDED_MS_DISABLED 0
289 #define MBEDTLS_SSL_EXTENDED_MS_ENABLED 1
290 
291 #define MBEDTLS_SSL_CID_DISABLED 0
292 #define MBEDTLS_SSL_CID_ENABLED 1
293 
294 #define MBEDTLS_SSL_ETM_DISABLED 0
295 #define MBEDTLS_SSL_ETM_ENABLED 1
296 
297 #define MBEDTLS_SSL_COMPRESS_NULL 0
298 
299 #define MBEDTLS_SSL_VERIFY_NONE 0
300 #define MBEDTLS_SSL_VERIFY_OPTIONAL 1
301 #define MBEDTLS_SSL_VERIFY_REQUIRED 2
302 #define MBEDTLS_SSL_VERIFY_UNSET 3 /* Used only for sni_authmode */
303 
304 #define MBEDTLS_SSL_LEGACY_RENEGOTIATION 0
305 #define MBEDTLS_SSL_SECURE_RENEGOTIATION 1
306 
307 #define MBEDTLS_SSL_RENEGOTIATION_DISABLED 0
308 #define MBEDTLS_SSL_RENEGOTIATION_ENABLED 1
309 
310 #define MBEDTLS_SSL_ANTI_REPLAY_DISABLED 0
311 #define MBEDTLS_SSL_ANTI_REPLAY_ENABLED 1
312 
313 #define MBEDTLS_SSL_RENEGOTIATION_NOT_ENFORCED -1
314 #define MBEDTLS_SSL_RENEGO_MAX_RECORDS_DEFAULT 16
315 
316 #define MBEDTLS_SSL_LEGACY_NO_RENEGOTIATION 0
317 #define MBEDTLS_SSL_LEGACY_ALLOW_RENEGOTIATION 1
318 #define MBEDTLS_SSL_LEGACY_BREAK_HANDSHAKE 2
319 
320 #define MBEDTLS_SSL_TRUNC_HMAC_DISABLED 0
321 #define MBEDTLS_SSL_TRUNC_HMAC_ENABLED 1
322 #define MBEDTLS_SSL_TRUNCATED_HMAC_LEN 10 /* 80 bits, rfc 6066 section 7 */
323 
324 #define MBEDTLS_SSL_SESSION_TICKETS_DISABLED 0
325 #define MBEDTLS_SSL_SESSION_TICKETS_ENABLED 1
326 
327 #define MBEDTLS_SSL_PRESET_DEFAULT 0
328 #define MBEDTLS_SSL_PRESET_SUITEB 2
329 
330 #define MBEDTLS_SSL_CERT_REQ_CA_LIST_ENABLED 1
331 #define MBEDTLS_SSL_CERT_REQ_CA_LIST_DISABLED 0
332 
333 #define MBEDTLS_SSL_EARLY_DATA_DISABLED 0
334 #define MBEDTLS_SSL_EARLY_DATA_ENABLED 1
335 
336 #define MBEDTLS_SSL_DTLS_SRTP_MKI_UNSUPPORTED 0
337 #define MBEDTLS_SSL_DTLS_SRTP_MKI_SUPPORTED 1
338 
339 #define MBEDTLS_SSL_SRV_CIPHERSUITE_ORDER_CLIENT 1
340 #define MBEDTLS_SSL_SRV_CIPHERSUITE_ORDER_SERVER 0
341 
342 #if defined(MBEDTLS_SSL_PROTO_TLS1_3) && defined(MBEDTLS_SSL_SESSION_TICKETS)
343 #if defined(PSA_WANT_ALG_SHA_384)
344 #define MBEDTLS_SSL_TLS1_3_TICKET_RESUMPTION_KEY_LEN 48
345 #elif defined(PSA_WANT_ALG_SHA_256)
346 #define MBEDTLS_SSL_TLS1_3_TICKET_RESUMPTION_KEY_LEN 32
347 #endif
348 #endif /* MBEDTLS_SSL_PROTO_TLS1_3 && MBEDTLS_SSL_SESSION_TICKETS */
349 /*
350  * Default range for DTLS retransmission timer value, in milliseconds.
351  * RFC 6347 4.2.4.1 says from 1 second to 60 seconds.
352  */
353 #define MBEDTLS_SSL_DTLS_TIMEOUT_DFL_MIN 1000
354 #define MBEDTLS_SSL_DTLS_TIMEOUT_DFL_MAX 60000
355 
356 /*
357  * Whether early data record should be discarded or not and how.
358  *
359  * The client has indicated early data and the server has rejected them.
360  * The server has then to skip past early data by either:
361  * - attempting to deprotect received records using the handshake traffic
362  * key, discarding records which fail deprotection (up to the configured
363  * max_early_data_size). Once a record is deprotected successfully,
364  * it is treated as the start of the client's second flight and the
365  * server proceeds as with an ordinary 1-RTT handshake.
366  * - skipping all records with an external content type of
367  * "application_data" (indicating that they are encrypted), up to the
368  * configured max_early_data_size. This is the expected behavior if the
369  * server has sent an HelloRetryRequest message. The server ignores
370  * application data message before 2nd ClientHello.
371  */
372 #define MBEDTLS_SSL_EARLY_DATA_NO_DISCARD 0
373 #define MBEDTLS_SSL_EARLY_DATA_TRY_TO_DEPROTECT_AND_DISCARD 1
374 #define MBEDTLS_SSL_EARLY_DATA_DISCARD 2
375 
376 /**
377  * \name SECTION: Module settings
378  *
379  * The configuration options you can set for this module are in this section.
380  * Either change them in mbedtls_config.h or define them on the compiler command line.
381  * \{
382  */
383 
384 /*
385  * Maximum fragment length in bytes,
386  * determines the size of each of the two internal I/O buffers.
387  *
388  * Note: the RFC defines the default size of SSL / TLS messages. If you
389  * change the value here, other clients / servers may not be able to
390  * communicate with you anymore. Only change this value if you control
391  * both sides of the connection and have it reduced at both sides, or
392  * if you're using the Max Fragment Length extension and you know all your
393  * peers are using it too!
394  */
395 #if !defined(MBEDTLS_SSL_IN_CONTENT_LEN)
396 #define MBEDTLS_SSL_IN_CONTENT_LEN 16384
397 #endif
398 
399 #if !defined(MBEDTLS_SSL_OUT_CONTENT_LEN)
400 #define MBEDTLS_SSL_OUT_CONTENT_LEN 16384
401 #endif
402 
403 /*
404  * Maximum number of heap-allocated bytes for the purpose of
405  * DTLS handshake message reassembly and future message buffering.
406  */
407 #if !defined(MBEDTLS_SSL_DTLS_MAX_BUFFERING)
408 #define MBEDTLS_SSL_DTLS_MAX_BUFFERING 32768
409 #endif
410 
411 /*
412  * Maximum length of CIDs for incoming and outgoing messages.
413  */
414 #if !defined(MBEDTLS_SSL_CID_IN_LEN_MAX)
415 #define MBEDTLS_SSL_CID_IN_LEN_MAX 32
416 #endif
417 
418 #if !defined(MBEDTLS_SSL_CID_OUT_LEN_MAX)
419 #define MBEDTLS_SSL_CID_OUT_LEN_MAX 32
420 #endif
421 
422 #if !defined(MBEDTLS_SSL_CID_TLS1_3_PADDING_GRANULARITY)
423 #define MBEDTLS_SSL_CID_TLS1_3_PADDING_GRANULARITY 16
424 #endif
425 
426 #if !defined(MBEDTLS_SSL_MAX_EARLY_DATA_SIZE)
427 #define MBEDTLS_SSL_MAX_EARLY_DATA_SIZE 1024
428 #endif
429 
430 #if !defined(MBEDTLS_SSL_TLS1_3_TICKET_AGE_TOLERANCE)
431 #define MBEDTLS_SSL_TLS1_3_TICKET_AGE_TOLERANCE 6000
432 #endif
433 
434 #if !defined(MBEDTLS_SSL_TLS1_3_TICKET_NONCE_LENGTH)
435 #define MBEDTLS_SSL_TLS1_3_TICKET_NONCE_LENGTH 32
436 #endif
437 
438 #if !defined(MBEDTLS_SSL_TLS1_3_DEFAULT_NEW_SESSION_TICKETS)
439 #define MBEDTLS_SSL_TLS1_3_DEFAULT_NEW_SESSION_TICKETS 1
440 #endif
441 
442 /** \} name SECTION: Module settings */
443 
444 /*
445  * Default to standard CID mode
446  */
447 #if defined(MBEDTLS_SSL_DTLS_CONNECTION_ID) && \
448  !defined(MBEDTLS_SSL_DTLS_CONNECTION_ID_COMPAT)
449 #define MBEDTLS_SSL_DTLS_CONNECTION_ID_COMPAT 0
450 #endif
451 
452 /*
453  * Length of the verify data for secure renegotiation
454  */
455 #define MBEDTLS_SSL_VERIFY_DATA_MAX_LEN 12
456 
457 /*
458  * Signaling ciphersuite values (SCSV)
459  */
460 #define MBEDTLS_SSL_EMPTY_RENEGOTIATION_INFO 0xFF /**< renegotiation info ext */
461 
462 /*
463  * Supported Signature and Hash algorithms (For TLS 1.2)
464  * RFC 5246 section 7.4.1.4.1
465  */
466 #define MBEDTLS_SSL_HASH_NONE 0
467 #define MBEDTLS_SSL_HASH_MD5 1
468 #define MBEDTLS_SSL_HASH_SHA1 2
469 #define MBEDTLS_SSL_HASH_SHA224 3
470 #define MBEDTLS_SSL_HASH_SHA256 4
471 #define MBEDTLS_SSL_HASH_SHA384 5
472 #define MBEDTLS_SSL_HASH_SHA512 6
473 
474 #define MBEDTLS_SSL_SIG_ANON 0
475 #define MBEDTLS_SSL_SIG_RSA 1
476 #define MBEDTLS_SSL_SIG_ECDSA 3
477 
478 /*
479  * TLS 1.3 signature algorithms
480  * RFC 8446, Section 4.2.3
481  */
482 
483 /* RSASSA-PKCS1-v1_5 algorithms */
484 #define MBEDTLS_TLS1_3_SIG_RSA_PKCS1_SHA256 0x0401
485 #define MBEDTLS_TLS1_3_SIG_RSA_PKCS1_SHA384 0x0501
486 #define MBEDTLS_TLS1_3_SIG_RSA_PKCS1_SHA512 0x0601
487 
488 /* ECDSA algorithms */
489 #define MBEDTLS_TLS1_3_SIG_ECDSA_SECP256R1_SHA256 0x0403
490 #define MBEDTLS_TLS1_3_SIG_ECDSA_SECP384R1_SHA384 0x0503
491 #define MBEDTLS_TLS1_3_SIG_ECDSA_SECP521R1_SHA512 0x0603
492 
493 /* RSASSA-PSS algorithms with public key OID rsaEncryption */
494 #define MBEDTLS_TLS1_3_SIG_RSA_PSS_RSAE_SHA256 0x0804
495 #define MBEDTLS_TLS1_3_SIG_RSA_PSS_RSAE_SHA384 0x0805
496 #define MBEDTLS_TLS1_3_SIG_RSA_PSS_RSAE_SHA512 0x0806
497 
498 /* EdDSA algorithms */
499 #define MBEDTLS_TLS1_3_SIG_ED25519 0x0807
500 #define MBEDTLS_TLS1_3_SIG_ED448 0x0808
501 
502 /* RSASSA-PSS algorithms with public key OID RSASSA-PSS */
503 #define MBEDTLS_TLS1_3_SIG_RSA_PSS_PSS_SHA256 0x0809
504 #define MBEDTLS_TLS1_3_SIG_RSA_PSS_PSS_SHA384 0x080A
505 #define MBEDTLS_TLS1_3_SIG_RSA_PSS_PSS_SHA512 0x080B
506 
507 /* LEGACY ALGORITHMS */
508 #define MBEDTLS_TLS1_3_SIG_RSA_PKCS1_SHA1 0x0201
509 #define MBEDTLS_TLS1_3_SIG_ECDSA_SHA1 0x0203
510 
511 #define MBEDTLS_TLS1_3_SIG_NONE 0x0
512 
513 /*
514  * Client Certificate Types
515  * RFC 5246 section 7.4.4 plus RFC 4492 section 5.5
516  */
517 #define MBEDTLS_SSL_CERT_TYPE_RSA_SIGN 1
518 #define MBEDTLS_SSL_CERT_TYPE_ECDSA_SIGN 64
519 
520 /*
521  * Message, alert and handshake types
522  */
523 #define MBEDTLS_SSL_MSG_CHANGE_CIPHER_SPEC 20
524 #define MBEDTLS_SSL_MSG_ALERT 21
525 #define MBEDTLS_SSL_MSG_HANDSHAKE 22
526 #define MBEDTLS_SSL_MSG_APPLICATION_DATA 23
527 #define MBEDTLS_SSL_MSG_CID 25
528 
529 #define MBEDTLS_SSL_ALERT_LEVEL_WARNING 1
530 #define MBEDTLS_SSL_ALERT_LEVEL_FATAL 2
531 
532 #define MBEDTLS_SSL_ALERT_MSG_CLOSE_NOTIFY 0 /* 0x00 */
533 #define MBEDTLS_SSL_ALERT_MSG_UNEXPECTED_MESSAGE 10 /* 0x0A */
534 #define MBEDTLS_SSL_ALERT_MSG_BAD_RECORD_MAC 20 /* 0x14 */
535 #define MBEDTLS_SSL_ALERT_MSG_DECRYPTION_FAILED 21 /* 0x15 */
536 #define MBEDTLS_SSL_ALERT_MSG_RECORD_OVERFLOW 22 /* 0x16 */
537 #define MBEDTLS_SSL_ALERT_MSG_DECOMPRESSION_FAILURE 30 /* 0x1E */
538 #define MBEDTLS_SSL_ALERT_MSG_HANDSHAKE_FAILURE 40 /* 0x28 */
539 #define MBEDTLS_SSL_ALERT_MSG_NO_CERT 41 /* 0x29 */
540 #define MBEDTLS_SSL_ALERT_MSG_BAD_CERT 42 /* 0x2A */
541 #define MBEDTLS_SSL_ALERT_MSG_UNSUPPORTED_CERT 43 /* 0x2B */
542 #define MBEDTLS_SSL_ALERT_MSG_CERT_REVOKED 44 /* 0x2C */
543 #define MBEDTLS_SSL_ALERT_MSG_CERT_EXPIRED 45 /* 0x2D */
544 #define MBEDTLS_SSL_ALERT_MSG_CERT_UNKNOWN 46 /* 0x2E */
545 #define MBEDTLS_SSL_ALERT_MSG_ILLEGAL_PARAMETER 47 /* 0x2F */
546 #define MBEDTLS_SSL_ALERT_MSG_UNKNOWN_CA 48 /* 0x30 */
547 #define MBEDTLS_SSL_ALERT_MSG_ACCESS_DENIED 49 /* 0x31 */
548 #define MBEDTLS_SSL_ALERT_MSG_DECODE_ERROR 50 /* 0x32 */
549 #define MBEDTLS_SSL_ALERT_MSG_DECRYPT_ERROR 51 /* 0x33 */
550 #define MBEDTLS_SSL_ALERT_MSG_EXPORT_RESTRICTION 60 /* 0x3C */
551 #define MBEDTLS_SSL_ALERT_MSG_PROTOCOL_VERSION 70 /* 0x46 */
552 #define MBEDTLS_SSL_ALERT_MSG_INSUFFICIENT_SECURITY 71 /* 0x47 */
553 #define MBEDTLS_SSL_ALERT_MSG_INTERNAL_ERROR 80 /* 0x50 */
554 #define MBEDTLS_SSL_ALERT_MSG_INAPROPRIATE_FALLBACK 86 /* 0x56 */
555 #define MBEDTLS_SSL_ALERT_MSG_USER_CANCELED 90 /* 0x5A */
556 #define MBEDTLS_SSL_ALERT_MSG_NO_RENEGOTIATION 100 /* 0x64 */
557 #define MBEDTLS_SSL_ALERT_MSG_MISSING_EXTENSION 109 /* 0x6d -- new in TLS 1.3 */
558 #define MBEDTLS_SSL_ALERT_MSG_UNSUPPORTED_EXT 110 /* 0x6E */
559 #define MBEDTLS_SSL_ALERT_MSG_UNRECOGNIZED_NAME 112 /* 0x70 */
560 #define MBEDTLS_SSL_ALERT_MSG_UNKNOWN_PSK_IDENTITY 115 /* 0x73 */
561 #define MBEDTLS_SSL_ALERT_MSG_CERT_REQUIRED 116 /* 0x74 */
562 #define MBEDTLS_SSL_ALERT_MSG_NO_APPLICATION_PROTOCOL 120 /* 0x78 */
563 
564 #define MBEDTLS_SSL_HS_HELLO_REQUEST 0
565 #define MBEDTLS_SSL_HS_CLIENT_HELLO 1
566 #define MBEDTLS_SSL_HS_SERVER_HELLO 2
567 #define MBEDTLS_SSL_HS_HELLO_VERIFY_REQUEST 3
568 #define MBEDTLS_SSL_HS_NEW_SESSION_TICKET 4
569 #define MBEDTLS_SSL_HS_END_OF_EARLY_DATA 5
570 #define MBEDTLS_SSL_HS_ENCRYPTED_EXTENSIONS 8
571 #define MBEDTLS_SSL_HS_CERTIFICATE 11
572 #define MBEDTLS_SSL_HS_SERVER_KEY_EXCHANGE 12
573 #define MBEDTLS_SSL_HS_CERTIFICATE_REQUEST 13
574 #define MBEDTLS_SSL_HS_SERVER_HELLO_DONE 14
575 #define MBEDTLS_SSL_HS_CERTIFICATE_VERIFY 15
576 #define MBEDTLS_SSL_HS_CLIENT_KEY_EXCHANGE 16
577 #define MBEDTLS_SSL_HS_FINISHED 20
578 #define MBEDTLS_SSL_HS_MESSAGE_HASH 254
579 
580 /*
581  * TLS extensions
582  */
583 #define MBEDTLS_TLS_EXT_SERVERNAME 0
584 #define MBEDTLS_TLS_EXT_SERVERNAME_HOSTNAME 0
585 
586 #define MBEDTLS_TLS_EXT_MAX_FRAGMENT_LENGTH 1
587 
588 #define MBEDTLS_TLS_EXT_TRUNCATED_HMAC 4
589 #define MBEDTLS_TLS_EXT_STATUS_REQUEST 5 /* RFC 6066 TLS 1.2 and 1.3 */
590 
591 #define MBEDTLS_TLS_EXT_SUPPORTED_ELLIPTIC_CURVES 10
592 #define MBEDTLS_TLS_EXT_SUPPORTED_GROUPS 10 /* RFC 8422,7919 TLS 1.2 and 1.3 */
593 #define MBEDTLS_TLS_EXT_SUPPORTED_POINT_FORMATS 11
594 
595 #define MBEDTLS_TLS_EXT_SIG_ALG 13 /* RFC 8446 TLS 1.3 */
596 #define MBEDTLS_TLS_EXT_USE_SRTP 14
597 #define MBEDTLS_TLS_EXT_HEARTBEAT 15 /* RFC 6520 TLS 1.2 and 1.3 */
598 #define MBEDTLS_TLS_EXT_ALPN 16
599 
600 #define MBEDTLS_TLS_EXT_SCT 18 /* RFC 6962 TLS 1.2 and 1.3 */
601 #define MBEDTLS_TLS_EXT_CLI_CERT_TYPE 19 /* RFC 7250 TLS 1.2 and 1.3 */
602 #define MBEDTLS_TLS_EXT_SERV_CERT_TYPE 20 /* RFC 7250 TLS 1.2 and 1.3 */
603 #define MBEDTLS_TLS_EXT_PADDING 21 /* RFC 7685 TLS 1.2 and 1.3 */
604 #define MBEDTLS_TLS_EXT_ENCRYPT_THEN_MAC 22 /* 0x16 */
605 #define MBEDTLS_TLS_EXT_EXTENDED_MASTER_SECRET 0x0017 /* 23 */
606 
607 #define MBEDTLS_TLS_EXT_RECORD_SIZE_LIMIT 28 /* RFC 8449 (implemented for TLS 1.3 only) */
608 
609 #define MBEDTLS_TLS_EXT_SESSION_TICKET 35
610 
611 #define MBEDTLS_TLS_EXT_PRE_SHARED_KEY 41 /* RFC 8446 TLS 1.3 */
612 #define MBEDTLS_TLS_EXT_EARLY_DATA 42 /* RFC 8446 TLS 1.3 */
613 #define MBEDTLS_TLS_EXT_SUPPORTED_VERSIONS 43 /* RFC 8446 TLS 1.3 */
614 #define MBEDTLS_TLS_EXT_COOKIE 44 /* RFC 8446 TLS 1.3 */
615 #define MBEDTLS_TLS_EXT_PSK_KEY_EXCHANGE_MODES 45 /* RFC 8446 TLS 1.3 */
616 
617 #define MBEDTLS_TLS_EXT_CERT_AUTH 47 /* RFC 8446 TLS 1.3 */
618 #define MBEDTLS_TLS_EXT_OID_FILTERS 48 /* RFC 8446 TLS 1.3 */
619 #define MBEDTLS_TLS_EXT_POST_HANDSHAKE_AUTH 49 /* RFC 8446 TLS 1.3 */
620 #define MBEDTLS_TLS_EXT_SIG_ALG_CERT 50 /* RFC 8446 TLS 1.3 */
621 #define MBEDTLS_TLS_EXT_KEY_SHARE 51 /* RFC 8446 TLS 1.3 */
622 
623 #if MBEDTLS_SSL_DTLS_CONNECTION_ID_COMPAT == 0
624 #define MBEDTLS_TLS_EXT_CID 54 /* RFC 9146 DTLS 1.2 CID */
625 #else
626 #define MBEDTLS_TLS_EXT_CID 254 /* Pre-RFC 9146 DTLS 1.2 CID */
627 #endif
628 
629 #define MBEDTLS_TLS_EXT_ECJPAKE_KKPP 256 /* experimental */
630 
631 #define MBEDTLS_TLS_EXT_RENEGOTIATION_INFO 0xFF01
632 
633 /*
634  * Size defines
635  */
636 #if !defined(MBEDTLS_PSK_MAX_LEN)
637 /*
638  * If the library supports TLS 1.3 tickets and the cipher suite
639  * TLS1-3-AES-256-GCM-SHA384, set the PSK maximum length to 48 instead of 32.
640  * That way, the TLS 1.3 client and server are able to resume sessions where
641  * the cipher suite is TLS1-3-AES-256-GCM-SHA384 (pre-shared keys are 48
642  * bytes long in that case).
643  */
644 #if defined(MBEDTLS_SSL_PROTO_TLS1_3) && \
645  defined(MBEDTLS_SSL_SESSION_TICKETS) && \
646  defined(MBEDTLS_SSL_HAVE_AES) && defined(MBEDTLS_SSL_HAVE_GCM) && \
647  defined(MBEDTLS_MD_CAN_SHA384)
648 #define MBEDTLS_PSK_MAX_LEN 48 /* 384 bits */
649 #else
650 #define MBEDTLS_PSK_MAX_LEN 32 /* 256 bits */
651 #endif
652 #endif /* !MBEDTLS_PSK_MAX_LEN */
653 
654 /* Dummy type used only for its size */
656  unsigned char dummy; /* Make the union non-empty even with SSL disabled */
657 #if defined(MBEDTLS_KEY_EXCHANGE_RSA_ENABLED)
658  unsigned char _pms_rsa[48]; /* RFC 5246 8.1.1 */
659 #endif
660 #if defined(MBEDTLS_KEY_EXCHANGE_DHE_RSA_ENABLED)
661  unsigned char _pms_dhm[MBEDTLS_MPI_MAX_SIZE]; /* RFC 5246 8.1.2 */
662 #endif
663 #if defined(MBEDTLS_KEY_EXCHANGE_ECDHE_RSA_ENABLED) || \
664  defined(MBEDTLS_KEY_EXCHANGE_ECDHE_ECDSA_ENABLED) || \
665  defined(MBEDTLS_KEY_EXCHANGE_ECDH_RSA_ENABLED) || \
666  defined(MBEDTLS_KEY_EXCHANGE_ECDH_ECDSA_ENABLED)
667  unsigned char _pms_ecdh[MBEDTLS_ECP_MAX_BYTES]; /* RFC 4492 5.10 */
668 #endif
669 #if defined(MBEDTLS_KEY_EXCHANGE_PSK_ENABLED)
670  unsigned char _pms_psk[4 + 2 * MBEDTLS_PSK_MAX_LEN]; /* RFC 4279 2 */
671 #endif
672 #if defined(MBEDTLS_KEY_EXCHANGE_DHE_PSK_ENABLED)
673  unsigned char _pms_dhe_psk[4 + MBEDTLS_MPI_MAX_SIZE
674  + MBEDTLS_PSK_MAX_LEN]; /* RFC 4279 3 */
675 #endif
676 #if defined(MBEDTLS_KEY_EXCHANGE_RSA_PSK_ENABLED)
677  unsigned char _pms_rsa_psk[52 + MBEDTLS_PSK_MAX_LEN]; /* RFC 4279 4 */
678 #endif
679 #if defined(MBEDTLS_KEY_EXCHANGE_ECDHE_PSK_ENABLED)
680  unsigned char _pms_ecdhe_psk[4 + MBEDTLS_ECP_MAX_BYTES
681  + MBEDTLS_PSK_MAX_LEN]; /* RFC 5489 2 */
682 #endif
683 #if defined(MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED)
684  unsigned char _pms_ecjpake[32]; /* Thread spec: SHA-256 output */
685 #endif
686 };
687 
688 #define MBEDTLS_PREMASTER_SIZE sizeof(union mbedtls_ssl_premaster_secret)
689 
690 #define MBEDTLS_TLS1_3_MD_MAX_SIZE PSA_HASH_MAX_SIZE
691 
692 
693 /* Length in number of bytes of the TLS sequence number */
694 #define MBEDTLS_SSL_SEQUENCE_NUMBER_LEN 8
695 
696 #ifdef __cplusplus
697 extern "C" {
698 #endif
699 
700 /*
701  * SSL state machine
702  */
703 typedef enum {
734 }
736 
737 /*
738  * Early data status, client side only.
739  */
740 
741 #if defined(MBEDTLS_SSL_EARLY_DATA) && defined(MBEDTLS_SSL_CLI_C)
742 typedef enum {
743 /*
744  * See documentation of mbedtls_ssl_get_early_data_status().
745  */
746  MBEDTLS_SSL_EARLY_DATA_STATUS_NOT_INDICATED,
747  MBEDTLS_SSL_EARLY_DATA_STATUS_ACCEPTED,
748  MBEDTLS_SSL_EARLY_DATA_STATUS_REJECTED,
749 } mbedtls_ssl_early_data_status;
750 #endif /* MBEDTLS_SSL_EARLY_DATA && MBEDTLS_SSL_CLI_C */
751 
752 /**
753  * \brief Callback type: send data on the network.
754  *
755  * \note That callback may be either blocking or non-blocking.
756  *
757  * \param ctx Context for the send callback (typically a file descriptor)
758  * \param buf Buffer holding the data to send
759  * \param len Length of the data to send
760  *
761  * \return The callback must return the number of bytes sent if any,
762  * or a non-zero error code.
763  * If performing non-blocking I/O, \c MBEDTLS_ERR_SSL_WANT_WRITE
764  * must be returned when the operation would block.
765  *
766  * \note The callback is allowed to send fewer bytes than requested.
767  * It must always return the number of bytes actually sent.
768  */
769 typedef int mbedtls_ssl_send_t(void *ctx,
770  const unsigned char *buf,
771  size_t len);
772 
773 /**
774  * \brief Callback type: receive data from the network.
775  *
776  * \note That callback may be either blocking or non-blocking.
777  *
778  * \param ctx Context for the receive callback (typically a file
779  * descriptor)
780  * \param buf Buffer to write the received data to
781  * \param len Length of the receive buffer
782  *
783  * \returns If data has been received, the positive number of bytes received.
784  * \returns \c 0 if the connection has been closed.
785  * \returns If performing non-blocking I/O, \c MBEDTLS_ERR_SSL_WANT_READ
786  * must be returned when the operation would block.
787  * \returns Another negative error code on other kinds of failures.
788  *
789  * \note The callback may receive fewer bytes than the length of the
790  * buffer. It must always return the number of bytes actually
791  * received and written to the buffer.
792  */
793 typedef int mbedtls_ssl_recv_t(void *ctx,
794  unsigned char *buf,
795  size_t len);
796 
797 /**
798  * \brief Callback type: receive data from the network, with timeout
799  *
800  * \note That callback must block until data is received, or the
801  * timeout delay expires, or the operation is interrupted by a
802  * signal.
803  *
804  * \param ctx Context for the receive callback (typically a file descriptor)
805  * \param buf Buffer to write the received data to
806  * \param len Length of the receive buffer
807  * \param timeout Maximum number of milliseconds to wait for data
808  * 0 means no timeout (potentially waiting forever)
809  *
810  * \return The callback must return the number of bytes received,
811  * or a non-zero error code:
812  * \c MBEDTLS_ERR_SSL_TIMEOUT if the operation timed out,
813  * \c MBEDTLS_ERR_SSL_WANT_READ if interrupted by a signal.
814  *
815  * \note The callback may receive fewer bytes than the length of the
816  * buffer. It must always return the number of bytes actually
817  * received and written to the buffer.
818  */
819 typedef int mbedtls_ssl_recv_timeout_t(void *ctx,
820  unsigned char *buf,
821  size_t len,
822  uint32_t timeout);
823 /**
824  * \brief Callback type: set a pair of timers/delays to watch
825  *
826  * \param ctx Context pointer
827  * \param int_ms Intermediate delay in milliseconds
828  * \param fin_ms Final delay in milliseconds
829  * 0 cancels the current timer.
830  *
831  * \note This callback must at least store the necessary information
832  * for the associated \c mbedtls_ssl_get_timer_t callback to
833  * return correct information.
834  *
835  * \note If using an event-driven style of programming, an event must
836  * be generated when the final delay is passed. The event must
837  * cause a call to \c mbedtls_ssl_handshake() with the proper
838  * SSL context to be scheduled. Care must be taken to ensure
839  * that at most one such call happens at a time.
840  *
841  * \note Only one timer at a time must be running. Calling this
842  * function while a timer is running must cancel it. Cancelled
843  * timers must not generate any event.
844  */
845 typedef void mbedtls_ssl_set_timer_t(void *ctx,
846  uint32_t int_ms,
847  uint32_t fin_ms);
848 
849 /**
850  * \brief Callback type: get status of timers/delays
851  *
852  * \param ctx Context pointer
853  *
854  * \return This callback must return:
855  * -1 if cancelled (fin_ms == 0),
856  * 0 if none of the delays have passed,
857  * 1 if only the intermediate delay has passed,
858  * 2 if the final delay has passed.
859  */
860 typedef int mbedtls_ssl_get_timer_t(void *ctx);
861 
862 /* Defined below */
866 
867 /* Defined in library/ssl_misc.h */
871 #if defined(MBEDTLS_X509_CRT_PARSE_C)
872 typedef struct mbedtls_ssl_key_cert mbedtls_ssl_key_cert;
873 #endif
874 #if defined(MBEDTLS_SSL_PROTO_DTLS)
875 typedef struct mbedtls_ssl_flight_item mbedtls_ssl_flight_item;
876 #endif
877 
878 #if defined(MBEDTLS_SSL_PROTO_TLS1_3) && defined(MBEDTLS_SSL_SESSION_TICKETS)
879 #define MBEDTLS_SSL_TLS1_3_TICKET_ALLOW_PSK_RESUMPTION \
880  MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK /* 1U << 0 */
881 #define MBEDTLS_SSL_TLS1_3_TICKET_ALLOW_PSK_EPHEMERAL_RESUMPTION \
882  MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_EPHEMERAL /* 1U << 2 */
883 #define MBEDTLS_SSL_TLS1_3_TICKET_ALLOW_EARLY_DATA (1U << 3)
884 
885 #define MBEDTLS_SSL_TLS1_3_TICKET_FLAGS_MASK \
886  (MBEDTLS_SSL_TLS1_3_TICKET_ALLOW_PSK_RESUMPTION | \
887  MBEDTLS_SSL_TLS1_3_TICKET_ALLOW_PSK_EPHEMERAL_RESUMPTION | \
888  MBEDTLS_SSL_TLS1_3_TICKET_ALLOW_EARLY_DATA)
889 #endif /* MBEDTLS_SSL_PROTO_TLS1_3 && MBEDTLS_SSL_SESSION_TICKETS */
890 
891 /**
892  * \brief Callback type: server-side session cache getter
893  *
894  * The session cache is logically a key value store, with
895  * keys being session IDs and values being instances of
896  * mbedtls_ssl_session.
897  *
898  * This callback retrieves an entry in this key-value store.
899  *
900  * \param data The address of the session cache structure to query.
901  * \param session_id The buffer holding the session ID to query.
902  * \param session_id_len The length of \p session_id in Bytes.
903  * \param session The address of the session structure to populate.
904  * It is initialized with mbdtls_ssl_session_init(),
905  * and the callback must always leave it in a state
906  * where it can safely be freed via
907  * mbedtls_ssl_session_free() independent of the
908  * return code of this function.
909  *
910  * \return \c 0 on success
911  * \return A non-zero return value on failure.
912  *
913  */
914 typedef int mbedtls_ssl_cache_get_t(void *data,
915  unsigned char const *session_id,
916  size_t session_id_len,
917  mbedtls_ssl_session *session);
918 /**
919  * \brief Callback type: server-side session cache setter
920  *
921  * The session cache is logically a key value store, with
922  * keys being session IDs and values being instances of
923  * mbedtls_ssl_session.
924  *
925  * This callback sets an entry in this key-value store.
926  *
927  * \param data The address of the session cache structure to modify.
928  * \param session_id The buffer holding the session ID to query.
929  * \param session_id_len The length of \p session_id in Bytes.
930  * \param session The address of the session to be stored in the
931  * session cache.
932  *
933  * \return \c 0 on success
934  * \return A non-zero return value on failure.
935  */
936 typedef int mbedtls_ssl_cache_set_t(void *data,
937  unsigned char const *session_id,
938  size_t session_id_len,
939  const mbedtls_ssl_session *session);
940 
941 #if defined(MBEDTLS_SSL_ASYNC_PRIVATE)
942 #if defined(MBEDTLS_X509_CRT_PARSE_C)
943 /**
944  * \brief Callback type: start external signature operation.
945  *
946  * This callback is called during an SSL handshake to start
947  * a signature decryption operation using an
948  * external processor. The parameter \p cert contains
949  * the public key; it is up to the callback function to
950  * determine how to access the associated private key.
951  *
952  * This function typically sends or enqueues a request, and
953  * does not wait for the operation to complete. This allows
954  * the handshake step to be non-blocking.
955  *
956  * The parameters \p ssl and \p cert are guaranteed to remain
957  * valid throughout the handshake. On the other hand, this
958  * function must save the contents of \p hash if the value
959  * is needed for later processing, because the \p hash buffer
960  * is no longer valid after this function returns.
961  *
962  * This function may call mbedtls_ssl_set_async_operation_data()
963  * to store an operation context for later retrieval
964  * by the resume or cancel callback.
965  *
966  * \note For RSA signatures, this function must produce output
967  * that is consistent with PKCS#1 v1.5 in the same way as
968  * mbedtls_rsa_pkcs1_sign(). Before the private key operation,
969  * apply the padding steps described in RFC 8017, section 9.2
970  * "EMSA-PKCS1-v1_5" as follows.
971  * - If \p md_alg is #MBEDTLS_MD_NONE, apply the PKCS#1 v1.5
972  * encoding, treating \p hash as the DigestInfo to be
973  * padded. In other words, apply EMSA-PKCS1-v1_5 starting
974  * from step 3, with `T = hash` and `tLen = hash_len`.
975  * - If `md_alg != MBEDTLS_MD_NONE`, apply the PKCS#1 v1.5
976  * encoding, treating \p hash as the hash to be encoded and
977  * padded. In other words, apply EMSA-PKCS1-v1_5 starting
978  * from step 2, with `digestAlgorithm` obtained by calling
979  * mbedtls_oid_get_oid_by_md() on \p md_alg.
980  *
981  * \note For ECDSA signatures, the output format is the DER encoding
982  * `Ecdsa-Sig-Value` defined in
983  * [RFC 4492 section 5.4](https://tools.ietf.org/html/rfc4492#section-5.4).
984  *
985  * \param ssl The SSL connection instance. It should not be
986  * modified other than via
987  * mbedtls_ssl_set_async_operation_data().
988  * \param cert Certificate containing the public key.
989  * In simple cases, this is one of the pointers passed to
990  * mbedtls_ssl_conf_own_cert() when configuring the SSL
991  * connection. However, if other callbacks are used, this
992  * property may not hold. For example, if an SNI callback
993  * is registered with mbedtls_ssl_conf_sni(), then
994  * this callback determines what certificate is used.
995  * \param md_alg Hash algorithm.
996  * \param hash Buffer containing the hash. This buffer is
997  * no longer valid when the function returns.
998  * \param hash_len Size of the \c hash buffer in bytes.
999  *
1000  * \return 0 if the operation was started successfully and the SSL
1001  * stack should call the resume callback immediately.
1002  * \return #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS if the operation
1003  * was started successfully and the SSL stack should return
1004  * immediately without calling the resume callback yet.
1005  * \return #MBEDTLS_ERR_SSL_HW_ACCEL_FALLTHROUGH if the external
1006  * processor does not support this key. The SSL stack will
1007  * use the private key object instead.
1008  * \return Any other error indicates a fatal failure and is
1009  * propagated up the call chain. The callback should
1010  * use \c MBEDTLS_ERR_PK_xxx error codes, and <b>must not</b>
1011  * use \c MBEDTLS_ERR_SSL_xxx error codes except as
1012  * directed in the documentation of this callback.
1013  */
1014 typedef int mbedtls_ssl_async_sign_t(mbedtls_ssl_context *ssl,
1015  mbedtls_x509_crt *cert,
1016  mbedtls_md_type_t md_alg,
1017  const unsigned char *hash,
1018  size_t hash_len);
1019 
1020 /**
1021  * \brief Callback type: start external decryption operation.
1022  *
1023  * This callback is called during an SSL handshake to start
1024  * an RSA decryption operation using an
1025  * external processor. The parameter \p cert contains
1026  * the public key; it is up to the callback function to
1027  * determine how to access the associated private key.
1028  *
1029  * This function typically sends or enqueues a request, and
1030  * does not wait for the operation to complete. This allows
1031  * the handshake step to be non-blocking.
1032  *
1033  * The parameters \p ssl and \p cert are guaranteed to remain
1034  * valid throughout the handshake. On the other hand, this
1035  * function must save the contents of \p input if the value
1036  * is needed for later processing, because the \p input buffer
1037  * is no longer valid after this function returns.
1038  *
1039  * This function may call mbedtls_ssl_set_async_operation_data()
1040  * to store an operation context for later retrieval
1041  * by the resume or cancel callback.
1042  *
1043  * \warning RSA decryption as used in TLS is subject to a potential
1044  * timing side channel attack first discovered by Bleichenbacher
1045  * in 1998. This attack can be remotely exploitable
1046  * in practice. To avoid this attack, you must ensure that
1047  * if the callback performs an RSA decryption, the time it
1048  * takes to execute and return the result does not depend
1049  * on whether the RSA decryption succeeded or reported
1050  * invalid padding.
1051  *
1052  * \param ssl The SSL connection instance. It should not be
1053  * modified other than via
1054  * mbedtls_ssl_set_async_operation_data().
1055  * \param cert Certificate containing the public key.
1056  * In simple cases, this is one of the pointers passed to
1057  * mbedtls_ssl_conf_own_cert() when configuring the SSL
1058  * connection. However, if other callbacks are used, this
1059  * property may not hold. For example, if an SNI callback
1060  * is registered with mbedtls_ssl_conf_sni(), then
1061  * this callback determines what certificate is used.
1062  * \param input Buffer containing the input ciphertext. This buffer
1063  * is no longer valid when the function returns.
1064  * \param input_len Size of the \p input buffer in bytes.
1065  *
1066  * \return 0 if the operation was started successfully and the SSL
1067  * stack should call the resume callback immediately.
1068  * \return #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS if the operation
1069  * was started successfully and the SSL stack should return
1070  * immediately without calling the resume callback yet.
1071  * \return #MBEDTLS_ERR_SSL_HW_ACCEL_FALLTHROUGH if the external
1072  * processor does not support this key. The SSL stack will
1073  * use the private key object instead.
1074  * \return Any other error indicates a fatal failure and is
1075  * propagated up the call chain. The callback should
1076  * use \c MBEDTLS_ERR_PK_xxx error codes, and <b>must not</b>
1077  * use \c MBEDTLS_ERR_SSL_xxx error codes except as
1078  * directed in the documentation of this callback.
1079  */
1080 typedef int mbedtls_ssl_async_decrypt_t(mbedtls_ssl_context *ssl,
1081  mbedtls_x509_crt *cert,
1082  const unsigned char *input,
1083  size_t input_len);
1084 #endif /* MBEDTLS_X509_CRT_PARSE_C */
1085 
1086 /**
1087  * \brief Callback type: resume external operation.
1088  *
1089  * This callback is called during an SSL handshake to resume
1090  * an external operation started by the
1091  * ::mbedtls_ssl_async_sign_t or
1092  * ::mbedtls_ssl_async_decrypt_t callback.
1093  *
1094  * This function typically checks the status of a pending
1095  * request or causes the request queue to make progress, and
1096  * does not wait for the operation to complete. This allows
1097  * the handshake step to be non-blocking.
1098  *
1099  * This function may call mbedtls_ssl_get_async_operation_data()
1100  * to retrieve an operation context set by the start callback.
1101  * It may call mbedtls_ssl_set_async_operation_data() to modify
1102  * this context.
1103  *
1104  * Note that when this function returns a status other than
1105  * #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS, it must free any
1106  * resources associated with the operation.
1107  *
1108  * \param ssl The SSL connection instance. It should not be
1109  * modified other than via
1110  * mbedtls_ssl_set_async_operation_data().
1111  * \param output Buffer containing the output (signature or decrypted
1112  * data) on success.
1113  * \param output_len On success, number of bytes written to \p output.
1114  * \param output_size Size of the \p output buffer in bytes.
1115  *
1116  * \return 0 if output of the operation is available in the
1117  * \p output buffer.
1118  * \return #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS if the operation
1119  * is still in progress. Subsequent requests for progress
1120  * on the SSL connection will call the resume callback
1121  * again.
1122  * \return Any other error means that the operation is aborted.
1123  * The SSL handshake is aborted. The callback should
1124  * use \c MBEDTLS_ERR_PK_xxx error codes, and <b>must not</b>
1125  * use \c MBEDTLS_ERR_SSL_xxx error codes except as
1126  * directed in the documentation of this callback.
1127  */
1128 typedef int mbedtls_ssl_async_resume_t(mbedtls_ssl_context *ssl,
1129  unsigned char *output,
1130  size_t *output_len,
1131  size_t output_size);
1132 
1133 /**
1134  * \brief Callback type: cancel external operation.
1135  *
1136  * This callback is called if an SSL connection is closed
1137  * while an asynchronous operation is in progress. Note that
1138  * this callback is not called if the
1139  * ::mbedtls_ssl_async_resume_t callback has run and has
1140  * returned a value other than
1141  * #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS, since in that case
1142  * the asynchronous operation has already completed.
1143  *
1144  * This function may call mbedtls_ssl_get_async_operation_data()
1145  * to retrieve an operation context set by the start callback.
1146  *
1147  * \param ssl The SSL connection instance. It should not be
1148  * modified.
1149  */
1150 typedef void mbedtls_ssl_async_cancel_t(mbedtls_ssl_context *ssl);
1151 #endif /* MBEDTLS_SSL_ASYNC_PRIVATE */
1152 
1153 #if defined(MBEDTLS_KEY_EXCHANGE_WITH_CERT_ENABLED) && \
1154  !defined(MBEDTLS_SSL_KEEP_PEER_CERTIFICATE)
1155 #define MBEDTLS_SSL_PEER_CERT_DIGEST_MAX_LEN 48
1156 #if defined(MBEDTLS_MD_CAN_SHA256)
1157 #define MBEDTLS_SSL_PEER_CERT_DIGEST_DFL_TYPE MBEDTLS_MD_SHA256
1158 #define MBEDTLS_SSL_PEER_CERT_DIGEST_DFL_LEN 32
1159 #elif defined(MBEDTLS_MD_CAN_SHA384)
1160 #define MBEDTLS_SSL_PEER_CERT_DIGEST_DFL_TYPE MBEDTLS_MD_SHA384
1161 #define MBEDTLS_SSL_PEER_CERT_DIGEST_DFL_LEN 48
1162 #elif defined(MBEDTLS_MD_CAN_SHA1)
1163 #define MBEDTLS_SSL_PEER_CERT_DIGEST_DFL_TYPE MBEDTLS_MD_SHA1
1164 #define MBEDTLS_SSL_PEER_CERT_DIGEST_DFL_LEN 20
1165 #else
1166 /* This is already checked in check_config.h, but be sure. */
1167 #error "Bad configuration - need SHA-1, SHA-256 or SHA-512 enabled to compute digest of peer CRT."
1168 #endif
1169 #endif /* MBEDTLS_KEY_EXCHANGE_WITH_CERT_ENABLED &&
1170  !MBEDTLS_SSL_KEEP_PEER_CERTIFICATE */
1171 
1172 typedef struct {
1173  unsigned char client_application_traffic_secret_N[MBEDTLS_TLS1_3_MD_MAX_SIZE];
1174  unsigned char server_application_traffic_secret_N[MBEDTLS_TLS1_3_MD_MAX_SIZE];
1175  unsigned char exporter_master_secret[MBEDTLS_TLS1_3_MD_MAX_SIZE];
1176  unsigned char resumption_master_secret[MBEDTLS_TLS1_3_MD_MAX_SIZE];
1178 
1179 #if defined(MBEDTLS_SSL_DTLS_SRTP)
1180 
1181 #define MBEDTLS_TLS_SRTP_MAX_MKI_LENGTH 255
1182 #define MBEDTLS_TLS_SRTP_MAX_PROFILE_LIST_LENGTH 4
1183 /*
1184  * For code readability use a typedef for DTLS-SRTP profiles
1185  *
1186  * Use_srtp extension protection profiles values as defined in
1187  * http://www.iana.org/assignments/srtp-protection/srtp-protection.xhtml
1188  *
1189  * Reminder: if this list is expanded mbedtls_ssl_check_srtp_profile_value
1190  * must be updated too.
1191  */
1192 #define MBEDTLS_TLS_SRTP_AES128_CM_HMAC_SHA1_80 ((uint16_t) 0x0001)
1193 #define MBEDTLS_TLS_SRTP_AES128_CM_HMAC_SHA1_32 ((uint16_t) 0x0002)
1194 #define MBEDTLS_TLS_SRTP_NULL_HMAC_SHA1_80 ((uint16_t) 0x0005)
1195 #define MBEDTLS_TLS_SRTP_NULL_HMAC_SHA1_32 ((uint16_t) 0x0006)
1196 /* This one is not iana defined, but for code readability. */
1197 #define MBEDTLS_TLS_SRTP_UNSET ((uint16_t) 0x0000)
1198 
1199 typedef uint16_t mbedtls_ssl_srtp_profile;
1200 
1201 typedef struct mbedtls_dtls_srtp_info_t {
1202  /*! The SRTP profile that was negotiated. */
1203  mbedtls_ssl_srtp_profile MBEDTLS_PRIVATE(chosen_dtls_srtp_profile);
1204  /*! The length of mki_value. */
1205  uint16_t MBEDTLS_PRIVATE(mki_len);
1206  /*! The mki_value used, with max size of 256 bytes. */
1207  unsigned char MBEDTLS_PRIVATE(mki_value)[MBEDTLS_TLS_SRTP_MAX_MKI_LENGTH];
1208 }
1209 mbedtls_dtls_srtp_info;
1210 
1211 #endif /* MBEDTLS_SSL_DTLS_SRTP */
1212 
1213 /** Human-friendly representation of the (D)TLS protocol version. */
1214 typedef enum {
1215  MBEDTLS_SSL_VERSION_UNKNOWN, /*!< Context not in use or version not yet negotiated. */
1216  MBEDTLS_SSL_VERSION_TLS1_2 = 0x0303, /*!< (D)TLS 1.2 */
1217  MBEDTLS_SSL_VERSION_TLS1_3 = 0x0304, /*!< (D)TLS 1.3 */
1219 
1220 /*
1221  * This structure is used for storing current session data.
1222  *
1223  * Note: when changing this definition, we need to check and update:
1224  * - in tests/suites/test_suite_ssl.function:
1225  * ssl_populate_session() and ssl_serialize_session_save_load()
1226  * - in library/ssl_tls.c:
1227  * mbedtls_ssl_session_init() and mbedtls_ssl_session_free()
1228  * mbedtls_ssl_session_save() and ssl_session_load()
1229  * ssl_session_copy()
1230  */
1232 #if defined(MBEDTLS_SSL_MAX_FRAGMENT_LENGTH)
1233  unsigned char MBEDTLS_PRIVATE(mfl_code); /*!< MaxFragmentLength negotiated by peer */
1234 #endif /* MBEDTLS_SSL_MAX_FRAGMENT_LENGTH */
1235 
1236 /*!< RecordSizeLimit received from the peer */
1237 #if defined(MBEDTLS_SSL_RECORD_SIZE_LIMIT)
1238  uint16_t MBEDTLS_PRIVATE(record_size_limit);
1239 #endif /* MBEDTLS_SSL_RECORD_SIZE_LIMIT */
1240 
1241  unsigned char MBEDTLS_PRIVATE(exported);
1242  uint8_t MBEDTLS_PRIVATE(endpoint); /*!< 0: client, 1: server */
1243 
1244  /** TLS version negotiated in the session. Used if and when renegotiating
1245  * or resuming a session instead of the configured minor TLS version.
1246  */
1248 
1249 #if defined(MBEDTLS_HAVE_TIME)
1250  mbedtls_time_t MBEDTLS_PRIVATE(start); /*!< start time of current session */
1251 #endif
1252  int MBEDTLS_PRIVATE(ciphersuite); /*!< chosen ciphersuite */
1253  size_t MBEDTLS_PRIVATE(id_len); /*!< session id length */
1254  unsigned char MBEDTLS_PRIVATE(id)[32]; /*!< session identifier */
1255  unsigned char MBEDTLS_PRIVATE(master)[48]; /*!< the master secret */
1256 
1257 #if defined(MBEDTLS_X509_CRT_PARSE_C)
1258 #if defined(MBEDTLS_SSL_KEEP_PEER_CERTIFICATE)
1259  mbedtls_x509_crt *MBEDTLS_PRIVATE(peer_cert); /*!< peer X.509 cert chain */
1260 #else /* MBEDTLS_SSL_KEEP_PEER_CERTIFICATE */
1261  /*! The digest of the peer's end-CRT. This must be kept to detect CRT
1262  * changes during renegotiation, mitigating the triple handshake attack. */
1263  unsigned char *MBEDTLS_PRIVATE(peer_cert_digest);
1264  size_t MBEDTLS_PRIVATE(peer_cert_digest_len);
1265  mbedtls_md_type_t MBEDTLS_PRIVATE(peer_cert_digest_type);
1266 #endif /* !MBEDTLS_SSL_KEEP_PEER_CERTIFICATE */
1267 #endif /* MBEDTLS_X509_CRT_PARSE_C */
1268  uint32_t MBEDTLS_PRIVATE(verify_result); /*!< verification result */
1269 
1270 #if defined(MBEDTLS_SSL_SESSION_TICKETS) && defined(MBEDTLS_SSL_CLI_C)
1271  unsigned char *MBEDTLS_PRIVATE(ticket); /*!< RFC 5077 session ticket */
1272  size_t MBEDTLS_PRIVATE(ticket_len); /*!< session ticket length */
1273  uint32_t MBEDTLS_PRIVATE(ticket_lifetime); /*!< ticket lifetime hint */
1274 #endif /* MBEDTLS_SSL_SESSION_TICKETS && MBEDTLS_SSL_CLI_C */
1275 
1276 #if defined(MBEDTLS_SSL_SESSION_TICKETS) && defined(MBEDTLS_SSL_SRV_C) && \
1277  defined(MBEDTLS_HAVE_TIME)
1278  /*! When a ticket is created by a TLS server as part of an established TLS
1279  * session, the ticket creation time may need to be saved for the ticket
1280  * module to be able to check the ticket age when the ticket is used.
1281  * That's the purpose of this field.
1282  * Before creating a new ticket, an Mbed TLS server set this field with
1283  * its current time in milliseconds. This time may then be saved in the
1284  * session ticket data by the session ticket writing function and
1285  * recovered by the ticket parsing function later when the ticket is used.
1286  * The ticket module may then use this time to compute the ticket age and
1287  * determine if it has expired or not.
1288  * The Mbed TLS implementations of the session ticket writing and parsing
1289  * functions save and retrieve the ticket creation time as part of the
1290  * session ticket data. The session ticket parsing function relies on
1291  * the mbedtls_ssl_session_get_ticket_creation_time() API to get the
1292  * ticket creation time from the session ticket data.
1293  */
1294  mbedtls_ms_time_t MBEDTLS_PRIVATE(ticket_creation_time);
1295 #endif
1296 
1297 #if defined(MBEDTLS_SSL_PROTO_TLS1_3) && defined(MBEDTLS_SSL_SESSION_TICKETS)
1298  uint32_t MBEDTLS_PRIVATE(ticket_age_add); /*!< Randomly generated value used to obscure the age of the ticket */
1299  uint8_t MBEDTLS_PRIVATE(ticket_flags); /*!< Ticket flags */
1300  uint8_t MBEDTLS_PRIVATE(resumption_key_len); /*!< resumption_key length */
1301  unsigned char MBEDTLS_PRIVATE(resumption_key)[MBEDTLS_SSL_TLS1_3_TICKET_RESUMPTION_KEY_LEN];
1302 
1303 #if defined(MBEDTLS_SSL_SERVER_NAME_INDICATION) && defined(MBEDTLS_SSL_CLI_C)
1304  char *MBEDTLS_PRIVATE(hostname); /*!< host name binded with tickets */
1305 #endif /* MBEDTLS_SSL_SERVER_NAME_INDICATION && MBEDTLS_SSL_CLI_C */
1306 
1307 #if defined(MBEDTLS_SSL_EARLY_DATA) && defined(MBEDTLS_SSL_ALPN) && defined(MBEDTLS_SSL_SRV_C)
1308  char *ticket_alpn; /*!< ALPN negotiated in the session
1309  during which the ticket was generated. */
1310 #endif
1311 
1312 #if defined(MBEDTLS_HAVE_TIME) && defined(MBEDTLS_SSL_CLI_C)
1313  /*! Time in milliseconds when the last ticket was received. */
1314  mbedtls_ms_time_t MBEDTLS_PRIVATE(ticket_reception_time);
1315 #endif
1316 #endif /* MBEDTLS_SSL_PROTO_TLS1_3 && MBEDTLS_SSL_SESSION_TICKETS */
1317 
1318 #if defined(MBEDTLS_SSL_EARLY_DATA)
1319  uint32_t MBEDTLS_PRIVATE(max_early_data_size); /*!< maximum amount of early data in tickets */
1320 #endif
1321 
1322 #if defined(MBEDTLS_SSL_ENCRYPT_THEN_MAC)
1323  int MBEDTLS_PRIVATE(encrypt_then_mac); /*!< flag for EtM activation */
1324 #endif
1325 
1326 #if defined(MBEDTLS_SSL_PROTO_TLS1_3)
1328 #endif
1329 };
1330 
1331 /*
1332  * Identifiers for PRFs used in various versions of TLS.
1333  */
1334 typedef enum {
1342 
1343 typedef enum {
1345 #if defined(MBEDTLS_SSL_PROTO_TLS1_3)
1346  MBEDTLS_SSL_KEY_EXPORT_TLS1_3_CLIENT_EARLY_SECRET,
1347  MBEDTLS_SSL_KEY_EXPORT_TLS1_3_EARLY_EXPORTER_SECRET,
1348  MBEDTLS_SSL_KEY_EXPORT_TLS1_3_CLIENT_HANDSHAKE_TRAFFIC_SECRET,
1349  MBEDTLS_SSL_KEY_EXPORT_TLS1_3_SERVER_HANDSHAKE_TRAFFIC_SECRET,
1350  MBEDTLS_SSL_KEY_EXPORT_TLS1_3_CLIENT_APPLICATION_TRAFFIC_SECRET,
1351  MBEDTLS_SSL_KEY_EXPORT_TLS1_3_SERVER_APPLICATION_TRAFFIC_SECRET,
1352 #endif /* MBEDTLS_SSL_PROTO_TLS1_3 */
1354 
1355 /**
1356  * \brief Callback type: Export key alongside random values for
1357  * session identification, and PRF for
1358  * implementation of TLS key exporters.
1359  *
1360  * \param p_expkey Context for the callback.
1361  * \param type The type of the key that is being exported.
1362  * \param secret The address of the buffer holding the secret
1363  * that's being exporterd.
1364  * \param secret_len The length of \p secret in bytes.
1365  * \param client_random The client random bytes.
1366  * \param server_random The server random bytes.
1367  * \param tls_prf_type The identifier for the PRF used in the handshake
1368  * to which the key belongs.
1369  */
1370 typedef void mbedtls_ssl_export_keys_t(void *p_expkey,
1372  const unsigned char *secret,
1373  size_t secret_len,
1374  const unsigned char client_random[32],
1375  const unsigned char server_random[32],
1376  mbedtls_tls_prf_types tls_prf_type);
1377 
1378 #if defined(MBEDTLS_SSL_SRV_C)
1379 /**
1380  * \brief Callback type: generic handshake callback
1381  *
1382  * \note Callbacks may use user_data funcs to set/get app user data.
1383  * See \c mbedtls_ssl_get_user_data_p()
1384  * \c mbedtls_ssl_get_user_data_n()
1385  * \c mbedtls_ssl_conf_get_user_data_p()
1386  * \c mbedtls_ssl_conf_get_user_data_n()
1387  *
1388  * \param ssl \c mbedtls_ssl_context on which the callback is run
1389  *
1390  * \return The return value of the callback is 0 if successful,
1391  * or a specific MBEDTLS_ERR_XXX code, which will cause
1392  * the handshake to be aborted.
1393  */
1394 typedef int (*mbedtls_ssl_hs_cb_t)(mbedtls_ssl_context *ssl);
1395 #endif
1396 
1397 /* A type for storing user data in a library structure.
1398  *
1399  * The representation of type may change in future versions of the library.
1400  * Only the behaviors guaranteed by documented accessor functions are
1401  * guaranteed to remain stable.
1402  */
1403 typedef union {
1404  uintptr_t n; /* typically a handle to an associated object */
1405  void *p; /* typically a pointer to extra data */
1407 
1408 /**
1409  * SSL/TLS configuration to be shared between mbedtls_ssl_context structures.
1410  */
1412  /* Group items mostly by size. This helps to reduce memory wasted to
1413  * padding. It also helps to keep smaller fields early in the structure,
1414  * so that elements tend to be in the 128-element direct access window
1415  * on Arm Thumb, which reduces the code size. */
1416 
1417  mbedtls_ssl_protocol_version MBEDTLS_PRIVATE(max_tls_version); /*!< max. TLS version used */
1418  mbedtls_ssl_protocol_version MBEDTLS_PRIVATE(min_tls_version); /*!< min. TLS version used */
1419 
1420  /*
1421  * Flags (could be bit-fields to save RAM, but separate bytes make
1422  * the code smaller on architectures with an instruction for direct
1423  * byte access).
1424  */
1425 
1426  uint8_t MBEDTLS_PRIVATE(endpoint); /*!< 0: client, 1: server */
1427  uint8_t MBEDTLS_PRIVATE(transport); /*!< 0: stream (TLS), 1: datagram (DTLS) */
1428  uint8_t MBEDTLS_PRIVATE(authmode); /*!< MBEDTLS_SSL_VERIFY_XXX */
1429  /* needed even with renego disabled for LEGACY_BREAK_HANDSHAKE */
1430  uint8_t MBEDTLS_PRIVATE(allow_legacy_renegotiation); /*!< MBEDTLS_LEGACY_XXX */
1431 #if defined(MBEDTLS_SSL_MAX_FRAGMENT_LENGTH)
1432  uint8_t MBEDTLS_PRIVATE(mfl_code); /*!< desired fragment length indicator
1433  (MBEDTLS_SSL_MAX_FRAG_LEN_XXX) */
1434 #endif
1435 #if defined(MBEDTLS_SSL_ENCRYPT_THEN_MAC)
1436  uint8_t MBEDTLS_PRIVATE(encrypt_then_mac); /*!< negotiate encrypt-then-mac? */
1437 #endif
1438 #if defined(MBEDTLS_SSL_EXTENDED_MASTER_SECRET)
1439  uint8_t MBEDTLS_PRIVATE(extended_ms); /*!< negotiate extended master secret? */
1440 #endif
1441 #if defined(MBEDTLS_SSL_DTLS_ANTI_REPLAY)
1442  uint8_t MBEDTLS_PRIVATE(anti_replay); /*!< detect and prevent replay? */
1443 #endif
1444 #if defined(MBEDTLS_SSL_RENEGOTIATION)
1445  uint8_t MBEDTLS_PRIVATE(disable_renegotiation); /*!< disable renegotiation? */
1446 #endif
1447 #if defined(MBEDTLS_SSL_SESSION_TICKETS) && \
1448  defined(MBEDTLS_SSL_CLI_C)
1449  uint8_t MBEDTLS_PRIVATE(session_tickets); /*!< use session tickets? */
1450 #endif
1451 
1452 #if defined(MBEDTLS_SSL_SESSION_TICKETS) && \
1453  defined(MBEDTLS_SSL_SRV_C) && \
1454  defined(MBEDTLS_SSL_PROTO_TLS1_3)
1455  uint16_t MBEDTLS_PRIVATE(new_session_tickets_count); /*!< number of NewSessionTicket */
1456 #endif
1457 
1458 #if defined(MBEDTLS_SSL_SRV_C)
1459  uint8_t MBEDTLS_PRIVATE(cert_req_ca_list); /*!< enable sending CA list in
1460  Certificate Request messages? */
1461  uint8_t MBEDTLS_PRIVATE(respect_cli_pref); /*!< pick the ciphersuite according to
1462  the client's preferences rather
1463  than ours? */
1464 #endif
1465 #if defined(MBEDTLS_SSL_DTLS_CONNECTION_ID)
1466  uint8_t MBEDTLS_PRIVATE(ignore_unexpected_cid); /*!< Should DTLS record with
1467  * unexpected CID
1468  * lead to failure? */
1469 #endif /* MBEDTLS_SSL_DTLS_CONNECTION_ID */
1470 #if defined(MBEDTLS_SSL_DTLS_SRTP)
1471  uint8_t MBEDTLS_PRIVATE(dtls_srtp_mki_support); /* support having mki_value
1472  in the use_srtp extension? */
1473 #endif
1474 
1475  /*
1476  * Pointers
1477  */
1478 
1479  /** Allowed ciphersuites for (D)TLS 1.2 (0-terminated) */
1480  const int *MBEDTLS_PRIVATE(ciphersuite_list);
1481 
1482 #if defined(MBEDTLS_SSL_PROTO_TLS1_3)
1483  /** Allowed TLS 1.3 key exchange modes. */
1484  int MBEDTLS_PRIVATE(tls13_kex_modes);
1485 #endif /* MBEDTLS_SSL_PROTO_TLS1_3 */
1486 
1487  /** Callback for printing debug output */
1488  void(*MBEDTLS_PRIVATE(f_dbg))(void *, int, const char *, int, const char *);
1489  void *MBEDTLS_PRIVATE(p_dbg); /*!< context for the debug function */
1490 
1491  /** Callback for getting (pseudo-)random numbers */
1492  int(*MBEDTLS_PRIVATE(f_rng))(void *, unsigned char *, size_t);
1493  void *MBEDTLS_PRIVATE(p_rng); /*!< context for the RNG function */
1494 
1495  /** Callback to retrieve a session from the cache */
1497  /** Callback to store a session into the cache */
1499  void *MBEDTLS_PRIVATE(p_cache); /*!< context for cache callbacks */
1500 
1501 #if defined(MBEDTLS_SSL_SERVER_NAME_INDICATION)
1502  /** Callback for setting cert according to SNI extension */
1503  int(*MBEDTLS_PRIVATE(f_sni))(void *, mbedtls_ssl_context *, const unsigned char *, size_t);
1504  void *MBEDTLS_PRIVATE(p_sni); /*!< context for SNI callback */
1505 #endif
1506 
1507 #if defined(MBEDTLS_X509_CRT_PARSE_C)
1508  /** Callback to customize X.509 certificate chain verification */
1509  int(*MBEDTLS_PRIVATE(f_vrfy))(void *, mbedtls_x509_crt *, int, uint32_t *);
1510  void *MBEDTLS_PRIVATE(p_vrfy); /*!< context for X.509 verify calllback */
1511 #endif
1512 
1513 #if defined(MBEDTLS_SSL_HANDSHAKE_WITH_PSK_ENABLED)
1514 #if defined(MBEDTLS_SSL_SRV_C)
1515  /** Callback to retrieve PSK key from identity */
1516  int(*MBEDTLS_PRIVATE(f_psk))(void *, mbedtls_ssl_context *, const unsigned char *, size_t);
1517  void *MBEDTLS_PRIVATE(p_psk); /*!< context for PSK callback */
1518 #endif
1519 #endif
1520 
1521 #if defined(MBEDTLS_SSL_DTLS_HELLO_VERIFY) && defined(MBEDTLS_SSL_SRV_C)
1522  /** Callback to create & write a cookie for ClientHello verification */
1523  int(*MBEDTLS_PRIVATE(f_cookie_write))(void *, unsigned char **, unsigned char *,
1524  const unsigned char *, size_t);
1525  /** Callback to verify validity of a ClientHello cookie */
1526  int(*MBEDTLS_PRIVATE(f_cookie_check))(void *, const unsigned char *, size_t,
1527  const unsigned char *, size_t);
1528  void *MBEDTLS_PRIVATE(p_cookie); /*!< context for the cookie callbacks */
1529 #endif
1530 
1531 #if defined(MBEDTLS_SSL_SESSION_TICKETS) && defined(MBEDTLS_SSL_SRV_C)
1532  /** Callback to create & write a session ticket */
1533  int(*MBEDTLS_PRIVATE(f_ticket_write))(void *, const mbedtls_ssl_session *,
1534  unsigned char *, const unsigned char *, size_t *,
1535  uint32_t *);
1536  /** Callback to parse a session ticket into a session structure */
1537  int(*MBEDTLS_PRIVATE(f_ticket_parse))(void *, mbedtls_ssl_session *, unsigned char *, size_t);
1538  void *MBEDTLS_PRIVATE(p_ticket); /*!< context for the ticket callbacks */
1539 #endif /* MBEDTLS_SSL_SESSION_TICKETS && MBEDTLS_SSL_SRV_C */
1540 #if defined(MBEDTLS_SSL_DTLS_CONNECTION_ID)
1541  size_t MBEDTLS_PRIVATE(cid_len); /*!< The length of CIDs for incoming DTLS records. */
1542 #endif /* MBEDTLS_SSL_DTLS_CONNECTION_ID */
1543 
1544 #if defined(MBEDTLS_X509_CRT_PARSE_C)
1545  const mbedtls_x509_crt_profile *MBEDTLS_PRIVATE(cert_profile); /*!< verification profile */
1546  mbedtls_ssl_key_cert *MBEDTLS_PRIVATE(key_cert); /*!< own certificate/key pair(s) */
1547  mbedtls_x509_crt *MBEDTLS_PRIVATE(ca_chain); /*!< trusted CAs */
1548  mbedtls_x509_crl *MBEDTLS_PRIVATE(ca_crl); /*!< trusted CAs CRLs */
1549 #if defined(MBEDTLS_X509_TRUSTED_CERTIFICATE_CALLBACK)
1550  mbedtls_x509_crt_ca_cb_t MBEDTLS_PRIVATE(f_ca_cb);
1551  void *MBEDTLS_PRIVATE(p_ca_cb);
1552 #endif /* MBEDTLS_X509_TRUSTED_CERTIFICATE_CALLBACK */
1553 #endif /* MBEDTLS_X509_CRT_PARSE_C */
1554 
1555 #if defined(MBEDTLS_SSL_ASYNC_PRIVATE)
1556 #if defined(MBEDTLS_X509_CRT_PARSE_C)
1557  mbedtls_ssl_async_sign_t *MBEDTLS_PRIVATE(f_async_sign_start); /*!< start asynchronous signature operation */
1558  mbedtls_ssl_async_decrypt_t *MBEDTLS_PRIVATE(f_async_decrypt_start); /*!< start asynchronous decryption operation */
1559 #endif /* MBEDTLS_X509_CRT_PARSE_C */
1560  mbedtls_ssl_async_resume_t *MBEDTLS_PRIVATE(f_async_resume); /*!< resume asynchronous operation */
1561  mbedtls_ssl_async_cancel_t *MBEDTLS_PRIVATE(f_async_cancel); /*!< cancel asynchronous operation */
1562  void *MBEDTLS_PRIVATE(p_async_config_data); /*!< Configuration data set by mbedtls_ssl_conf_async_private_cb(). */
1563 #endif /* MBEDTLS_SSL_ASYNC_PRIVATE */
1564 
1565 #if defined(MBEDTLS_SSL_HANDSHAKE_WITH_CERT_ENABLED)
1566 
1567 #if !defined(MBEDTLS_DEPRECATED_REMOVED)
1568  const int *MBEDTLS_PRIVATE(sig_hashes); /*!< allowed signature hashes */
1569 #endif
1570  const uint16_t *MBEDTLS_PRIVATE(sig_algs); /*!< allowed signature algorithms */
1571 #endif /* MBEDTLS_SSL_HANDSHAKE_WITH_CERT_ENABLED */
1572 
1573 #if defined(MBEDTLS_ECP_C) && !defined(MBEDTLS_DEPRECATED_REMOVED)
1574  const mbedtls_ecp_group_id *MBEDTLS_PRIVATE(curve_list); /*!< allowed curves */
1575 #endif
1576 
1577  const uint16_t *MBEDTLS_PRIVATE(group_list); /*!< allowed IANA NamedGroups */
1578 
1579 #if defined(MBEDTLS_DHM_C)
1580  mbedtls_mpi MBEDTLS_PRIVATE(dhm_P); /*!< prime modulus for DHM */
1581  mbedtls_mpi MBEDTLS_PRIVATE(dhm_G); /*!< generator for DHM */
1582 #endif
1583 
1584 #if defined(MBEDTLS_SSL_HANDSHAKE_WITH_PSK_ENABLED)
1585 
1586 #if defined(MBEDTLS_USE_PSA_CRYPTO)
1587  mbedtls_svc_key_id_t MBEDTLS_PRIVATE(psk_opaque); /*!< PSA key slot holding opaque PSK. This field
1588  * should only be set via
1589  * mbedtls_ssl_conf_psk_opaque().
1590  * If either no PSK or a raw PSK have been
1591  * configured, this has value \c 0.
1592  */
1593 #endif /* MBEDTLS_USE_PSA_CRYPTO */
1594  unsigned char *MBEDTLS_PRIVATE(psk); /*!< The raw pre-shared key. This field should
1595  * only be set via mbedtls_ssl_conf_psk().
1596  * If either no PSK or an opaque PSK
1597  * have been configured, this has value NULL. */
1598  size_t MBEDTLS_PRIVATE(psk_len); /*!< The length of the raw pre-shared key.
1599  * This field should only be set via
1600  * mbedtls_ssl_conf_psk().
1601  * Its value is non-zero if and only if
1602  * \c psk is not \c NULL. */
1603 
1604  unsigned char *MBEDTLS_PRIVATE(psk_identity); /*!< The PSK identity for PSK negotiation.
1605  * This field should only be set via
1606  * mbedtls_ssl_conf_psk().
1607  * This is set if and only if either
1608  * \c psk or \c psk_opaque are set. */
1609  size_t MBEDTLS_PRIVATE(psk_identity_len);/*!< The length of PSK identity.
1610  * This field should only be set via
1611  * mbedtls_ssl_conf_psk().
1612  * Its value is non-zero if and only if
1613  * \c psk is not \c NULL or \c psk_opaque
1614  * is not \c 0. */
1615 #endif /* MBEDTLS_SSL_HANDSHAKE_WITH_PSK_ENABLED */
1616 
1617 #if defined(MBEDTLS_SSL_EARLY_DATA)
1618  int MBEDTLS_PRIVATE(early_data_enabled); /*!< Early data enablement:
1619  * - MBEDTLS_SSL_EARLY_DATA_DISABLED,
1620  * - MBEDTLS_SSL_EARLY_DATA_ENABLED */
1621 
1622 #if defined(MBEDTLS_SSL_SRV_C)
1623  /* The maximum amount of 0-RTT data. RFC 8446 section 4.6.1 */
1624  uint32_t MBEDTLS_PRIVATE(max_early_data_size);
1625 #endif /* MBEDTLS_SSL_SRV_C */
1626 
1627 #endif /* MBEDTLS_SSL_EARLY_DATA */
1628 
1629 #if defined(MBEDTLS_SSL_ALPN)
1630  const char **MBEDTLS_PRIVATE(alpn_list); /*!< ordered list of protocols */
1631 #endif
1632 
1633 #if defined(MBEDTLS_SSL_DTLS_SRTP)
1634  /*! ordered list of supported srtp profile */
1635  const mbedtls_ssl_srtp_profile *MBEDTLS_PRIVATE(dtls_srtp_profile_list);
1636  /*! number of supported profiles */
1637  size_t MBEDTLS_PRIVATE(dtls_srtp_profile_list_len);
1638 #endif /* MBEDTLS_SSL_DTLS_SRTP */
1639 
1640  /*
1641  * Numerical settings (int)
1642  */
1643 
1644  uint32_t MBEDTLS_PRIVATE(read_timeout); /*!< timeout for mbedtls_ssl_read (ms) */
1645 
1646 #if defined(MBEDTLS_SSL_PROTO_DTLS)
1647  uint32_t MBEDTLS_PRIVATE(hs_timeout_min); /*!< initial value of the handshake
1648  retransmission timeout (ms) */
1649  uint32_t MBEDTLS_PRIVATE(hs_timeout_max); /*!< maximum value of the handshake
1650  retransmission timeout (ms) */
1651 #endif
1652 
1653 #if defined(MBEDTLS_SSL_RENEGOTIATION)
1654  int MBEDTLS_PRIVATE(renego_max_records); /*!< grace period for renegotiation */
1655  unsigned char MBEDTLS_PRIVATE(renego_period)[8]; /*!< value of the record counters
1656  that triggers renegotiation */
1657 #endif
1658 
1659  unsigned int MBEDTLS_PRIVATE(badmac_limit); /*!< limit of records with a bad MAC */
1660 
1661 #if defined(MBEDTLS_DHM_C) && defined(MBEDTLS_SSL_CLI_C)
1662  unsigned int MBEDTLS_PRIVATE(dhm_min_bitlen); /*!< min. bit length of the DHM prime */
1663 #endif
1664 
1665  /** User data pointer or handle.
1666  *
1667  * The library sets this to \p 0 when creating a context and does not
1668  * access it afterwards.
1669  */
1671 
1672 #if defined(MBEDTLS_SSL_SRV_C)
1673  mbedtls_ssl_hs_cb_t MBEDTLS_PRIVATE(f_cert_cb); /*!< certificate selection callback */
1674 #endif /* MBEDTLS_SSL_SRV_C */
1675 
1676 #if defined(MBEDTLS_KEY_EXCHANGE_CERT_REQ_ALLOWED_ENABLED)
1677  const mbedtls_x509_crt *MBEDTLS_PRIVATE(dn_hints);/*!< acceptable client cert issuers */
1678 #endif
1679 };
1680 
1682  const mbedtls_ssl_config *MBEDTLS_PRIVATE(conf); /*!< configuration information */
1683 
1684  /*
1685  * Miscellaneous
1686  */
1687  int MBEDTLS_PRIVATE(state); /*!< SSL handshake: current state */
1688 #if defined(MBEDTLS_SSL_RENEGOTIATION)
1689  int MBEDTLS_PRIVATE(renego_status); /*!< Initial, in progress, pending? */
1690  int MBEDTLS_PRIVATE(renego_records_seen); /*!< Records since renego request, or with DTLS,
1691  number of retransmissions of request if
1692  renego_max_records is < 0 */
1693 #endif /* MBEDTLS_SSL_RENEGOTIATION */
1694 
1695  /**
1696  * Maximum TLS version to be negotiated, then negotiated TLS version.
1697  *
1698  * It is initialized as the configured maximum TLS version to be
1699  * negotiated by mbedtls_ssl_setup().
1700  *
1701  * When renegotiating or resuming a session, it is overwritten in the
1702  * ClientHello writing preparation stage with the previously negotiated
1703  * TLS version.
1704  *
1705  * On client side, it is updated to the TLS version selected by the server
1706  * for the handshake when the ServerHello is received.
1707  *
1708  * On server side, it is updated to the TLS version the server selects for
1709  * the handshake when the ClientHello is received.
1710  */
1712 
1713 #if defined(MBEDTLS_SSL_EARLY_DATA) && defined(MBEDTLS_SSL_CLI_C)
1714  /**
1715  * State of the negotiation and transfer of early data. Reset to
1716  * MBEDTLS_SSL_EARLY_DATA_STATE_IDLE when the context is reset.
1717  */
1718  int MBEDTLS_PRIVATE(early_data_state);
1719 #endif
1720 
1721  unsigned MBEDTLS_PRIVATE(badmac_seen); /*!< records with a bad MAC received */
1722 
1723 #if defined(MBEDTLS_X509_CRT_PARSE_C)
1724  /** Callback to customize X.509 certificate chain verification */
1725  int(*MBEDTLS_PRIVATE(f_vrfy))(void *, mbedtls_x509_crt *, int, uint32_t *);
1726  void *MBEDTLS_PRIVATE(p_vrfy); /*!< context for X.509 verify callback */
1727 #endif
1728 
1729  mbedtls_ssl_send_t *MBEDTLS_PRIVATE(f_send); /*!< Callback for network send */
1730  mbedtls_ssl_recv_t *MBEDTLS_PRIVATE(f_recv); /*!< Callback for network receive */
1732  /*!< Callback for network receive with timeout */
1733 
1734  void *MBEDTLS_PRIVATE(p_bio); /*!< context for I/O operations */
1735 
1736  /*
1737  * Session layer
1738  */
1739  mbedtls_ssl_session *MBEDTLS_PRIVATE(session_in); /*!< current session data (in) */
1740  mbedtls_ssl_session *MBEDTLS_PRIVATE(session_out); /*!< current session data (out) */
1741  mbedtls_ssl_session *MBEDTLS_PRIVATE(session); /*!< negotiated session data */
1742  mbedtls_ssl_session *MBEDTLS_PRIVATE(session_negotiate); /*!< session data in negotiation */
1743 
1744  mbedtls_ssl_handshake_params *MBEDTLS_PRIVATE(handshake); /*!< params required only during
1745  the handshake process */
1746 
1747  /*
1748  * Record layer transformations
1749  */
1750  mbedtls_ssl_transform *MBEDTLS_PRIVATE(transform_in); /*!< current transform params (in)
1751  * This is always a reference,
1752  * never an owning pointer. */
1753  mbedtls_ssl_transform *MBEDTLS_PRIVATE(transform_out); /*!< current transform params (out)
1754  * This is always a reference,
1755  * never an owning pointer. */
1756  mbedtls_ssl_transform *MBEDTLS_PRIVATE(transform); /*!< negotiated transform params
1757  * This pointer owns the transform
1758  * it references. */
1759 #if defined(MBEDTLS_SSL_PROTO_TLS1_2)
1760  mbedtls_ssl_transform *MBEDTLS_PRIVATE(transform_negotiate); /*!< transform params in negotiation
1761  * This pointer owns the transform
1762  * it references. */
1763 #endif /* MBEDTLS_SSL_PROTO_TLS1_2 */
1764 
1765 #if defined(MBEDTLS_SSL_PROTO_TLS1_3)
1766  /*! The application data transform in TLS 1.3.
1767  * This pointer owns the transform it references. */
1768  mbedtls_ssl_transform *MBEDTLS_PRIVATE(transform_application);
1769 #endif /* MBEDTLS_SSL_PROTO_TLS1_3 */
1770 
1771  /*
1772  * Timers
1773  */
1774  void *MBEDTLS_PRIVATE(p_timer); /*!< context for the timer callbacks */
1775 
1776  mbedtls_ssl_set_timer_t *MBEDTLS_PRIVATE(f_set_timer); /*!< set timer callback */
1777  mbedtls_ssl_get_timer_t *MBEDTLS_PRIVATE(f_get_timer); /*!< get timer callback */
1778 
1779  /*
1780  * Record layer (incoming data)
1781  */
1782  unsigned char *MBEDTLS_PRIVATE(in_buf); /*!< input buffer */
1783  unsigned char *MBEDTLS_PRIVATE(in_ctr); /*!< 64-bit incoming message counter
1784  TLS: maintained by us
1785  DTLS: read from peer */
1786  unsigned char *MBEDTLS_PRIVATE(in_hdr); /*!< start of record header */
1787 #if defined(MBEDTLS_SSL_DTLS_CONNECTION_ID)
1788  unsigned char *MBEDTLS_PRIVATE(in_cid); /*!< The start of the CID;
1789  * (the end is marked by in_len). */
1790 #endif /* MBEDTLS_SSL_DTLS_CONNECTION_ID */
1791  unsigned char *MBEDTLS_PRIVATE(in_len); /*!< two-bytes message length field */
1792  unsigned char *MBEDTLS_PRIVATE(in_iv); /*!< ivlen-byte IV */
1793  unsigned char *MBEDTLS_PRIVATE(in_msg); /*!< message contents (in_iv+ivlen) */
1794  unsigned char *MBEDTLS_PRIVATE(in_offt); /*!< read offset in application data */
1795 
1796  int MBEDTLS_PRIVATE(in_msgtype); /*!< record header: message type */
1797  size_t MBEDTLS_PRIVATE(in_msglen); /*!< record header: message length */
1798  size_t MBEDTLS_PRIVATE(in_left); /*!< amount of data read so far */
1799 #if defined(MBEDTLS_SSL_VARIABLE_BUFFER_LENGTH)
1800  size_t MBEDTLS_PRIVATE(in_buf_len); /*!< length of input buffer */
1801 #endif
1802 #if defined(MBEDTLS_SSL_PROTO_DTLS)
1803  uint16_t MBEDTLS_PRIVATE(in_epoch); /*!< DTLS epoch for incoming records */
1804  size_t MBEDTLS_PRIVATE(next_record_offset); /*!< offset of the next record in datagram
1805  (equal to in_left if none) */
1806 #endif /* MBEDTLS_SSL_PROTO_DTLS */
1807 #if defined(MBEDTLS_SSL_DTLS_ANTI_REPLAY)
1808  uint64_t MBEDTLS_PRIVATE(in_window_top); /*!< last validated record seq_num */
1809  uint64_t MBEDTLS_PRIVATE(in_window); /*!< bitmask for replay detection */
1810 #endif /* MBEDTLS_SSL_DTLS_ANTI_REPLAY */
1811 
1812  size_t MBEDTLS_PRIVATE(in_hslen); /*!< current handshake message length,
1813  including the handshake header */
1814  int MBEDTLS_PRIVATE(nb_zero); /*!< # of 0-length encrypted messages */
1815 
1816  int MBEDTLS_PRIVATE(keep_current_message); /*!< drop or reuse current message
1817  on next call to record layer? */
1818 
1819  /* The following three variables indicate if and, if yes,
1820  * what kind of alert is pending to be sent.
1821  */
1822  unsigned char MBEDTLS_PRIVATE(send_alert); /*!< Determines if a fatal alert
1823  should be sent. Values:
1824  - \c 0 , no alert is to be sent.
1825  - \c 1 , alert is to be sent. */
1826  unsigned char MBEDTLS_PRIVATE(alert_type); /*!< Type of alert if send_alert
1827  != 0 */
1828  int MBEDTLS_PRIVATE(alert_reason); /*!< The error code to be returned
1829  to the user once the fatal alert
1830  has been sent. */
1831 
1832 #if defined(MBEDTLS_SSL_PROTO_DTLS)
1833  uint8_t MBEDTLS_PRIVATE(disable_datagram_packing); /*!< Disable packing multiple records
1834  * within a single datagram. */
1835 #endif /* MBEDTLS_SSL_PROTO_DTLS */
1836 
1837 #if defined(MBEDTLS_SSL_EARLY_DATA)
1838 #if defined(MBEDTLS_SSL_SRV_C)
1839  /*
1840  * One of:
1841  * MBEDTLS_SSL_EARLY_DATA_NO_DISCARD
1842  * MBEDTLS_SSL_EARLY_DATA_TRY_TO_DEPROTECT_AND_DISCARD
1843  * MBEDTLS_SSL_EARLY_DATA_DISCARD
1844  */
1845  uint8_t MBEDTLS_PRIVATE(discard_early_data_record);
1846 #endif
1847  uint32_t MBEDTLS_PRIVATE(total_early_data_size); /*!< Number of received/written early data bytes */
1848 #endif /* MBEDTLS_SSL_EARLY_DATA */
1849 
1850  /*
1851  * Record layer (outgoing data)
1852  */
1853  unsigned char *MBEDTLS_PRIVATE(out_buf); /*!< output buffer */
1854  unsigned char *MBEDTLS_PRIVATE(out_ctr); /*!< 64-bit outgoing message counter */
1855  unsigned char *MBEDTLS_PRIVATE(out_hdr); /*!< start of record header */
1856 #if defined(MBEDTLS_SSL_DTLS_CONNECTION_ID)
1857  unsigned char *MBEDTLS_PRIVATE(out_cid); /*!< The start of the CID;
1858  * (the end is marked by in_len). */
1859 #endif /* MBEDTLS_SSL_DTLS_CONNECTION_ID */
1860  unsigned char *MBEDTLS_PRIVATE(out_len); /*!< two-bytes message length field */
1861  unsigned char *MBEDTLS_PRIVATE(out_iv); /*!< ivlen-byte IV */
1862  unsigned char *MBEDTLS_PRIVATE(out_msg); /*!< message contents (out_iv+ivlen) */
1863 
1864  int MBEDTLS_PRIVATE(out_msgtype); /*!< record header: message type */
1865  size_t MBEDTLS_PRIVATE(out_msglen); /*!< record header: message length */
1866  size_t MBEDTLS_PRIVATE(out_left); /*!< amount of data not yet written */
1867 #if defined(MBEDTLS_SSL_VARIABLE_BUFFER_LENGTH)
1868  size_t MBEDTLS_PRIVATE(out_buf_len); /*!< length of output buffer */
1869 #endif
1870 
1871  unsigned char MBEDTLS_PRIVATE(cur_out_ctr)[MBEDTLS_SSL_SEQUENCE_NUMBER_LEN]; /*!< Outgoing record sequence number. */
1872 
1873 #if defined(MBEDTLS_SSL_PROTO_DTLS)
1874  uint16_t MBEDTLS_PRIVATE(mtu); /*!< path mtu, used to fragment outgoing messages */
1875 #endif /* MBEDTLS_SSL_PROTO_DTLS */
1876 
1877  /*
1878  * User settings
1879  */
1880 #if defined(MBEDTLS_X509_CRT_PARSE_C)
1881  char *MBEDTLS_PRIVATE(hostname); /*!< expected peer CN for verification
1882  (and SNI if available) */
1883 #endif /* MBEDTLS_X509_CRT_PARSE_C */
1884 
1885 #if defined(MBEDTLS_SSL_ALPN)
1886  const char *MBEDTLS_PRIVATE(alpn_chosen); /*!< negotiated protocol */
1887 #endif /* MBEDTLS_SSL_ALPN */
1888 
1889 #if defined(MBEDTLS_SSL_DTLS_SRTP)
1890  /*
1891  * use_srtp extension
1892  */
1893  mbedtls_dtls_srtp_info MBEDTLS_PRIVATE(dtls_srtp_info);
1894 #endif /* MBEDTLS_SSL_DTLS_SRTP */
1895 
1896  /*
1897  * Information for DTLS hello verify
1898  */
1899 #if defined(MBEDTLS_SSL_DTLS_HELLO_VERIFY) && defined(MBEDTLS_SSL_SRV_C)
1900  unsigned char *MBEDTLS_PRIVATE(cli_id); /*!< transport-level ID of the client */
1901  size_t MBEDTLS_PRIVATE(cli_id_len); /*!< length of cli_id */
1902 #endif /* MBEDTLS_SSL_DTLS_HELLO_VERIFY && MBEDTLS_SSL_SRV_C */
1903 
1904  /*
1905  * Secure renegotiation
1906  */
1907  /* needed to know when to send extension on server */
1908  int MBEDTLS_PRIVATE(secure_renegotiation); /*!< does peer support legacy or
1909  secure renegotiation */
1910 #if defined(MBEDTLS_SSL_RENEGOTIATION)
1911  size_t MBEDTLS_PRIVATE(verify_data_len); /*!< length of verify data stored */
1912  char MBEDTLS_PRIVATE(own_verify_data)[MBEDTLS_SSL_VERIFY_DATA_MAX_LEN]; /*!< previous handshake verify data */
1913  char MBEDTLS_PRIVATE(peer_verify_data)[MBEDTLS_SSL_VERIFY_DATA_MAX_LEN]; /*!< previous handshake verify data */
1914 #endif /* MBEDTLS_SSL_RENEGOTIATION */
1915 
1916 #if defined(MBEDTLS_SSL_DTLS_CONNECTION_ID)
1917  /* CID configuration to use in subsequent handshakes. */
1918 
1919  /*! The next incoming CID, chosen by the user and applying to
1920  * all subsequent handshakes. This may be different from the
1921  * CID currently used in case the user has re-configured the CID
1922  * after an initial handshake. */
1923  unsigned char MBEDTLS_PRIVATE(own_cid)[MBEDTLS_SSL_CID_IN_LEN_MAX];
1924  uint8_t MBEDTLS_PRIVATE(own_cid_len); /*!< The length of \c own_cid. */
1925  uint8_t MBEDTLS_PRIVATE(negotiate_cid); /*!< This indicates whether the CID extension should
1926  * be negotiated in the next handshake or not.
1927  * Possible values are #MBEDTLS_SSL_CID_ENABLED
1928  * and #MBEDTLS_SSL_CID_DISABLED. */
1929 #endif /* MBEDTLS_SSL_DTLS_CONNECTION_ID */
1930 
1931  /** Callback to export key block and master secret */
1933  void *MBEDTLS_PRIVATE(p_export_keys); /*!< context for key export callback */
1934 
1935  /** User data pointer or handle.
1936  *
1937  * The library sets this to \p 0 when creating a context and does not
1938  * access it afterwards.
1939  *
1940  * \warning Serializing and restoring an SSL context with
1941  * mbedtls_ssl_context_save() and mbedtls_ssl_context_load()
1942  * does not currently restore the user data.
1943  */
1945 };
1946 
1947 /**
1948  * \brief Return the name of the ciphersuite associated with the
1949  * given ID
1950  *
1951  * \param ciphersuite_id SSL ciphersuite ID
1952  *
1953  * \return a string containing the ciphersuite name
1954  */
1955 const char *mbedtls_ssl_get_ciphersuite_name(const int ciphersuite_id);
1956 
1957 /**
1958  * \brief Return the ID of the ciphersuite associated with the
1959  * given name
1960  *
1961  * \param ciphersuite_name SSL ciphersuite name
1962  *
1963  * \return the ID with the ciphersuite or 0 if not found
1964  */
1965 int mbedtls_ssl_get_ciphersuite_id(const char *ciphersuite_name);
1966 
1967 /**
1968  * \brief Initialize an SSL context
1969  * Just makes the context ready for mbedtls_ssl_setup() or
1970  * mbedtls_ssl_free()
1971  *
1972  * \param ssl SSL context
1973  */
1975 
1976 /**
1977  * \brief Set up an SSL context for use
1978  *
1979  * \note No copy of the configuration context is made, it can be
1980  * shared by many mbedtls_ssl_context structures.
1981  *
1982  * \warning The conf structure will be accessed during the session.
1983  * It must not be modified or freed as long as the session
1984  * is active.
1985  *
1986  * \warning This function must be called exactly once per context.
1987  * Calling mbedtls_ssl_setup again is not supported, even
1988  * if no session is active.
1989  *
1990  * \note If #MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto
1991  * subsystem must have been initialized by calling
1992  * psa_crypto_init() before calling this function.
1993  *
1994  * \param ssl SSL context
1995  * \param conf SSL configuration to use
1996  *
1997  * \return 0 if successful, or MBEDTLS_ERR_SSL_ALLOC_FAILED if
1998  * memory allocation failed
1999  */
2001  const mbedtls_ssl_config *conf);
2002 
2003 /**
2004  * \brief Reset an already initialized SSL context for re-use
2005  * while retaining application-set variables, function
2006  * pointers and data.
2007  *
2008  * \param ssl SSL context
2009  * \return 0 if successful, or MBEDTLS_ERR_SSL_ALLOC_FAILED or
2010  MBEDTLS_ERR_SSL_HW_ACCEL_FAILED
2011  */
2013 
2014 /**
2015  * \brief Set the current endpoint type
2016  *
2017  * \param conf SSL configuration
2018  * \param endpoint must be MBEDTLS_SSL_IS_CLIENT or MBEDTLS_SSL_IS_SERVER
2019  */
2021 
2022 /**
2023  * \brief Get the current endpoint type
2024  *
2025  * \param conf SSL configuration
2026  *
2027  * \return Endpoint type, either MBEDTLS_SSL_IS_CLIENT
2028  * or MBEDTLS_SSL_IS_SERVER
2029  */
2031 {
2032  return conf->MBEDTLS_PRIVATE(endpoint);
2033 }
2034 
2035 /**
2036  * \brief Set the transport type (TLS or DTLS).
2037  * Default: TLS
2038  *
2039  * \note For DTLS, you must either provide a recv callback that
2040  * doesn't block, or one that handles timeouts, see
2041  * \c mbedtls_ssl_set_bio(). You also need to provide timer
2042  * callbacks with \c mbedtls_ssl_set_timer_cb().
2043  *
2044  * \param conf SSL configuration
2045  * \param transport transport type:
2046  * MBEDTLS_SSL_TRANSPORT_STREAM for TLS,
2047  * MBEDTLS_SSL_TRANSPORT_DATAGRAM for DTLS.
2048  */
2050 
2051 /**
2052  * \brief Set the certificate verification mode
2053  * Default: NONE on server, REQUIRED on client
2054  *
2055  * \param conf SSL configuration
2056  * \param authmode can be:
2057  *
2058  * MBEDTLS_SSL_VERIFY_NONE: peer certificate is not checked
2059  * (default on server)
2060  * (insecure on client)
2061  *
2062  * MBEDTLS_SSL_VERIFY_OPTIONAL: peer certificate is checked, however the
2063  * handshake continues even if verification failed;
2064  * mbedtls_ssl_get_verify_result() can be called after the
2065  * handshake is complete.
2066  *
2067  * MBEDTLS_SSL_VERIFY_REQUIRED: peer *must* present a valid certificate,
2068  * handshake is aborted if verification failed.
2069  * (default on client)
2070  *
2071  * \note On client, MBEDTLS_SSL_VERIFY_REQUIRED is the recommended mode.
2072  * With MBEDTLS_SSL_VERIFY_OPTIONAL, the user needs to call mbedtls_ssl_get_verify_result() at
2073  * the right time(s), which may not be obvious, while REQUIRED always perform
2074  * the verification as soon as possible. For example, REQUIRED was protecting
2075  * against the "triple handshake" attack even before it was found.
2076  */
2078 
2079 #if defined(MBEDTLS_SSL_EARLY_DATA)
2080 /**
2081  * \brief Set the early data mode
2082  * Default: disabled on server and client
2083  *
2084  * \param conf The SSL configuration to use.
2085  * \param early_data_enabled can be:
2086  *
2087  * MBEDTLS_SSL_EARLY_DATA_DISABLED:
2088  * Early data functionality is disabled. This is the default on client and
2089  * server.
2090  *
2091  * MBEDTLS_SSL_EARLY_DATA_ENABLED:
2092  * Early data functionality is enabled and may be negotiated in the handshake.
2093  * Application using early data functionality needs to be aware that the
2094  * security properties for early data (also refered to as 0-RTT data) are
2095  * weaker than those for other kinds of TLS data. See the documentation of
2096  * mbedtls_ssl_write_early_data() and mbedtls_ssl_read_early_data() for more
2097  * information.
2098  * When early data functionality is enabled on server and only in that case,
2099  * the call to one of the APIs that trigger or resume an handshake sequence,
2100  * namely mbedtls_ssl_handshake(), mbedtls_ssl_handshake_step(),
2101  * mbedtls_ssl_read() or mbedtls_ssl_write() may return with the error code
2102  * MBEDTLS_ERR_SSL_RECEIVED_EARLY_DATA indicating that some early data have
2103  * been received. To read the early data, call mbedtls_ssl_read_early_data()
2104  * before calling the original function again.
2105  */
2106 void mbedtls_ssl_conf_early_data(mbedtls_ssl_config *conf,
2107  int early_data_enabled);
2108 
2109 #if defined(MBEDTLS_SSL_SRV_C)
2110 /**
2111  * \brief Set the maximum amount of 0-RTT data in bytes
2112  * Default: #MBEDTLS_SSL_MAX_EARLY_DATA_SIZE
2113  *
2114  * This function sets the value of the max_early_data_size
2115  * field of the early data indication extension included in
2116  * the NewSessionTicket messages that the server may send.
2117  *
2118  * The value defines the maximum amount of 0-RTT data
2119  * in bytes that a client will be allowed to send when using
2120  * one of the tickets defined by the NewSessionTicket messages.
2121  *
2122  * \note When resuming a session using a ticket, if the server receives more
2123  * early data than allowed for the ticket, it terminates the connection.
2124  * The maximum amount of 0-RTT data should thus be large enough
2125  * to allow a minimum of early data to be exchanged.
2126  *
2127  * \param[in] conf The SSL configuration to use.
2128  * \param[in] max_early_data_size The maximum amount of 0-RTT data.
2129  *
2130  * \warning This interface DOES NOT influence/limit the amount of early data
2131  * that can be received through previously created and issued tickets,
2132  * which clients may have stored.
2133  */
2134 void mbedtls_ssl_conf_max_early_data_size(
2135  mbedtls_ssl_config *conf, uint32_t max_early_data_size);
2136 #endif /* MBEDTLS_SSL_SRV_C */
2137 
2138 #endif /* MBEDTLS_SSL_EARLY_DATA */
2139 
2140 #if defined(MBEDTLS_X509_CRT_PARSE_C)
2141 /**
2142  * \brief Set the verification callback (Optional).
2143  *
2144  * If set, the provided verify callback is called for each
2145  * certificate in the peer's CRT chain, including the trusted
2146  * root. For more information, please see the documentation of
2147  * \c mbedtls_x509_crt_verify().
2148  *
2149  * \note For per context callbacks and contexts, please use
2150  * mbedtls_ssl_set_verify() instead.
2151  *
2152  * \param conf The SSL configuration to use.
2153  * \param f_vrfy The verification callback to use during CRT verification.
2154  * \param p_vrfy The opaque context to be passed to the callback.
2155  */
2157  int (*f_vrfy)(void *, mbedtls_x509_crt *, int, uint32_t *),
2158  void *p_vrfy);
2159 #endif /* MBEDTLS_X509_CRT_PARSE_C */
2160 
2161 /**
2162  * \brief Set the random number generator callback
2163  *
2164  * \param conf SSL configuration
2165  * \param f_rng RNG function (mandatory)
2166  * \param p_rng RNG parameter
2167  */
2169  int (*f_rng)(void *, unsigned char *, size_t),
2170  void *p_rng);
2171 
2172 /**
2173  * \brief Set the debug callback
2174  *
2175  * The callback has the following argument:
2176  * void * opaque context for the callback
2177  * int debug level
2178  * const char * file name
2179  * int line number
2180  * const char * message
2181  *
2182  * \param conf SSL configuration
2183  * \param f_dbg debug function
2184  * \param p_dbg debug parameter
2185  */
2187  void (*f_dbg)(void *, int, const char *, int, const char *),
2188  void *p_dbg);
2189 
2190 /**
2191  * \brief Return the SSL configuration structure associated
2192  * with the given SSL context.
2193  *
2194  * \note The pointer returned by this function is guaranteed to
2195  * remain valid until the context is freed.
2196  *
2197  * \param ssl The SSL context to query.
2198  * \return Pointer to the SSL configuration associated with \p ssl.
2199  */
2201  const mbedtls_ssl_context *ssl)
2202 {
2203  return ssl->MBEDTLS_PRIVATE(conf);
2204 }
2205 
2206 /**
2207  * \brief Set the underlying BIO callbacks for write, read and
2208  * read-with-timeout.
2209  *
2210  * \param ssl SSL context
2211  * \param p_bio parameter (context) shared by BIO callbacks
2212  * \param f_send write callback
2213  * \param f_recv read callback
2214  * \param f_recv_timeout blocking read callback with timeout.
2215  *
2216  * \note One of f_recv or f_recv_timeout can be NULL, in which case
2217  * the other is used. If both are non-NULL, f_recv_timeout is
2218  * used and f_recv is ignored (as if it were NULL).
2219  *
2220  * \note The two most common use cases are:
2221  * - non-blocking I/O, f_recv != NULL, f_recv_timeout == NULL
2222  * - blocking I/O, f_recv == NULL, f_recv_timeout != NULL
2223  *
2224  * \note For DTLS, you need to provide either a non-NULL
2225  * f_recv_timeout callback, or a f_recv that doesn't block.
2226  *
2227  * \note See the documentations of \c mbedtls_ssl_send_t,
2228  * \c mbedtls_ssl_recv_t and \c mbedtls_ssl_recv_timeout_t for
2229  * the conventions those callbacks must follow.
2230  *
2231  * \note On some platforms, net_sockets.c provides
2232  * \c mbedtls_net_send(), \c mbedtls_net_recv() and
2233  * \c mbedtls_net_recv_timeout() that are suitable to be used
2234  * here.
2235  */
2237  void *p_bio,
2238  mbedtls_ssl_send_t *f_send,
2239  mbedtls_ssl_recv_t *f_recv,
2240  mbedtls_ssl_recv_timeout_t *f_recv_timeout);
2241 
2242 #if defined(MBEDTLS_SSL_PROTO_DTLS)
2243 
2244 #if defined(MBEDTLS_SSL_DTLS_CONNECTION_ID)
2245 
2246 
2247 /**
2248  * \brief Configure the use of the Connection ID (CID)
2249  * extension in the next handshake.
2250  *
2251  * Reference: RFC 9146 (or draft-ietf-tls-dtls-connection-id-05
2252  * https://tools.ietf.org/html/draft-ietf-tls-dtls-connection-id-05
2253  * for legacy version)
2254  *
2255  * The DTLS CID extension allows the reliable association of
2256  * DTLS records to DTLS connections across changes in the
2257  * underlying transport (changed IP and Port metadata) by
2258  * adding explicit connection identifiers (CIDs) to the
2259  * headers of encrypted DTLS records. The desired CIDs are
2260  * configured by the application layer and are exchanged in
2261  * new `ClientHello` / `ServerHello` extensions during the
2262  * handshake, where each side indicates the CID it wants the
2263  * peer to use when writing encrypted messages. The CIDs are
2264  * put to use once records get encrypted: the stack discards
2265  * any incoming records that don't include the configured CID
2266  * in their header, and adds the peer's requested CID to the
2267  * headers of outgoing messages.
2268  *
2269  * This API enables or disables the use of the CID extension
2270  * in the next handshake and sets the value of the CID to
2271  * be used for incoming messages.
2272  *
2273  * \param ssl The SSL context to configure. This must be initialized.
2274  * \param enable This value determines whether the CID extension should
2275  * be used or not. Possible values are:
2276  * - MBEDTLS_SSL_CID_ENABLED to enable the use of the CID.
2277  * - MBEDTLS_SSL_CID_DISABLED (default) to disable the use
2278  * of the CID.
2279  * \param own_cid The address of the readable buffer holding the CID we want
2280  * the peer to use when sending encrypted messages to us.
2281  * This may be \c NULL if \p own_cid_len is \c 0.
2282  * This parameter is unused if \p enable is set to
2283  * MBEDTLS_SSL_CID_DISABLED.
2284  * \param own_cid_len The length of \p own_cid.
2285  * This parameter is unused if \p enable is set to
2286  * MBEDTLS_SSL_CID_DISABLED.
2287  *
2288  * \note The value of \p own_cid_len must match the value of the
2289  * \c len parameter passed to mbedtls_ssl_conf_cid()
2290  * when configuring the ::mbedtls_ssl_config that \p ssl
2291  * is bound to.
2292  *
2293  * \note This CID configuration applies to subsequent handshakes
2294  * performed on the SSL context \p ssl, but does not trigger
2295  * one. You still have to call `mbedtls_ssl_handshake()`
2296  * (for the initial handshake) or `mbedtls_ssl_renegotiate()`
2297  * (for a renegotiation handshake) explicitly after a
2298  * successful call to this function to run the handshake.
2299  *
2300  * \note This call cannot guarantee that the use of the CID
2301  * will be successfully negotiated in the next handshake,
2302  * because the peer might not support it. Specifically:
2303  * - On the Client, enabling the use of the CID through
2304  * this call implies that the `ClientHello` in the next
2305  * handshake will include the CID extension, thereby
2306  * offering the use of the CID to the server. Only if
2307  * the `ServerHello` contains the CID extension, too,
2308  * the CID extension will actually be put to use.
2309  * - On the Server, enabling the use of the CID through
2310  * this call implies that the server will look for
2311  * the CID extension in a `ClientHello` from the client,
2312  * and, if present, reply with a CID extension in its
2313  * `ServerHello`.
2314  *
2315  * \note To check whether the use of the CID was negotiated
2316  * after the subsequent handshake has completed, please
2317  * use the API mbedtls_ssl_get_peer_cid().
2318  *
2319  * \warning If the use of the CID extension is enabled in this call
2320  * and the subsequent handshake negotiates its use, Mbed TLS
2321  * will silently drop every packet whose CID does not match
2322  * the CID configured in \p own_cid. It is the responsibility
2323  * of the user to adapt the underlying transport to take care
2324  * of CID-based demultiplexing before handing datagrams to
2325  * Mbed TLS.
2326  *
2327  * \return \c 0 on success. In this case, the CID configuration
2328  * applies to the next handshake.
2329  * \return A negative error code on failure.
2330  */
2332  int enable,
2333  unsigned char const *own_cid,
2334  size_t own_cid_len);
2335 
2336 /**
2337  * \brief Get information about our request for usage of the CID
2338  * extension in the current connection.
2339  *
2340  * \param ssl The SSL context to query.
2341  * \param enabled The address at which to store whether the CID extension
2342  * is requested to be used or not. If the CID is
2343  * requested, `*enabled` is set to
2344  * MBEDTLS_SSL_CID_ENABLED; otherwise, it is set to
2345  * MBEDTLS_SSL_CID_DISABLED.
2346  * \param own_cid The address of the buffer in which to store our own
2347  * CID (if the CID extension is requested). This may be
2348  * \c NULL in case the value of our CID isn't needed. If
2349  * it is not \c NULL, \p own_cid_len must not be \c NULL.
2350  * \param own_cid_len The address at which to store the size of our own CID
2351  * (if the CID extension is requested). This is also the
2352  * number of Bytes in \p own_cid that have been written.
2353  * This may be \c NULL in case the length of our own CID
2354  * isn't needed. If it is \c NULL, \p own_cid must be
2355  * \c NULL, too.
2356  *
2357  *\note If we are requesting an empty CID this function sets
2358  * `*enabled` to #MBEDTLS_SSL_CID_DISABLED (the rationale
2359  * for this is that the resulting outcome is the
2360  * same as if the CID extensions wasn't requested).
2361  *
2362  * \return \c 0 on success.
2363  * \return A negative error code on failure.
2364  */
2366  int *enabled,
2367  unsigned char own_cid[MBEDTLS_SSL_CID_OUT_LEN_MAX],
2368  size_t *own_cid_len);
2369 
2370 /**
2371  * \brief Get information about the use of the CID extension
2372  * in the current connection.
2373  *
2374  * \param ssl The SSL context to query.
2375  * \param enabled The address at which to store whether the CID extension
2376  * is currently in use or not. If the CID is in use,
2377  * `*enabled` is set to MBEDTLS_SSL_CID_ENABLED;
2378  * otherwise, it is set to MBEDTLS_SSL_CID_DISABLED.
2379  * \param peer_cid The address of the buffer in which to store the CID
2380  * chosen by the peer (if the CID extension is used).
2381  * This may be \c NULL in case the value of peer CID
2382  * isn't needed. If it is not \c NULL, \p peer_cid_len
2383  * must not be \c NULL.
2384  * \param peer_cid_len The address at which to store the size of the CID
2385  * chosen by the peer (if the CID extension is used).
2386  * This is also the number of Bytes in \p peer_cid that
2387  * have been written.
2388  * This may be \c NULL in case the length of the peer CID
2389  * isn't needed. If it is \c NULL, \p peer_cid must be
2390  * \c NULL, too.
2391  *
2392  * \note This applies to the state of the CID negotiated in
2393  * the last complete handshake. If a handshake is in
2394  * progress, this function will attempt to complete
2395  * the handshake first.
2396  *
2397  * \note If CID extensions have been exchanged but both client
2398  * and server chose to use an empty CID, this function
2399  * sets `*enabled` to #MBEDTLS_SSL_CID_DISABLED
2400  * (the rationale for this is that the resulting
2401  * communication is the same as if the CID extensions
2402  * hadn't been used).
2403  *
2404  * \return \c 0 on success.
2405  * \return A negative error code on failure.
2406  */
2408  int *enabled,
2409  unsigned char peer_cid[MBEDTLS_SSL_CID_OUT_LEN_MAX],
2410  size_t *peer_cid_len);
2411 
2412 #endif /* MBEDTLS_SSL_DTLS_CONNECTION_ID */
2413 
2414 /**
2415  * \brief Set the Maximum Transport Unit (MTU).
2416  * Special value: 0 means unset (no limit).
2417  * This represents the maximum size of a datagram payload
2418  * handled by the transport layer (usually UDP) as determined
2419  * by the network link and stack. In practice, this controls
2420  * the maximum size datagram the DTLS layer will pass to the
2421  * \c f_send() callback set using \c mbedtls_ssl_set_bio().
2422  *
2423  * \note The limit on datagram size is converted to a limit on
2424  * record payload by subtracting the current overhead of
2425  * encapsulation and encryption/authentication if any.
2426  *
2427  * \note This can be called at any point during the connection, for
2428  * example when a Path Maximum Transfer Unit (PMTU)
2429  * estimate becomes available from other sources,
2430  * such as lower (or higher) protocol layers.
2431  *
2432  * \note This setting only controls the size of the packets we send,
2433  * and does not restrict the size of the datagrams we're
2434  * willing to receive. Client-side, you can request the
2435  * server to use smaller records with \c
2436  * mbedtls_ssl_conf_max_frag_len().
2437  *
2438  * \note If both a MTU and a maximum fragment length have been
2439  * configured (or negotiated with the peer), the resulting
2440  * lower limit on record payload (see first note) is used.
2441  *
2442  * \note This can only be used to decrease the maximum size
2443  * of datagrams (hence records, see first note) sent. It
2444  * cannot be used to increase the maximum size of records over
2445  * the limit set by #MBEDTLS_SSL_OUT_CONTENT_LEN.
2446  *
2447  * \note Values lower than the current record layer expansion will
2448  * result in an error when trying to send data.
2449  *
2450  * \param ssl SSL context
2451  * \param mtu Value of the path MTU in bytes
2452  */
2454 #endif /* MBEDTLS_SSL_PROTO_DTLS */
2455 
2456 #if defined(MBEDTLS_X509_CRT_PARSE_C)
2457 /**
2458  * \brief Set a connection-specific verification callback (optional).
2459  *
2460  * If set, the provided verify callback is called for each
2461  * certificate in the peer's CRT chain, including the trusted
2462  * root. For more information, please see the documentation of
2463  * \c mbedtls_x509_crt_verify().
2464  *
2465  * \note This call is analogous to mbedtls_ssl_conf_verify() but
2466  * binds the verification callback and context to an SSL context
2467  * as opposed to an SSL configuration.
2468  * If mbedtls_ssl_conf_verify() and mbedtls_ssl_set_verify()
2469  * are both used, mbedtls_ssl_set_verify() takes precedence.
2470  *
2471  * \param ssl The SSL context to use.
2472  * \param f_vrfy The verification callback to use during CRT verification.
2473  * \param p_vrfy The opaque context to be passed to the callback.
2474  */
2476  int (*f_vrfy)(void *, mbedtls_x509_crt *, int, uint32_t *),
2477  void *p_vrfy);
2478 #endif /* MBEDTLS_X509_CRT_PARSE_C */
2479 
2480 /**
2481  * \brief Set the timeout period for mbedtls_ssl_read()
2482  * (Default: no timeout.)
2483  *
2484  * \param conf SSL configuration context
2485  * \param timeout Timeout value in milliseconds.
2486  * Use 0 for no timeout (default).
2487  *
2488  * \note With blocking I/O, this will only work if a non-NULL
2489  * \c f_recv_timeout was set with \c mbedtls_ssl_set_bio().
2490  * With non-blocking I/O, this will only work if timer
2491  * callbacks were set with \c mbedtls_ssl_set_timer_cb().
2492  *
2493  * \note With non-blocking I/O, you may also skip this function
2494  * altogether and handle timeouts at the application layer.
2495  */
2497 
2498 /**
2499  * \brief Check whether a buffer contains a valid and authentic record
2500  * that has not been seen before. (DTLS only).
2501  *
2502  * This function does not change the user-visible state
2503  * of the SSL context. Its sole purpose is to provide
2504  * an indication of the legitimacy of an incoming record.
2505  *
2506  * This can be useful e.g. in distributed server environments
2507  * using the DTLS Connection ID feature, in which connections
2508  * might need to be passed between service instances on a change
2509  * of peer address, but where such disruptive operations should
2510  * only happen after the validity of incoming records has been
2511  * confirmed.
2512  *
2513  * \param ssl The SSL context to use.
2514  * \param buf The address of the buffer holding the record to be checked.
2515  * This must be a read/write buffer of length \p buflen Bytes.
2516  * \param buflen The length of \p buf in Bytes.
2517  *
2518  * \note This routine only checks whether the provided buffer begins
2519  * with a valid and authentic record that has not been seen
2520  * before, but does not check potential data following the
2521  * initial record. In particular, it is possible to pass DTLS
2522  * datagrams containing multiple records, in which case only
2523  * the first record is checked.
2524  *
2525  * \note This function modifies the input buffer \p buf. If you need
2526  * to preserve the original record, you have to maintain a copy.
2527  *
2528  * \return \c 0 if the record is valid and authentic and has not been
2529  * seen before.
2530  * \return MBEDTLS_ERR_SSL_INVALID_MAC if the check completed
2531  * successfully but the record was found to be not authentic.
2532  * \return MBEDTLS_ERR_SSL_INVALID_RECORD if the check completed
2533  * successfully but the record was found to be invalid for
2534  * a reason different from authenticity checking.
2535  * \return MBEDTLS_ERR_SSL_UNEXPECTED_RECORD if the check completed
2536  * successfully but the record was found to be unexpected
2537  * in the state of the SSL context, including replayed records.
2538  * \return Another negative error code on different kinds of failure.
2539  * In this case, the SSL context becomes unusable and needs
2540  * to be freed or reset before reuse.
2541  */
2543  unsigned char *buf,
2544  size_t buflen);
2545 
2546 /**
2547  * \brief Set the timer callbacks (Mandatory for DTLS.)
2548  *
2549  * \param ssl SSL context
2550  * \param p_timer parameter (context) shared by timer callbacks
2551  * \param f_set_timer set timer callback
2552  * \param f_get_timer get timer callback. Must return:
2553  *
2554  * \note See the documentation of \c mbedtls_ssl_set_timer_t and
2555  * \c mbedtls_ssl_get_timer_t for the conventions this pair of
2556  * callbacks must follow.
2557  *
2558  * \note On some platforms, timing.c provides
2559  * \c mbedtls_timing_set_delay() and
2560  * \c mbedtls_timing_get_delay() that are suitable for using
2561  * here, except if using an event-driven style.
2562  *
2563  * \note See also the "DTLS tutorial" article in our knowledge base.
2564  * https://mbed-tls.readthedocs.io/en/latest/kb/how-to/dtls-tutorial
2565  */
2567  void *p_timer,
2568  mbedtls_ssl_set_timer_t *f_set_timer,
2569  mbedtls_ssl_get_timer_t *f_get_timer);
2570 
2571 #if defined(MBEDTLS_SSL_SRV_C)
2572 /**
2573  * \brief Set the certificate selection callback (server-side only).
2574  *
2575  * If set, the callback is always called for each handshake,
2576  * after `ClientHello` processing has finished.
2577  *
2578  * \param conf The SSL configuration to register the callback with.
2579  * \param f_cert_cb The callback for selecting server certificate after
2580  * `ClientHello` processing has finished.
2581  */
2582 static inline void mbedtls_ssl_conf_cert_cb(mbedtls_ssl_config *conf,
2583  mbedtls_ssl_hs_cb_t f_cert_cb)
2584 {
2585  conf->MBEDTLS_PRIVATE(f_cert_cb) = f_cert_cb;
2586 }
2587 #endif /* MBEDTLS_SSL_SRV_C */
2588 
2589 /**
2590  * \brief Callback type: generate and write session ticket
2591  *
2592  * \note This describes what a callback implementation should do.
2593  * This callback should generate an encrypted and
2594  * authenticated ticket for the session and write it to the
2595  * output buffer. Here, ticket means the opaque ticket part
2596  * of the NewSessionTicket structure of RFC 5077.
2597  *
2598  * \param p_ticket Context for the callback
2599  * \param session SSL session to be written in the ticket
2600  * \param start Start of the output buffer
2601  * \param end End of the output buffer
2602  * \param tlen On exit, holds the length written
2603  * \param lifetime On exit, holds the lifetime of the ticket in seconds
2604  *
2605  * \return 0 if successful, or
2606  * a specific MBEDTLS_ERR_XXX code.
2607  */
2608 typedef int mbedtls_ssl_ticket_write_t(void *p_ticket,
2609  const mbedtls_ssl_session *session,
2610  unsigned char *start,
2611  const unsigned char *end,
2612  size_t *tlen,
2613  uint32_t *lifetime);
2614 
2615 /**
2616  * \brief Callback type: parse and load session ticket
2617  *
2618  * \note This describes what a callback implementation should do.
2619  * This callback should parse a session ticket as generated
2620  * by the corresponding mbedtls_ssl_ticket_write_t function,
2621  * and, if the ticket is authentic and valid, load the
2622  * session.
2623  *
2624  * \note The implementation is allowed to modify the first len
2625  * bytes of the input buffer, eg to use it as a temporary
2626  * area for the decrypted ticket contents.
2627  *
2628  * \param p_ticket Context for the callback
2629  * \param session SSL session to be loaded
2630  * \param buf Start of the buffer containing the ticket
2631  * \param len Length of the ticket.
2632  *
2633  * \return 0 if successful, or
2634  * MBEDTLS_ERR_SSL_INVALID_MAC if not authentic, or
2635  * MBEDTLS_ERR_SSL_SESSION_TICKET_EXPIRED if expired, or
2636  * any other non-zero code for other failures.
2637  */
2638 typedef int mbedtls_ssl_ticket_parse_t(void *p_ticket,
2639  mbedtls_ssl_session *session,
2640  unsigned char *buf,
2641  size_t len);
2642 
2643 #if defined(MBEDTLS_SSL_SESSION_TICKETS) && defined(MBEDTLS_SSL_SRV_C)
2644 /**
2645  * \brief Configure SSL session ticket callbacks (server only).
2646  * (Default: none.)
2647  *
2648  * \note On server, session tickets are enabled by providing
2649  * non-NULL callbacks.
2650  *
2651  * \note On client, use \c mbedtls_ssl_conf_session_tickets().
2652  *
2653  * \param conf SSL configuration context
2654  * \param f_ticket_write Callback for writing a ticket
2655  * \param f_ticket_parse Callback for parsing a ticket
2656  * \param p_ticket Context shared by the two callbacks
2657  */
2659  mbedtls_ssl_ticket_write_t *f_ticket_write,
2660  mbedtls_ssl_ticket_parse_t *f_ticket_parse,
2661  void *p_ticket);
2662 
2663 #if defined(MBEDTLS_HAVE_TIME)
2664 /**
2665  * \brief Get the creation time of a session ticket.
2666  *
2667  * \note See the documentation of \c ticket_creation_time for information about
2668  * the intended usage of this function.
2669  *
2670  * \param session SSL session
2671  * \param ticket_creation_time On exit, holds the ticket creation time in
2672  * milliseconds.
2673  *
2674  * \return 0 on success,
2675  * MBEDTLS_ERR_SSL_BAD_INPUT_DATA if an input is not valid.
2676  */
2677 static inline int mbedtls_ssl_session_get_ticket_creation_time(
2678  mbedtls_ssl_session *session, mbedtls_ms_time_t *ticket_creation_time)
2679 {
2680  if (session == NULL || ticket_creation_time == NULL ||
2681  session->MBEDTLS_PRIVATE(endpoint) != MBEDTLS_SSL_IS_SERVER) {
2683  }
2684 
2685  *ticket_creation_time = session->MBEDTLS_PRIVATE(ticket_creation_time);
2686 
2687  return 0;
2688 }
2689 #endif /* MBEDTLS_HAVE_TIME */
2690 #endif /* MBEDTLS_SSL_SESSION_TICKETS && MBEDTLS_SSL_SRV_C */
2691 
2692 /**
2693  * \brief Get the session-id buffer.
2694  *
2695  * \param session SSL session.
2696  *
2697  * \return The address of the session-id buffer.
2698  */
2699 static inline unsigned const char (*mbedtls_ssl_session_get_id(const mbedtls_ssl_session *
2700  session))[32]
2701 {
2702  return &session->MBEDTLS_PRIVATE(id);
2703 }
2704 
2705 /**
2706  * \brief Get the size of the session-id.
2707  *
2708  * \param session SSL session.
2709  *
2710  * \return size_t size of session-id buffer.
2711  */
2712 static inline size_t mbedtls_ssl_session_get_id_len(const mbedtls_ssl_session *session)
2713 {
2714  return session->MBEDTLS_PRIVATE(id_len);
2715 }
2716 
2717 /**
2718  * \brief Get the ciphersuite-id.
2719  *
2720  * \param session SSL session.
2721  *
2722  * \return int represetation for ciphersuite.
2723  */
2725 {
2726  return session->MBEDTLS_PRIVATE(ciphersuite);
2727 }
2728 
2729 /**
2730  * \brief Configure a key export callback.
2731  * (Default: none.)
2732  *
2733  * This API can be used for two purposes:
2734  * - Debugging: Use this API to e.g. generate an NSSKeylog
2735  * file and use it to inspect encrypted traffic in tools
2736  * such as Wireshark.
2737  * - Application-specific export: Use this API to implement
2738  * key exporters, e.g. for EAP-TLS or DTLS-SRTP.
2739  *
2740  *
2741  * \param ssl The SSL context to which the export
2742  * callback should be attached.
2743  * \param f_export_keys The callback for the key export.
2744  * \param p_export_keys The opaque context pointer to be passed to the
2745  * callback \p f_export_keys.
2746  */
2748  mbedtls_ssl_export_keys_t *f_export_keys,
2749  void *p_export_keys);
2750 
2751 /** \brief Set the user data in an SSL configuration to a pointer.
2752  *
2753  * You can retrieve this value later with mbedtls_ssl_conf_get_user_data_p().
2754  *
2755  * \note The library stores \c p without accessing it. It is the responsibility
2756  * of the caller to ensure that the pointer remains valid.
2757  *
2758  * \param conf The SSL configuration context to modify.
2759  * \param p The new value of the user data.
2760  */
2762  mbedtls_ssl_config *conf,
2763  void *p)
2764 {
2765  conf->MBEDTLS_PRIVATE(user_data).p = p;
2766 }
2767 
2768 /** \brief Set the user data in an SSL configuration to an integer.
2769  *
2770  * You can retrieve this value later with mbedtls_ssl_conf_get_user_data_n().
2771  *
2772  * \param conf The SSL configuration context to modify.
2773  * \param n The new value of the user data.
2774  */
2776  mbedtls_ssl_config *conf,
2777  uintptr_t n)
2778 {
2779  conf->MBEDTLS_PRIVATE(user_data).n = n;
2780 }
2781 
2782 /** \brief Retrieve the user data in an SSL configuration as a pointer.
2783  *
2784  * This is the value last set with mbedtls_ssl_conf_set_user_data_p(), or
2785  * \c NULL if mbedtls_ssl_conf_set_user_data_p() has not previously been
2786  * called. The value is undefined if mbedtls_ssl_conf_set_user_data_n() has
2787  * been called without a subsequent call to mbedtls_ssl_conf_set_user_data_p().
2788  *
2789  * \param conf The SSL configuration context to modify.
2790  * \return The current value of the user data.
2791  */
2793  mbedtls_ssl_config *conf)
2794 {
2795  return conf->MBEDTLS_PRIVATE(user_data).p;
2796 }
2797 
2798 /** \brief Retrieve the user data in an SSL configuration as an integer.
2799  *
2800  * This is the value last set with mbedtls_ssl_conf_set_user_data_n(), or
2801  * \c 0 if mbedtls_ssl_conf_set_user_data_n() has not previously been
2802  * called. The value is undefined if mbedtls_ssl_conf_set_user_data_p() has
2803  * been called without a subsequent call to mbedtls_ssl_conf_set_user_data_n().
2804  *
2805  * \param conf The SSL configuration context to modify.
2806  * \return The current value of the user data.
2807  */
2809  mbedtls_ssl_config *conf)
2810 {
2811  return conf->MBEDTLS_PRIVATE(user_data).n;
2812 }
2813 
2814 /** \brief Set the user data in an SSL context to a pointer.
2815  *
2816  * You can retrieve this value later with mbedtls_ssl_get_user_data_p().
2817  *
2818  * \note The library stores \c p without accessing it. It is the responsibility
2819  * of the caller to ensure that the pointer remains valid.
2820  *
2821  * \param ssl The SSL context to modify.
2822  * \param p The new value of the user data.
2823  */
2824 static inline void mbedtls_ssl_set_user_data_p(
2825  mbedtls_ssl_context *ssl,
2826  void *p)
2827 {
2828  ssl->MBEDTLS_PRIVATE(user_data).p = p;
2829 }
2830 
2831 /** \brief Set the user data in an SSL context to an integer.
2832  *
2833  * You can retrieve this value later with mbedtls_ssl_get_user_data_n().
2834  *
2835  * \param ssl The SSL context to modify.
2836  * \param n The new value of the user data.
2837  */
2838 static inline void mbedtls_ssl_set_user_data_n(
2839  mbedtls_ssl_context *ssl,
2840  uintptr_t n)
2841 {
2842  ssl->MBEDTLS_PRIVATE(user_data).n = n;
2843 }
2844 
2845 /** \brief Retrieve the user data in an SSL context as a pointer.
2846  *
2847  * This is the value last set with mbedtls_ssl_set_user_data_p(), or
2848  * \c NULL if mbedtls_ssl_set_user_data_p() has not previously been
2849  * called. The value is undefined if mbedtls_ssl_set_user_data_n() has
2850  * been called without a subsequent call to mbedtls_ssl_set_user_data_p().
2851  *
2852  * \param ssl The SSL context to modify.
2853  * \return The current value of the user data.
2854  */
2855 static inline void *mbedtls_ssl_get_user_data_p(
2856  mbedtls_ssl_context *ssl)
2857 {
2858  return ssl->MBEDTLS_PRIVATE(user_data).p;
2859 }
2860 
2861 /** \brief Retrieve the user data in an SSL context as an integer.
2862  *
2863  * This is the value last set with mbedtls_ssl_set_user_data_n(), or
2864  * \c 0 if mbedtls_ssl_set_user_data_n() has not previously been
2865  * called. The value is undefined if mbedtls_ssl_set_user_data_p() has
2866  * been called without a subsequent call to mbedtls_ssl_set_user_data_n().
2867  *
2868  * \param ssl The SSL context to modify.
2869  * \return The current value of the user data.
2870  */
2872  mbedtls_ssl_context *ssl)
2873 {
2874  return ssl->MBEDTLS_PRIVATE(user_data).n;
2875 }
2876 
2877 #if defined(MBEDTLS_SSL_ASYNC_PRIVATE)
2878 /**
2879  * \brief Configure asynchronous private key operation callbacks.
2880  *
2881  * \param conf SSL configuration context
2882  * \param f_async_sign Callback to start a signature operation. See
2883  * the description of ::mbedtls_ssl_async_sign_t
2884  * for more information. This may be \c NULL if the
2885  * external processor does not support any signature
2886  * operation; in this case the private key object
2887  * associated with the certificate will be used.
2888  * \param f_async_decrypt Callback to start a decryption operation. See
2889  * the description of ::mbedtls_ssl_async_decrypt_t
2890  * for more information. This may be \c NULL if the
2891  * external processor does not support any decryption
2892  * operation; in this case the private key object
2893  * associated with the certificate will be used.
2894  * \param f_async_resume Callback to resume an asynchronous operation. See
2895  * the description of ::mbedtls_ssl_async_resume_t
2896  * for more information. This may not be \c NULL unless
2897  * \p f_async_sign and \p f_async_decrypt are both
2898  * \c NULL.
2899  * \param f_async_cancel Callback to cancel an asynchronous operation. See
2900  * the description of ::mbedtls_ssl_async_cancel_t
2901  * for more information. This may be \c NULL if
2902  * no cleanup is needed.
2903  * \param config_data A pointer to configuration data which can be
2904  * retrieved with
2905  * mbedtls_ssl_conf_get_async_config_data(). The
2906  * library stores this value without dereferencing it.
2907  */
2908 void mbedtls_ssl_conf_async_private_cb(mbedtls_ssl_config *conf,
2909  mbedtls_ssl_async_sign_t *f_async_sign,
2910  mbedtls_ssl_async_decrypt_t *f_async_decrypt,
2911  mbedtls_ssl_async_resume_t *f_async_resume,
2912  mbedtls_ssl_async_cancel_t *f_async_cancel,
2913  void *config_data);
2914 
2915 /**
2916  * \brief Retrieve the configuration data set by
2917  * mbedtls_ssl_conf_async_private_cb().
2918  *
2919  * \param conf SSL configuration context
2920  * \return The configuration data set by
2921  * mbedtls_ssl_conf_async_private_cb().
2922  */
2923 void *mbedtls_ssl_conf_get_async_config_data(const mbedtls_ssl_config *conf);
2924 
2925 /**
2926  * \brief Retrieve the asynchronous operation user context.
2927  *
2928  * \note This function may only be called while a handshake
2929  * is in progress.
2930  *
2931  * \param ssl The SSL context to access.
2932  *
2933  * \return The asynchronous operation user context that was last
2934  * set during the current handshake. If
2935  * mbedtls_ssl_set_async_operation_data() has not yet been
2936  * called during the current handshake, this function returns
2937  * \c NULL.
2938  */
2939 void *mbedtls_ssl_get_async_operation_data(const mbedtls_ssl_context *ssl);
2940 
2941 /**
2942  * \brief Retrieve the asynchronous operation user context.
2943  *
2944  * \note This function may only be called while a handshake
2945  * is in progress.
2946  *
2947  * \param ssl The SSL context to access.
2948  * \param ctx The new value of the asynchronous operation user context.
2949  * Call mbedtls_ssl_get_async_operation_data() later during the
2950  * same handshake to retrieve this value.
2951  */
2952 void mbedtls_ssl_set_async_operation_data(mbedtls_ssl_context *ssl,
2953  void *ctx);
2954 #endif /* MBEDTLS_SSL_ASYNC_PRIVATE */
2955 
2956 /**
2957  * \brief Callback type: generate a cookie
2958  *
2959  * \param ctx Context for the callback
2960  * \param p Buffer to write to,
2961  * must be updated to point right after the cookie
2962  * \param end Pointer to one past the end of the output buffer
2963  * \param info Client ID info that was passed to
2964  * \c mbedtls_ssl_set_client_transport_id()
2965  * \param ilen Length of info in bytes
2966  *
2967  * \return The callback must return 0 on success,
2968  * or a negative error code.
2969  */
2971  unsigned char **p, unsigned char *end,
2972  const unsigned char *info, size_t ilen);
2973 
2974 /**
2975  * \brief Callback type: verify a cookie
2976  *
2977  * \param ctx Context for the callback
2978  * \param cookie Cookie to verify
2979  * \param clen Length of cookie
2980  * \param info Client ID info that was passed to
2981  * \c mbedtls_ssl_set_client_transport_id()
2982  * \param ilen Length of info in bytes
2983  *
2984  * \return The callback must return 0 if cookie is valid,
2985  * or a negative error code.
2986  */
2988  const unsigned char *cookie, size_t clen,
2989  const unsigned char *info, size_t ilen);
2990 
2991 #if defined(MBEDTLS_SSL_DTLS_HELLO_VERIFY) && defined(MBEDTLS_SSL_SRV_C)
2992 /**
2993  * \brief Register callbacks for DTLS cookies
2994  * (Server only. DTLS only.)
2995  *
2996  * Default: dummy callbacks that fail, in order to force you to
2997  * register working callbacks (and initialize their context).
2998  *
2999  * To disable HelloVerifyRequest, register NULL callbacks.
3000  *
3001  * \warning Disabling hello verification allows your server to be used
3002  * for amplification in DoS attacks against other hosts.
3003  * Only disable if you known this can't happen in your
3004  * particular environment.
3005  *
3006  * \note See comments on \c mbedtls_ssl_handshake() about handling
3007  * the MBEDTLS_ERR_SSL_HELLO_VERIFY_REQUIRED that is expected
3008  * on the first handshake attempt when this is enabled.
3009  *
3010  * \note This is also necessary to handle client reconnection from
3011  * the same port as described in RFC 6347 section 4.2.8 (only
3012  * the variant with cookies is supported currently). See
3013  * comments on \c mbedtls_ssl_read() for details.
3014  *
3015  * \param conf SSL configuration
3016  * \param f_cookie_write Cookie write callback
3017  * \param f_cookie_check Cookie check callback
3018  * \param p_cookie Context for both callbacks
3019  */
3021  mbedtls_ssl_cookie_write_t *f_cookie_write,
3022  mbedtls_ssl_cookie_check_t *f_cookie_check,
3023  void *p_cookie);
3024 
3025 /**
3026  * \brief Set client's transport-level identification info.
3027  * (Server only. DTLS only.)
3028  *
3029  * This is usually the IP address (and port), but could be
3030  * anything identify the client depending on the underlying
3031  * network stack. Used for HelloVerifyRequest with DTLS.
3032  * This is *not* used to route the actual packets.
3033  *
3034  * \param ssl SSL context
3035  * \param info Transport-level info identifying the client (eg IP + port)
3036  * \param ilen Length of info in bytes
3037  *
3038  * \note An internal copy is made, so the info buffer can be reused.
3039  *
3040  * \return 0 on success,
3041  * MBEDTLS_ERR_SSL_BAD_INPUT_DATA if used on client,
3042  * MBEDTLS_ERR_SSL_ALLOC_FAILED if out of memory.
3043  */
3045  const unsigned char *info,
3046  size_t ilen);
3047 
3048 #endif /* MBEDTLS_SSL_DTLS_HELLO_VERIFY && MBEDTLS_SSL_SRV_C */
3049 
3050 #if defined(MBEDTLS_SSL_DTLS_ANTI_REPLAY)
3051 /**
3052  * \brief Enable or disable anti-replay protection for DTLS.
3053  * (DTLS only, no effect on TLS.)
3054  * Default: enabled.
3055  *
3056  * \param conf SSL configuration
3057  * \param mode MBEDTLS_SSL_ANTI_REPLAY_ENABLED or MBEDTLS_SSL_ANTI_REPLAY_DISABLED.
3058  *
3059  * \warning Disabling this is a security risk unless the application
3060  * protocol handles duplicated packets in a safe way. You
3061  * should not disable this without careful consideration.
3062  * However, if your application already detects duplicated
3063  * packets and needs information about them to adjust its
3064  * transmission strategy, then you'll want to disable this.
3065  */
3067 #endif /* MBEDTLS_SSL_DTLS_ANTI_REPLAY */
3068 
3069 /**
3070  * \brief Set a limit on the number of records with a bad MAC
3071  * before terminating the connection.
3072  * (DTLS only, no effect on TLS.)
3073  * Default: 0 (disabled).
3074  *
3075  * \param conf SSL configuration
3076  * \param limit Limit, or 0 to disable.
3077  *
3078  * \note If the limit is N, then the connection is terminated when
3079  * the Nth non-authentic record is seen.
3080  *
3081  * \note Records with an invalid header are not counted, only the
3082  * ones going through the authentication-decryption phase.
3083  *
3084  * \note This is a security trade-off related to the fact that it's
3085  * often relatively easy for an active attacker to inject UDP
3086  * datagrams. On one hand, setting a low limit here makes it
3087  * easier for such an attacker to forcibly terminated a
3088  * connection. On the other hand, a high limit or no limit
3089  * might make us waste resources checking authentication on
3090  * many bogus packets.
3091  */
3093 
3094 #if defined(MBEDTLS_SSL_PROTO_DTLS)
3095 
3096 /**
3097  * \brief Allow or disallow packing of multiple handshake records
3098  * within a single datagram.
3099  *
3100  * \param ssl The SSL context to configure.
3101  * \param allow_packing This determines whether datagram packing may
3102  * be used or not. A value of \c 0 means that every
3103  * record will be sent in a separate datagram; a
3104  * value of \c 1 means that, if space permits,
3105  * multiple handshake messages (including CCS) belonging to
3106  * a single flight may be packed within a single datagram.
3107  *
3108  * \note This is enabled by default and should only be disabled
3109  * for test purposes, or if datagram packing causes
3110  * interoperability issues with peers that don't support it.
3111  *
3112  * \note Allowing datagram packing reduces the network load since
3113  * there's less overhead if multiple messages share the same
3114  * datagram. Also, it increases the handshake efficiency
3115  * since messages belonging to a single datagram will not
3116  * be reordered in transit, and so future message buffering
3117  * or flight retransmission (if no buffering is used) as
3118  * means to deal with reordering are needed less frequently.
3119  *
3120  * \note Application records are not affected by this option and
3121  * are currently always sent in separate datagrams.
3122  *
3123  */
3125  unsigned allow_packing);
3126 
3127 /**
3128  * \brief Set retransmit timeout values for the DTLS handshake.
3129  * (DTLS only, no effect on TLS.)
3130  *
3131  * \param conf SSL configuration
3132  * \param min Initial timeout value in milliseconds.
3133  * Default: 1000 (1 second).
3134  * \param max Maximum timeout value in milliseconds.
3135  * Default: 60000 (60 seconds).
3136  *
3137  * \note Default values are from RFC 6347 section 4.2.4.1.
3138  *
3139  * \note The 'min' value should typically be slightly above the
3140  * expected round-trip time to your peer, plus whatever time
3141  * it takes for the peer to process the message. For example,
3142  * if your RTT is about 600ms and you peer needs up to 1s to
3143  * do the cryptographic operations in the handshake, then you
3144  * should set 'min' slightly above 1600. Lower values of 'min'
3145  * might cause spurious resends which waste network resources,
3146  * while larger value of 'min' will increase overall latency
3147  * on unreliable network links.
3148  *
3149  * \note The more unreliable your network connection is, the larger
3150  * your max / min ratio needs to be in order to achieve
3151  * reliable handshakes.
3152  *
3153  * \note Messages are retransmitted up to log2(ceil(max/min)) times.
3154  * For example, if min = 1s and max = 5s, the retransmit plan
3155  * goes: send ... 1s -> resend ... 2s -> resend ... 4s ->
3156  * resend ... 5s -> give up and return a timeout error.
3157  */
3159 #endif /* MBEDTLS_SSL_PROTO_DTLS */
3160 
3161 #if defined(MBEDTLS_SSL_SRV_C)
3162 /**
3163  * \brief Set the session cache callbacks (server-side only)
3164  * If not set, no session resuming is done (except if session
3165  * tickets are enabled too).
3166  *
3167  * The session cache has the responsibility to check for stale
3168  * entries based on timeout. See RFC 5246 for recommendations.
3169  *
3170  * Warning: session.peer_cert is cleared by the SSL/TLS layer on
3171  * connection shutdown, so do not cache the pointer! Either set
3172  * it to NULL or make a full copy of the certificate.
3173  *
3174  * The get callback is called once during the initial handshake
3175  * to enable session resuming. The get function has the
3176  * following parameters: (void *parameter, mbedtls_ssl_session *session)
3177  * If a valid entry is found, it should fill the master of
3178  * the session object with the cached values and return 0,
3179  * return 1 otherwise. Optionally peer_cert can be set as well
3180  * if it is properly present in cache entry.
3181  *
3182  * The set callback is called once during the initial handshake
3183  * to enable session resuming after the entire handshake has
3184  * been finished. The set function has the following parameters:
3185  * (void *parameter, const mbedtls_ssl_session *session). The function
3186  * should create a cache entry for future retrieval based on
3187  * the data in the session structure and should keep in mind
3188  * that the mbedtls_ssl_session object presented (and all its referenced
3189  * data) is cleared by the SSL/TLS layer when the connection is
3190  * terminated. It is recommended to add metadata to determine if
3191  * an entry is still valid in the future. Return 0 if
3192  * successfully cached, return 1 otherwise.
3193  *
3194  * \param conf SSL configuration
3195  * \param p_cache parameter (context) for both callbacks
3196  * \param f_get_cache session get callback
3197  * \param f_set_cache session set callback
3198  */
3200  void *p_cache,
3201  mbedtls_ssl_cache_get_t *f_get_cache,
3202  mbedtls_ssl_cache_set_t *f_set_cache);
3203 #endif /* MBEDTLS_SSL_SRV_C */
3204 
3205 #if defined(MBEDTLS_SSL_CLI_C)
3206 /**
3207  * \brief Load a session for session resumption.
3208  *
3209  * Sessions loaded through this call will be considered
3210  * for session resumption in the next handshake.
3211  *
3212  * \note Even if this call succeeds, it is not guaranteed that
3213  * the next handshake will indeed be shortened through the
3214  * use of session resumption: The server is always free
3215  * to reject any attempt for resumption and fall back to
3216  * a full handshake.
3217  *
3218  * \note This function can handle a variety of mechanisms for session
3219  * resumption: For TLS 1.2, both session ID-based resumption and
3220  * ticket-based resumption will be considered. For TLS 1.3,
3221  * once implemented, sessions equate to tickets, and loading
3222  * one or more sessions via this call will lead to their
3223  * corresponding tickets being advertised as resumption PSKs
3224  * by the client.
3225  *
3226  * \note Calling this function multiple times will only be useful
3227  * once TLS 1.3 is supported. For TLS 1.2 connections, this
3228  * function should be called at most once.
3229  *
3230  * \param ssl The SSL context representing the connection which should
3231  * be attempted to be setup using session resumption. This
3232  * must be initialized via mbedtls_ssl_init() and bound to
3233  * an SSL configuration via mbedtls_ssl_setup(), but
3234  * the handshake must not yet have been started.
3235  * \param session The session to be considered for session resumption.
3236  * This must be a session previously exported via
3237  * mbedtls_ssl_get_session(), and potentially serialized and
3238  * deserialized through mbedtls_ssl_session_save() and
3239  * mbedtls_ssl_session_load() in the meantime.
3240  *
3241  * \return \c 0 if successful.
3242  * \return \c MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE if the session
3243  * could not be loaded because of an implementation limitation.
3244  * This error is non-fatal, and has no observable effect on
3245  * the SSL context or the session that was attempted to be loaded.
3246  * \return Another negative error code on other kinds of failure.
3247  *
3248  * \sa mbedtls_ssl_get_session()
3249  * \sa mbedtls_ssl_session_load()
3250  */
3252 #endif /* MBEDTLS_SSL_CLI_C */
3253 
3254 /**
3255  * \brief Load serialized session data into a session structure.
3256  * On client, this can be used for loading saved sessions
3257  * before resuming them with mbedtls_ssl_set_session().
3258  * On server, this can be used for alternative implementations
3259  * of session cache or session tickets.
3260  *
3261  * \warning If a peer certificate chain is associated with the session,
3262  * the serialized state will only contain the peer's
3263  * end-entity certificate and the result of the chain
3264  * verification (unless verification was disabled), but not
3265  * the rest of the chain.
3266  *
3267  * \see mbedtls_ssl_session_save()
3268  * \see mbedtls_ssl_set_session()
3269  *
3270  * \param session The session structure to be populated. It must have been
3271  * initialised with mbedtls_ssl_session_init() but not
3272  * populated yet.
3273  * \param buf The buffer holding the serialized session data. It must be a
3274  * readable buffer of at least \p len bytes.
3275  * \param len The size of the serialized data in bytes.
3276  *
3277  * \return \c 0 if successful.
3278  * \return #MBEDTLS_ERR_SSL_ALLOC_FAILED if memory allocation failed.
3279  * \return #MBEDTLS_ERR_SSL_BAD_INPUT_DATA if input data is invalid.
3280  * \return #MBEDTLS_ERR_SSL_VERSION_MISMATCH if the serialized data
3281  * was generated in a different version or configuration of
3282  * Mbed TLS.
3283  * \return Another negative value for other kinds of errors (for
3284  * example, unsupported features in the embedded certificate).
3285  */
3287  const unsigned char *buf,
3288  size_t len);
3289 
3290 /**
3291  * \brief Save session structure as serialized data in a buffer.
3292  * On client, this can be used for saving session data,
3293  * potentially in non-volatile storage, for resuming later.
3294  * On server, this can be used for alternative implementations
3295  * of session cache or session tickets.
3296  *
3297  * \see mbedtls_ssl_session_load()
3298  *
3299  * \param session The session structure to be saved.
3300  * \param buf The buffer to write the serialized data to. It must be a
3301  * writeable buffer of at least \p buf_len bytes, or may be \c
3302  * NULL if \p buf_len is \c 0.
3303  * \param buf_len The number of bytes available for writing in \p buf.
3304  * \param olen The size in bytes of the data that has been or would have
3305  * been written. It must point to a valid \c size_t.
3306  *
3307  * \note \p olen is updated to the correct value regardless of
3308  * whether \p buf_len was large enough. This makes it possible
3309  * to determine the necessary size by calling this function
3310  * with \p buf set to \c NULL and \p buf_len to \c 0.
3311  *
3312  * \return \c 0 if successful.
3313  * \return #MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL if \p buf is too small.
3314  */
3316  unsigned char *buf,
3317  size_t buf_len,
3318  size_t *olen);
3319 
3320 /**
3321  * \brief Set the list of allowed ciphersuites and the preference
3322  * order. First in the list has the highest preference.
3323  *
3324  * For TLS 1.2, the notion of ciphersuite determines both
3325  * the key exchange mechanism and the suite of symmetric
3326  * algorithms to be used during and after the handshake.
3327  *
3328  * For TLS 1.3 (in development), the notion of ciphersuite
3329  * only determines the suite of symmetric algorithms to be
3330  * used during and after the handshake, while key exchange
3331  * mechanisms are configured separately.
3332  *
3333  * In Mbed TLS, ciphersuites for both TLS 1.2 and TLS 1.3
3334  * are configured via this function. For users of TLS 1.3,
3335  * there will be separate API for the configuration of key
3336  * exchange mechanisms.
3337  *
3338  * The list of ciphersuites passed to this function may
3339  * contain a mixture of TLS 1.2 and TLS 1.3 ciphersuite
3340  * identifiers. This is useful if negotiation of TLS 1.3
3341  * should be attempted, but a fallback to TLS 1.2 would
3342  * be tolerated.
3343  *
3344  * \note By default, the server chooses its preferred
3345  * ciphersuite among those that the client supports. If
3346  * mbedtls_ssl_conf_preference_order() is called to prefer
3347  * the client's preferences, the server instead chooses
3348  * the client's preferred ciphersuite among those that
3349  * the server supports.
3350  *
3351  * \warning The ciphersuites array \p ciphersuites is not copied.
3352  * It must remain valid for the lifetime of the SSL
3353  * configuration \p conf.
3354  *
3355  * \param conf The SSL configuration to modify.
3356  * \param ciphersuites A 0-terminated list of IANA identifiers of supported
3357  * ciphersuites, accessible through \c MBEDTLS_TLS_XXX
3358  * and \c MBEDTLS_TLS1_3_XXX macros defined in
3359  * ssl_ciphersuites.h.
3360  */
3362  const int *ciphersuites);
3363 
3364 #if defined(MBEDTLS_SSL_PROTO_TLS1_3)
3365 /**
3366  * \brief Set the supported key exchange modes for TLS 1.3 connections.
3367  *
3368  * In contrast to TLS 1.2, the ciphersuite concept in TLS 1.3 does not
3369  * include the choice of key exchange mechanism. It is therefore not
3370  * covered by the API mbedtls_ssl_conf_ciphersuites(). See the
3371  * documentation of mbedtls_ssl_conf_ciphersuites() for more
3372  * information on the ciphersuite concept in TLS 1.2 and TLS 1.3.
3373  *
3374  * The present function is specific to TLS 1.3 and allows users to
3375  * configure the set of supported key exchange mechanisms in TLS 1.3.
3376  *
3377  * \param conf The SSL configuration the change should apply to.
3378  * \param kex_modes A bitwise combination of one or more of the following:
3379  * - MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK
3380  * This flag enables pure-PSK key exchanges.
3381  * - MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_EPHEMERAL
3382  * This flag enables combined PSK-ephemeral key exchanges.
3383  * - MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_EPHEMERAL
3384  * This flag enables pure-ephemeral key exchanges.
3385  * For convenience, the following pre-defined macros are
3386  * available for combinations of the above:
3387  * - MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_ALL
3388  * Includes all of pure-PSK, PSK-ephemeral and pure-ephemeral.
3389  * - MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_ALL
3390  * Includes both pure-PSK and combined PSK-ephemeral
3391  * key exchanges, but excludes pure-ephemeral key exchanges.
3392  * - MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_EPHEMERAL_ALL
3393  * Includes both pure-ephemeral and combined PSK-ephemeral
3394  * key exchanges.
3395  *
3396  * \note If a PSK-based key exchange mode shall be supported, applications
3397  * must also use the APIs mbedtls_ssl_conf_psk() or
3398  * mbedtls_ssl_conf_psk_cb() or mbedtls_ssl_conf_psk_opaque()
3399  * to configure the PSKs to be used.
3400  *
3401  * \note If a pure-ephemeral key exchange mode shall be supported,
3402  * server-side applications must also provide a certificate via
3403  * mbedtls_ssl_conf_own_cert().
3404  *
3405  */
3406 
3408  const int kex_modes);
3409 #endif /* MBEDTLS_SSL_PROTO_TLS1_3 */
3410 
3411 #if defined(MBEDTLS_SSL_DTLS_CONNECTION_ID)
3412 #define MBEDTLS_SSL_UNEXPECTED_CID_IGNORE 0
3413 #define MBEDTLS_SSL_UNEXPECTED_CID_FAIL 1
3414 /**
3415  * \brief Specify the length of Connection IDs for incoming
3416  * encrypted DTLS records, as well as the behaviour
3417  * on unexpected CIDs.
3418  *
3419  * By default, the CID length is set to \c 0,
3420  * and unexpected CIDs are silently ignored.
3421  *
3422  * \param conf The SSL configuration to modify.
3423  * \param len The length in Bytes of the CID fields in encrypted
3424  * DTLS records using the CID mechanism. This must
3425  * not be larger than #MBEDTLS_SSL_CID_OUT_LEN_MAX.
3426  * \param ignore_other_cids This determines the stack's behaviour when
3427  * receiving a record with an unexpected CID.
3428  * Possible values are:
3429  * - #MBEDTLS_SSL_UNEXPECTED_CID_IGNORE
3430  * In this case, the record is silently ignored.
3431  * - #MBEDTLS_SSL_UNEXPECTED_CID_FAIL
3432  * In this case, the stack fails with the specific
3433  * error code #MBEDTLS_ERR_SSL_UNEXPECTED_CID.
3434  *
3435  * \note The CID specification allows implementations to either
3436  * use a common length for all incoming connection IDs or
3437  * allow variable-length incoming IDs. Mbed TLS currently
3438  * requires a common length for all connections sharing the
3439  * same SSL configuration; this allows simpler parsing of
3440  * record headers.
3441  *
3442  * \return \c 0 on success.
3443  * \return #MBEDTLS_ERR_SSL_BAD_INPUT_DATA if \p len
3444  * is too large.
3445  */
3446 int mbedtls_ssl_conf_cid(mbedtls_ssl_config *conf, size_t len,
3447  int ignore_other_cids);
3448 #endif /* MBEDTLS_SSL_DTLS_CONNECTION_ID */
3449 
3450 #if defined(MBEDTLS_X509_CRT_PARSE_C)
3451 /**
3452  * \brief Set the X.509 security profile used for verification
3453  *
3454  * \note The restrictions are enforced for all certificates in the
3455  * chain. However, signatures in the handshake are not covered
3456  * by this setting but by \b mbedtls_ssl_conf_sig_hashes().
3457  *
3458  * \param conf SSL configuration
3459  * \param profile Profile to use
3460  */
3462  const mbedtls_x509_crt_profile *profile);
3463 
3464 /**
3465  * \brief Set the data required to verify peer certificate
3466  *
3467  * \note See \c mbedtls_x509_crt_verify() for notes regarding the
3468  * parameters ca_chain (maps to trust_ca for that function)
3469  * and ca_crl.
3470  *
3471  * \param conf SSL configuration
3472  * \param ca_chain trusted CA chain (meaning all fully trusted top-level CAs)
3473  * \param ca_crl trusted CA CRLs
3474  */
3476  mbedtls_x509_crt *ca_chain,
3477  mbedtls_x509_crl *ca_crl);
3478 
3479 #if defined(MBEDTLS_KEY_EXCHANGE_CERT_REQ_ALLOWED_ENABLED)
3480 /**
3481  * \brief Set DN hints sent to client in CertificateRequest message
3482  *
3483  * \note If not set, subject distinguished names (DNs) are taken
3484  * from \c mbedtls_ssl_conf_ca_chain()
3485  * or \c mbedtls_ssl_set_hs_ca_chain())
3486  *
3487  * \param conf SSL configuration
3488  * \param crt crt chain whose subject DNs are issuer DNs of client certs
3489  * from which the client should select client peer certificate.
3490  */
3491 static inline
3492 void mbedtls_ssl_conf_dn_hints(mbedtls_ssl_config *conf,
3493  const mbedtls_x509_crt *crt)
3494 {
3495  conf->MBEDTLS_PRIVATE(dn_hints) = crt;
3496 }
3497 #endif /* MBEDTLS_KEY_EXCHANGE_CERT_REQ_ALLOWED_ENABLED */
3498 
3499 #if defined(MBEDTLS_X509_TRUSTED_CERTIFICATE_CALLBACK)
3500 /**
3501  * \brief Set the trusted certificate callback.
3502  *
3503  * This API allows to register the set of trusted certificates
3504  * through a callback, instead of a linked list as configured
3505  * by mbedtls_ssl_conf_ca_chain().
3506  *
3507  * This is useful for example in contexts where a large number
3508  * of CAs are used, and the inefficiency of maintaining them
3509  * in a linked list cannot be tolerated. It is also useful when
3510  * the set of trusted CAs needs to be modified frequently.
3511  *
3512  * See the documentation of `mbedtls_x509_crt_ca_cb_t` for
3513  * more information.
3514  *
3515  * \param conf The SSL configuration to register the callback with.
3516  * \param f_ca_cb The trusted certificate callback to use when verifying
3517  * certificate chains.
3518  * \param p_ca_cb The context to be passed to \p f_ca_cb (for example,
3519  * a reference to a trusted CA database).
3520  *
3521  * \note This API is incompatible with mbedtls_ssl_conf_ca_chain():
3522  * Any call to this function overwrites the values set through
3523  * earlier calls to mbedtls_ssl_conf_ca_chain() or
3524  * mbedtls_ssl_conf_ca_cb().
3525  *
3526  * \note This API is incompatible with CA indication in
3527  * CertificateRequest messages: A server-side SSL context which
3528  * is bound to an SSL configuration that uses a CA callback
3529  * configured via mbedtls_ssl_conf_ca_cb(), and which requires
3530  * client authentication, will send an empty CA list in the
3531  * corresponding CertificateRequest message.
3532  *
3533  * \note This API is incompatible with mbedtls_ssl_set_hs_ca_chain():
3534  * If an SSL context is bound to an SSL configuration which uses
3535  * CA callbacks configured via mbedtls_ssl_conf_ca_cb(), then
3536  * calls to mbedtls_ssl_set_hs_ca_chain() have no effect.
3537  *
3538  * \note The use of this API disables the use of restartable ECC
3539  * during X.509 CRT signature verification (but doesn't affect
3540  * other uses).
3541  *
3542  * \warning This API is incompatible with the use of CRLs. Any call to
3543  * mbedtls_ssl_conf_ca_cb() unsets CRLs configured through
3544  * earlier calls to mbedtls_ssl_conf_ca_chain().
3545  *
3546  * \warning In multi-threaded environments, the callback \p f_ca_cb
3547  * must be thread-safe, and it is the user's responsibility
3548  * to guarantee this (for example through a mutex
3549  * contained in the callback context pointed to by \p p_ca_cb).
3550  */
3551 void mbedtls_ssl_conf_ca_cb(mbedtls_ssl_config *conf,
3552  mbedtls_x509_crt_ca_cb_t f_ca_cb,
3553  void *p_ca_cb);
3554 #endif /* MBEDTLS_X509_TRUSTED_CERTIFICATE_CALLBACK */
3555 
3556 /**
3557  * \brief Set own certificate chain and private key
3558  *
3559  * \note own_cert should contain in order from the bottom up your
3560  * certificate chain. The top certificate (self-signed)
3561  * can be omitted.
3562  *
3563  * \note On server, this function can be called multiple times to
3564  * provision more than one cert/key pair (eg one ECDSA, one
3565  * RSA with SHA-256, one RSA with SHA-1). An adequate
3566  * certificate will be selected according to the client's
3567  * advertised capabilities. In case multiple certificates are
3568  * adequate, preference is given to the one set by the first
3569  * call to this function, then second, etc.
3570  *
3571  * \note On client, only the first call has any effect. That is,
3572  * only one client certificate can be provisioned. The
3573  * server's preferences in its CertificateRequest message will
3574  * be ignored and our only cert will be sent regardless of
3575  * whether it matches those preferences - the server can then
3576  * decide what it wants to do with it.
3577  *
3578  * \note The provided \p pk_key needs to match the public key in the
3579  * first certificate in \p own_cert, or all handshakes using
3580  * that certificate will fail. It is your responsibility
3581  * to ensure that; this function will not perform any check.
3582  * You may use mbedtls_pk_check_pair() in order to perform
3583  * this check yourself, but be aware that this function can
3584  * be computationally expensive on some key types.
3585  *
3586  * \param conf SSL configuration
3587  * \param own_cert own public certificate chain
3588  * \param pk_key own private key
3589  *
3590  * \return 0 on success or MBEDTLS_ERR_SSL_ALLOC_FAILED
3591  */
3593  mbedtls_x509_crt *own_cert,
3594  mbedtls_pk_context *pk_key);
3595 #endif /* MBEDTLS_X509_CRT_PARSE_C */
3596 
3597 #if defined(MBEDTLS_SSL_HANDSHAKE_WITH_PSK_ENABLED)
3598 /**
3599  * \brief Configure pre-shared keys (PSKs) and their
3600  * identities to be used in PSK-based ciphersuites.
3601  *
3602  * Only one PSK can be registered, through either
3603  * mbedtls_ssl_conf_psk() or mbedtls_ssl_conf_psk_opaque().
3604  * If you attempt to register more than one PSK, this function
3605  * fails, though this may change in future versions, which
3606  * may add support for multiple PSKs.
3607  *
3608  * \note This is mainly useful for clients. Servers will usually
3609  * want to use \c mbedtls_ssl_conf_psk_cb() instead.
3610  *
3611  * \note A PSK set by \c mbedtls_ssl_set_hs_psk() in the PSK callback
3612  * takes precedence over a PSK configured by this function.
3613  *
3614  * \param conf The SSL configuration to register the PSK with.
3615  * \param psk The pointer to the pre-shared key to use.
3616  * \param psk_len The length of the pre-shared key in bytes.
3617  * \param psk_identity The pointer to the pre-shared key identity.
3618  * \param psk_identity_len The length of the pre-shared key identity
3619  * in bytes.
3620  *
3621  * \note The PSK and its identity are copied internally and
3622  * hence need not be preserved by the caller for the lifetime
3623  * of the SSL configuration.
3624  *
3625  * \return \c 0 if successful.
3626  * \return #MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE if no more PSKs
3627  * can be configured. In this case, the old PSK(s) remain intact.
3628  * \return Another negative error code on other kinds of failure.
3629  */
3631  const unsigned char *psk, size_t psk_len,
3632  const unsigned char *psk_identity, size_t psk_identity_len);
3633 
3634 #if defined(MBEDTLS_USE_PSA_CRYPTO)
3635 /**
3636  * \brief Configure one or more opaque pre-shared keys (PSKs) and
3637  * their identities to be used in PSK-based ciphersuites.
3638  *
3639  * Only one PSK can be registered, through either
3640  * mbedtls_ssl_conf_psk() or mbedtls_ssl_conf_psk_opaque().
3641  * If you attempt to register more than one PSK, this function
3642  * fails, though this may change in future versions, which
3643  * may add support for multiple PSKs.
3644  *
3645  * \note This is mainly useful for clients. Servers will usually
3646  * want to use \c mbedtls_ssl_conf_psk_cb() instead.
3647  *
3648  * \note An opaque PSK set by \c mbedtls_ssl_set_hs_psk_opaque() in
3649  * the PSK callback takes precedence over an opaque PSK
3650  * configured by this function.
3651  *
3652  * \param conf The SSL configuration to register the PSK with.
3653  * \param psk The identifier of the key slot holding the PSK.
3654  * Until \p conf is destroyed or this function is successfully
3655  * called again, the key slot \p psk must be populated with a
3656  * key of type PSA_ALG_CATEGORY_KEY_DERIVATION whose policy
3657  * allows its use for the key derivation algorithm applied
3658  * in the handshake.
3659  * \param psk_identity The pointer to the pre-shared key identity.
3660  * \param psk_identity_len The length of the pre-shared key identity
3661  * in bytes.
3662  *
3663  * \note The PSK identity hint is copied internally and hence need
3664  * not be preserved by the caller for the lifetime of the
3665  * SSL configuration.
3666  *
3667  * \return \c 0 if successful.
3668  * \return #MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE if no more PSKs
3669  * can be configured. In this case, the old PSK(s) remain intact.
3670  * \return Another negative error code on other kinds of failure.
3671  */
3672 int mbedtls_ssl_conf_psk_opaque(mbedtls_ssl_config *conf,
3674  const unsigned char *psk_identity,
3675  size_t psk_identity_len);
3676 #endif /* MBEDTLS_USE_PSA_CRYPTO */
3677 
3678 /**
3679  * \brief Set the pre-shared Key (PSK) for the current handshake.
3680  *
3681  * \note This should only be called inside the PSK callback,
3682  * i.e. the function passed to \c mbedtls_ssl_conf_psk_cb().
3683  *
3684  * \note A PSK set by this function takes precedence over a PSK
3685  * configured by \c mbedtls_ssl_conf_psk().
3686  *
3687  * \param ssl The SSL context to configure a PSK for.
3688  * \param psk The pointer to the pre-shared key.
3689  * \param psk_len The length of the pre-shared key in bytes.
3690  *
3691  * \return \c 0 if successful.
3692  * \return An \c MBEDTLS_ERR_SSL_XXX error code on failure.
3693  */
3695  const unsigned char *psk, size_t psk_len);
3696 
3697 #if defined(MBEDTLS_USE_PSA_CRYPTO)
3698 /**
3699  * \brief Set an opaque pre-shared Key (PSK) for the current handshake.
3700  *
3701  * \note This should only be called inside the PSK callback,
3702  * i.e. the function passed to \c mbedtls_ssl_conf_psk_cb().
3703  *
3704  * \note An opaque PSK set by this function takes precedence over an
3705  * opaque PSK configured by \c mbedtls_ssl_conf_psk_opaque().
3706  *
3707  * \param ssl The SSL context to configure a PSK for.
3708  * \param psk The identifier of the key slot holding the PSK.
3709  * For the duration of the current handshake, the key slot
3710  * must be populated with a key of type
3711  * PSA_ALG_CATEGORY_KEY_DERIVATION whose policy allows its
3712  * use for the key derivation algorithm
3713  * applied in the handshake.
3714  *
3715  * \return \c 0 if successful.
3716  * \return An \c MBEDTLS_ERR_SSL_XXX error code on failure.
3717  */
3718 int mbedtls_ssl_set_hs_psk_opaque(mbedtls_ssl_context *ssl,
3719  mbedtls_svc_key_id_t psk);
3720 #endif /* MBEDTLS_USE_PSA_CRYPTO */
3721 
3722 #if defined(MBEDTLS_SSL_SRV_C)
3723 /**
3724  * \brief Set the PSK callback (server-side only).
3725  *
3726  * If set, the PSK callback is called for each
3727  * handshake where a PSK-based ciphersuite was negotiated.
3728  * The caller provides the identity received and wants to
3729  * receive the actual PSK data and length.
3730  *
3731  * The callback has the following parameters:
3732  * - \c void*: The opaque pointer \p p_psk.
3733  * - \c mbedtls_ssl_context*: The SSL context to which
3734  * the operation applies.
3735  * - \c const unsigned char*: The PSK identity
3736  * selected by the client.
3737  * - \c size_t: The length of the PSK identity
3738  * selected by the client.
3739  *
3740  * If a valid PSK identity is found, the callback should use
3741  * \c mbedtls_ssl_set_hs_psk() or
3742  * \c mbedtls_ssl_set_hs_psk_opaque()
3743  * on the SSL context to set the correct PSK and return \c 0.
3744  * Any other return value will result in a denied PSK identity.
3745  *
3746  * \note A dynamic PSK (i.e. set by the PSK callback) takes
3747  * precedence over a static PSK (i.e. set by
3748  * \c mbedtls_ssl_conf_psk() or
3749  * \c mbedtls_ssl_conf_psk_opaque()).
3750  * This means that if you set a PSK callback using this
3751  * function, you don't need to set a PSK using
3752  * \c mbedtls_ssl_conf_psk() or
3753  * \c mbedtls_ssl_conf_psk_opaque()).
3754  *
3755  * \param conf The SSL configuration to register the callback with.
3756  * \param f_psk The callback for selecting and setting the PSK based
3757  * in the PSK identity chosen by the client.
3758  * \param p_psk A pointer to an opaque structure to be passed to
3759  * the callback, for example a PSK store.
3760  */
3762  int (*f_psk)(void *, mbedtls_ssl_context *, const unsigned char *,
3763  size_t),
3764  void *p_psk);
3765 #endif /* MBEDTLS_SSL_SRV_C */
3766 #endif /* MBEDTLS_SSL_HANDSHAKE_WITH_PSK_ENABLED */
3767 
3768 #if defined(MBEDTLS_DHM_C) && defined(MBEDTLS_SSL_SRV_C)
3769 /**
3770  * \brief Set the Diffie-Hellman public P and G values
3771  * from big-endian binary presentations.
3772  * (Default values: MBEDTLS_DHM_RFC3526_MODP_2048_[PG]_BIN)
3773  *
3774  * \param conf SSL configuration
3775  * \param dhm_P Diffie-Hellman-Merkle modulus in big-endian binary form
3776  * \param P_len Length of DHM modulus
3777  * \param dhm_G Diffie-Hellman-Merkle generator in big-endian binary form
3778  * \param G_len Length of DHM generator
3779  *
3780  * \return 0 if successful
3781  */
3783  const unsigned char *dhm_P, size_t P_len,
3784  const unsigned char *dhm_G, size_t G_len);
3785 
3786 /**
3787  * \brief Set the Diffie-Hellman public P and G values,
3788  * read from existing context (server-side only)
3789  *
3790  * \param conf SSL configuration
3791  * \param dhm_ctx Diffie-Hellman-Merkle context
3792  *
3793  * \return 0 if successful
3794  */
3796 #endif /* MBEDTLS_DHM_C && defined(MBEDTLS_SSL_SRV_C) */
3797 
3798 #if defined(MBEDTLS_DHM_C) && defined(MBEDTLS_SSL_CLI_C)
3799 /**
3800  * \brief Set the minimum length for Diffie-Hellman parameters.
3801  * (Client-side only.)
3802  * (Default: 1024 bits.)
3803  *
3804  * \param conf SSL configuration
3805  * \param bitlen Minimum bit length of the DHM prime
3806  */
3808  unsigned int bitlen);
3809 #endif /* MBEDTLS_DHM_C && MBEDTLS_SSL_CLI_C */
3810 
3811 #if defined(MBEDTLS_ECP_C)
3812 #if !defined(MBEDTLS_DEPRECATED_REMOVED)
3813 /**
3814  * \brief Set the allowed curves in order of preference.
3815  *
3816  * On server: this only affects selection of the ECDHE curve;
3817  * the curves used for ECDH and ECDSA are determined by the
3818  * list of available certificates instead.
3819  *
3820  * On client: this affects the list of curves offered for any
3821  * use. The server can override our preference order.
3822  *
3823  * Both sides: limits the set of curves accepted for use in
3824  * ECDHE and in the peer's end-entity certificate.
3825  *
3826  * \deprecated Superseded by mbedtls_ssl_conf_groups().
3827  *
3828  * \note This has no influence on which curves are allowed inside the
3829  * certificate chains, see \c mbedtls_ssl_conf_cert_profile()
3830  * for that. For the end-entity certificate however, the key
3831  * will be accepted only if it is allowed both by this list
3832  * and by the cert profile.
3833  *
3834  * \note This list should be ordered by decreasing preference
3835  * (preferred curve first).
3836  *
3837  * \note The default list is the same set of curves that
3838  * #mbedtls_x509_crt_profile_default allows, plus
3839  * ECDHE-only curves selected according to the same criteria.
3840  * The order favors curves with the lowest resource usage.
3841  *
3842  * \note New minor versions of Mbed TLS may extend this list,
3843  * for example if new curves are added to the library.
3844  * New minor versions of Mbed TLS will not remove items
3845  * from this list unless serious security concerns require it.
3846  * New minor versions of Mbed TLS may change the order in
3847  * keeping with the general principle of favoring the lowest
3848  * resource usage.
3849  *
3850  * \param conf SSL configuration
3851  * \param curves Ordered list of allowed curves,
3852  * terminated by MBEDTLS_ECP_DP_NONE.
3853  */
3855  const mbedtls_ecp_group_id *curves);
3856 #endif /* MBEDTLS_DEPRECATED_REMOVED */
3857 #endif /* MBEDTLS_ECP_C */
3858 
3859 /**
3860  * \brief Set the allowed groups in order of preference.
3861  *
3862  * On server: This only affects the choice of key agreement mechanism
3863  *
3864  * On client: this affects the list of groups offered for any
3865  * use. The server can override our preference order.
3866  *
3867  * Both sides: limits the set of groups accepted for use in
3868  * key sharing.
3869  *
3870  * \note This function replaces the deprecated mbedtls_ssl_conf_curves(),
3871  * which only allows ECP curves to be configured.
3872  *
3873  * \note The most recent invocation of either mbedtls_ssl_conf_curves()
3874  * or mbedtls_ssl_conf_groups() nullifies all previous invocations
3875  * of both.
3876  *
3877  * \note This list should be ordered by decreasing preference
3878  * (preferred group first).
3879  *
3880  * \note When this function is not called, a default list is used,
3881  * consisting of all supported curves at 255 bits and above,
3882  * and all supported finite fields at 2048 bits and above.
3883  * The order favors groups with the lowest resource usage.
3884  *
3885  * \note New minor versions of Mbed TLS will not remove items
3886  * from the default list unless serious security concerns require it.
3887  * New minor versions of Mbed TLS may change the order in
3888  * keeping with the general principle of favoring the lowest
3889  * resource usage.
3890  *
3891  * \param conf SSL configuration
3892  * \param groups List of allowed groups ordered by preference, terminated by 0.
3893  * Must contain valid IANA NamedGroup IDs (provided via either an integer
3894  * or using MBEDTLS_TLS1_3_NAMED_GROUP_XXX macros).
3895  */
3897  const uint16_t *groups);
3898 
3899 #if defined(MBEDTLS_SSL_HANDSHAKE_WITH_CERT_ENABLED)
3900 #if !defined(MBEDTLS_DEPRECATED_REMOVED) && defined(MBEDTLS_SSL_PROTO_TLS1_2)
3901 /**
3902  * \brief Set the allowed hashes for signatures during the handshake.
3903  *
3904  * \note This only affects which hashes are offered and can be used
3905  * for signatures during the handshake. Hashes for message
3906  * authentication and the TLS PRF are controlled by the
3907  * ciphersuite, see \c mbedtls_ssl_conf_ciphersuites(). Hashes
3908  * used for certificate signature are controlled by the
3909  * verification profile, see \c mbedtls_ssl_conf_cert_profile().
3910  *
3911  * \deprecated Superseded by mbedtls_ssl_conf_sig_algs().
3912  *
3913  * \note This list should be ordered by decreasing preference
3914  * (preferred hash first).
3915  *
3916  * \note By default, all supported hashes whose length is at least
3917  * 256 bits are allowed. This is the same set as the default
3918  * for certificate verification
3919  * (#mbedtls_x509_crt_profile_default).
3920  * The preference order is currently unspecified and may
3921  * change in future versions.
3922  *
3923  * \note New minor versions of Mbed TLS may extend this list,
3924  * for example if new curves are added to the library.
3925  * New minor versions of Mbed TLS will not remove items
3926  * from this list unless serious security concerns require it.
3927  *
3928  * \param conf SSL configuration
3929  * \param hashes Ordered list of allowed signature hashes,
3930  * terminated by \c MBEDTLS_MD_NONE.
3931  */
3933  const int *hashes);
3934 #endif /* !MBEDTLS_DEPRECATED_REMOVED && MBEDTLS_SSL_PROTO_TLS1_2 */
3935 
3936 /**
3937  * \brief Configure allowed signature algorithms for use in TLS
3938  *
3939  * \param conf The SSL configuration to use.
3940  * \param sig_algs List of allowed IANA values for TLS 1.3 signature algorithms,
3941  * terminated by #MBEDTLS_TLS1_3_SIG_NONE. The list must remain
3942  * available throughout the lifetime of the conf object.
3943  * - For TLS 1.3, values of \c MBEDTLS_TLS1_3_SIG_XXXX should be
3944  * used.
3945  * - For TLS 1.2, values should be given as
3946  * "(HashAlgorithm << 8) | SignatureAlgorithm".
3947  */
3949  const uint16_t *sig_algs);
3950 #endif /* MBEDTLS_SSL_HANDSHAKE_WITH_CERT_ENABLED */
3951 
3952 #if defined(MBEDTLS_X509_CRT_PARSE_C)
3953 /**
3954  * \brief Set or reset the hostname to check against the received
3955  * server certificate. It sets the ServerName TLS extension,
3956  * too, if that extension is enabled. (client-side only)
3957  *
3958  * \param ssl SSL context
3959  * \param hostname the server hostname, may be NULL to clear hostname
3960 
3961  * \note Maximum hostname length MBEDTLS_SSL_MAX_HOST_NAME_LEN.
3962  *
3963  * \return 0 if successful, MBEDTLS_ERR_SSL_ALLOC_FAILED on
3964  * allocation failure, MBEDTLS_ERR_SSL_BAD_INPUT_DATA on
3965  * too long input hostname.
3966  *
3967  * Hostname set to the one provided on success (cleared
3968  * when NULL). On allocation failure hostname is cleared.
3969  * On too long input failure, old hostname is unchanged.
3970  */
3971 int mbedtls_ssl_set_hostname(mbedtls_ssl_context *ssl, const char *hostname);
3972 
3973 /**
3974  * \brief Get the hostname that checked against the received
3975  * server certificate. It is used to set the ServerName
3976  * TLS extension, too, if that extension is enabled.
3977  * (client-side only)
3978  *
3979  * \param ssl SSL context
3980  *
3981  * \return const pointer to the hostname value
3982  */
3983 static inline const char *mbedtls_ssl_get_hostname(mbedtls_ssl_context *ssl)
3984 {
3985  return ssl->MBEDTLS_PRIVATE(hostname);
3986 }
3987 #endif /* MBEDTLS_X509_CRT_PARSE_C */
3988 
3989 #if defined(MBEDTLS_SSL_SERVER_NAME_INDICATION)
3990 /**
3991  * \brief Retrieve SNI extension value for the current handshake.
3992  * Available in \c f_cert_cb of \c mbedtls_ssl_conf_cert_cb(),
3993  * this is the same value passed to \c f_sni callback of
3994  * \c mbedtls_ssl_conf_sni() and may be used instead of
3995  * \c mbedtls_ssl_conf_sni().
3996  *
3997  * \param ssl SSL context
3998  * \param name_len pointer into which to store length of returned value.
3999  * 0 if SNI extension is not present or not yet processed.
4000  *
4001  * \return const pointer to SNI extension value.
4002  * - value is valid only when called in \c f_cert_cb
4003  * registered with \c mbedtls_ssl_conf_cert_cb().
4004  * - value is NULL if SNI extension is not present.
4005  * - value is not '\0'-terminated. Use \c name_len for len.
4006  * - value must not be freed.
4007  */
4008 const unsigned char *mbedtls_ssl_get_hs_sni(mbedtls_ssl_context *ssl,
4009  size_t *name_len);
4010 
4011 /**
4012  * \brief Set own certificate and key for the current handshake
4013  *
4014  * \note Same as \c mbedtls_ssl_conf_own_cert() but for use within
4015  * the SNI callback or the certificate selection callback.
4016  *
4017  * \note Passing null \c own_cert clears the certificate list for
4018  * the current handshake.
4019  *
4020  * \param ssl SSL context
4021  * \param own_cert own public certificate chain
4022  * \param pk_key own private key
4023  *
4024  * \return 0 on success or MBEDTLS_ERR_SSL_ALLOC_FAILED
4025  */
4027  mbedtls_x509_crt *own_cert,
4028  mbedtls_pk_context *pk_key);
4029 
4030 /**
4031  * \brief Set the data required to verify peer certificate for the
4032  * current handshake
4033  *
4034  * \note Same as \c mbedtls_ssl_conf_ca_chain() but for use within
4035  * the SNI callback or the certificate selection callback.
4036  *
4037  * \param ssl SSL context
4038  * \param ca_chain trusted CA chain (meaning all fully trusted top-level CAs)
4039  * \param ca_crl trusted CA CRLs
4040  */
4042  mbedtls_x509_crt *ca_chain,
4043  mbedtls_x509_crl *ca_crl);
4044 
4045 #if defined(MBEDTLS_KEY_EXCHANGE_CERT_REQ_ALLOWED_ENABLED)
4046 /**
4047  * \brief Set DN hints sent to client in CertificateRequest message
4048  *
4049  * \note Same as \c mbedtls_ssl_conf_dn_hints() but for use within
4050  * the SNI callback or the certificate selection callback.
4051  *
4052  * \param ssl SSL context
4053  * \param crt crt chain whose subject DNs are issuer DNs of client certs
4054  * from which the client should select client peer certificate.
4055  */
4057  const mbedtls_x509_crt *crt);
4058 #endif /* MBEDTLS_KEY_EXCHANGE_CERT_REQ_ALLOWED_ENABLED */
4059 
4060 /**
4061  * \brief Set authmode for the current handshake.
4062  *
4063  * \note Same as \c mbedtls_ssl_conf_authmode() but for use within
4064  * the SNI callback or the certificate selection callback.
4065  *
4066  * \param ssl SSL context
4067  * \param authmode MBEDTLS_SSL_VERIFY_NONE, MBEDTLS_SSL_VERIFY_OPTIONAL or
4068  * MBEDTLS_SSL_VERIFY_REQUIRED
4069  */
4071  int authmode);
4072 
4073 /**
4074  * \brief Set server side ServerName TLS extension callback
4075  * (optional, server-side only).
4076  *
4077  * If set, the ServerName callback is called whenever the
4078  * server receives a ServerName TLS extension from the client
4079  * during a handshake. The ServerName callback has the
4080  * following parameters: (void *parameter, mbedtls_ssl_context *ssl,
4081  * const unsigned char *hostname, size_t len). If a suitable
4082  * certificate is found, the callback must set the
4083  * certificate(s) and key(s) to use with \c
4084  * mbedtls_ssl_set_hs_own_cert() (can be called repeatedly),
4085  * and may optionally adjust the CA and associated CRL with \c
4086  * mbedtls_ssl_set_hs_ca_chain() as well as the client
4087  * authentication mode with \c mbedtls_ssl_set_hs_authmode(),
4088  * then must return 0. If no matching name is found, the
4089  * callback may return non-zero to abort the handshake.
4090  *
4091  * \param conf SSL configuration
4092  * \param f_sni verification function
4093  * \param p_sni verification parameter
4094  */
4096  int (*f_sni)(void *, mbedtls_ssl_context *, const unsigned char *,
4097  size_t),
4098  void *p_sni);
4099 #endif /* MBEDTLS_SSL_SERVER_NAME_INDICATION */
4100 
4101 #if defined(MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED)
4102 /**
4103  * \brief Set the EC J-PAKE password for current handshake.
4104  *
4105  * \note An internal copy is made, and destroyed as soon as the
4106  * handshake is completed, or when the SSL context is reset or
4107  * freed.
4108  *
4109  * \note The SSL context needs to be already set up. The right place
4110  * to call this function is between \c mbedtls_ssl_setup() or
4111  * \c mbedtls_ssl_reset() and \c mbedtls_ssl_handshake().
4112  * Password cannot be empty (see RFC 8236).
4113  *
4114  * \param ssl SSL context
4115  * \param pw EC J-PAKE password (pre-shared secret). It cannot be empty
4116  * \param pw_len length of pw in bytes
4117  *
4118  * \return 0 on success, or a negative error code.
4119  */
4120 int mbedtls_ssl_set_hs_ecjpake_password(mbedtls_ssl_context *ssl,
4121  const unsigned char *pw,
4122  size_t pw_len);
4123 
4124 /**
4125  * \brief Set the EC J-PAKE opaque password for current handshake.
4126  *
4127  * \note The key must remain valid until the handshake is over.
4128  *
4129  * \note The SSL context needs to be already set up. The right place
4130  * to call this function is between \c mbedtls_ssl_setup() or
4131  * \c mbedtls_ssl_reset() and \c mbedtls_ssl_handshake().
4132  *
4133  * \param ssl SSL context
4134  * \param pwd EC J-PAKE opaque password
4135  *
4136  * \return 0 on success, or a negative error code.
4137  */
4138 int mbedtls_ssl_set_hs_ecjpake_password_opaque(mbedtls_ssl_context *ssl,
4139  mbedtls_svc_key_id_t pwd);
4140 #endif /*MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED */
4141 
4142 #if defined(MBEDTLS_SSL_ALPN)
4143 /**
4144  * \brief Set the supported Application Layer Protocols.
4145  *
4146  * \param conf SSL configuration
4147  * \param protos Pointer to a NULL-terminated list of supported protocols,
4148  * in decreasing preference order. The pointer to the list is
4149  * recorded by the library for later reference as required, so
4150  * the lifetime of the table must be at least as long as the
4151  * lifetime of the SSL configuration structure.
4152  *
4153  * \return 0 on success, or MBEDTLS_ERR_SSL_BAD_INPUT_DATA.
4154  */
4155 int mbedtls_ssl_conf_alpn_protocols(mbedtls_ssl_config *conf, const char **protos);
4156 
4157 /**
4158  * \brief Get the name of the negotiated Application Layer Protocol.
4159  * This function should be called after the handshake is
4160  * completed.
4161  *
4162  * \param ssl SSL context
4163  *
4164  * \return Protocol name, or NULL if no protocol was negotiated.
4165  */
4166 const char *mbedtls_ssl_get_alpn_protocol(const mbedtls_ssl_context *ssl);
4167 #endif /* MBEDTLS_SSL_ALPN */
4168 
4169 #if defined(MBEDTLS_SSL_DTLS_SRTP)
4170 #if defined(MBEDTLS_DEBUG_C)
4171 static inline const char *mbedtls_ssl_get_srtp_profile_as_string(mbedtls_ssl_srtp_profile profile)
4172 {
4173  switch (profile) {
4174  case MBEDTLS_TLS_SRTP_AES128_CM_HMAC_SHA1_80:
4175  return "MBEDTLS_TLS_SRTP_AES128_CM_HMAC_SHA1_80";
4176  case MBEDTLS_TLS_SRTP_AES128_CM_HMAC_SHA1_32:
4177  return "MBEDTLS_TLS_SRTP_AES128_CM_HMAC_SHA1_32";
4178  case MBEDTLS_TLS_SRTP_NULL_HMAC_SHA1_80:
4179  return "MBEDTLS_TLS_SRTP_NULL_HMAC_SHA1_80";
4180  case MBEDTLS_TLS_SRTP_NULL_HMAC_SHA1_32:
4181  return "MBEDTLS_TLS_SRTP_NULL_HMAC_SHA1_32";
4182  default: break;
4183  }
4184  return "";
4185 }
4186 #endif /* MBEDTLS_DEBUG_C */
4187 /**
4188  * \brief Manage support for mki(master key id) value
4189  * in use_srtp extension.
4190  * MKI is an optional part of SRTP used for key management
4191  * and re-keying. See RFC3711 section 3.1 for details.
4192  * The default value is
4193  * #MBEDTLS_SSL_DTLS_SRTP_MKI_UNSUPPORTED.
4194  *
4195  * \param conf The SSL configuration to manage mki support.
4196  * \param support_mki_value Enable or disable mki usage. Values are
4197  * #MBEDTLS_SSL_DTLS_SRTP_MKI_UNSUPPORTED
4198  * or #MBEDTLS_SSL_DTLS_SRTP_MKI_SUPPORTED.
4199  */
4200 void mbedtls_ssl_conf_srtp_mki_value_supported(mbedtls_ssl_config *conf,
4201  int support_mki_value);
4202 
4203 /**
4204  * \brief Set the supported DTLS-SRTP protection profiles.
4205  *
4206  * \param conf SSL configuration
4207  * \param profiles Pointer to a List of MBEDTLS_TLS_SRTP_UNSET terminated
4208  * supported protection profiles
4209  * in decreasing preference order.
4210  * The pointer to the list is recorded by the library
4211  * for later reference as required, so the lifetime
4212  * of the table must be at least as long as the lifetime
4213  * of the SSL configuration structure.
4214  * The list must not hold more than
4215  * MBEDTLS_TLS_SRTP_MAX_PROFILE_LIST_LENGTH elements
4216  * (excluding the terminating MBEDTLS_TLS_SRTP_UNSET).
4217  *
4218  * \return 0 on success
4219  * \return #MBEDTLS_ERR_SSL_BAD_INPUT_DATA when the list of
4220  * protection profiles is incorrect.
4221  */
4222 int mbedtls_ssl_conf_dtls_srtp_protection_profiles
4223  (mbedtls_ssl_config *conf,
4224  const mbedtls_ssl_srtp_profile *profiles);
4225 
4226 /**
4227  * \brief Set the mki_value for the current DTLS-SRTP session.
4228  *
4229  * \param ssl SSL context to use.
4230  * \param mki_value The MKI value to set.
4231  * \param mki_len The length of the MKI value.
4232  *
4233  * \note This function is relevant on client side only.
4234  * The server discovers the mki value during handshake.
4235  * A mki value set on server side using this function
4236  * is ignored.
4237  *
4238  * \return 0 on success
4239  * \return #MBEDTLS_ERR_SSL_BAD_INPUT_DATA
4240  * \return #MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE
4241  */
4242 int mbedtls_ssl_dtls_srtp_set_mki_value(mbedtls_ssl_context *ssl,
4243  unsigned char *mki_value,
4244  uint16_t mki_len);
4245 /**
4246  * \brief Get the negotiated DTLS-SRTP information:
4247  * Protection profile and MKI value.
4248  *
4249  * \warning This function must be called after the handshake is
4250  * completed. The value returned by this function must
4251  * not be trusted or acted upon before the handshake completes.
4252  *
4253  * \param ssl The SSL context to query.
4254  * \param dtls_srtp_info The negotiated DTLS-SRTP information:
4255  * - Protection profile in use.
4256  * A direct mapping of the iana defined value for protection
4257  * profile on an uint16_t.
4258  http://www.iana.org/assignments/srtp-protection/srtp-protection.xhtml
4259  * #MBEDTLS_TLS_SRTP_UNSET if the use of SRTP was not negotiated
4260  * or peer's Hello packet was not parsed yet.
4261  * - mki size and value( if size is > 0 ).
4262  */
4263 void mbedtls_ssl_get_dtls_srtp_negotiation_result(const mbedtls_ssl_context *ssl,
4264  mbedtls_dtls_srtp_info *dtls_srtp_info);
4265 #endif /* MBEDTLS_SSL_DTLS_SRTP */
4266 
4267 #if !defined(MBEDTLS_DEPRECATED_REMOVED)
4268 /**
4269  * \brief Set the maximum supported version sent from the client side
4270  * and/or accepted at the server side.
4271  *
4272  * See also the documentation of mbedtls_ssl_conf_min_version().
4273  *
4274  * \note This ignores ciphersuites from higher versions.
4275  *
4276  * \note This function is deprecated and has been replaced by
4277  * \c mbedtls_ssl_conf_max_tls_version().
4278  *
4279  * \param conf SSL configuration
4280  * \param major Major version number (#MBEDTLS_SSL_MAJOR_VERSION_3)
4281  * \param minor Minor version number
4282  * (#MBEDTLS_SSL_MINOR_VERSION_3 for (D)TLS 1.2,
4283  * #MBEDTLS_SSL_MINOR_VERSION_4 for TLS 1.3)
4284  */
4286  int minor);
4287 #endif /* MBEDTLS_DEPRECATED_REMOVED */
4288 
4289 /**
4290  * \brief Set the maximum supported version sent from the client side
4291  * and/or accepted at the server side.
4292  *
4293  * \note After the handshake, you can call
4294  * mbedtls_ssl_get_version_number() to see what version was
4295  * negotiated.
4296  *
4297  * \param conf SSL configuration
4298  * \param tls_version TLS protocol version number (\c mbedtls_ssl_protocol_version)
4299  * (#MBEDTLS_SSL_VERSION_UNKNOWN is not valid)
4300  */
4302  mbedtls_ssl_protocol_version tls_version)
4303 {
4304  conf->MBEDTLS_PRIVATE(max_tls_version) = tls_version;
4305 }
4306 
4307 #if !defined(MBEDTLS_DEPRECATED_REMOVED)
4308 /**
4309  * \brief Set the minimum accepted SSL/TLS protocol version
4310  *
4311  * \note By default, all supported versions are accepted.
4312  * Future versions of the library may disable older
4313  * protocol versions by default if they become deprecated.
4314  *
4315  * \note The following versions are supported (if enabled at
4316  * compile time):
4317  * - (D)TLS 1.2: \p major = #MBEDTLS_SSL_MAJOR_VERSION_3,
4318  * \p minor = #MBEDTLS_SSL_MINOR_VERSION_3
4319  * - TLS 1.3: \p major = #MBEDTLS_SSL_MAJOR_VERSION_3,
4320  * \p minor = #MBEDTLS_SSL_MINOR_VERSION_4
4321  *
4322  * Note that the numbers in the constant names are the
4323  * TLS internal protocol numbers, and the minor versions
4324  * differ by one from the human-readable versions!
4325  *
4326  * \note Input outside of the SSL_MAX_XXXXX_VERSION and
4327  * SSL_MIN_XXXXX_VERSION range is ignored.
4328  *
4329  * \note After the handshake, you can call
4330  * mbedtls_ssl_get_version_number() to see what version was
4331  * negotiated.
4332  *
4333  * \note This function is deprecated and has been replaced by
4334  * \c mbedtls_ssl_conf_min_tls_version().
4335  *
4336  * \param conf SSL configuration
4337  * \param major Major version number (#MBEDTLS_SSL_MAJOR_VERSION_3)
4338  * \param minor Minor version number
4339  * (#MBEDTLS_SSL_MINOR_VERSION_3 for (D)TLS 1.2,
4340  * #MBEDTLS_SSL_MINOR_VERSION_4 for TLS 1.3)
4341  */
4343  int minor);
4344 #endif /* MBEDTLS_DEPRECATED_REMOVED */
4345 
4346 /**
4347  * \brief Set the minimum supported version sent from the client side
4348  * and/or accepted at the server side.
4349  *
4350  * \note After the handshake, you can call
4351  * mbedtls_ssl_get_version_number() to see what version was
4352  * negotiated.
4353  *
4354  * \param conf SSL configuration
4355  * \param tls_version TLS protocol version number (\c mbedtls_ssl_protocol_version)
4356  * (#MBEDTLS_SSL_VERSION_UNKNOWN is not valid)
4357  */
4359  mbedtls_ssl_protocol_version tls_version)
4360 {
4361  conf->MBEDTLS_PRIVATE(min_tls_version) = tls_version;
4362 }
4363 
4364 #if defined(MBEDTLS_SSL_ENCRYPT_THEN_MAC)
4365 /**
4366  * \brief Enable or disable Encrypt-then-MAC
4367  * (Default: MBEDTLS_SSL_ETM_ENABLED)
4368  *
4369  * \note This should always be enabled, it is a security
4370  * improvement, and should not cause any interoperability
4371  * issue (used only if the peer supports it too).
4372  *
4373  * \param conf SSL configuration
4374  * \param etm MBEDTLS_SSL_ETM_ENABLED or MBEDTLS_SSL_ETM_DISABLED
4375  */
4377 #endif /* MBEDTLS_SSL_ENCRYPT_THEN_MAC */
4378 
4379 #if defined(MBEDTLS_SSL_EXTENDED_MASTER_SECRET)
4380 /**
4381  * \brief Enable or disable Extended Master Secret negotiation.
4382  * (Default: MBEDTLS_SSL_EXTENDED_MS_ENABLED)
4383  *
4384  * \note This should always be enabled, it is a security fix to the
4385  * protocol, and should not cause any interoperability issue
4386  * (used only if the peer supports it too).
4387  *
4388  * \param conf SSL configuration
4389  * \param ems MBEDTLS_SSL_EXTENDED_MS_ENABLED or MBEDTLS_SSL_EXTENDED_MS_DISABLED
4390  */
4392 #endif /* MBEDTLS_SSL_EXTENDED_MASTER_SECRET */
4393 
4394 #if defined(MBEDTLS_SSL_SRV_C)
4395 /**
4396  * \brief Whether to send a list of acceptable CAs in
4397  * CertificateRequest messages.
4398  * (Default: do send)
4399  *
4400  * \param conf SSL configuration
4401  * \param cert_req_ca_list MBEDTLS_SSL_CERT_REQ_CA_LIST_ENABLED or
4402  * MBEDTLS_SSL_CERT_REQ_CA_LIST_DISABLED
4403  */
4405  char cert_req_ca_list);
4406 #endif /* MBEDTLS_SSL_SRV_C */
4407 
4408 #if defined(MBEDTLS_SSL_MAX_FRAGMENT_LENGTH)
4409 /**
4410  * \brief Set the maximum fragment length to emit and/or negotiate.
4411  * (Typical: the smaller of #MBEDTLS_SSL_IN_CONTENT_LEN and
4412  * #MBEDTLS_SSL_OUT_CONTENT_LEN, usually `2^14` bytes)
4413  * (Server: set maximum fragment length to emit,
4414  * usually negotiated by the client during handshake)
4415  * (Client: set maximum fragment length to emit *and*
4416  * negotiate with the server during handshake)
4417  * (Default: #MBEDTLS_SSL_MAX_FRAG_LEN_NONE)
4418  *
4419  * \note On the client side, the maximum fragment length extension
4420  * *will not* be used, unless the maximum fragment length has
4421  * been set via this function to a value different than
4422  * #MBEDTLS_SSL_MAX_FRAG_LEN_NONE.
4423  *
4424  * \note With TLS, this currently only affects ApplicationData (sent
4425  * with \c mbedtls_ssl_read()), not handshake messages.
4426  * With DTLS, this affects both ApplicationData and handshake.
4427  *
4428  * \note This sets the maximum length for a record's payload,
4429  * excluding record overhead that will be added to it, see
4430  * \c mbedtls_ssl_get_record_expansion().
4431  *
4432  * \note For DTLS, it is also possible to set a limit for the total
4433  * size of datagrams passed to the transport layer, including
4434  * record overhead, see \c mbedtls_ssl_set_mtu().
4435  *
4436  * \param conf SSL configuration
4437  * \param mfl_code Code for maximum fragment length (allowed values:
4438  * MBEDTLS_SSL_MAX_FRAG_LEN_512, MBEDTLS_SSL_MAX_FRAG_LEN_1024,
4439  * MBEDTLS_SSL_MAX_FRAG_LEN_2048, MBEDTLS_SSL_MAX_FRAG_LEN_4096)
4440  *
4441  * \return 0 if successful or MBEDTLS_ERR_SSL_BAD_INPUT_DATA
4442  */
4443 int mbedtls_ssl_conf_max_frag_len(mbedtls_ssl_config *conf, unsigned char mfl_code);
4444 #endif /* MBEDTLS_SSL_MAX_FRAGMENT_LENGTH */
4445 
4446 #if defined(MBEDTLS_SSL_SRV_C)
4447 /**
4448  * \brief Pick the ciphersuites order according to the second parameter
4449  * in the SSL Server module (MBEDTLS_SSL_SRV_C).
4450  * (Default, if never called: MBEDTLS_SSL_SRV_CIPHERSUITE_ORDER_SERVER)
4451  *
4452  * \param conf SSL configuration
4453  * \param order Server or client (MBEDTLS_SSL_SRV_CIPHERSUITE_ORDER_SERVER
4454  * or MBEDTLS_SSL_SRV_CIPHERSUITE_ORDER_CLIENT)
4455  */
4457 #endif /* MBEDTLS_SSL_SRV_C */
4458 
4459 #if defined(MBEDTLS_SSL_SESSION_TICKETS) && \
4460  defined(MBEDTLS_SSL_CLI_C)
4461 /**
4462  * \brief Enable / Disable session tickets (client only).
4463  * (Default: MBEDTLS_SSL_SESSION_TICKETS_ENABLED.)
4464  *
4465  * \note On server, use \c mbedtls_ssl_conf_session_tickets_cb().
4466  *
4467  * \param conf SSL configuration
4468  * \param use_tickets Enable or disable (MBEDTLS_SSL_SESSION_TICKETS_ENABLED or
4469  * MBEDTLS_SSL_SESSION_TICKETS_DISABLED)
4470  */
4471 void mbedtls_ssl_conf_session_tickets(mbedtls_ssl_config *conf, int use_tickets);
4472 #endif /* MBEDTLS_SSL_SESSION_TICKETS &&
4473  MBEDTLS_SSL_CLI_C */
4474 
4475 #if defined(MBEDTLS_SSL_SESSION_TICKETS) && \
4476  defined(MBEDTLS_SSL_SRV_C) && \
4477  defined(MBEDTLS_SSL_PROTO_TLS1_3)
4478 /**
4479  * \brief Number of NewSessionTicket messages for the server to send
4480  * after handshake completion.
4481  *
4482  * \note The default value is
4483  * \c MBEDTLS_SSL_TLS1_3_DEFAULT_NEW_SESSION_TICKETS.
4484  *
4485  * \note In case of a session resumption, this setting only partially apply.
4486  * At most one ticket is sent in that case to just renew the pool of
4487  * tickets of the client. The rationale is to avoid the number of
4488  * tickets on the server to become rapidly out of control when the
4489  * server has the same configuration for all its connection instances.
4490  *
4491  * \param conf SSL configuration
4492  * \param num_tickets Number of NewSessionTicket.
4493  *
4494  */
4496  uint16_t num_tickets);
4497 #endif /* MBEDTLS_SSL_SESSION_TICKETS &&
4498  MBEDTLS_SSL_SRV_C &&
4499  MBEDTLS_SSL_PROTO_TLS1_3*/
4500 
4501 #if defined(MBEDTLS_SSL_RENEGOTIATION)
4502 /**
4503  * \brief Enable / Disable renegotiation support for connection when
4504  * initiated by peer
4505  * (Default: MBEDTLS_SSL_RENEGOTIATION_DISABLED)
4506  *
4507  * \warning It is recommended to always disable renegotiation unless you
4508  * know you need it and you know what you're doing. In the
4509  * past, there have been several issues associated with
4510  * renegotiation or a poor understanding of its properties.
4511  *
4512  * \note Server-side, enabling renegotiation also makes the server
4513  * susceptible to a resource DoS by a malicious client.
4514  *
4515  * \param conf SSL configuration
4516  * \param renegotiation Enable or disable (MBEDTLS_SSL_RENEGOTIATION_ENABLED or
4517  * MBEDTLS_SSL_RENEGOTIATION_DISABLED)
4518  */
4519 void mbedtls_ssl_conf_renegotiation(mbedtls_ssl_config *conf, int renegotiation);
4520 #endif /* MBEDTLS_SSL_RENEGOTIATION */
4521 
4522 /**
4523  * \brief Prevent or allow legacy renegotiation.
4524  * (Default: MBEDTLS_SSL_LEGACY_NO_RENEGOTIATION)
4525  *
4526  * MBEDTLS_SSL_LEGACY_NO_RENEGOTIATION allows connections to
4527  * be established even if the peer does not support
4528  * secure renegotiation, but does not allow renegotiation
4529  * to take place if not secure.
4530  * (Interoperable and secure option)
4531  *
4532  * MBEDTLS_SSL_LEGACY_ALLOW_RENEGOTIATION allows renegotiations
4533  * with non-upgraded peers. Allowing legacy renegotiation
4534  * makes the connection vulnerable to specific man in the
4535  * middle attacks. (See RFC 5746)
4536  * (Most interoperable and least secure option)
4537  *
4538  * MBEDTLS_SSL_LEGACY_BREAK_HANDSHAKE breaks off connections
4539  * if peer does not support secure renegotiation. Results
4540  * in interoperability issues with non-upgraded peers
4541  * that do not support renegotiation altogether.
4542  * (Most secure option, interoperability issues)
4543  *
4544  * \param conf SSL configuration
4545  * \param allow_legacy Prevent or allow (SSL_NO_LEGACY_RENEGOTIATION,
4546  * SSL_ALLOW_LEGACY_RENEGOTIATION or
4547  * MBEDTLS_SSL_LEGACY_BREAK_HANDSHAKE)
4548  */
4550 
4551 #if defined(MBEDTLS_SSL_RENEGOTIATION)
4552 /**
4553  * \brief Enforce renegotiation requests.
4554  * (Default: enforced, max_records = 16)
4555  *
4556  * When we request a renegotiation, the peer can comply or
4557  * ignore the request. This function allows us to decide
4558  * whether to enforce our renegotiation requests by closing
4559  * the connection if the peer doesn't comply.
4560  *
4561  * However, records could already be in transit from the peer
4562  * when the request is emitted. In order to increase
4563  * reliability, we can accept a number of records before the
4564  * expected handshake records.
4565  *
4566  * The optimal value is highly dependent on the specific usage
4567  * scenario.
4568  *
4569  * \note With DTLS and server-initiated renegotiation, the
4570  * HelloRequest is retransmitted every time mbedtls_ssl_read() times
4571  * out or receives Application Data, until:
4572  * - max_records records have beens seen, if it is >= 0, or
4573  * - the number of retransmits that would happen during an
4574  * actual handshake has been reached.
4575  * Please remember the request might be lost a few times
4576  * if you consider setting max_records to a really low value.
4577  *
4578  * \warning On client, the grace period can only happen during
4579  * mbedtls_ssl_read(), as opposed to mbedtls_ssl_write() and mbedtls_ssl_renegotiate()
4580  * which always behave as if max_record was 0. The reason is,
4581  * if we receive application data from the server, we need a
4582  * place to write it, which only happens during mbedtls_ssl_read().
4583  *
4584  * \param conf SSL configuration
4585  * \param max_records Use MBEDTLS_SSL_RENEGOTIATION_NOT_ENFORCED if you don't want to
4586  * enforce renegotiation, or a non-negative value to enforce
4587  * it but allow for a grace period of max_records records.
4588  */
4589 void mbedtls_ssl_conf_renegotiation_enforced(mbedtls_ssl_config *conf, int max_records);
4590 
4591 /**
4592  * \brief Set record counter threshold for periodic renegotiation.
4593  * (Default: 2^48 - 1)
4594  *
4595  * Renegotiation is automatically triggered when a record
4596  * counter (outgoing or incoming) crosses the defined
4597  * threshold. The default value is meant to prevent the
4598  * connection from being closed when the counter is about to
4599  * reached its maximal value (it is not allowed to wrap).
4600  *
4601  * Lower values can be used to enforce policies such as "keys
4602  * must be refreshed every N packets with cipher X".
4603  *
4604  * The renegotiation period can be disabled by setting
4605  * conf->disable_renegotiation to
4606  * MBEDTLS_SSL_RENEGOTIATION_DISABLED.
4607  *
4608  * \note When the configured transport is
4609  * MBEDTLS_SSL_TRANSPORT_DATAGRAM the maximum renegotiation
4610  * period is 2^48 - 1, and for MBEDTLS_SSL_TRANSPORT_STREAM,
4611  * the maximum renegotiation period is 2^64 - 1.
4612  *
4613  * \param conf SSL configuration
4614  * \param period The threshold value: a big-endian 64-bit number.
4615  */
4617  const unsigned char period[8]);
4618 #endif /* MBEDTLS_SSL_RENEGOTIATION */
4619 
4620 /**
4621  * \brief Check if there is data already read from the
4622  * underlying transport but not yet processed.
4623  *
4624  * \param ssl SSL context
4625  *
4626  * \return 0 if nothing's pending, 1 otherwise.
4627  *
4628  * \note This is different in purpose and behaviour from
4629  * \c mbedtls_ssl_get_bytes_avail in that it considers
4630  * any kind of unprocessed data, not only unread
4631  * application data. If \c mbedtls_ssl_get_bytes
4632  * returns a non-zero value, this function will
4633  * also signal pending data, but the converse does
4634  * not hold. For example, in DTLS there might be
4635  * further records waiting to be processed from
4636  * the current underlying transport's datagram.
4637  *
4638  * \note If this function returns 1 (data pending), this
4639  * does not imply that a subsequent call to
4640  * \c mbedtls_ssl_read will provide any data;
4641  * e.g., the unprocessed data might turn out
4642  * to be an alert or a handshake message.
4643  *
4644  * \note This function is useful in the following situation:
4645  * If the SSL/TLS module successfully returns from an
4646  * operation - e.g. a handshake or an application record
4647  * read - and you're awaiting incoming data next, you
4648  * must not immediately idle on the underlying transport
4649  * to have data ready, but you need to check the value
4650  * of this function first. The reason is that the desired
4651  * data might already be read but not yet processed.
4652  * If, in contrast, a previous call to the SSL/TLS module
4653  * returned MBEDTLS_ERR_SSL_WANT_READ, it is not necessary
4654  * to call this function, as the latter error code entails
4655  * that all internal data has been processed.
4656  *
4657  */
4659 
4660 /**
4661  * \brief Return the number of application data bytes
4662  * remaining to be read from the current record.
4663  *
4664  * \param ssl SSL context
4665  *
4666  * \return How many bytes are available in the application
4667  * data record read buffer.
4668  *
4669  * \note When working over a datagram transport, this is
4670  * useful to detect the current datagram's boundary
4671  * in case \c mbedtls_ssl_read has written the maximal
4672  * amount of data fitting into the input buffer.
4673  *
4674  */
4676 
4677 /**
4678  * \brief Return the result of the certificate verification
4679  *
4680  * \param ssl The SSL context to use.
4681  *
4682  * \return \c 0 if the certificate verification was successful.
4683  * \return \c -1u if the result is not available. This may happen
4684  * e.g. if the handshake aborts early, or a verification
4685  * callback returned a fatal error.
4686  * \return A bitwise combination of \c MBEDTLS_X509_BADCERT_XXX
4687  * and \c MBEDTLS_X509_BADCRL_XXX failure flags; see x509.h.
4688  */
4690 
4691 /**
4692  * \brief Return the id of the current ciphersuite
4693  *
4694  * \param ssl SSL context
4695  *
4696  * \return a ciphersuite id
4697  */
4699 
4700 /**
4701  * \brief Return the name of the current ciphersuite
4702  *
4703  * \param ssl SSL context
4704  *
4705  * \return a string containing the ciphersuite name
4706  */
4708 
4709 
4710 /**
4711  * \brief Return the (D)TLS protocol version negotiated in the
4712  * given connection.
4713  *
4714  * \note If you call this function too early during the initial
4715  * handshake, before the two sides have agreed on a version,
4716  * this function returns #MBEDTLS_SSL_VERSION_UNKNOWN.
4717  *
4718  * \param ssl The SSL context to query.
4719  * \return The negotiated protocol version.
4720  */
4722  const mbedtls_ssl_context *ssl)
4723 {
4724  return ssl->MBEDTLS_PRIVATE(tls_version);
4725 }
4726 
4727 /**
4728  * \brief Return the current TLS version
4729  *
4730  * \param ssl SSL context
4731  *
4732  * \return a string containing the TLS version
4733  */
4735 
4736 /**
4737  * \brief Return the (maximum) number of bytes added by the record
4738  * layer: header + encryption/MAC overhead (inc. padding)
4739  *
4740  * \param ssl SSL context
4741  *
4742  * \return Current maximum record expansion in bytes
4743  */
4745 
4746 /**
4747  * \brief Return the current maximum outgoing record payload in bytes.
4748  *
4749  * \note The logic to determine the maximum outgoing record payload is
4750  * version-specific. It takes into account various factors, such as
4751  * the mbedtls_config.h setting \c MBEDTLS_SSL_OUT_CONTENT_LEN, extensions
4752  * such as the max fragment length or record size limit extension if
4753  * used, and for DTLS the path MTU as configured and current
4754  * record expansion.
4755  *
4756  * \note With DTLS, \c mbedtls_ssl_write() will return an error if
4757  * called with a larger length value.
4758  * With TLS, \c mbedtls_ssl_write() will fragment the input if
4759  * necessary and return the number of bytes written; it is up
4760  * to the caller to call \c mbedtls_ssl_write() again in
4761  * order to send the remaining bytes if any.
4762  *
4763  * \sa mbedtls_ssl_get_max_out_record_payload()
4764  * \sa mbedtls_ssl_get_record_expansion()
4765  *
4766  * \param ssl SSL context
4767  *
4768  * \return Current maximum payload for an outgoing record,
4769  * or a negative error code.
4770  */
4772 
4773 /**
4774  * \brief Return the current maximum incoming record payload in bytes.
4775  *
4776  * \note The logic to determine the maximum incoming record payload is
4777  * version-specific. It takes into account various factors, such as
4778  * the mbedtls_config.h setting \c MBEDTLS_SSL_IN_CONTENT_LEN, extensions
4779  * such as the max fragment length extension or record size limit
4780  * extension if used, and the current record expansion.
4781  *
4782  * \sa mbedtls_ssl_set_mtu()
4783  * \sa mbedtls_ssl_get_max_in_record_payload()
4784  * \sa mbedtls_ssl_get_record_expansion()
4785  *
4786  * \param ssl SSL context
4787  *
4788  * \return Current maximum payload for an incoming record,
4789  * or a negative error code.
4790  */
4792 
4793 #if defined(MBEDTLS_X509_CRT_PARSE_C)
4794 /**
4795  * \brief Return the peer certificate from the current connection.
4796  *
4797  * \param ssl The SSL context to use. This must be initialized and setup.
4798  *
4799  * \return The current peer certificate, if available.
4800  * The returned certificate is owned by the SSL context and
4801  * is valid only until the next call to the SSL API.
4802  * \return \c NULL if no peer certificate is available. This might
4803  * be because the chosen ciphersuite doesn't use CRTs
4804  * (PSK-based ciphersuites, for example), or because
4805  * #MBEDTLS_SSL_KEEP_PEER_CERTIFICATE has been disabled,
4806  * allowing the stack to free the peer's CRT to save memory.
4807  *
4808  * \note For one-time inspection of the peer's certificate during
4809  * the handshake, consider registering an X.509 CRT verification
4810  * callback through mbedtls_ssl_conf_verify() instead of calling
4811  * this function. Using mbedtls_ssl_conf_verify() also comes at
4812  * the benefit of allowing you to influence the verification
4813  * process, for example by masking expected and tolerated
4814  * verification failures.
4815  *
4816  * \warning You must not use the pointer returned by this function
4817  * after any further call to the SSL API, including
4818  * mbedtls_ssl_read() and mbedtls_ssl_write(); this is
4819  * because the pointer might change during renegotiation,
4820  * which happens transparently to the user.
4821  * If you want to use the certificate across API calls,
4822  * you must make a copy.
4823  */
4825 #endif /* MBEDTLS_X509_CRT_PARSE_C */
4826 
4827 #if defined(MBEDTLS_SSL_CLI_C)
4828 /**
4829  * \brief Export a session in order to resume it later.
4830  *
4831  * \param ssl The SSL context representing the connection for which to
4832  * to export a session structure for later resumption.
4833  * \param session The target structure in which to store the exported session.
4834  * This must have been initialized with mbedtls_ssl_session_init()
4835  * but otherwise be unused.
4836  *
4837  * \note This function can handle a variety of mechanisms for session
4838  * resumption: For TLS 1.2, both session ID-based resumption and
4839  * ticket-based resumption will be considered. For TLS 1.3,
4840  * once implemented, sessions equate to tickets, and calling
4841  * this function multiple times will export the available
4842  * tickets one a time until no further tickets are available,
4843  * in which case MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE will
4844  * be returned.
4845  *
4846  * \note Calling this function multiple times will only be useful
4847  * once TLS 1.3 is supported. For TLS 1.2 connections, this
4848  * function should be called at most once.
4849  *
4850  * \return \c 0 if successful. In this case, \p session can be used for
4851  * session resumption by passing it to mbedtls_ssl_set_session(),
4852  * and serialized for storage via mbedtls_ssl_session_save().
4853  * \return #MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE if no further session
4854  * is available for export.
4855  * This error is a non-fatal, and has no observable effect on
4856  * the SSL context or the destination session.
4857  * \return Another negative error code on other kinds of failure.
4858  *
4859  * \sa mbedtls_ssl_set_session()
4860  * \sa mbedtls_ssl_session_save()
4861  */
4863  mbedtls_ssl_session *session);
4864 #endif /* MBEDTLS_SSL_CLI_C */
4865 
4866 /**
4867  * \brief Perform the SSL handshake
4868  *
4869  * \param ssl SSL context
4870  *
4871  * \return \c 0 if successful.
4872  * \return #MBEDTLS_ERR_SSL_WANT_READ or #MBEDTLS_ERR_SSL_WANT_WRITE
4873  * if the handshake is incomplete and waiting for data to
4874  * be available for reading from or writing to the underlying
4875  * transport - in this case you must call this function again
4876  * when the underlying transport is ready for the operation.
4877  * \return #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS if an asynchronous
4878  * operation is in progress (see
4879  * mbedtls_ssl_conf_async_private_cb()) - in this case you
4880  * must call this function again when the operation is ready.
4881  * \return #MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS if a cryptographic
4882  * operation is in progress (see mbedtls_ecp_set_max_ops()) -
4883  * in this case you must call this function again to complete
4884  * the handshake when you're done attending other tasks.
4885  * \return #MBEDTLS_ERR_SSL_HELLO_VERIFY_REQUIRED if DTLS is in use
4886  * and the client did not demonstrate reachability yet - in
4887  * this case you must stop using the context (see below).
4888  * \return #MBEDTLS_ERR_SSL_RECEIVED_EARLY_DATA if early data, as
4889  * defined in RFC 8446 (TLS 1.3 specification), has been
4890  * received as part of the handshake. This is server specific
4891  * and may occur only if the early data feature has been
4892  * enabled on server (see mbedtls_ssl_conf_early_data()
4893  * documentation). You must call mbedtls_ssl_read_early_data()
4894  * to read the early data before resuming the handshake.
4895  * \return Another SSL error code - in this case you must stop using
4896  * the context (see below).
4897  *
4898  * \warning If this function returns something other than
4899  * \c 0,
4900  * #MBEDTLS_ERR_SSL_WANT_READ,
4901  * #MBEDTLS_ERR_SSL_WANT_WRITE,
4902  * #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS or
4903  * #MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS or
4904  * #MBEDTLS_ERR_SSL_RECEIVED_EARLY_DATA,
4905  * you must stop using the SSL context for reading or writing,
4906  * and either free it or call \c mbedtls_ssl_session_reset()
4907  * on it before re-using it for a new connection; the current
4908  * connection must be closed.
4909  *
4910  * \note If DTLS is in use, then you may choose to handle
4911  * #MBEDTLS_ERR_SSL_HELLO_VERIFY_REQUIRED specially for logging
4912  * purposes, as it is an expected return value rather than an
4913  * actual error, but you still need to reset/free the context.
4914  *
4915  * \note Remarks regarding event-driven DTLS:
4916  * If the function returns #MBEDTLS_ERR_SSL_WANT_READ, no datagram
4917  * from the underlying transport layer is currently being processed,
4918  * and it is safe to idle until the timer or the underlying transport
4919  * signal a new event. This is not true for a successful handshake,
4920  * in which case the datagram of the underlying transport that is
4921  * currently being processed might or might not contain further
4922  * DTLS records.
4923  *
4924  * \note If the context is configured to allow TLS 1.3, or if
4925  * #MBEDTLS_USE_PSA_CRYPTO is enabled, the PSA crypto
4926  * subsystem must have been initialized by calling
4927  * psa_crypto_init() before calling this function.
4928  */
4930 
4931 /**
4932  * \brief After calling mbedtls_ssl_handshake() to start the SSL
4933  * handshake you can call this function to check whether the
4934  * handshake is over for a given SSL context. This function
4935  * should be also used to determine when to stop calling
4936  * mbedtls_handshake_step() for that context.
4937  *
4938  * \param ssl SSL context
4939  *
4940  * \return \c 1 if handshake is over, \c 0 if it is still ongoing.
4941  */
4943 {
4945 }
4946 
4947 /**
4948  * \brief Perform a single step of the SSL handshake
4949  *
4950  * \note The state of the context (ssl->state) will be at
4951  * the next state after this function returns \c 0. Do not
4952  * call this function if mbedtls_ssl_is_handshake_over()
4953  * returns \c 1.
4954  *
4955  * \warning Whilst in the past you may have used direct access to the
4956  * context state (ssl->state) in order to ascertain when to
4957  * stop calling this function and although you can still do
4958  * so with something like ssl->MBEDTLS_PRIVATE(state) or by
4959  * defining MBEDTLS_ALLOW_PRIVATE_ACCESS, this is now
4960  * considered deprecated and could be broken in any future
4961  * release. If you still find you have good reason for such
4962  * direct access, then please do contact the team to explain
4963  * this (raise an issue or post to the mailing list), so that
4964  * we can add a solution to your problem that will be
4965  * guaranteed to work in the future.
4966  *
4967  * \param ssl SSL context
4968  *
4969  * \return See mbedtls_ssl_handshake().
4970  *
4971  * \warning If this function returns something other than \c 0,
4972  * #MBEDTLS_ERR_SSL_WANT_READ, #MBEDTLS_ERR_SSL_WANT_WRITE,
4973  * #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS,
4974  * #MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS or
4975  * #MBEDTLS_ERR_SSL_RECEIVED_EARLY_DATA, you must stop using
4976  * the SSL context for reading or writing, and either free it
4977  * or call \c mbedtls_ssl_session_reset() on it before
4978  * re-using it for a new connection; the current connection
4979  * must be closed.
4980  */
4982 
4983 #if defined(MBEDTLS_SSL_RENEGOTIATION)
4984 /**
4985  * \brief Initiate an SSL renegotiation on the running connection.
4986  * Client: perform the renegotiation right now.
4987  * Server: request renegotiation, which will be performed
4988  * during the next call to mbedtls_ssl_read() if honored by
4989  * client.
4990  *
4991  * \param ssl SSL context
4992  *
4993  * \return 0 if successful, or any mbedtls_ssl_handshake() return
4994  * value except #MBEDTLS_ERR_SSL_CLIENT_RECONNECT that can't
4995  * happen during a renegotiation.
4996  *
4997  * \warning If this function returns something other than \c 0,
4998  * #MBEDTLS_ERR_SSL_WANT_READ, #MBEDTLS_ERR_SSL_WANT_WRITE,
4999  * #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS or
5000  * #MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS, you must stop using
5001  * the SSL context for reading or writing, and either free it
5002  * or call \c mbedtls_ssl_session_reset() on it before
5003  * re-using it for a new connection; the current connection
5004  * must be closed.
5005  *
5006  */
5008 #endif /* MBEDTLS_SSL_RENEGOTIATION */
5009 
5010 /**
5011  * \brief Read at most 'len' application data bytes
5012  *
5013  * \param ssl SSL context
5014  * \param buf buffer that will hold the data
5015  * \param len maximum number of bytes to read
5016  *
5017  * \return The (positive) number of bytes read if successful.
5018  * \return \c 0 if the read end of the underlying transport was closed
5019  * without sending a CloseNotify beforehand, which might happen
5020  * because of various reasons (internal error of an underlying
5021  * stack, non-conformant peer not sending a CloseNotify and
5022  * such) - in this case you must stop using the context
5023  * (see below).
5024  * \return #MBEDTLS_ERR_SSL_PEER_CLOSE_NOTIFY if the underlying
5025  * transport is still functional, but the peer has
5026  * acknowledged to not send anything anymore.
5027  * \return #MBEDTLS_ERR_SSL_WANT_READ or #MBEDTLS_ERR_SSL_WANT_WRITE
5028  * if the handshake is incomplete and waiting for data to
5029  * be available for reading from or writing to the underlying
5030  * transport - in this case you must call this function again
5031  * when the underlying transport is ready for the operation.
5032  * \return #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS if an asynchronous
5033  * operation is in progress (see
5034  * mbedtls_ssl_conf_async_private_cb()) - in this case you
5035  * must call this function again when the operation is ready.
5036  * \return #MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS if a cryptographic
5037  * operation is in progress (see mbedtls_ecp_set_max_ops()) -
5038  * in this case you must call this function again to complete
5039  * the handshake when you're done attending other tasks.
5040  * \return #MBEDTLS_ERR_SSL_CLIENT_RECONNECT if we're at the server
5041  * side of a DTLS connection and the client is initiating a
5042  * new connection using the same source port. See below.
5043  * \return #MBEDTLS_ERR_SSL_RECEIVED_EARLY_DATA if early data, as
5044  * defined in RFC 8446 (TLS 1.3 specification), has been
5045  * received as part of the handshake. This is server specific
5046  * and may occur only if the early data feature has been
5047  * enabled on server (see mbedtls_ssl_conf_early_data()
5048  * documentation). You must call mbedtls_ssl_read_early_data()
5049  * to read the early data before resuming the handshake.
5050  * \return Another SSL error code - in this case you must stop using
5051  * the context (see below).
5052  *
5053  * \warning If this function returns something other than
5054  * a positive value,
5055  * #MBEDTLS_ERR_SSL_WANT_READ,
5056  * #MBEDTLS_ERR_SSL_WANT_WRITE,
5057  * #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS,
5058  * #MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS,
5059  * #MBEDTLS_ERR_SSL_CLIENT_RECONNECT or
5060  * #MBEDTLS_ERR_SSL_RECEIVED_EARLY_DATA,
5061  * you must stop using the SSL context for reading or writing,
5062  * and either free it or call \c mbedtls_ssl_session_reset()
5063  * on it before re-using it for a new connection; the current
5064  * connection must be closed.
5065  *
5066  * \note When this function returns #MBEDTLS_ERR_SSL_CLIENT_RECONNECT
5067  * (which can only happen server-side), it means that a client
5068  * is initiating a new connection using the same source port.
5069  * You can either treat that as a connection close and wait
5070  * for the client to resend a ClientHello, or directly
5071  * continue with \c mbedtls_ssl_handshake() with the same
5072  * context (as it has been reset internally). Either way, you
5073  * must make sure this is seen by the application as a new
5074  * connection: application state, if any, should be reset, and
5075  * most importantly the identity of the client must be checked
5076  * again. WARNING: not validating the identity of the client
5077  * again, or not transmitting the new identity to the
5078  * application layer, would allow authentication bypass!
5079  *
5080  * \note Remarks regarding event-driven DTLS:
5081  * - If the function returns #MBEDTLS_ERR_SSL_WANT_READ, no datagram
5082  * from the underlying transport layer is currently being processed,
5083  * and it is safe to idle until the timer or the underlying transport
5084  * signal a new event.
5085  * - This function may return MBEDTLS_ERR_SSL_WANT_READ even if data was
5086  * initially available on the underlying transport, as this data may have
5087  * been only e.g. duplicated messages or a renegotiation request.
5088  * Therefore, you must be prepared to receive MBEDTLS_ERR_SSL_WANT_READ even
5089  * when reacting to an incoming-data event from the underlying transport.
5090  * - On success, the datagram of the underlying transport that is currently
5091  * being processed may contain further DTLS records. You should call
5092  * \c mbedtls_ssl_check_pending to check for remaining records.
5093  *
5094  */
5095 int mbedtls_ssl_read(mbedtls_ssl_context *ssl, unsigned char *buf, size_t len);
5096 
5097 /**
5098  * \brief Try to write exactly 'len' application data bytes
5099  *
5100  * \warning This function will do partial writes in some cases. If the
5101  * return value is non-negative but less than length, the
5102  * function must be called again with updated arguments:
5103  * buf + ret, len - ret (if ret is the return value) until
5104  * it returns a value equal to the last 'len' argument.
5105  *
5106  * \param ssl SSL context
5107  * \param buf buffer holding the data
5108  * \param len how many bytes must be written
5109  *
5110  * \return The (non-negative) number of bytes actually written if
5111  * successful (may be less than \p len).
5112  * \return #MBEDTLS_ERR_SSL_WANT_READ or #MBEDTLS_ERR_SSL_WANT_WRITE
5113  * if the handshake is incomplete and waiting for data to
5114  * be available for reading from or writing to the underlying
5115  * transport - in this case you must call this function again
5116  * when the underlying transport is ready for the operation.
5117  * \return #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS if an asynchronous
5118  * operation is in progress (see
5119  * mbedtls_ssl_conf_async_private_cb()) - in this case you
5120  * must call this function again when the operation is ready.
5121  * \return #MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS if a cryptographic
5122  * operation is in progress (see mbedtls_ecp_set_max_ops()) -
5123  * in this case you must call this function again to complete
5124  * the handshake when you're done attending other tasks.
5125  * \return #MBEDTLS_ERR_SSL_RECEIVED_EARLY_DATA if early data, as
5126  * defined in RFC 8446 (TLS 1.3 specification), has been
5127  * received as part of the handshake. This is server specific
5128  * and may occur only if the early data feature has been
5129  * enabled on server (see mbedtls_ssl_conf_early_data()
5130  * documentation). You must call mbedtls_ssl_read_early_data()
5131  * to read the early data before resuming the handshake.
5132  * \return Another SSL error code - in this case you must stop using
5133  * the context (see below).
5134  *
5135  * \warning If this function returns something other than
5136  * a non-negative value,
5137  * #MBEDTLS_ERR_SSL_WANT_READ,
5138  * #MBEDTLS_ERR_SSL_WANT_WRITE,
5139  * #MBEDTLS_ERR_SSL_ASYNC_IN_PROGRESS,
5140  * #MBEDTLS_ERR_SSL_CRYPTO_IN_PROGRESS or
5141  * #MBEDTLS_ERR_SSL_RECEIVED_EARLY_DATA,
5142  * you must stop using the SSL context for reading or writing,
5143  * and either free it or call \c mbedtls_ssl_session_reset()
5144  * on it before re-using it for a new connection; the current
5145  * connection must be closed.
5146  *
5147  * \note When this function returns #MBEDTLS_ERR_SSL_WANT_WRITE/READ,
5148  * it must be called later with the *same* arguments,
5149  * until it returns a value greater than or equal to 0. When
5150  * the function returns #MBEDTLS_ERR_SSL_WANT_WRITE there may be
5151  * some partial data in the output buffer, however this is not
5152  * yet sent.
5153  *
5154  * \note If the requested length is greater than the maximum
5155  * fragment length (either the built-in limit or the one set
5156  * or negotiated with the peer), then:
5157  * - with TLS, less bytes than requested are written.
5158  * - with DTLS, MBEDTLS_ERR_SSL_BAD_INPUT_DATA is returned.
5159  * \c mbedtls_ssl_get_max_out_record_payload() may be used to
5160  * query the active maximum fragment length.
5161  *
5162  * \note Attempting to write 0 bytes will result in an empty TLS
5163  * application record being sent.
5164  */
5165 int mbedtls_ssl_write(mbedtls_ssl_context *ssl, const unsigned char *buf, size_t len);
5166 
5167 /**
5168  * \brief Send an alert message
5169  *
5170  * \param ssl SSL context
5171  * \param level The alert level of the message
5172  * (MBEDTLS_SSL_ALERT_LEVEL_WARNING or MBEDTLS_SSL_ALERT_LEVEL_FATAL)
5173  * \param message The alert message (SSL_ALERT_MSG_*)
5174  *
5175  * \return 0 if successful, or a specific SSL error code.
5176  *
5177  * \note If this function returns something other than 0 or
5178  * MBEDTLS_ERR_SSL_WANT_READ/WRITE, you must stop using
5179  * the SSL context for reading or writing, and either free it or
5180  * call \c mbedtls_ssl_session_reset() on it before re-using it
5181  * for a new connection; the current connection must be closed.
5182  */
5184  unsigned char level,
5185  unsigned char message);
5186 /**
5187  * \brief Notify the peer that the connection is being closed
5188  *
5189  * \param ssl SSL context
5190  *
5191  * \return 0 if successful, or a specific SSL error code.
5192  *
5193  * \note If this function returns something other than 0 or
5194  * MBEDTLS_ERR_SSL_WANT_READ/WRITE, you must stop using
5195  * the SSL context for reading or writing, and either free it or
5196  * call \c mbedtls_ssl_session_reset() on it before re-using it
5197  * for a new connection; the current connection must be closed.
5198  */
5200 
5201 #if defined(MBEDTLS_SSL_EARLY_DATA)
5202 
5203 #if defined(MBEDTLS_SSL_SRV_C)
5204 /**
5205  * \brief Read at most 'len' bytes of early data
5206  *
5207  * \note This API is server specific.
5208  *
5209  * \warning Early data is defined in the TLS 1.3 specification, RFC 8446.
5210  * IMPORTANT NOTE from section 2.3 of the specification:
5211  *
5212  * The security properties for 0-RTT data are weaker than
5213  * those for other kinds of TLS data. Specifically:
5214  * - This data is not forward secret, as it is encrypted
5215  * solely under keys derived using the offered PSK.
5216  * - There are no guarantees of non-replay between connections.
5217  * Protection against replay for ordinary TLS 1.3 1-RTT data
5218  * is provided via the server's Random value, but 0-RTT data
5219  * does not depend on the ServerHello and therefore has
5220  * weaker guarantees. This is especially relevant if the
5221  * data is authenticated either with TLS client
5222  * authentication or inside the application protocol. The
5223  * same warnings apply to any use of the
5224  * early_exporter_master_secret.
5225  *
5226  * \warning Mbed TLS does not implement any of the anti-replay defenses
5227  * defined in section 8 of the TLS 1.3 specification:
5228  * single-use of tickets or ClientHello recording within a
5229  * given time window.
5230  *
5231  * \note This function is used in conjunction with
5232  * mbedtls_ssl_handshake(), mbedtls_ssl_handshake_step(),
5233  * mbedtls_ssl_read() and mbedtls_ssl_write() to read early
5234  * data when these functions return
5235  * #MBEDTLS_ERR_SSL_RECEIVED_EARLY_DATA.
5236  *
5237  * \param ssl SSL context, it must have been initialized and set up.
5238  * \param buf buffer that will hold the data
5239  * \param len maximum number of bytes to read
5240  *
5241  * \return The (positive) number of bytes read if successful.
5242  * \return #MBEDTLS_ERR_SSL_BAD_INPUT_DATA if input data is invalid.
5243  * \return #MBEDTLS_ERR_SSL_CANNOT_READ_EARLY_DATA if it is not
5244  * possible to read early data for the SSL context \p ssl. Note
5245  * that this function is intended to be called for an SSL
5246  * context \p ssl only after a call to mbedtls_ssl_handshake(),
5247  * mbedtls_ssl_handshake_step(), mbedtls_ssl_read() or
5248  * mbedtls_ssl_write() for \p ssl that has returned
5249  * #MBEDTLS_ERR_SSL_RECEIVED_EARLY_DATA.
5250  */
5251 int mbedtls_ssl_read_early_data(mbedtls_ssl_context *ssl,
5252  unsigned char *buf, size_t len);
5253 #endif /* MBEDTLS_SSL_SRV_C */
5254 
5255 #if defined(MBEDTLS_SSL_CLI_C)
5256 /**
5257  * \brief Try to write exactly 'len' application data bytes while
5258  * performing the handshake (early data).
5259  *
5260  * \warning Early data is defined in the TLS 1.3 specification, RFC 8446.
5261  * IMPORTANT NOTE from section 2.3 of the specification:
5262  *
5263  * The security properties for 0-RTT data are weaker than
5264  * those for other kinds of TLS data. Specifically:
5265  * - This data is not forward secret, as it is encrypted
5266  * solely under keys derived using the offered PSK.
5267  * - There are no guarantees of non-replay between connections.
5268  * Protection against replay for ordinary TLS 1.3 1-RTT data
5269  * is provided via the server's Random value, but 0-RTT data
5270  * does not depend on the ServerHello and therefore has
5271  * weaker guarantees. This is especially relevant if the
5272  * data is authenticated either with TLS client
5273  * authentication or inside the application protocol. The
5274  * same warnings apply to any use of the
5275  * early_exporter_master_secret.
5276  *
5277  * \note This function behaves mainly as mbedtls_ssl_write(). The
5278  * specification of mbedtls_ssl_write() relevant to TLS 1.3
5279  * (thus not the parts specific to (D)TLS1.2) applies to this
5280  * function and the present documentation is mainly restricted
5281  * to the differences with mbedtls_ssl_write(). One noticeable
5282  * difference though is that mbedtls_ssl_write() aims to
5283  * complete the handshake before to write application data
5284  * while mbedtls_ssl_write_early() aims to drive the handshake
5285  * just past the point where it is not possible to send early
5286  * data anymore.
5287  *
5288  * \param ssl SSL context
5289  * \param buf buffer holding the data
5290  * \param len how many bytes must be written
5291  *
5292  * \return The (non-negative) number of bytes actually written if
5293  * successful (may be less than \p len).
5294  *
5295  * \return One additional specific error code compared to
5296  * mbedtls_ssl_write():
5297  * #MBEDTLS_ERR_SSL_CANNOT_WRITE_EARLY_DATA.
5298  *
5299  * #MBEDTLS_ERR_SSL_CANNOT_WRITE_EARLY_DATA is returned when it
5300  * is not possible to write early data for the SSL context
5301  * \p ssl.
5302  *
5303  * It may have been possible and it is not possible
5304  * anymore because the client received the server Finished
5305  * message, the server rejected early data or the maximum
5306  * number of allowed early data for the PSK in use has been
5307  * reached.
5308  *
5309  * It may never have been possible and will never be possible
5310  * for the SSL context \p ssl because the use of early data
5311  * is disabled for that context or more generally the context
5312  * is not suitably configured to enable early data or the first
5313  * call to the function was done while the handshake was
5314  * already completed.
5315  *
5316  * It is not possible to write early data for the SSL context
5317  * \p ssl and any subsequent call to this API will return this
5318  * error code. But this does not preclude for using it with
5319  * mbedtls_ssl_write(), mbedtls_ssl_read() or
5320  * mbedtls_ssl_handshake() and the handshake can be
5321  * completed by calling one of these APIs.
5322  *
5323  * \note This function may write early data only if the SSL context
5324  * has been configured for the handshake with a PSK for which
5325  * early data is allowed.
5326  *
5327  * \note To maximize the number of early data that can be written in
5328  * the course of the handshake, it is expected that this
5329  * function starts the handshake for the SSL context \p ssl.
5330  * But this is not mandatory.
5331  *
5332  * \note This function does not provide any information on whether
5333  * the server has accepted or will accept early data or not.
5334  * When it returns a positive value, it just means that it
5335  * has written early data to the server. To know whether the
5336  * server has accepted early data or not, you should call
5337  * mbedtls_ssl_get_early_data_status() with the handshake
5338  * completed.
5339  */
5340 int mbedtls_ssl_write_early_data(mbedtls_ssl_context *ssl,
5341  const unsigned char *buf, size_t len);
5342 
5343 /**
5344  * \brief Get the status of the negotiation of the use of early data.
5345  *
5346  * \param ssl The SSL context to query
5347  *
5348  * \return #MBEDTLS_ERR_SSL_BAD_INPUT_DATA if this function is called
5349  * from the server-side.
5350  *
5351  * \return #MBEDTLS_ERR_SSL_BAD_INPUT_DATA if this function is called
5352  * prior to completion of the handshake.
5353  *
5354  * \return #MBEDTLS_SSL_EARLY_DATA_STATUS_NOT_INDICATED if the client
5355  * has not indicated the use of early data to the server.
5356  *
5357  * \return #MBEDTLS_SSL_EARLY_DATA_STATUS_ACCEPTED if the client has
5358  * indicated the use of early data and the server has accepted
5359  * it.
5360  *
5361  * \return #MBEDTLS_SSL_EARLY_DATA_STATUS_REJECTED if the client has
5362  * indicated the use of early data but the server has rejected
5363  * it. In this situation, the client may want to re-send the
5364  * early data it may have tried to send by calling
5365  * mbedtls_ssl_write_early_data() as ordinary post-handshake
5366  * application data by calling mbedtls_ssl_write().
5367  *
5368  */
5369 int mbedtls_ssl_get_early_data_status(mbedtls_ssl_context *ssl);
5370 #endif /* MBEDTLS_SSL_CLI_C */
5371 
5372 #endif /* MBEDTLS_SSL_EARLY_DATA */
5373 
5374 /**
5375  * \brief Free referenced items in an SSL context and clear memory
5376  *
5377  * \param ssl SSL context
5378  */
5380 
5381 #if defined(MBEDTLS_SSL_CONTEXT_SERIALIZATION)
5382 /**
5383  * \brief Save an active connection as serialized data in a buffer.
5384  * This allows the freeing or re-using of the SSL context
5385  * while still picking up the connection later in a way that
5386  * it entirely transparent to the peer.
5387  *
5388  * \see mbedtls_ssl_context_load()
5389  *
5390  * \note The serialized data only contains the data that is
5391  * necessary to resume the connection: negotiated protocol
5392  * options, session identifier, keys, etc.
5393  * Loading a saved SSL context does not restore settings and
5394  * state related to how the application accesses the context,
5395  * such as configured callback functions, user data, pending
5396  * incoming or outgoing data, etc.
5397  *
5398  * \note This feature is currently only available under certain
5399  * conditions, see the documentation of the return value
5400  * #MBEDTLS_ERR_SSL_BAD_INPUT_DATA for details.
5401  *
5402  * \note When this function succeeds, it calls
5403  * mbedtls_ssl_session_reset() on \p ssl which as a result is
5404  * no longer associated with the connection that has been
5405  * serialized. This avoids creating copies of the connection
5406  * state. You're then free to either re-use the context
5407  * structure for a different connection, or call
5408  * mbedtls_ssl_free() on it. See the documentation of
5409  * mbedtls_ssl_session_reset() for more details.
5410  *
5411  * \param ssl The SSL context to save. On success, it is no longer
5412  * associated with the connection that has been serialized.
5413  * \param buf The buffer to write the serialized data to. It must be a
5414  * writeable buffer of at least \p buf_len bytes, or may be \c
5415  * NULL if \p buf_len is \c 0.
5416  * \param buf_len The number of bytes available for writing in \p buf.
5417  * \param olen The size in bytes of the data that has been or would have
5418  * been written. It must point to a valid \c size_t.
5419  *
5420  * \note \p olen is updated to the correct value regardless of
5421  * whether \p buf_len was large enough. This makes it possible
5422  * to determine the necessary size by calling this function
5423  * with \p buf set to \c NULL and \p buf_len to \c 0. However,
5424  * the value of \p olen is only guaranteed to be correct when
5425  * the function returns #MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL or
5426  * \c 0. If the return value is different, then the value of
5427  * \p olen is undefined.
5428  *
5429  * \return \c 0 if successful.
5430  * \return #MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL if \p buf is too small.
5431  * \return #MBEDTLS_ERR_SSL_ALLOC_FAILED if memory allocation failed
5432  * while resetting the context.
5433  * \return #MBEDTLS_ERR_SSL_BAD_INPUT_DATA if a handshake is in
5434  * progress, or there is pending data for reading or sending,
5435  * or the connection does not use DTLS 1.2 with an AEAD
5436  * ciphersuite, or renegotiation is enabled.
5437  */
5439  unsigned char *buf,
5440  size_t buf_len,
5441  size_t *olen);
5442 
5443 /**
5444  * \brief Load serialized connection data to an SSL context.
5445  *
5446  * \see mbedtls_ssl_context_save()
5447  *
5448  * \warning The same serialized data must never be loaded into more
5449  * that one context. In order to ensure that, after
5450  * successfully loading serialized data to an SSL context, you
5451  * should immediately destroy or invalidate all copies of the
5452  * serialized data that was loaded. Loading the same data in
5453  * more than one context would cause severe security failures
5454  * including but not limited to loss of confidentiality.
5455  *
5456  * \note Before calling this function, the SSL context must be
5457  * prepared in one of the two following ways. The first way is
5458  * to take a context freshly initialised with
5459  * mbedtls_ssl_init() and call mbedtls_ssl_setup() on it with
5460  * the same ::mbedtls_ssl_config structure that was used in
5461  * the original connection. The second way is to
5462  * call mbedtls_ssl_session_reset() on a context that was
5463  * previously prepared as above but used in the meantime.
5464  * Either way, you must not use the context to perform a
5465  * handshake between calling mbedtls_ssl_setup() or
5466  * mbedtls_ssl_session_reset() and calling this function. You
5467  * may however call other setter functions in that time frame
5468  * as indicated in the note below.
5469  *
5470  * \note Before or after calling this function successfully, you
5471  * also need to configure some connection-specific callbacks
5472  * and settings before you can use the connection again
5473  * (unless they were already set before calling
5474  * mbedtls_ssl_session_reset() and the values are suitable for
5475  * the present connection). Specifically, you want to call
5476  * at least mbedtls_ssl_set_bio(),
5477  * mbedtls_ssl_set_timer_cb(), and
5478  * mbedtls_ssl_set_user_data_n() or
5479  * mbedtls_ssl_set_user_data_p() if they were set originally.
5480  * All other SSL setter functions
5481  * are not necessary to call, either because they're only used
5482  * in handshakes, or because the setting is already saved. You
5483  * might choose to call them anyway, for example in order to
5484  * share code between the cases of establishing a new
5485  * connection and the case of loading an already-established
5486  * connection.
5487  *
5488  * \note If you have new information about the path MTU, you want to
5489  * call mbedtls_ssl_set_mtu() after calling this function, as
5490  * otherwise this function would overwrite your
5491  * newly-configured value with the value that was active when
5492  * the context was saved.
5493  *
5494  * \note When this function returns an error code, it calls
5495  * mbedtls_ssl_free() on \p ssl. In this case, you need to
5496  * prepare the context with the usual sequence starting with a
5497  * call to mbedtls_ssl_init() if you want to use it again.
5498  *
5499  * \param ssl The SSL context structure to be populated. It must have
5500  * been prepared as described in the note above.
5501  * \param buf The buffer holding the serialized connection data. It must
5502  * be a readable buffer of at least \p len bytes.
5503  * \param len The size of the serialized data in bytes.
5504  *
5505  * \return \c 0 if successful.
5506  * \return #MBEDTLS_ERR_SSL_ALLOC_FAILED if memory allocation failed.
5507  * \return #MBEDTLS_ERR_SSL_VERSION_MISMATCH if the serialized data
5508  * comes from a different Mbed TLS version or build.
5509  * \return #MBEDTLS_ERR_SSL_BAD_INPUT_DATA if input data is invalid.
5510  */
5512  const unsigned char *buf,
5513  size_t len);
5514 #endif /* MBEDTLS_SSL_CONTEXT_SERIALIZATION */
5515 
5516 /**
5517  * \brief Initialize an SSL configuration context
5518  * Just makes the context ready for
5519  * mbedtls_ssl_config_defaults() or mbedtls_ssl_config_free().
5520  *
5521  * \note You need to call mbedtls_ssl_config_defaults() unless you
5522  * manually set all of the relevant fields yourself.
5523  *
5524  * \param conf SSL configuration context
5525  */
5527 
5528 /**
5529  * \brief Load reasonable default SSL configuration values.
5530  * (You need to call mbedtls_ssl_config_init() first.)
5531  *
5532  * \param conf SSL configuration context
5533  * \param endpoint MBEDTLS_SSL_IS_CLIENT or MBEDTLS_SSL_IS_SERVER
5534  * \param transport MBEDTLS_SSL_TRANSPORT_STREAM for TLS, or
5535  * MBEDTLS_SSL_TRANSPORT_DATAGRAM for DTLS
5536  * \param preset a MBEDTLS_SSL_PRESET_XXX value
5537  *
5538  * \note See \c mbedtls_ssl_conf_transport() for notes on DTLS.
5539  *
5540  * \return 0 if successful, or
5541  * MBEDTLS_ERR_XXX_ALLOC_FAILED on memory allocation error.
5542  */
5544  int endpoint, int transport, int preset);
5545 
5546 /**
5547  * \brief Free an SSL configuration context
5548  *
5549  * \param conf SSL configuration context
5550  */
5552 
5553 /**
5554  * \brief Initialize SSL session structure
5555  *
5556  * \param session SSL session
5557  */
5559 
5560 /**
5561  * \brief Free referenced items in an SSL session including the
5562  * peer certificate and clear memory
5563  *
5564  * \note A session object can be freed even if the SSL context
5565  * that was used to retrieve the session is still in use.
5566  *
5567  * \param session SSL session
5568  */
5570 
5571 /**
5572  * \brief TLS-PRF function for key derivation.
5573  *
5574  * \param prf The tls_prf type function type to be used.
5575  * \param secret Secret for the key derivation function.
5576  * \param slen Length of the secret.
5577  * \param label String label for the key derivation function,
5578  * terminated with null character.
5579  * \param random Random bytes.
5580  * \param rlen Length of the random bytes buffer.
5581  * \param dstbuf The buffer holding the derived key.
5582  * \param dlen Length of the output buffer.
5583  *
5584  * \return 0 on success. An SSL specific error on failure.
5585  */
5587  const unsigned char *secret, size_t slen,
5588  const char *label,
5589  const unsigned char *random, size_t rlen,
5590  unsigned char *dstbuf, size_t dlen);
5591 
5592 #ifdef __cplusplus
5593 }
5594 #endif
5595 
5596 #endif /* ssl.h */
Multi-precision integer library.
#define MBEDTLS_MPI_MAX_SIZE
Maximum number of bytes for usable MPIs.
Definition: bignum.h:73
void transform(Container &c, UnaryFunction *op)
Definition: chainer.hpp:86
Platform Security Architecture cryptography module.
This file contains Diffie-Hellman-Merkle (DHM) key exchange definitions and functions.
This file contains ECDH definitions and functions.
This file provides an API for Elliptic Curves over GF(P) (ECP).
#define MBEDTLS_ECP_MAX_BYTES
Definition: ecp.h:354
mbedtls_ecp_group_id
Domain-parameter identifiers: curve, subgroup, and generator.
Definition: ecp.h:102
CS_CONTEXT * ctx
Definition: t0006.c:12
static SQLCHAR output[256]
Definition: print.c:5
char data[12]
Definition: iconv.c:80
Uint8 uint64_t
unsigned char uint8_t
Uint2 uint16_t
Uint4 uint32_t
#define NULL
Definition: ncbistd.hpp:225
unsigned int uintptr_t
Definition: ncbitype.h:197
static const char label[]
psa_key_id_t mbedtls_svc_key_id_t
Encoding of key identifiers as seen inside the PSA Crypto implementation.
Definition: crypto_types.h:292
unsigned int
A callback function used to compare two keys in a database.
Definition: types.hpp:1210
char * buf
static int input()
yy_size_t n
int len
Build-time configuration info.
This file contains the generic functions for message-digest (hashing) and HMAC.
mbedtls_md_type_t
Supported message digests.
Definition: md.h:47
static MDB_envinfo info
Definition: mdb_load.c:37
mdb_mode_t mode
Definition: lmdb++.h:38
#define mbedtls_ssl_conf_renegotiation
#define mbedtls_ssl_conf_sni
#define mbedtls_ssl_conf_cert_req_ca_list
#define mbedtls_ssl_conf_dh_param_ctx
#define mbedtls_ssl_conf_psk_cb
#define mbedtls_ssl_conf_curves
#define mbedtls_ssl_conf_extended_master_secret
#define mbedtls_ssl_set_cid
#define mbedtls_ssl_conf_ca_chain
#define mbedtls_ssl_conf_tls13_key_exchange_modes
#define mbedtls_ssl_conf_own_cert
#define mbedtls_ssl_set_verify
#define mbedtls_ssl_set_hostname
#define mbedtls_ssl_conf_session_tickets_cb
#define mbedtls_ssl_conf_psk
#define mbedtls_ssl_set_hs_authmode
#define mbedtls_ssl_set_client_transport_id
#define mbedtls_ssl_conf_session_cache
#define mbedtls_ssl_get_session
#define mbedtls_ssl_conf_cid
#define mbedtls_ssl_context_save
#define mbedtls_ssl_conf_new_session_tickets
#define mbedtls_ssl_conf_encrypt_then_mac
Definition: