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