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
20 #include "mbedtls/ssl_ciphersuites.h"
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 */
655 union mbedtls_ssl_premaster_secret {
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 {
704 MBEDTLS_SSL_HELLO_REQUEST,
705 MBEDTLS_SSL_CLIENT_HELLO,
706 MBEDTLS_SSL_SERVER_HELLO,
707 MBEDTLS_SSL_SERVER_CERTIFICATE,
708 MBEDTLS_SSL_SERVER_KEY_EXCHANGE,
709 MBEDTLS_SSL_CERTIFICATE_REQUEST,
710 MBEDTLS_SSL_SERVER_HELLO_DONE,
711 MBEDTLS_SSL_CLIENT_CERTIFICATE,
712 MBEDTLS_SSL_CLIENT_KEY_EXCHANGE,
713 MBEDTLS_SSL_CERTIFICATE_VERIFY,
714 MBEDTLS_SSL_CLIENT_CHANGE_CIPHER_SPEC,
715 MBEDTLS_SSL_CLIENT_FINISHED,
716 MBEDTLS_SSL_SERVER_CHANGE_CIPHER_SPEC,
717 MBEDTLS_SSL_SERVER_FINISHED,
718 MBEDTLS_SSL_FLUSH_BUFFERS,
719 MBEDTLS_SSL_HANDSHAKE_WRAPUP,
720 MBEDTLS_SSL_NEW_SESSION_TICKET,
721 MBEDTLS_SSL_SERVER_HELLO_VERIFY_REQUEST_SENT,
722 MBEDTLS_SSL_HELLO_RETRY_REQUEST,
723 MBEDTLS_SSL_ENCRYPTED_EXTENSIONS,
724 MBEDTLS_SSL_END_OF_EARLY_DATA,
725 MBEDTLS_SSL_CLIENT_CERTIFICATE_VERIFY,
726 MBEDTLS_SSL_CLIENT_CCS_AFTER_SERVER_FINISHED,
727 MBEDTLS_SSL_CLIENT_CCS_BEFORE_2ND_CLIENT_HELLO,
728 MBEDTLS_SSL_SERVER_CCS_AFTER_SERVER_HELLO,
729 MBEDTLS_SSL_CLIENT_CCS_AFTER_CLIENT_HELLO,
730 MBEDTLS_SSL_SERVER_CCS_AFTER_HELLO_RETRY_REQUEST,
731 MBEDTLS_SSL_HANDSHAKE_OVER,
732 MBEDTLS_SSL_TLS1_3_NEW_SESSION_TICKET,
733 MBEDTLS_SSL_TLS1_3_NEW_SESSION_TICKET_FLUSH,
734 }
735 mbedtls_ssl_states;
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 */
863 typedef struct mbedtls_ssl_session mbedtls_ssl_session;
864 typedef struct mbedtls_ssl_context mbedtls_ssl_context;
865 typedef struct mbedtls_ssl_config mbedtls_ssl_config;
866
867 /* Defined in library/ssl_misc.h */
868 typedef struct mbedtls_ssl_transform mbedtls_ssl_transform;
869 typedef struct mbedtls_ssl_handshake_params mbedtls_ssl_handshake_params;
870 typedef struct mbedtls_ssl_sig_hash_set_t mbedtls_ssl_sig_hash_set_t;
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];
1177 } mbedtls_ssl_tls13_application_secrets;
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 */
1218 } mbedtls_ssl_protocol_version;
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 */
1231 struct mbedtls_ssl_session {
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 */
1247 mbedtls_ssl_protocol_version MBEDTLS_PRIVATE(tls_version);
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)
1327 mbedtls_ssl_tls13_application_secrets MBEDTLS_PRIVATE(app_secrets);
1328 #endif
1329 };
1330
1331 /*
1332 * Identifiers for PRFs used in various versions of TLS.
1333 */
1334 typedef enum {
1335 MBEDTLS_SSL_TLS_PRF_NONE,
1336 MBEDTLS_SSL_TLS_PRF_SHA384,
1337 MBEDTLS_SSL_TLS_PRF_SHA256,
1338 MBEDTLS_SSL_HKDF_EXPAND_SHA384,
1339 MBEDTLS_SSL_HKDF_EXPAND_SHA256
1340 }
1341 mbedtls_tls_prf_types;
1342
1343 typedef enum {
1344 MBEDTLS_SSL_KEY_EXPORT_TLS12_MASTER_SECRET = 0,
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 */
1353 } mbedtls_ssl_key_export_type;
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,
1371 mbedtls_ssl_key_export_type type,
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 */
1406 } mbedtls_ssl_user_data_t;
1407
1408 /**
1409 * SSL/TLS configuration to be shared between mbedtls_ssl_context structures.
1410 */
1411 struct mbedtls_ssl_config {
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 */
1496 mbedtls_ssl_cache_get_t *MBEDTLS_PRIVATE(f_get_cache);
1497 /** Callback to store a session into the cache */
1498 mbedtls_ssl_cache_set_t *MBEDTLS_PRIVATE(f_set_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 */
1670 mbedtls_ssl_user_data_t MBEDTLS_PRIVATE(user_data);
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
1681 struct mbedtls_ssl_context {
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 */
1711 mbedtls_ssl_protocol_version MBEDTLS_PRIVATE(tls_version);
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 */
1731 mbedtls_ssl_recv_timeout_t *MBEDTLS_PRIVATE(f_recv_timeout);
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 */
1932 mbedtls_ssl_export_keys_t *MBEDTLS_PRIVATE(f_export_keys);
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 */
1944 mbedtls_ssl_user_data_t MBEDTLS_PRIVATE(user_data);
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 */
1974 void mbedtls_ssl_init(mbedtls_ssl_context *ssl);
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 */
2000 int mbedtls_ssl_setup(mbedtls_ssl_context *ssl,
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 */
2012 int mbedtls_ssl_session_reset(mbedtls_ssl_context *ssl);
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 */
2020 void mbedtls_ssl_conf_endpoint(mbedtls_ssl_config *conf, int endpoint);
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 */
mbedtls_ssl_conf_get_endpoint(const mbedtls_ssl_config * conf)2030 static inline int mbedtls_ssl_conf_get_endpoint(const mbedtls_ssl_config *conf)
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 */
2049 void mbedtls_ssl_conf_transport(mbedtls_ssl_config *conf, int transport);
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 */
2077 void mbedtls_ssl_conf_authmode(mbedtls_ssl_config *conf, int authmode);
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 */
2156 void mbedtls_ssl_conf_verify(mbedtls_ssl_config *conf,
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 */
2168 void mbedtls_ssl_conf_rng(mbedtls_ssl_config *conf,
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 */
2186 void mbedtls_ssl_conf_dbg(mbedtls_ssl_config *conf,
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 */
mbedtls_ssl_context_get_config(const mbedtls_ssl_context * ssl)2200 static inline const mbedtls_ssl_config *mbedtls_ssl_context_get_config(
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 */
2236 void mbedtls_ssl_set_bio(mbedtls_ssl_context *ssl,
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 */
2331 int mbedtls_ssl_set_cid(mbedtls_ssl_context *ssl,
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 */
2365 int mbedtls_ssl_get_own_cid(mbedtls_ssl_context *ssl,
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 */
2407 int mbedtls_ssl_get_peer_cid(mbedtls_ssl_context *ssl,
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 */
2453 void mbedtls_ssl_set_mtu(mbedtls_ssl_context *ssl, uint16_t mtu);
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 */
2475 void mbedtls_ssl_set_verify(mbedtls_ssl_context *ssl,
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 */
2496 void mbedtls_ssl_conf_read_timeout(mbedtls_ssl_config *conf, uint32_t timeout);
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 */
2542 int mbedtls_ssl_check_record(mbedtls_ssl_context const *ssl,
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 */
2566 void mbedtls_ssl_set_timer_cb(mbedtls_ssl_context *ssl,
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 */
mbedtls_ssl_conf_cert_cb(mbedtls_ssl_config * conf,mbedtls_ssl_hs_cb_t f_cert_cb)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 */
2658 void mbedtls_ssl_conf_session_tickets_cb(mbedtls_ssl_config *conf,
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 */
mbedtls_ssl_session_get_ticket_creation_time(mbedtls_ssl_session * session,mbedtls_ms_time_t * ticket_creation_time)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) {
2682 return MBEDTLS_ERR_SSL_BAD_INPUT_DATA;
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 */
mbedtls_ssl_session_get_id(const mbedtls_ssl_session * session)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 */
mbedtls_ssl_session_get_id_len(const mbedtls_ssl_session * session)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 */
mbedtls_ssl_session_get_ciphersuite_id(const mbedtls_ssl_session * session)2724 static inline int mbedtls_ssl_session_get_ciphersuite_id(const mbedtls_ssl_session *session)
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 */
2747 void mbedtls_ssl_set_export_keys_cb(mbedtls_ssl_context *ssl,
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 */
mbedtls_ssl_conf_set_user_data_p(mbedtls_ssl_config * conf,void * p)2761 static inline void mbedtls_ssl_conf_set_user_data_p(
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 */
mbedtls_ssl_conf_set_user_data_n(mbedtls_ssl_config * conf,uintptr_t n)2775 static inline void mbedtls_ssl_conf_set_user_data_n(
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 */
mbedtls_ssl_conf_get_user_data_p(mbedtls_ssl_config * conf)2792 static inline void *mbedtls_ssl_conf_get_user_data_p(
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 */
mbedtls_ssl_conf_get_user_data_n(mbedtls_ssl_config * conf)2808 static inline uintptr_t mbedtls_ssl_conf_get_user_data_n(
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 */
mbedtls_ssl_set_user_data_p(mbedtls_ssl_context * ssl,void * p)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 */
mbedtls_ssl_set_user_data_n(mbedtls_ssl_context * ssl,uintptr_t n)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 */
mbedtls_ssl_get_user_data_p(mbedtls_ssl_context * ssl)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 */
mbedtls_ssl_get_user_data_n(mbedtls_ssl_context * ssl)2871 static inline uintptr_t mbedtls_ssl_get_user_data_n(
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 */
2970 typedef int mbedtls_ssl_cookie_write_t(void *ctx,
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 */
2987 typedef int mbedtls_ssl_cookie_check_t(void *ctx,
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 */
3020 void mbedtls_ssl_conf_dtls_cookies(mbedtls_ssl_config *conf,
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 */
3044 int mbedtls_ssl_set_client_transport_id(mbedtls_ssl_context *ssl,
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 */
3066 void mbedtls_ssl_conf_dtls_anti_replay(mbedtls_ssl_config *conf, char mode);
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 */
3092 void mbedtls_ssl_conf_dtls_badmac_limit(mbedtls_ssl_config *conf, unsigned limit);
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 */
3124 void mbedtls_ssl_set_datagram_packing(mbedtls_ssl_context *ssl,
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 */
3158 void mbedtls_ssl_conf_handshake_timeout(mbedtls_ssl_config *conf, uint32_t min, uint32_t max);
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 */
3199 void mbedtls_ssl_conf_session_cache(mbedtls_ssl_config *conf,
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 */
3251 int mbedtls_ssl_set_session(mbedtls_ssl_context *ssl, const mbedtls_ssl_session *session);
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 */
3286 int mbedtls_ssl_session_load(mbedtls_ssl_session *session,
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 */
3315 int mbedtls_ssl_session_save(const mbedtls_ssl_session *session,
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 */
3361 void mbedtls_ssl_conf_ciphersuites(mbedtls_ssl_config *conf,
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
3407 void mbedtls_ssl_conf_tls13_key_exchange_modes(mbedtls_ssl_config *conf,
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 */
3461 void mbedtls_ssl_conf_cert_profile(mbedtls_ssl_config *conf,
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 */
3475 void mbedtls_ssl_conf_ca_chain(mbedtls_ssl_config *conf,
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
mbedtls_ssl_conf_dn_hints(mbedtls_ssl_config * conf,const mbedtls_x509_crt * crt)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 */
3592 int mbedtls_ssl_conf_own_cert(mbedtls_ssl_config *conf,
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 */
3630 int mbedtls_ssl_conf_psk(mbedtls_ssl_config *conf,
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,
3673 mbedtls_svc_key_id_t psk,
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 */
3694 int mbedtls_ssl_set_hs_psk(mbedtls_ssl_context *ssl,
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 */
3761 void mbedtls_ssl_conf_psk_cb(mbedtls_ssl_config *conf,
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 */
3782 int mbedtls_ssl_conf_dh_param_bin(mbedtls_ssl_config *conf,
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 */
3795 int mbedtls_ssl_conf_dh_param_ctx(mbedtls_ssl_config *conf, mbedtls_dhm_context *dhm_ctx);
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 */
3807 void mbedtls_ssl_conf_dhm_min_bitlen(mbedtls_ssl_config *conf,
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 */
3854 void MBEDTLS_DEPRECATED mbedtls_ssl_conf_curves(mbedtls_ssl_config *conf,
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 */
3896 void mbedtls_ssl_conf_groups(mbedtls_ssl_config *conf,
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 */
3932 void MBEDTLS_DEPRECATED mbedtls_ssl_conf_sig_hashes(mbedtls_ssl_config *conf,
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 */
3948 void mbedtls_ssl_conf_sig_algs(mbedtls_ssl_config *conf,
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 */
mbedtls_ssl_get_hostname(mbedtls_ssl_context * ssl)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 */
4026 int mbedtls_ssl_set_hs_own_cert(mbedtls_ssl_context *ssl,
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 */
4041 void mbedtls_ssl_set_hs_ca_chain(mbedtls_ssl_context *ssl,
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 */
4056 void mbedtls_ssl_set_hs_dn_hints(mbedtls_ssl_context *ssl,
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 */
4070 void mbedtls_ssl_set_hs_authmode(mbedtls_ssl_context *ssl,
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 */
4095 void mbedtls_ssl_conf_sni(mbedtls_ssl_config *conf,
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)
mbedtls_ssl_get_srtp_profile_as_string(mbedtls_ssl_srtp_profile profile)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 */
4285 void MBEDTLS_DEPRECATED mbedtls_ssl_conf_max_version(mbedtls_ssl_config *conf, int major,
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 */
mbedtls_ssl_conf_max_tls_version(mbedtls_ssl_config * conf,mbedtls_ssl_protocol_version tls_version)4301 static inline void mbedtls_ssl_conf_max_tls_version(mbedtls_ssl_config *conf,
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 */
4342 void MBEDTLS_DEPRECATED mbedtls_ssl_conf_min_version(mbedtls_ssl_config *conf, int major,
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 */
mbedtls_ssl_conf_min_tls_version(mbedtls_ssl_config * conf,mbedtls_ssl_protocol_version tls_version)4358 static inline void mbedtls_ssl_conf_min_tls_version(mbedtls_ssl_config *conf,
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 */
4376 void mbedtls_ssl_conf_encrypt_then_mac(mbedtls_ssl_config *conf, char etm);
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 */
4391 void mbedtls_ssl_conf_extended_master_secret(mbedtls_ssl_config *conf, char ems);
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 */
4404 void mbedtls_ssl_conf_cert_req_ca_list(mbedtls_ssl_config *conf,
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 */
4456 void mbedtls_ssl_conf_preference_order(mbedtls_ssl_config *conf, int order);
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 */
4495 void mbedtls_ssl_conf_new_session_tickets(mbedtls_ssl_config *conf,
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 */
4549 void mbedtls_ssl_conf_legacy_renegotiation(mbedtls_ssl_config *conf, int allow_legacy);
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 */
4616 void mbedtls_ssl_conf_renegotiation_period(mbedtls_ssl_config *conf,
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 */
4658 int mbedtls_ssl_check_pending(const mbedtls_ssl_context *ssl);
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 */
4675 size_t mbedtls_ssl_get_bytes_avail(const mbedtls_ssl_context *ssl);
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 */
4689 uint32_t mbedtls_ssl_get_verify_result(const mbedtls_ssl_context *ssl);
4690
4691 /**
4692 * \brief Return the id of the current ciphersuite
4693 *
4694 * \param ssl SSL context
4695 *
4696 * \return a ciphersuite id
4697 */
4698 int mbedtls_ssl_get_ciphersuite_id_from_ssl(const mbedtls_ssl_context *ssl);
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 */
4707 const char *mbedtls_ssl_get_ciphersuite(const mbedtls_ssl_context *ssl);
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 */
mbedtls_ssl_get_version_number(const mbedtls_ssl_context * ssl)4721 static inline mbedtls_ssl_protocol_version mbedtls_ssl_get_version_number(
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 */
4734 const char *mbedtls_ssl_get_version(const mbedtls_ssl_context *ssl);
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 */
4744 int mbedtls_ssl_get_record_expansion(const mbedtls_ssl_context *ssl);
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 */
4771 int mbedtls_ssl_get_max_out_record_payload(const mbedtls_ssl_context *ssl);
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 */
4791 int mbedtls_ssl_get_max_in_record_payload(const mbedtls_ssl_context *ssl);
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 */
4824 const mbedtls_x509_crt *mbedtls_ssl_get_peer_cert(const mbedtls_ssl_context *ssl);
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 */
4862 int mbedtls_ssl_get_session(const mbedtls_ssl_context *ssl,
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 */
4929 int mbedtls_ssl_handshake(mbedtls_ssl_context *ssl);
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 */
mbedtls_ssl_is_handshake_over(mbedtls_ssl_context * ssl)4942 static inline int mbedtls_ssl_is_handshake_over(mbedtls_ssl_context *ssl)
4943 {
4944 return ssl->MBEDTLS_PRIVATE(state) >= MBEDTLS_SSL_HANDSHAKE_OVER;
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 */
4981 int mbedtls_ssl_handshake_step(mbedtls_ssl_context *ssl);
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 */
5007 int mbedtls_ssl_renegotiate(mbedtls_ssl_context *ssl);
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 */
5183 int mbedtls_ssl_send_alert_message(mbedtls_ssl_context *ssl,
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 */
5199 int mbedtls_ssl_close_notify(mbedtls_ssl_context *ssl);
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 */
5379 void mbedtls_ssl_free(mbedtls_ssl_context *ssl);
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 */
5438 int mbedtls_ssl_context_save(mbedtls_ssl_context *ssl,
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 */
5511 int mbedtls_ssl_context_load(mbedtls_ssl_context *ssl,
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 */
5526 void mbedtls_ssl_config_init(mbedtls_ssl_config *conf);
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 */
5543 int mbedtls_ssl_config_defaults(mbedtls_ssl_config *conf,
5544 int endpoint, int transport, int preset);
5545
5546 /**
5547 * \brief Free an SSL configuration context
5548 *
5549 * \param conf SSL configuration context
5550 */
5551 void mbedtls_ssl_config_free(mbedtls_ssl_config *conf);
5552
5553 /**
5554 * \brief Initialize SSL session structure
5555 *
5556 * \param session SSL session
5557 */
5558 void mbedtls_ssl_session_init(mbedtls_ssl_session *session);
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 */
5569 void mbedtls_ssl_session_free(mbedtls_ssl_session *session);
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 */
5586 int mbedtls_ssl_tls_prf(const mbedtls_tls_prf_types prf,
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 */
5597
