1 /**
2 * \file ssl_internal.h
3 *
4 * \brief Internal functions shared by the SSL modules
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_INTERNAL_H
23 #define MBEDTLS_SSL_INTERNAL_H
24
25 #if !defined(MBEDTLS_CONFIG_FILE)
26 #include "mbedtls/config.h"
27 #else
28 #include MBEDTLS_CONFIG_FILE
29 #endif
30
31 #include "mbedtls/ssl.h"
32 #include "mbedtls/cipher.h"
33
34 #if defined(MBEDTLS_USE_PSA_CRYPTO)
35 #include "psa/crypto.h"
36 #endif
37
38 #if defined(MBEDTLS_MD5_C)
39 #include "mbedtls/md5.h"
40 #endif
41
42 #if defined(MBEDTLS_SHA1_C)
43 #include "mbedtls/sha1.h"
44 #endif
45
46 #if defined(MBEDTLS_SHA256_C)
47 #include "mbedtls/sha256.h"
48 #endif
49
50 #if defined(MBEDTLS_SHA512_C)
51 #include "mbedtls/sha512.h"
52 #endif
53
54 #if defined(MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED)
55 #include "mbedtls/ecjpake.h"
56 #endif
57
58 #if defined(MBEDTLS_USE_PSA_CRYPTO)
59 #include "psa/crypto.h"
60 #include "mbedtls/psa_util.h"
61 #endif /* MBEDTLS_USE_PSA_CRYPTO */
62
63 #if ( defined(__ARMCC_VERSION) || defined(_MSC_VER) ) && \
64 !defined(inline) && !defined(__cplusplus)
65 #define inline __inline
66 #endif
67
68 /* Determine minimum supported version */
69 #define MBEDTLS_SSL_MIN_MAJOR_VERSION MBEDTLS_SSL_MAJOR_VERSION_3
70
71 #if defined(MBEDTLS_SSL_PROTO_SSL3)
72 #define MBEDTLS_SSL_MIN_MINOR_VERSION MBEDTLS_SSL_MINOR_VERSION_0
73 #else
74 #if defined(MBEDTLS_SSL_PROTO_TLS1)
75 #define MBEDTLS_SSL_MIN_MINOR_VERSION MBEDTLS_SSL_MINOR_VERSION_1
76 #else
77 #if defined(MBEDTLS_SSL_PROTO_TLS1_1)
78 #define MBEDTLS_SSL_MIN_MINOR_VERSION MBEDTLS_SSL_MINOR_VERSION_2
79 #else
80 #if defined(MBEDTLS_SSL_PROTO_TLS1_2)
81 #define MBEDTLS_SSL_MIN_MINOR_VERSION MBEDTLS_SSL_MINOR_VERSION_3
82 #endif /* MBEDTLS_SSL_PROTO_TLS1_2 */
83 #endif /* MBEDTLS_SSL_PROTO_TLS1_1 */
84 #endif /* MBEDTLS_SSL_PROTO_TLS1 */
85 #endif /* MBEDTLS_SSL_PROTO_SSL3 */
86
87 #define MBEDTLS_SSL_MIN_VALID_MINOR_VERSION MBEDTLS_SSL_MINOR_VERSION_1
88 #define MBEDTLS_SSL_MIN_VALID_MAJOR_VERSION MBEDTLS_SSL_MAJOR_VERSION_3
89
90 /* Determine maximum supported version */
91 #define MBEDTLS_SSL_MAX_MAJOR_VERSION MBEDTLS_SSL_MAJOR_VERSION_3
92
93 #if defined(MBEDTLS_SSL_PROTO_TLS1_2)
94 #define MBEDTLS_SSL_MAX_MINOR_VERSION MBEDTLS_SSL_MINOR_VERSION_3
95 #else
96 #if defined(MBEDTLS_SSL_PROTO_TLS1_1)
97 #define MBEDTLS_SSL_MAX_MINOR_VERSION MBEDTLS_SSL_MINOR_VERSION_2
98 #else
99 #if defined(MBEDTLS_SSL_PROTO_TLS1)
100 #define MBEDTLS_SSL_MAX_MINOR_VERSION MBEDTLS_SSL_MINOR_VERSION_1
101 #else
102 #if defined(MBEDTLS_SSL_PROTO_SSL3)
103 #define MBEDTLS_SSL_MAX_MINOR_VERSION MBEDTLS_SSL_MINOR_VERSION_0
104 #endif /* MBEDTLS_SSL_PROTO_SSL3 */
105 #endif /* MBEDTLS_SSL_PROTO_TLS1 */
106 #endif /* MBEDTLS_SSL_PROTO_TLS1_1 */
107 #endif /* MBEDTLS_SSL_PROTO_TLS1_2 */
108
109 /* Shorthand for restartable ECC */
110 #if defined(MBEDTLS_ECP_RESTARTABLE) && \
111 defined(MBEDTLS_SSL_CLI_C) && \
112 defined(MBEDTLS_SSL_PROTO_TLS1_2) && \
113 defined(MBEDTLS_KEY_EXCHANGE_ECDHE_ECDSA_ENABLED)
114 #define MBEDTLS_SSL_ECP_RESTARTABLE_ENABLED
115 #endif
116
117 #define MBEDTLS_SSL_INITIAL_HANDSHAKE 0
118 #define MBEDTLS_SSL_RENEGOTIATION_IN_PROGRESS 1 /* In progress */
119 #define MBEDTLS_SSL_RENEGOTIATION_DONE 2 /* Done or aborted */
120 #define MBEDTLS_SSL_RENEGOTIATION_PENDING 3 /* Requested (server only) */
121
122 /*
123 * DTLS retransmission states, see RFC 6347 4.2.4
124 *
125 * The SENDING state is merged in PREPARING for initial sends,
126 * but is distinct for resends.
127 *
128 * Note: initial state is wrong for server, but is not used anyway.
129 */
130 #define MBEDTLS_SSL_RETRANS_PREPARING 0
131 #define MBEDTLS_SSL_RETRANS_SENDING 1
132 #define MBEDTLS_SSL_RETRANS_WAITING 2
133 #define MBEDTLS_SSL_RETRANS_FINISHED 3
134
135 /*
136 * Allow extra bytes for record, authentication and encryption overhead:
137 * counter (8) + header (5) + IV(16) + MAC (16-48) + padding (0-256)
138 * and allow for a maximum of 1024 of compression expansion if
139 * enabled.
140 */
141 #if defined(MBEDTLS_ZLIB_SUPPORT)
142 #define MBEDTLS_SSL_COMPRESSION_ADD 1024
143 #else
144 #define MBEDTLS_SSL_COMPRESSION_ADD 0
145 #endif
146
147 /* This macro determines whether CBC is supported. */
148 #if defined(MBEDTLS_CIPHER_MODE_CBC) && \
149 ( defined(MBEDTLS_AES_C) || \
150 defined(MBEDTLS_CAMELLIA_C) || \
151 defined(MBEDTLS_ARIA_C) || \
152 defined(MBEDTLS_DES_C) )
153 #define MBEDTLS_SSL_SOME_SUITES_USE_CBC
154 #endif
155
156 /* This macro determines whether the CBC construct used in TLS 1.0-1.2 (as
157 * opposed to the very different CBC construct used in SSLv3) is supported. */
158 #if defined(MBEDTLS_SSL_SOME_SUITES_USE_CBC) && \
159 ( defined(MBEDTLS_SSL_PROTO_TLS1) || \
160 defined(MBEDTLS_SSL_PROTO_TLS1_1) || \
161 defined(MBEDTLS_SSL_PROTO_TLS1_2) )
162 #define MBEDTLS_SSL_SOME_SUITES_USE_TLS_CBC
163 #endif
164
165 #if defined(MBEDTLS_ARC4_C) || defined(MBEDTLS_CIPHER_NULL_CIPHER) || \
166 defined(MBEDTLS_SSL_SOME_SUITES_USE_CBC)
167 #define MBEDTLS_SSL_SOME_MODES_USE_MAC
168 #endif
169
170 #if defined(MBEDTLS_SSL_SOME_MODES_USE_MAC)
171 /* Ciphersuites using HMAC */
172 #if defined(MBEDTLS_SHA512_C)
173 #define MBEDTLS_SSL_MAC_ADD 48 /* SHA-384 used for HMAC */
174 #elif defined(MBEDTLS_SHA256_C)
175 #define MBEDTLS_SSL_MAC_ADD 32 /* SHA-256 used for HMAC */
176 #else
177 #define MBEDTLS_SSL_MAC_ADD 20 /* SHA-1 used for HMAC */
178 #endif
179 #else /* MBEDTLS_SSL_SOME_MODES_USE_MAC */
180 /* AEAD ciphersuites: GCM and CCM use a 128 bits tag */
181 #define MBEDTLS_SSL_MAC_ADD 16
182 #endif
183
184 #if defined(MBEDTLS_CIPHER_MODE_CBC)
185 #define MBEDTLS_SSL_PADDING_ADD 256
186 #else
187 #define MBEDTLS_SSL_PADDING_ADD 0
188 #endif
189
190 #if defined(MBEDTLS_SSL_DTLS_CONNECTION_ID)
191 #define MBEDTLS_SSL_MAX_CID_EXPANSION MBEDTLS_SSL_CID_PADDING_GRANULARITY
192 #else
193 #define MBEDTLS_SSL_MAX_CID_EXPANSION 0
194 #endif
195
196 #define MBEDTLS_SSL_PAYLOAD_OVERHEAD ( MBEDTLS_SSL_COMPRESSION_ADD + \
197 MBEDTLS_MAX_IV_LENGTH + \
198 MBEDTLS_SSL_MAC_ADD + \
199 MBEDTLS_SSL_PADDING_ADD + \
200 MBEDTLS_SSL_MAX_CID_EXPANSION \
201 )
202
203 #define MBEDTLS_SSL_IN_PAYLOAD_LEN ( MBEDTLS_SSL_PAYLOAD_OVERHEAD + \
204 ( MBEDTLS_SSL_IN_CONTENT_LEN ) )
205
206 #define MBEDTLS_SSL_OUT_PAYLOAD_LEN ( MBEDTLS_SSL_PAYLOAD_OVERHEAD + \
207 ( MBEDTLS_SSL_OUT_CONTENT_LEN ) )
208
209 /* The maximum number of buffered handshake messages. */
210 #define MBEDTLS_SSL_MAX_BUFFERED_HS 4
211
212 /* Maximum length we can advertise as our max content length for
213 RFC 6066 max_fragment_length extension negotiation purposes
214 (the lesser of both sizes, if they are unequal.)
215 */
216 #define MBEDTLS_TLS_EXT_ADV_CONTENT_LEN ( \
217 (MBEDTLS_SSL_IN_CONTENT_LEN > MBEDTLS_SSL_OUT_CONTENT_LEN) \
218 ? ( MBEDTLS_SSL_OUT_CONTENT_LEN ) \
219 : ( MBEDTLS_SSL_IN_CONTENT_LEN ) \
220 )
221
222 /* Maximum size in bytes of list in sig-hash algorithm ext., RFC 5246 */
223 #define MBEDTLS_SSL_MAX_SIG_HASH_ALG_LIST_LEN 65534
224
225 /* Maximum size in bytes of list in supported elliptic curve ext., RFC 4492 */
226 #define MBEDTLS_SSL_MAX_CURVE_LIST_LEN 65535
227
228 /*
229 * Check that we obey the standard's message size bounds
230 */
231
232 #if MBEDTLS_SSL_MAX_CONTENT_LEN > 16384
233 #error "Bad configuration - record content too large."
234 #endif
235
236 #if MBEDTLS_SSL_IN_CONTENT_LEN > MBEDTLS_SSL_MAX_CONTENT_LEN
237 #error "Bad configuration - incoming record content should not be larger than MBEDTLS_SSL_MAX_CONTENT_LEN."
238 #endif
239
240 #if MBEDTLS_SSL_OUT_CONTENT_LEN > MBEDTLS_SSL_MAX_CONTENT_LEN
241 #error "Bad configuration - outgoing record content should not be larger than MBEDTLS_SSL_MAX_CONTENT_LEN."
242 #endif
243
244 #if MBEDTLS_SSL_IN_PAYLOAD_LEN > MBEDTLS_SSL_MAX_CONTENT_LEN + 2048
245 #error "Bad configuration - incoming protected record payload too large."
246 #endif
247
248 #if MBEDTLS_SSL_OUT_PAYLOAD_LEN > MBEDTLS_SSL_MAX_CONTENT_LEN + 2048
249 #error "Bad configuration - outgoing protected record payload too large."
250 #endif
251
252 /* Calculate buffer sizes */
253
254 /* Note: Even though the TLS record header is only 5 bytes
255 long, we're internally using 8 bytes to store the
256 implicit sequence number. */
257 #define MBEDTLS_SSL_HEADER_LEN 13
258
259 #if !defined(MBEDTLS_SSL_DTLS_CONNECTION_ID)
260 #define MBEDTLS_SSL_IN_BUFFER_LEN \
261 ( ( MBEDTLS_SSL_HEADER_LEN ) + ( MBEDTLS_SSL_IN_PAYLOAD_LEN ) )
262 #else
263 #define MBEDTLS_SSL_IN_BUFFER_LEN \
264 ( ( MBEDTLS_SSL_HEADER_LEN ) + ( MBEDTLS_SSL_IN_PAYLOAD_LEN ) \
265 + ( MBEDTLS_SSL_CID_IN_LEN_MAX ) )
266 #endif
267
268 #if !defined(MBEDTLS_SSL_DTLS_CONNECTION_ID)
269 #define MBEDTLS_SSL_OUT_BUFFER_LEN \
270 ( ( MBEDTLS_SSL_HEADER_LEN ) + ( MBEDTLS_SSL_OUT_PAYLOAD_LEN ) )
271 #else
272 #define MBEDTLS_SSL_OUT_BUFFER_LEN \
273 ( ( MBEDTLS_SSL_HEADER_LEN ) + ( MBEDTLS_SSL_OUT_PAYLOAD_LEN ) \
274 + ( MBEDTLS_SSL_CID_OUT_LEN_MAX ) )
275 #endif
276
277 #if defined(MBEDTLS_SSL_VARIABLE_BUFFER_LENGTH)
mbedtls_ssl_get_output_buflen(const mbedtls_ssl_context * ctx)278 static inline size_t mbedtls_ssl_get_output_buflen( const mbedtls_ssl_context *ctx )
279 {
280 #if defined (MBEDTLS_SSL_DTLS_CONNECTION_ID)
281 return mbedtls_ssl_get_output_max_frag_len( ctx )
282 + MBEDTLS_SSL_HEADER_LEN + MBEDTLS_SSL_PAYLOAD_OVERHEAD
283 + MBEDTLS_SSL_CID_OUT_LEN_MAX;
284 #else
285 return mbedtls_ssl_get_output_max_frag_len( ctx )
286 + MBEDTLS_SSL_HEADER_LEN + MBEDTLS_SSL_PAYLOAD_OVERHEAD;
287 #endif
288 }
289
mbedtls_ssl_get_input_buflen(const mbedtls_ssl_context * ctx)290 static inline size_t mbedtls_ssl_get_input_buflen( const mbedtls_ssl_context *ctx )
291 {
292 #if defined (MBEDTLS_SSL_DTLS_CONNECTION_ID)
293 return mbedtls_ssl_get_input_max_frag_len( ctx )
294 + MBEDTLS_SSL_HEADER_LEN + MBEDTLS_SSL_PAYLOAD_OVERHEAD
295 + MBEDTLS_SSL_CID_IN_LEN_MAX;
296 #else
297 return mbedtls_ssl_get_input_max_frag_len( ctx )
298 + MBEDTLS_SSL_HEADER_LEN + MBEDTLS_SSL_PAYLOAD_OVERHEAD;
299 #endif
300 }
301 #endif
302
303 #ifdef MBEDTLS_ZLIB_SUPPORT
304 /* Compression buffer holds both IN and OUT buffers, so should be size of the larger */
305 #define MBEDTLS_SSL_COMPRESS_BUFFER_LEN ( \
306 ( MBEDTLS_SSL_IN_BUFFER_LEN > MBEDTLS_SSL_OUT_BUFFER_LEN ) \
307 ? MBEDTLS_SSL_IN_BUFFER_LEN \
308 : MBEDTLS_SSL_OUT_BUFFER_LEN \
309 )
310 #endif
311
312 /*
313 * TLS extension flags (for extensions with outgoing ServerHello content
314 * that need it (e.g. for RENEGOTIATION_INFO the server already knows because
315 * of state of the renegotiation flag, so no indicator is required)
316 */
317 #define MBEDTLS_TLS_EXT_SUPPORTED_POINT_FORMATS_PRESENT (1 << 0)
318 #define MBEDTLS_TLS_EXT_ECJPAKE_KKPP_OK (1 << 1)
319
320 /**
321 * \brief This function checks if the remaining size in a buffer is
322 * greater or equal than a needed space.
323 *
324 * \param cur Pointer to the current position in the buffer.
325 * \param end Pointer to one past the end of the buffer.
326 * \param need Needed space in bytes.
327 *
328 * \return Zero if the needed space is available in the buffer, non-zero
329 * otherwise.
330 */
mbedtls_ssl_chk_buf_ptr(const uint8_t * cur,const uint8_t * end,size_t need)331 static inline int mbedtls_ssl_chk_buf_ptr( const uint8_t *cur,
332 const uint8_t *end, size_t need )
333 {
334 return( ( cur > end ) || ( need > (size_t)( end - cur ) ) );
335 }
336
337 /**
338 * \brief This macro checks if the remaining size in a buffer is
339 * greater or equal than a needed space. If it is not the case,
340 * it returns an SSL_BUFFER_TOO_SMALL error.
341 *
342 * \param cur Pointer to the current position in the buffer.
343 * \param end Pointer to one past the end of the buffer.
344 * \param need Needed space in bytes.
345 *
346 */
347 #define MBEDTLS_SSL_CHK_BUF_PTR( cur, end, need ) \
348 do { \
349 if( mbedtls_ssl_chk_buf_ptr( ( cur ), ( end ), ( need ) ) != 0 ) \
350 { \
351 return( MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL ); \
352 } \
353 } while( 0 )
354
355 #ifdef __cplusplus
356 extern "C" {
357 #endif
358
359 #if defined(MBEDTLS_SSL_PROTO_TLS1_2) && \
360 defined(MBEDTLS_KEY_EXCHANGE_WITH_CERT_ENABLED)
361 /*
362 * Abstraction for a grid of allowed signature-hash-algorithm pairs.
363 */
364 struct mbedtls_ssl_sig_hash_set_t
365 {
366 /* At the moment, we only need to remember a single suitable
367 * hash algorithm per signature algorithm. As long as that's
368 * the case - and we don't need a general lookup function -
369 * we can implement the sig-hash-set as a map from signatures
370 * to hash algorithms. */
371 mbedtls_md_type_t rsa;
372 mbedtls_md_type_t ecdsa;
373 };
374 #endif /* MBEDTLS_SSL_PROTO_TLS1_2 &&
375 MBEDTLS_KEY_EXCHANGE_WITH_CERT_ENABLED */
376
377 typedef int mbedtls_ssl_tls_prf_cb( const unsigned char *secret, size_t slen,
378 const char *label,
379 const unsigned char *random, size_t rlen,
380 unsigned char *dstbuf, size_t dlen );
381
382 /* cipher.h exports the maximum IV, key and block length from
383 * all ciphers enabled in the config, regardless of whether those
384 * ciphers are actually usable in SSL/TLS. Notably, XTS is enabled
385 * in the default configuration and uses 64 Byte keys, but it is
386 * not used for record protection in SSL/TLS.
387 *
388 * In order to prevent unnecessary inflation of key structures,
389 * we introduce SSL-specific variants of the max-{key,block,IV}
390 * macros here which are meant to only take those ciphers into
391 * account which can be negotiated in SSL/TLS.
392 *
393 * Since the current definitions of MBEDTLS_MAX_{KEY|BLOCK|IV}_LENGTH
394 * in cipher.h are rough overapproximations of the real maxima, here
395 * we content ourselves with replicating those overapproximations
396 * for the maximum block and IV length, and excluding XTS from the
397 * computation of the maximum key length. */
398 #define MBEDTLS_SSL_MAX_BLOCK_LENGTH 16
399 #define MBEDTLS_SSL_MAX_IV_LENGTH 16
400 #define MBEDTLS_SSL_MAX_KEY_LENGTH 32
401
402 /**
403 * \brief The data structure holding the cryptographic material (key and IV)
404 * used for record protection in TLS 1.3.
405 */
406 struct mbedtls_ssl_key_set
407 {
408 /*! The key for client->server records. */
409 unsigned char client_write_key[ MBEDTLS_SSL_MAX_KEY_LENGTH ];
410 /*! The key for server->client records. */
411 unsigned char server_write_key[ MBEDTLS_SSL_MAX_KEY_LENGTH ];
412 /*! The IV for client->server records. */
413 unsigned char client_write_iv[ MBEDTLS_SSL_MAX_IV_LENGTH ];
414 /*! The IV for server->client records. */
415 unsigned char server_write_iv[ MBEDTLS_SSL_MAX_IV_LENGTH ];
416
417 size_t key_len; /*!< The length of client_write_key and
418 * server_write_key, in Bytes. */
419 size_t iv_len; /*!< The length of client_write_iv and
420 * server_write_iv, in Bytes. */
421 };
422 typedef struct mbedtls_ssl_key_set mbedtls_ssl_key_set;
423
424 /*
425 * This structure contains the parameters only needed during handshake.
426 */
427 struct mbedtls_ssl_handshake_params
428 {
429 /*
430 * Handshake specific crypto variables
431 */
432
433 uint8_t max_major_ver; /*!< max. major version client*/
434 uint8_t max_minor_ver; /*!< max. minor version client*/
435 uint8_t resume; /*!< session resume indicator*/
436 uint8_t cli_exts; /*!< client extension presence*/
437
438 #if defined(MBEDTLS_X509_CRT_PARSE_C) && \
439 defined(MBEDTLS_SSL_SERVER_NAME_INDICATION)
440 uint8_t sni_authmode; /*!< authmode from SNI callback */
441 #endif
442
443 #if defined(MBEDTLS_SSL_SESSION_TICKETS)
444 uint8_t new_session_ticket; /*!< use NewSessionTicket? */
445 #endif /* MBEDTLS_SSL_SESSION_TICKETS */
446
447 #if defined(MBEDTLS_SSL_EXTENDED_MASTER_SECRET)
448 uint8_t extended_ms; /*!< use Extended Master Secret? */
449 #endif
450
451 #if defined(MBEDTLS_SSL_ASYNC_PRIVATE)
452 uint8_t async_in_progress; /*!< an asynchronous operation is in progress */
453 #endif /* MBEDTLS_SSL_ASYNC_PRIVATE */
454
455 #if defined(MBEDTLS_SSL_PROTO_DTLS)
456 unsigned char retransmit_state; /*!< Retransmission state */
457 #endif
458
459 #if defined(MBEDTLS_SSL_ECP_RESTARTABLE_ENABLED)
460 uint8_t ecrs_enabled; /*!< Handshake supports EC restart? */
461 enum { /* this complements ssl->state with info on intra-state operations */
462 ssl_ecrs_none = 0, /*!< nothing going on (yet) */
463 ssl_ecrs_crt_verify, /*!< Certificate: crt_verify() */
464 ssl_ecrs_ske_start_processing, /*!< ServerKeyExchange: pk_verify() */
465 ssl_ecrs_cke_ecdh_calc_secret, /*!< ClientKeyExchange: ECDH step 2 */
466 ssl_ecrs_crt_vrfy_sign, /*!< CertificateVerify: pk_sign() */
467 } ecrs_state; /*!< current (or last) operation */
468 mbedtls_x509_crt *ecrs_peer_cert; /*!< The peer's CRT chain. */
469 size_t ecrs_n; /*!< place for saving a length */
470 #endif
471
472 #if defined(MBEDTLS_SSL_PROTO_TLS1_2) && \
473 defined(MBEDTLS_KEY_EXCHANGE_WITH_CERT_ENABLED)
474 mbedtls_ssl_sig_hash_set_t hash_algs; /*!< Set of suitable sig-hash pairs */
475 #endif
476
477 size_t pmslen; /*!< premaster length */
478
479 mbedtls_ssl_ciphersuite_t const *ciphersuite_info;
480
481 void (*update_checksum)(mbedtls_ssl_context *, const unsigned char *, size_t);
482 void (*calc_verify)(const mbedtls_ssl_context *, unsigned char *, size_t *);
483 void (*calc_finished)(mbedtls_ssl_context *, unsigned char *, int);
484 mbedtls_ssl_tls_prf_cb *tls_prf;
485
486 #if defined(MBEDTLS_DHM_C)
487 mbedtls_dhm_context dhm_ctx; /*!< DHM key exchange */
488 #endif
489
490 /* Adding guard for MBEDTLS_ECDSA_C to ensure no compile errors due
491 * to guards also being in ssl_srv.c and ssl_cli.c. There is a gap
492 * in functionality that access to ecdh_ctx structure is needed for
493 * MBEDTLS_ECDSA_C which does not seem correct.
494 */
495 #if defined(MBEDTLS_ECDH_C) || defined(MBEDTLS_ECDSA_C)
496 mbedtls_ecdh_context ecdh_ctx; /*!< ECDH key exchange */
497
498 #if defined(MBEDTLS_USE_PSA_CRYPTO)
499 psa_key_type_t ecdh_psa_type;
500 uint16_t ecdh_bits;
501 psa_key_id_t ecdh_psa_privkey;
502 unsigned char ecdh_psa_peerkey[MBEDTLS_PSA_MAX_EC_PUBKEY_LENGTH];
503 size_t ecdh_psa_peerkey_len;
504 #endif /* MBEDTLS_USE_PSA_CRYPTO */
505 #endif /* MBEDTLS_ECDH_C || MBEDTLS_ECDSA_C */
506
507 #if defined(MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED)
508 mbedtls_ecjpake_context ecjpake_ctx; /*!< EC J-PAKE key exchange */
509 #if defined(MBEDTLS_SSL_CLI_C)
510 unsigned char *ecjpake_cache; /*!< Cache for ClientHello ext */
511 size_t ecjpake_cache_len; /*!< Length of cached data */
512 #endif
513 #endif /* MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED */
514
515 #if defined(MBEDTLS_ECDH_C) || defined(MBEDTLS_ECDSA_C) || \
516 defined(MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED)
517 const mbedtls_ecp_curve_info **curves; /*!< Supported elliptic curves */
518 #endif
519
520 #if defined(MBEDTLS_KEY_EXCHANGE_SOME_PSK_ENABLED)
521 #if defined(MBEDTLS_USE_PSA_CRYPTO)
522 psa_key_id_t psk_opaque; /*!< Opaque PSK from the callback */
523 #endif /* MBEDTLS_USE_PSA_CRYPTO */
524 unsigned char *psk; /*!< PSK from the callback */
525 size_t psk_len; /*!< Length of PSK from callback */
526 #endif /* MBEDTLS_KEY_EXCHANGE_SOME_PSK_ENABLED */
527
528 #if defined(MBEDTLS_X509_CRT_PARSE_C)
529 mbedtls_ssl_key_cert *key_cert; /*!< chosen key/cert pair (server) */
530 #if defined(MBEDTLS_SSL_SERVER_NAME_INDICATION)
531 mbedtls_ssl_key_cert *sni_key_cert; /*!< key/cert list from SNI */
532 mbedtls_x509_crt *sni_ca_chain; /*!< trusted CAs from SNI callback */
533 mbedtls_x509_crl *sni_ca_crl; /*!< trusted CAs CRLs from SNI */
534 #endif /* MBEDTLS_SSL_SERVER_NAME_INDICATION */
535 #endif /* MBEDTLS_X509_CRT_PARSE_C */
536
537 #if defined(MBEDTLS_SSL_ECP_RESTARTABLE_ENABLED)
538 mbedtls_x509_crt_restart_ctx ecrs_ctx; /*!< restart context */
539 #endif
540
541 #if defined(MBEDTLS_X509_CRT_PARSE_C) && \
542 !defined(MBEDTLS_SSL_KEEP_PEER_CERTIFICATE)
543 mbedtls_pk_context peer_pubkey; /*!< The public key from the peer. */
544 #endif /* MBEDTLS_X509_CRT_PARSE_C && !MBEDTLS_SSL_KEEP_PEER_CERTIFICATE */
545
546 #if defined(MBEDTLS_SSL_PROTO_DTLS)
547 struct
548 {
549 size_t total_bytes_buffered; /*!< Cumulative size of heap allocated
550 * buffers used for message buffering. */
551
552 uint8_t seen_ccs; /*!< Indicates if a CCS message has
553 * been seen in the current flight. */
554
555 struct mbedtls_ssl_hs_buffer
556 {
557 unsigned is_valid : 1;
558 unsigned is_fragmented : 1;
559 unsigned is_complete : 1;
560 unsigned char *data;
561 size_t data_len;
562 } hs[MBEDTLS_SSL_MAX_BUFFERED_HS];
563
564 struct
565 {
566 unsigned char *data;
567 size_t len;
568 unsigned epoch;
569 } future_record;
570
571 } buffering;
572
573 unsigned int out_msg_seq; /*!< Outgoing handshake sequence number */
574 unsigned int in_msg_seq; /*!< Incoming handshake sequence number */
575
576 unsigned char *verify_cookie; /*!< Cli: HelloVerifyRequest cookie
577 Srv: unused */
578 unsigned char verify_cookie_len; /*!< Cli: cookie length
579 Srv: flag for sending a cookie */
580
581 uint32_t retransmit_timeout; /*!< Current value of timeout */
582 mbedtls_ssl_flight_item *flight; /*!< Current outgoing flight */
583 mbedtls_ssl_flight_item *cur_msg; /*!< Current message in flight */
584 unsigned char *cur_msg_p; /*!< Position in current message */
585 unsigned int in_flight_start_seq; /*!< Minimum message sequence in the
586 flight being received */
587 mbedtls_ssl_transform *alt_transform_out; /*!< Alternative transform for
588 resending messages */
589 unsigned char alt_out_ctr[8]; /*!< Alternative record epoch/counter
590 for resending messages */
591
592 #if defined(MBEDTLS_SSL_DTLS_CONNECTION_ID)
593 /* The state of CID configuration in this handshake. */
594
595 uint8_t cid_in_use; /*!< This indicates whether the use of the CID extension
596 * has been negotiated. Possible values are
597 * #MBEDTLS_SSL_CID_ENABLED and
598 * #MBEDTLS_SSL_CID_DISABLED. */
599 unsigned char peer_cid[ MBEDTLS_SSL_CID_OUT_LEN_MAX ]; /*! The peer's CID */
600 uint8_t peer_cid_len; /*!< The length of
601 * \c peer_cid. */
602 #endif /* MBEDTLS_SSL_DTLS_CONNECTION_ID */
603
604 uint16_t mtu; /*!< Handshake mtu, used to fragment outgoing messages */
605 #endif /* MBEDTLS_SSL_PROTO_DTLS */
606
607 /*
608 * Checksum contexts
609 */
610 #if defined(MBEDTLS_SSL_PROTO_SSL3) || defined(MBEDTLS_SSL_PROTO_TLS1) || \
611 defined(MBEDTLS_SSL_PROTO_TLS1_1)
612 mbedtls_md5_context fin_md5;
613 mbedtls_sha1_context fin_sha1;
614 #endif
615 #if defined(MBEDTLS_SSL_PROTO_TLS1_2)
616 #if defined(MBEDTLS_SHA256_C)
617 #if defined(MBEDTLS_USE_PSA_CRYPTO)
618 psa_hash_operation_t fin_sha256_psa;
619 #else
620 mbedtls_sha256_context fin_sha256;
621 #endif
622 #endif
623 #if defined(MBEDTLS_SHA512_C)
624 #if defined(MBEDTLS_USE_PSA_CRYPTO)
625 psa_hash_operation_t fin_sha384_psa;
626 #else
627 mbedtls_sha512_context fin_sha512;
628 #endif
629 #endif
630 #endif /* MBEDTLS_SSL_PROTO_TLS1_2 */
631
632 unsigned char randbytes[64]; /*!< random bytes */
633 unsigned char premaster[MBEDTLS_PREMASTER_SIZE];
634 /*!< premaster secret */
635
636 #if defined(MBEDTLS_SSL_ASYNC_PRIVATE)
637 /** Asynchronous operation context. This field is meant for use by the
638 * asynchronous operation callbacks (mbedtls_ssl_config::f_async_sign_start,
639 * mbedtls_ssl_config::f_async_decrypt_start,
640 * mbedtls_ssl_config::f_async_resume, mbedtls_ssl_config::f_async_cancel).
641 * The library does not use it internally. */
642 void *user_async_ctx;
643 #endif /* MBEDTLS_SSL_ASYNC_PRIVATE */
644 };
645
646 typedef struct mbedtls_ssl_hs_buffer mbedtls_ssl_hs_buffer;
647
648 /*
649 * Representation of decryption/encryption transformations on records
650 *
651 * There are the following general types of record transformations:
652 * - Stream transformations (TLS versions <= 1.2 only)
653 * Transformation adding a MAC and applying a stream-cipher
654 * to the authenticated message.
655 * - CBC block cipher transformations ([D]TLS versions <= 1.2 only)
656 * In addition to the distinction of the order of encryption and
657 * authentication, there's a fundamental difference between the
658 * handling in SSL3 & TLS 1.0 and TLS 1.1 and TLS 1.2: For SSL3
659 * and TLS 1.0, the final IV after processing a record is used
660 * as the IV for the next record. No explicit IV is contained
661 * in an encrypted record. The IV for the first record is extracted
662 * at key extraction time. In contrast, for TLS 1.1 and 1.2, no
663 * IV is generated at key extraction time, but every encrypted
664 * record is explicitly prefixed by the IV with which it was encrypted.
665 * - AEAD transformations ([D]TLS versions >= 1.2 only)
666 * These come in two fundamentally different versions, the first one
667 * used in TLS 1.2, excluding ChaChaPoly ciphersuites, and the second
668 * one used for ChaChaPoly ciphersuites in TLS 1.2 as well as for TLS 1.3.
669 * In the first transformation, the IV to be used for a record is obtained
670 * as the concatenation of an explicit, static 4-byte IV and the 8-byte
671 * record sequence number, and explicitly prepending this sequence number
672 * to the encrypted record. In contrast, in the second transformation
673 * the IV is obtained by XOR'ing a static IV obtained at key extraction
674 * time with the 8-byte record sequence number, without prepending the
675 * latter to the encrypted record.
676 *
677 * Additionally, DTLS 1.2 + CID as well as TLS 1.3 use an inner plaintext
678 * which allows to add flexible length padding and to hide a record's true
679 * content type.
680 *
681 * In addition to type and version, the following parameters are relevant:
682 * - The symmetric cipher algorithm to be used.
683 * - The (static) encryption/decryption keys for the cipher.
684 * - For stream/CBC, the type of message digest to be used.
685 * - For stream/CBC, (static) encryption/decryption keys for the digest.
686 * - For AEAD transformations, the size (potentially 0) of an explicit,
687 * random initialization vector placed in encrypted records.
688 * - For some transformations (currently AEAD and CBC in SSL3 and TLS 1.0)
689 * an implicit IV. It may be static (e.g. AEAD) or dynamic (e.g. CBC)
690 * and (if present) is combined with the explicit IV in a transformation-
691 * dependent way (e.g. appending in TLS 1.2 and XOR'ing in TLS 1.3).
692 * - For stream/CBC, a flag determining the order of encryption and MAC.
693 * - The details of the transformation depend on the SSL/TLS version.
694 * - The length of the authentication tag.
695 *
696 * Note: Except for CBC in SSL3 and TLS 1.0, these parameters are
697 * constant across multiple encryption/decryption operations.
698 * For CBC, the implicit IV needs to be updated after each
699 * operation.
700 *
701 * The struct below refines this abstract view as follows:
702 * - The cipher underlying the transformation is managed in
703 * cipher contexts cipher_ctx_{enc/dec}, which must have the
704 * same cipher type. The mode of these cipher contexts determines
705 * the type of the transformation in the sense above: e.g., if
706 * the type is MBEDTLS_CIPHER_AES_256_CBC resp. MBEDTLS_CIPHER_AES_192_GCM
707 * then the transformation has type CBC resp. AEAD.
708 * - The cipher keys are never stored explicitly but
709 * are maintained within cipher_ctx_{enc/dec}.
710 * - For stream/CBC transformations, the message digest contexts
711 * used for the MAC's are stored in md_ctx_{enc/dec}. These contexts
712 * are unused for AEAD transformations.
713 * - For stream/CBC transformations and versions > SSL3, the
714 * MAC keys are not stored explicitly but maintained within
715 * md_ctx_{enc/dec}.
716 * - For stream/CBC transformations and version SSL3, the MAC
717 * keys are stored explicitly in mac_enc, mac_dec and have
718 * a fixed size of 20 bytes. These fields are unused for
719 * AEAD transformations or transformations >= TLS 1.0.
720 * - For transformations using an implicit IV maintained within
721 * the transformation context, its contents are stored within
722 * iv_{enc/dec}.
723 * - The value of ivlen indicates the length of the IV.
724 * This is redundant in case of stream/CBC transformations
725 * which always use 0 resp. the cipher's block length as the
726 * IV length, but is needed for AEAD ciphers and may be
727 * different from the underlying cipher's block length
728 * in this case.
729 * - The field fixed_ivlen is nonzero for AEAD transformations only
730 * and indicates the length of the static part of the IV which is
731 * constant throughout the communication, and which is stored in
732 * the first fixed_ivlen bytes of the iv_{enc/dec} arrays.
733 * Note: For CBC in SSL3 and TLS 1.0, the fields iv_{enc/dec}
734 * still store IV's for continued use across multiple transformations,
735 * so it is not true that fixed_ivlen == 0 means that iv_{enc/dec} are
736 * not being used!
737 * - minor_ver denotes the SSL/TLS version
738 * - For stream/CBC transformations, maclen denotes the length of the
739 * authentication tag, while taglen is unused and 0.
740 * - For AEAD transformations, taglen denotes the length of the
741 * authentication tag, while maclen is unused and 0.
742 * - For CBC transformations, encrypt_then_mac determines the
743 * order of encryption and authentication. This field is unused
744 * in other transformations.
745 *
746 */
747 struct mbedtls_ssl_transform
748 {
749 /*
750 * Session specific crypto layer
751 */
752 size_t minlen; /*!< min. ciphertext length */
753 size_t ivlen; /*!< IV length */
754 size_t fixed_ivlen; /*!< Fixed part of IV (AEAD) */
755 size_t maclen; /*!< MAC(CBC) len */
756 size_t taglen; /*!< TAG(AEAD) len */
757
758 unsigned char iv_enc[16]; /*!< IV (encryption) */
759 unsigned char iv_dec[16]; /*!< IV (decryption) */
760
761 #if defined(MBEDTLS_SSL_SOME_MODES_USE_MAC)
762
763 #if defined(MBEDTLS_SSL_PROTO_SSL3)
764 /* Needed only for SSL v3.0 secret */
765 unsigned char mac_enc[20]; /*!< SSL v3.0 secret (enc) */
766 unsigned char mac_dec[20]; /*!< SSL v3.0 secret (dec) */
767 #endif /* MBEDTLS_SSL_PROTO_SSL3 */
768
769 mbedtls_md_context_t md_ctx_enc; /*!< MAC (encryption) */
770 mbedtls_md_context_t md_ctx_dec; /*!< MAC (decryption) */
771
772 #if defined(MBEDTLS_SSL_ENCRYPT_THEN_MAC)
773 int encrypt_then_mac; /*!< flag for EtM activation */
774 #endif
775
776 #endif /* MBEDTLS_SSL_SOME_MODES_USE_MAC */
777
778 mbedtls_cipher_context_t cipher_ctx_enc; /*!< encryption context */
779 mbedtls_cipher_context_t cipher_ctx_dec; /*!< decryption context */
780 int minor_ver;
781
782 #if defined(MBEDTLS_SSL_DTLS_CONNECTION_ID)
783 uint8_t in_cid_len;
784 uint8_t out_cid_len;
785 unsigned char in_cid [ MBEDTLS_SSL_CID_OUT_LEN_MAX ];
786 unsigned char out_cid[ MBEDTLS_SSL_CID_OUT_LEN_MAX ];
787 #endif /* MBEDTLS_SSL_DTLS_CONNECTION_ID */
788
789 /*
790 * Session specific compression layer
791 */
792 #if defined(MBEDTLS_ZLIB_SUPPORT)
793 z_stream ctx_deflate; /*!< compression context */
794 z_stream ctx_inflate; /*!< decompression context */
795 #endif
796
797 #if defined(MBEDTLS_SSL_CONTEXT_SERIALIZATION)
798 /* We need the Hello random bytes in order to re-derive keys from the
799 * Master Secret and other session info, see ssl_populate_transform() */
800 unsigned char randbytes[64]; /*!< ServerHello.random+ClientHello.random */
801 #endif /* MBEDTLS_SSL_CONTEXT_SERIALIZATION */
802 };
803
804 /*
805 * Return 1 if the transform uses an AEAD cipher, 0 otherwise.
806 * Equivalently, return 0 if a separate MAC is used, 1 otherwise.
807 */
mbedtls_ssl_transform_uses_aead(const mbedtls_ssl_transform * transform)808 static inline int mbedtls_ssl_transform_uses_aead(
809 const mbedtls_ssl_transform *transform )
810 {
811 #if defined(MBEDTLS_SSL_SOME_MODES_USE_MAC)
812 return( transform->maclen == 0 && transform->taglen != 0 );
813 #else
814 (void) transform;
815 return( 1 );
816 #endif
817 }
818
819 /*
820 * Internal representation of record frames
821 *
822 * Instances come in two flavors:
823 * (1) Encrypted
824 * These always have data_offset = 0
825 * (2) Unencrypted
826 * These have data_offset set to the amount of
827 * pre-expansion during record protection. Concretely,
828 * this is the length of the fixed part of the explicit IV
829 * used for encryption, or 0 if no explicit IV is used
830 * (e.g. for CBC in TLS 1.0, or stream ciphers).
831 *
832 * The reason for the data_offset in the unencrypted case
833 * is to allow for in-place conversion of an unencrypted to
834 * an encrypted record. If the offset wasn't included, the
835 * encrypted content would need to be shifted afterwards to
836 * make space for the fixed IV.
837 *
838 */
839 #if MBEDTLS_SSL_CID_OUT_LEN_MAX > MBEDTLS_SSL_CID_IN_LEN_MAX
840 #define MBEDTLS_SSL_CID_LEN_MAX MBEDTLS_SSL_CID_OUT_LEN_MAX
841 #else
842 #define MBEDTLS_SSL_CID_LEN_MAX MBEDTLS_SSL_CID_IN_LEN_MAX
843 #endif
844
845 typedef struct
846 {
847 uint8_t ctr[8]; /* In TLS: The implicit record sequence number.
848 * In DTLS: The 2-byte epoch followed by
849 * the 6-byte sequence number.
850 * This is stored as a raw big endian byte array
851 * as opposed to a uint64_t because we rarely
852 * need to perform arithmetic on this, but do
853 * need it as a Byte array for the purpose of
854 * MAC computations. */
855 uint8_t type; /* The record content type. */
856 uint8_t ver[2]; /* SSL/TLS version as present on the wire.
857 * Convert to internal presentation of versions
858 * using mbedtls_ssl_read_version() and
859 * mbedtls_ssl_write_version().
860 * Keep wire-format for MAC computations. */
861
862 unsigned char *buf; /* Memory buffer enclosing the record content */
863 size_t buf_len; /* Buffer length */
864 size_t data_offset; /* Offset of record content */
865 size_t data_len; /* Length of record content */
866
867 #if defined(MBEDTLS_SSL_DTLS_CONNECTION_ID)
868 uint8_t cid_len; /* Length of the CID (0 if not present) */
869 unsigned char cid[ MBEDTLS_SSL_CID_LEN_MAX ]; /* The CID */
870 #endif /* MBEDTLS_SSL_DTLS_CONNECTION_ID */
871 } mbedtls_record;
872
873 #if defined(MBEDTLS_X509_CRT_PARSE_C)
874 /*
875 * List of certificate + private key pairs
876 */
877 struct mbedtls_ssl_key_cert
878 {
879 mbedtls_x509_crt *cert; /*!< cert */
880 mbedtls_pk_context *key; /*!< private key */
881 mbedtls_ssl_key_cert *next; /*!< next key/cert pair */
882 };
883 #endif /* MBEDTLS_X509_CRT_PARSE_C */
884
885 #if defined(MBEDTLS_SSL_PROTO_DTLS)
886 /*
887 * List of handshake messages kept around for resending
888 */
889 struct mbedtls_ssl_flight_item
890 {
891 unsigned char *p; /*!< message, including handshake headers */
892 size_t len; /*!< length of p */
893 unsigned char type; /*!< type of the message: handshake or CCS */
894 mbedtls_ssl_flight_item *next; /*!< next handshake message(s) */
895 };
896 #endif /* MBEDTLS_SSL_PROTO_DTLS */
897
898 #if defined(MBEDTLS_SSL_PROTO_TLS1_2) && \
899 defined(MBEDTLS_KEY_EXCHANGE_WITH_CERT_ENABLED)
900
901 /* Find an entry in a signature-hash set matching a given hash algorithm. */
902 mbedtls_md_type_t mbedtls_ssl_sig_hash_set_find( mbedtls_ssl_sig_hash_set_t *set,
903 mbedtls_pk_type_t sig_alg );
904 /* Add a signature-hash-pair to a signature-hash set */
905 void mbedtls_ssl_sig_hash_set_add( mbedtls_ssl_sig_hash_set_t *set,
906 mbedtls_pk_type_t sig_alg,
907 mbedtls_md_type_t md_alg );
908 /* Allow exactly one hash algorithm for each signature. */
909 void mbedtls_ssl_sig_hash_set_const_hash( mbedtls_ssl_sig_hash_set_t *set,
910 mbedtls_md_type_t md_alg );
911
912 /* Setup an empty signature-hash set */
mbedtls_ssl_sig_hash_set_init(mbedtls_ssl_sig_hash_set_t * set)913 static inline void mbedtls_ssl_sig_hash_set_init( mbedtls_ssl_sig_hash_set_t *set )
914 {
915 mbedtls_ssl_sig_hash_set_const_hash( set, MBEDTLS_MD_NONE );
916 }
917
918 #endif /* MBEDTLS_SSL_PROTO_TLS1_2) &&
919 MBEDTLS_KEY_EXCHANGE_WITH_CERT_ENABLED */
920
921 /**
922 * \brief Free referenced items in an SSL transform context and clear
923 * memory
924 *
925 * \param transform SSL transform context
926 */
927 void mbedtls_ssl_transform_free( mbedtls_ssl_transform *transform );
928
929 /**
930 * \brief Free referenced items in an SSL handshake context and clear
931 * memory
932 *
933 * \param ssl SSL context
934 */
935 void mbedtls_ssl_handshake_free( mbedtls_ssl_context *ssl );
936
937 MBEDTLS_CHECK_RETURN_CRITICAL
938 int mbedtls_ssl_handshake_client_step( mbedtls_ssl_context *ssl );
939 MBEDTLS_CHECK_RETURN_CRITICAL
940 int mbedtls_ssl_handshake_server_step( mbedtls_ssl_context *ssl );
941 void mbedtls_ssl_handshake_wrapup( mbedtls_ssl_context *ssl );
942
943 MBEDTLS_CHECK_RETURN_CRITICAL
944 int mbedtls_ssl_send_fatal_handshake_failure( mbedtls_ssl_context *ssl );
945
946 void mbedtls_ssl_reset_checksum( mbedtls_ssl_context *ssl );
947 MBEDTLS_CHECK_RETURN_CRITICAL
948 int mbedtls_ssl_derive_keys( mbedtls_ssl_context *ssl );
949
950 MBEDTLS_CHECK_RETURN_CRITICAL
951 int mbedtls_ssl_handle_message_type( mbedtls_ssl_context *ssl );
952 MBEDTLS_CHECK_RETURN_CRITICAL
953 int mbedtls_ssl_prepare_handshake_record( mbedtls_ssl_context *ssl );
954 void mbedtls_ssl_update_handshake_status( mbedtls_ssl_context *ssl );
955
956 /**
957 * \brief Update record layer
958 *
959 * This function roughly separates the implementation
960 * of the logic of (D)TLS from the implementation
961 * of the secure transport.
962 *
963 * \param ssl The SSL context to use.
964 * \param update_hs_digest This indicates if the handshake digest
965 * should be automatically updated in case
966 * a handshake message is found.
967 *
968 * \return 0 or non-zero error code.
969 *
970 * \note A clarification on what is called 'record layer' here
971 * is in order, as many sensible definitions are possible:
972 *
973 * The record layer takes as input an untrusted underlying
974 * transport (stream or datagram) and transforms it into
975 * a serially multiplexed, secure transport, which
976 * conceptually provides the following:
977 *
978 * (1) Three datagram based, content-agnostic transports
979 * for handshake, alert and CCS messages.
980 * (2) One stream- or datagram-based transport
981 * for application data.
982 * (3) Functionality for changing the underlying transform
983 * securing the contents.
984 *
985 * The interface to this functionality is given as follows:
986 *
987 * a Updating
988 * [Currently implemented by mbedtls_ssl_read_record]
989 *
990 * Check if and on which of the four 'ports' data is pending:
991 * Nothing, a controlling datagram of type (1), or application
992 * data (2). In any case data is present, internal buffers
993 * provide access to the data for the user to process it.
994 * Consumption of type (1) datagrams is done automatically
995 * on the next update, invalidating that the internal buffers
996 * for previous datagrams, while consumption of application
997 * data (2) is user-controlled.
998 *
999 * b Reading of application data
1000 * [Currently manual adaption of ssl->in_offt pointer]
1001 *
1002 * As mentioned in the last paragraph, consumption of data
1003 * is different from the automatic consumption of control
1004 * datagrams (1) because application data is treated as a stream.
1005 *
1006 * c Tracking availability of application data
1007 * [Currently manually through decreasing ssl->in_msglen]
1008 *
1009 * For efficiency and to retain datagram semantics for
1010 * application data in case of DTLS, the record layer
1011 * provides functionality for checking how much application
1012 * data is still available in the internal buffer.
1013 *
1014 * d Changing the transformation securing the communication.
1015 *
1016 * Given an opaque implementation of the record layer in the
1017 * above sense, it should be possible to implement the logic
1018 * of (D)TLS on top of it without the need to know anything
1019 * about the record layer's internals. This is done e.g.
1020 * in all the handshake handling functions, and in the
1021 * application data reading function mbedtls_ssl_read.
1022 *
1023 * \note The above tries to give a conceptual picture of the
1024 * record layer, but the current implementation deviates
1025 * from it in some places. For example, our implementation of
1026 * the update functionality through mbedtls_ssl_read_record
1027 * discards datagrams depending on the current state, which
1028 * wouldn't fall under the record layer's responsibility
1029 * following the above definition.
1030 *
1031 */
1032 MBEDTLS_CHECK_RETURN_CRITICAL
1033 int mbedtls_ssl_read_record( mbedtls_ssl_context *ssl,
1034 unsigned update_hs_digest );
1035 MBEDTLS_CHECK_RETURN_CRITICAL
1036 int mbedtls_ssl_fetch_input( mbedtls_ssl_context *ssl, size_t nb_want );
1037
1038 MBEDTLS_CHECK_RETURN_CRITICAL
1039 int mbedtls_ssl_write_handshake_msg( mbedtls_ssl_context *ssl );
1040 MBEDTLS_CHECK_RETURN_CRITICAL
1041 int mbedtls_ssl_write_record( mbedtls_ssl_context *ssl, uint8_t force_flush );
1042 MBEDTLS_CHECK_RETURN_CRITICAL
1043 int mbedtls_ssl_flush_output( mbedtls_ssl_context *ssl );
1044
1045 MBEDTLS_CHECK_RETURN_CRITICAL
1046 int mbedtls_ssl_parse_certificate( mbedtls_ssl_context *ssl );
1047 MBEDTLS_CHECK_RETURN_CRITICAL
1048 int mbedtls_ssl_write_certificate( mbedtls_ssl_context *ssl );
1049
1050 MBEDTLS_CHECK_RETURN_CRITICAL
1051 int mbedtls_ssl_parse_change_cipher_spec( mbedtls_ssl_context *ssl );
1052 MBEDTLS_CHECK_RETURN_CRITICAL
1053 int mbedtls_ssl_write_change_cipher_spec( mbedtls_ssl_context *ssl );
1054
1055 MBEDTLS_CHECK_RETURN_CRITICAL
1056 int mbedtls_ssl_parse_finished( mbedtls_ssl_context *ssl );
1057 MBEDTLS_CHECK_RETURN_CRITICAL
1058 int mbedtls_ssl_write_finished( mbedtls_ssl_context *ssl );
1059
1060 void mbedtls_ssl_optimize_checksum( mbedtls_ssl_context *ssl,
1061 const mbedtls_ssl_ciphersuite_t *ciphersuite_info );
1062
1063 #if defined(MBEDTLS_KEY_EXCHANGE_SOME_PSK_ENABLED)
1064 MBEDTLS_CHECK_RETURN_CRITICAL
1065 int mbedtls_ssl_psk_derive_premaster( mbedtls_ssl_context *ssl, mbedtls_key_exchange_type_t key_ex );
1066
1067 /**
1068 * Get the first defined PSK by order of precedence:
1069 * 1. handshake PSK set by \c mbedtls_ssl_set_hs_psk() in the PSK callback
1070 * 2. static PSK configured by \c mbedtls_ssl_conf_psk()
1071 * Return a code and update the pair (PSK, PSK length) passed to this function
1072 */
mbedtls_ssl_get_psk(const mbedtls_ssl_context * ssl,const unsigned char ** psk,size_t * psk_len)1073 static inline int mbedtls_ssl_get_psk( const mbedtls_ssl_context *ssl,
1074 const unsigned char **psk, size_t *psk_len )
1075 {
1076 if( ssl->handshake->psk != NULL && ssl->handshake->psk_len > 0 )
1077 {
1078 *psk = ssl->handshake->psk;
1079 *psk_len = ssl->handshake->psk_len;
1080 }
1081
1082 else if( ssl->conf->psk != NULL && ssl->conf->psk_len > 0 )
1083 {
1084 *psk = ssl->conf->psk;
1085 *psk_len = ssl->conf->psk_len;
1086 }
1087
1088 else
1089 {
1090 *psk = NULL;
1091 *psk_len = 0;
1092 return( MBEDTLS_ERR_SSL_PRIVATE_KEY_REQUIRED );
1093 }
1094
1095 return( 0 );
1096 }
1097
1098 #if defined(MBEDTLS_USE_PSA_CRYPTO)
1099 /**
1100 * Get the first defined opaque PSK by order of precedence:
1101 * 1. handshake PSK set by \c mbedtls_ssl_set_hs_psk_opaque() in the PSK
1102 * callback
1103 * 2. static PSK configured by \c mbedtls_ssl_conf_psk_opaque()
1104 * Return an opaque PSK
1105 */
mbedtls_ssl_get_opaque_psk(const mbedtls_ssl_context * ssl)1106 static inline psa_key_id_t mbedtls_ssl_get_opaque_psk(
1107 const mbedtls_ssl_context *ssl )
1108 {
1109 if( ! mbedtls_svc_key_id_is_null( ssl->handshake->psk_opaque ) )
1110 return( ssl->handshake->psk_opaque );
1111
1112 if( ! mbedtls_svc_key_id_is_null( ssl->conf->psk_opaque ) )
1113 return( ssl->conf->psk_opaque );
1114
1115 return( MBEDTLS_SVC_KEY_ID_INIT );
1116 }
1117 #endif /* MBEDTLS_USE_PSA_CRYPTO */
1118
1119 #endif /* MBEDTLS_KEY_EXCHANGE_SOME_PSK_ENABLED */
1120
1121 #if defined(MBEDTLS_PK_C)
1122 unsigned char mbedtls_ssl_sig_from_pk( mbedtls_pk_context *pk );
1123 unsigned char mbedtls_ssl_sig_from_pk_alg( mbedtls_pk_type_t type );
1124 mbedtls_pk_type_t mbedtls_ssl_pk_alg_from_sig( unsigned char sig );
1125 #endif
1126
1127 mbedtls_md_type_t mbedtls_ssl_md_alg_from_hash( unsigned char hash );
1128 unsigned char mbedtls_ssl_hash_from_md_alg( int md );
1129 MBEDTLS_CHECK_RETURN_CRITICAL
1130 int mbedtls_ssl_set_calc_verify_md( mbedtls_ssl_context *ssl, int md );
1131
1132 #if defined(MBEDTLS_ECP_C)
1133 MBEDTLS_CHECK_RETURN_CRITICAL
1134 int mbedtls_ssl_check_curve( const mbedtls_ssl_context *ssl, mbedtls_ecp_group_id grp_id );
1135 MBEDTLS_CHECK_RETURN_CRITICAL
1136 int mbedtls_ssl_check_curve_tls_id( const mbedtls_ssl_context *ssl, uint16_t tls_id );
1137 #endif
1138
1139 #if defined(MBEDTLS_KEY_EXCHANGE_WITH_CERT_ENABLED)
1140 MBEDTLS_CHECK_RETURN_CRITICAL
1141 int mbedtls_ssl_check_sig_hash( const mbedtls_ssl_context *ssl,
1142 mbedtls_md_type_t md );
1143 #endif
1144
1145 #if defined(MBEDTLS_SSL_DTLS_SRTP)
mbedtls_ssl_check_srtp_profile_value(const uint16_t srtp_profile_value)1146 static inline mbedtls_ssl_srtp_profile mbedtls_ssl_check_srtp_profile_value
1147 ( const uint16_t srtp_profile_value )
1148 {
1149 switch( srtp_profile_value )
1150 {
1151 case MBEDTLS_TLS_SRTP_AES128_CM_HMAC_SHA1_80:
1152 case MBEDTLS_TLS_SRTP_AES128_CM_HMAC_SHA1_32:
1153 case MBEDTLS_TLS_SRTP_NULL_HMAC_SHA1_80:
1154 case MBEDTLS_TLS_SRTP_NULL_HMAC_SHA1_32:
1155 return srtp_profile_value;
1156 default: break;
1157 }
1158 return( MBEDTLS_TLS_SRTP_UNSET );
1159 }
1160 #endif
1161
1162 #if defined(MBEDTLS_X509_CRT_PARSE_C)
mbedtls_ssl_own_key(mbedtls_ssl_context * ssl)1163 static inline mbedtls_pk_context *mbedtls_ssl_own_key( mbedtls_ssl_context *ssl )
1164 {
1165 mbedtls_ssl_key_cert *key_cert;
1166
1167 if( ssl->handshake != NULL && ssl->handshake->key_cert != NULL )
1168 key_cert = ssl->handshake->key_cert;
1169 else
1170 key_cert = ssl->conf->key_cert;
1171
1172 return( key_cert == NULL ? NULL : key_cert->key );
1173 }
1174
mbedtls_ssl_own_cert(mbedtls_ssl_context * ssl)1175 static inline mbedtls_x509_crt *mbedtls_ssl_own_cert( mbedtls_ssl_context *ssl )
1176 {
1177 mbedtls_ssl_key_cert *key_cert;
1178
1179 if( ssl->handshake != NULL && ssl->handshake->key_cert != NULL )
1180 key_cert = ssl->handshake->key_cert;
1181 else
1182 key_cert = ssl->conf->key_cert;
1183
1184 return( key_cert == NULL ? NULL : key_cert->cert );
1185 }
1186
1187 /*
1188 * Check usage of a certificate wrt extensions:
1189 * keyUsage, extendedKeyUsage (later), and nSCertType (later).
1190 *
1191 * Warning: cert_endpoint is the endpoint of the cert (ie, of our peer when we
1192 * check a cert we received from them)!
1193 *
1194 * Return 0 if everything is OK, -1 if not.
1195 */
1196 MBEDTLS_CHECK_RETURN_CRITICAL
1197 int mbedtls_ssl_check_cert_usage( const mbedtls_x509_crt *cert,
1198 const mbedtls_ssl_ciphersuite_t *ciphersuite,
1199 int cert_endpoint,
1200 uint32_t *flags );
1201 #endif /* MBEDTLS_X509_CRT_PARSE_C */
1202
1203 void mbedtls_ssl_write_version( int major, int minor, int transport,
1204 unsigned char ver[2] );
1205 void mbedtls_ssl_read_version( int *major, int *minor, int transport,
1206 const unsigned char ver[2] );
1207
mbedtls_ssl_in_hdr_len(const mbedtls_ssl_context * ssl)1208 static inline size_t mbedtls_ssl_in_hdr_len( const mbedtls_ssl_context *ssl )
1209 {
1210 #if !defined(MBEDTLS_SSL_PROTO_DTLS)
1211 ((void) ssl);
1212 #endif
1213
1214 #if defined(MBEDTLS_SSL_PROTO_DTLS)
1215 if( ssl->conf->transport == MBEDTLS_SSL_TRANSPORT_DATAGRAM )
1216 {
1217 return( 13 );
1218 }
1219 else
1220 #endif /* MBEDTLS_SSL_PROTO_DTLS */
1221 {
1222 return( 5 );
1223 }
1224 }
1225
mbedtls_ssl_out_hdr_len(const mbedtls_ssl_context * ssl)1226 static inline size_t mbedtls_ssl_out_hdr_len( const mbedtls_ssl_context *ssl )
1227 {
1228 return( (size_t) ( ssl->out_iv - ssl->out_hdr ) );
1229 }
1230
mbedtls_ssl_hs_hdr_len(const mbedtls_ssl_context * ssl)1231 static inline size_t mbedtls_ssl_hs_hdr_len( const mbedtls_ssl_context *ssl )
1232 {
1233 #if defined(MBEDTLS_SSL_PROTO_DTLS)
1234 if( ssl->conf->transport == MBEDTLS_SSL_TRANSPORT_DATAGRAM )
1235 return( 12 );
1236 #else
1237 ((void) ssl);
1238 #endif
1239 return( 4 );
1240 }
1241
1242 #if defined(MBEDTLS_SSL_PROTO_DTLS)
1243 void mbedtls_ssl_send_flight_completed( mbedtls_ssl_context *ssl );
1244 void mbedtls_ssl_recv_flight_completed( mbedtls_ssl_context *ssl );
1245 MBEDTLS_CHECK_RETURN_CRITICAL
1246 int mbedtls_ssl_resend( mbedtls_ssl_context *ssl );
1247 MBEDTLS_CHECK_RETURN_CRITICAL
1248 int mbedtls_ssl_flight_transmit( mbedtls_ssl_context *ssl );
1249 #endif
1250
1251 /* Visible for testing purposes only */
1252 #if defined(MBEDTLS_SSL_DTLS_ANTI_REPLAY)
1253 MBEDTLS_CHECK_RETURN_CRITICAL
1254 int mbedtls_ssl_dtls_replay_check( mbedtls_ssl_context const *ssl );
1255 void mbedtls_ssl_dtls_replay_update( mbedtls_ssl_context *ssl );
1256 #endif
1257
1258 MBEDTLS_CHECK_RETURN_CRITICAL
1259 int mbedtls_ssl_session_copy( mbedtls_ssl_session *dst,
1260 const mbedtls_ssl_session *src );
1261
1262 #if defined(MBEDTLS_SSL_PROTO_SSL3) || defined(MBEDTLS_SSL_PROTO_TLS1) || \
1263 defined(MBEDTLS_SSL_PROTO_TLS1_1)
1264 MBEDTLS_CHECK_RETURN_CRITICAL
1265 int mbedtls_ssl_get_key_exchange_md_ssl_tls( mbedtls_ssl_context *ssl,
1266 unsigned char *output,
1267 unsigned char *data, size_t data_len );
1268 #endif /* MBEDTLS_SSL_PROTO_SSL3 || MBEDTLS_SSL_PROTO_TLS1 || \
1269 MBEDTLS_SSL_PROTO_TLS1_1 */
1270
1271 #if defined(MBEDTLS_SSL_PROTO_TLS1) || defined(MBEDTLS_SSL_PROTO_TLS1_1) || \
1272 defined(MBEDTLS_SSL_PROTO_TLS1_2)
1273 /* The hash buffer must have at least MBEDTLS_MD_MAX_SIZE bytes of length. */
1274 MBEDTLS_CHECK_RETURN_CRITICAL
1275 int mbedtls_ssl_get_key_exchange_md_tls1_2( mbedtls_ssl_context *ssl,
1276 unsigned char *hash, size_t *hashlen,
1277 unsigned char *data, size_t data_len,
1278 mbedtls_md_type_t md_alg );
1279 #endif /* MBEDTLS_SSL_PROTO_TLS1 || MBEDTLS_SSL_PROTO_TLS1_1 || \
1280 MBEDTLS_SSL_PROTO_TLS1_2 */
1281
1282 #ifdef __cplusplus
1283 }
1284 #endif
1285
1286 void mbedtls_ssl_transform_init( mbedtls_ssl_transform *transform );
1287 MBEDTLS_CHECK_RETURN_CRITICAL
1288 int mbedtls_ssl_encrypt_buf( mbedtls_ssl_context *ssl,
1289 mbedtls_ssl_transform *transform,
1290 mbedtls_record *rec,
1291 int (*f_rng)(void *, unsigned char *, size_t),
1292 void *p_rng );
1293 MBEDTLS_CHECK_RETURN_CRITICAL
1294 int mbedtls_ssl_decrypt_buf( mbedtls_ssl_context const *ssl,
1295 mbedtls_ssl_transform *transform,
1296 mbedtls_record *rec );
1297
1298 /* Length of the "epoch" field in the record header */
mbedtls_ssl_ep_len(const mbedtls_ssl_context * ssl)1299 static inline size_t mbedtls_ssl_ep_len( const mbedtls_ssl_context *ssl )
1300 {
1301 #if defined(MBEDTLS_SSL_PROTO_DTLS)
1302 if( ssl->conf->transport == MBEDTLS_SSL_TRANSPORT_DATAGRAM )
1303 return( 2 );
1304 #else
1305 ((void) ssl);
1306 #endif
1307 return( 0 );
1308 }
1309
1310 #if defined(MBEDTLS_SSL_PROTO_DTLS)
1311 MBEDTLS_CHECK_RETURN_CRITICAL
1312 int mbedtls_ssl_resend_hello_request( mbedtls_ssl_context *ssl );
1313 #endif /* MBEDTLS_SSL_PROTO_DTLS */
1314
1315 void mbedtls_ssl_set_timer( mbedtls_ssl_context *ssl, uint32_t millisecs );
1316 MBEDTLS_CHECK_RETURN_CRITICAL
1317 int mbedtls_ssl_check_timer( mbedtls_ssl_context *ssl );
1318
1319 void mbedtls_ssl_reset_in_out_pointers( mbedtls_ssl_context *ssl );
1320 void mbedtls_ssl_update_out_pointers( mbedtls_ssl_context *ssl,
1321 mbedtls_ssl_transform *transform );
1322 void mbedtls_ssl_update_in_pointers( mbedtls_ssl_context *ssl );
1323
1324 MBEDTLS_CHECK_RETURN_CRITICAL
1325 int mbedtls_ssl_session_reset_int( mbedtls_ssl_context *ssl, int partial );
1326
1327 #if defined(MBEDTLS_SSL_DTLS_ANTI_REPLAY)
1328 void mbedtls_ssl_dtls_replay_reset( mbedtls_ssl_context *ssl );
1329 #endif
1330
1331 void mbedtls_ssl_handshake_wrapup_free_hs_transform( mbedtls_ssl_context *ssl );
1332
1333 #if defined(MBEDTLS_SSL_RENEGOTIATION)
1334 MBEDTLS_CHECK_RETURN_CRITICAL
1335 int mbedtls_ssl_start_renegotiation( mbedtls_ssl_context *ssl );
1336 #endif /* MBEDTLS_SSL_RENEGOTIATION */
1337
1338 #if defined(MBEDTLS_SSL_PROTO_DTLS)
1339 size_t mbedtls_ssl_get_current_mtu( const mbedtls_ssl_context *ssl );
1340 void mbedtls_ssl_buffering_free( mbedtls_ssl_context *ssl );
1341 void mbedtls_ssl_flight_free( mbedtls_ssl_flight_item *flight );
1342 #endif /* MBEDTLS_SSL_PROTO_DTLS */
1343
1344 #if defined(MBEDTLS_TEST_HOOKS)
1345 int mbedtls_ssl_check_dtls_clihlo_cookie(
1346 mbedtls_ssl_context *ssl,
1347 const unsigned char *cli_id, size_t cli_id_len,
1348 const unsigned char *in, size_t in_len,
1349 unsigned char *obuf, size_t buf_len, size_t *olen );
1350 #endif
1351
1352 #endif /* ssl_internal.h */
1353