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