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