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 OR GPL-2.0-or-later
9 *
10 * This file is provided under the Apache License 2.0, or the
11 * GNU General Public License v2.0 or later.
12 *
13 * **********
14 * Apache License 2.0:
15 *
16 * Licensed under the Apache License, Version 2.0 (the "License"); you may
17 * not use this file except in compliance with the License.
18 * You may obtain a copy of the License at
19 *
20 * http://www.apache.org/licenses/LICENSE-2.0
21 *
22 * Unless required by applicable law or agreed to in writing, software
23 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
24 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
25 * See the License for the specific language governing permissions and
26 * limitations under the License.
27 *
28 * **********
29 *
30 * **********
31 * GNU General Public License v2.0 or later:
32 *
33 * This program is free software; you can redistribute it and/or modify
34 * it under the terms of the GNU General Public License as published by
35 * the Free Software Foundation; either version 2 of the License, or
36 * (at your option) any later version.
37 *
38 * This program is distributed in the hope that it will be useful,
39 * but WITHOUT ANY WARRANTY; without even the implied warranty of
40 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
41 * GNU General Public License for more details.
42 *
43 * You should have received a copy of the GNU General Public License along
44 * with this program; if not, write to the Free Software Foundation, Inc.,
45 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
46 *
47 * **********
48 */
49 #ifndef MBEDTLS_SSL_INTERNAL_H
50 #define MBEDTLS_SSL_INTERNAL_H
51
52 #if !defined(MBEDTLS_CONFIG_FILE)
53 #include "config.h"
54 #else
55 #include MBEDTLS_CONFIG_FILE
56 #endif
57
58 #include "ssl.h"
59 #include "cipher.h"
60
61 #if defined(MBEDTLS_MD5_C)
62 #include "md5.h"
63 #endif
64
65 #if defined(MBEDTLS_SHA1_C)
66 #include "sha1.h"
67 #endif
68
69 #if defined(MBEDTLS_SHA256_C)
70 #include "sha256.h"
71 #endif
72
73 #if defined(MBEDTLS_SHA512_C)
74 #include "sha512.h"
75 #endif
76
77 #if defined(MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED)
78 #include "ecjpake.h"
79 #endif
80
81 #if ( defined(__ARMCC_VERSION) || defined(_MSC_VER) ) && \
82 !defined(inline) && !defined(__cplusplus)
83 #define inline __inline
84 #endif
85
86 /* Determine minimum supported version */
87 #define MBEDTLS_SSL_MIN_MAJOR_VERSION MBEDTLS_SSL_MAJOR_VERSION_3
88
89 #if defined(MBEDTLS_SSL_PROTO_SSL3)
90 #define MBEDTLS_SSL_MIN_MINOR_VERSION MBEDTLS_SSL_MINOR_VERSION_0
91 #else
92 #if defined(MBEDTLS_SSL_PROTO_TLS1)
93 #define MBEDTLS_SSL_MIN_MINOR_VERSION MBEDTLS_SSL_MINOR_VERSION_1
94 #else
95 #if defined(MBEDTLS_SSL_PROTO_TLS1_1)
96 #define MBEDTLS_SSL_MIN_MINOR_VERSION MBEDTLS_SSL_MINOR_VERSION_2
97 #else
98 #if defined(MBEDTLS_SSL_PROTO_TLS1_2)
99 #define MBEDTLS_SSL_MIN_MINOR_VERSION MBEDTLS_SSL_MINOR_VERSION_3
100 #endif /* MBEDTLS_SSL_PROTO_TLS1_2 */
101 #endif /* MBEDTLS_SSL_PROTO_TLS1_1 */
102 #endif /* MBEDTLS_SSL_PROTO_TLS1 */
103 #endif /* MBEDTLS_SSL_PROTO_SSL3 */
104
105 #define MBEDTLS_SSL_MIN_VALID_MINOR_VERSION MBEDTLS_SSL_MINOR_VERSION_1
106 #define MBEDTLS_SSL_MIN_VALID_MAJOR_VERSION MBEDTLS_SSL_MAJOR_VERSION_3
107
108 /* Determine maximum supported version */
109 #define MBEDTLS_SSL_MAX_MAJOR_VERSION MBEDTLS_SSL_MAJOR_VERSION_3
110
111 #if defined(MBEDTLS_SSL_PROTO_TLS1_2)
112 #define MBEDTLS_SSL_MAX_MINOR_VERSION MBEDTLS_SSL_MINOR_VERSION_3
113 #else
114 #if defined(MBEDTLS_SSL_PROTO_TLS1_1)
115 #define MBEDTLS_SSL_MAX_MINOR_VERSION MBEDTLS_SSL_MINOR_VERSION_2
116 #else
117 #if defined(MBEDTLS_SSL_PROTO_TLS1)
118 #define MBEDTLS_SSL_MAX_MINOR_VERSION MBEDTLS_SSL_MINOR_VERSION_1
119 #else
120 #if defined(MBEDTLS_SSL_PROTO_SSL3)
121 #define MBEDTLS_SSL_MAX_MINOR_VERSION MBEDTLS_SSL_MINOR_VERSION_0
122 #endif /* MBEDTLS_SSL_PROTO_SSL3 */
123 #endif /* MBEDTLS_SSL_PROTO_TLS1 */
124 #endif /* MBEDTLS_SSL_PROTO_TLS1_1 */
125 #endif /* MBEDTLS_SSL_PROTO_TLS1_2 */
126
127 #define MBEDTLS_SSL_INITIAL_HANDSHAKE 0
128 #define MBEDTLS_SSL_RENEGOTIATION_IN_PROGRESS 1 /* In progress */
129 #define MBEDTLS_SSL_RENEGOTIATION_DONE 2 /* Done or aborted */
130 #define MBEDTLS_SSL_RENEGOTIATION_PENDING 3 /* Requested (server only) */
131
132 /*
133 * DTLS retransmission states, see RFC 6347 4.2.4
134 *
135 * The SENDING state is merged in PREPARING for initial sends,
136 * but is distinct for resends.
137 *
138 * Note: initial state is wrong for server, but is not used anyway.
139 */
140 #define MBEDTLS_SSL_RETRANS_PREPARING 0
141 #define MBEDTLS_SSL_RETRANS_SENDING 1
142 #define MBEDTLS_SSL_RETRANS_WAITING 2
143 #define MBEDTLS_SSL_RETRANS_FINISHED 3
144
145 /* This macro determines whether CBC is supported. */
146 #if defined(MBEDTLS_CIPHER_MODE_CBC) && \
147 ( defined(MBEDTLS_AES_C) || \
148 defined(MBEDTLS_CAMELLIA_C) || \
149 defined(MBEDTLS_DES_C) )
150 #define MBEDTLS_SSL_SOME_SUITES_USE_CBC
151 #endif
152
153 /* This macro determines whether the CBC construct used in TLS 1.0-1.2 (as
154 * opposed to the very different CBC construct used in SSLv3) is supported. */
155 #if defined(MBEDTLS_SSL_SOME_SUITES_USE_CBC) && \
156 ( defined(MBEDTLS_SSL_PROTO_TLS1) || \
157 defined(MBEDTLS_SSL_PROTO_TLS1_1) || \
158 defined(MBEDTLS_SSL_PROTO_TLS1_2) )
159 #define MBEDTLS_SSL_SOME_SUITES_USE_TLS_CBC
160 #endif
161
162 /*
163 * Allow extra bytes for record, authentication and encryption overhead:
164 * counter (8) + header (5) + IV(16) + MAC (16-48) + padding (0-256)
165 * and allow for a maximum of 1024 of compression expansion if
166 * enabled.
167 */
168 #if defined(MBEDTLS_ZLIB_SUPPORT)
169 #define MBEDTLS_SSL_COMPRESSION_ADD 1024
170 #else
171 #define MBEDTLS_SSL_COMPRESSION_ADD 0
172 #endif
173
174 #if defined(MBEDTLS_ARC4_C) || defined(MBEDTLS_CIPHER_MODE_CBC)
175 /* Ciphersuites using HMAC */
176 #if defined(MBEDTLS_SHA512_C)
177 #define MBEDTLS_SSL_MAC_ADD 48 /* SHA-384 used for HMAC */
178 #elif defined(MBEDTLS_SHA256_C)
179 #define MBEDTLS_SSL_MAC_ADD 32 /* SHA-256 used for HMAC */
180 #else
181 #define MBEDTLS_SSL_MAC_ADD 20 /* SHA-1 used for HMAC */
182 #endif
183 #else
184 /* AEAD ciphersuites: GCM and CCM use a 128 bits tag */
185 #define MBEDTLS_SSL_MAC_ADD 16
186 #endif
187
188 #if defined(MBEDTLS_CIPHER_MODE_CBC)
189 #define MBEDTLS_SSL_PADDING_ADD 256
190 #else
191 #define MBEDTLS_SSL_PADDING_ADD 0
192 #endif
193
194 #define MBEDTLS_SSL_PAYLOAD_LEN ( MBEDTLS_SSL_MAX_CONTENT_LEN \
195 + MBEDTLS_SSL_COMPRESSION_ADD \
196 + MBEDTLS_MAX_IV_LENGTH \
197 + MBEDTLS_SSL_MAC_ADD \
198 + MBEDTLS_SSL_PADDING_ADD \
199 )
200
201 /* Maximum size in bytes of list in sig-hash algorithm ext., RFC 5246 */
202 #define MBEDTLS_SSL_MAX_SIG_HASH_ALG_LIST_LEN 65534
203
204 /* Maximum size in bytes of list in supported elliptic curve ext., RFC 4492 */
205 #define MBEDTLS_SSL_MAX_CURVE_LIST_LEN 65535
206
207 /*
208 * Check that we obey the standard's message size bounds
209 */
210
211 #if MBEDTLS_SSL_MAX_CONTENT_LEN > 16384
212 #error Bad configuration - record content too large.
213 #endif
214
215 #if MBEDTLS_SSL_PAYLOAD_LEN > 16384 + 2048
216 #error Bad configuration - protected record payload too large.
217 #endif
218
219 /* Note: Even though the TLS record header is only 5 bytes
220 long, we're internally using 8 bytes to store the
221 implicit sequence number. */
222 #define MBEDTLS_SSL_HEADER_LEN 13
223
224 #define MBEDTLS_SSL_BUFFER_LEN \
225 ( ( MBEDTLS_SSL_HEADER_LEN ) + ( MBEDTLS_SSL_PAYLOAD_LEN ) )
226
227 /*
228 * TLS extension flags (for extensions with outgoing ServerHello content
229 * that need it (e.g. for RENEGOTIATION_INFO the server already knows because
230 * of state of the renegotiation flag, so no indicator is required)
231 */
232 #define MBEDTLS_TLS_EXT_SUPPORTED_POINT_FORMATS_PRESENT (1 << 0)
233 #define MBEDTLS_TLS_EXT_ECJPAKE_KKPP_OK (1 << 1)
234
235 /**
236 * \brief This function checks if the remaining size in a buffer is
237 * greater or equal than a needed space.
238 *
239 * \param cur Pointer to the current position in the buffer.
240 * \param end Pointer to one past the end of the buffer.
241 * \param need Needed space in bytes.
242 *
243 * \return Zero if the needed space is available in the buffer, non-zero
244 * otherwise.
245 */
mbedtls_ssl_chk_buf_ptr(const uint8_t * cur,const uint8_t * end,size_t need)246 static inline int mbedtls_ssl_chk_buf_ptr( const uint8_t *cur,
247 const uint8_t *end, size_t need )
248 {
249 return( ( cur > end ) || ( need > (size_t)( end - cur ) ) );
250 }
251
252 /**
253 * \brief This macro checks if the remaining size in a buffer is
254 * greater or equal than a needed space. If it is not the case,
255 * it returns an SSL_BUFFER_TOO_SMALL error.
256 *
257 * \param cur Pointer to the current position in the buffer.
258 * \param end Pointer to one past the end of the buffer.
259 * \param need Needed space in bytes.
260 *
261 */
262 #define MBEDTLS_SSL_CHK_BUF_PTR( cur, end, need ) \
263 do { \
264 if( mbedtls_ssl_chk_buf_ptr( ( cur ), ( end ), ( need ) ) != 0 ) \
265 { \
266 return( MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL ); \
267 } \
268 } while( 0 )
269
270 #ifdef __cplusplus
271 extern "C" {
272 #endif
273
274 #if defined(MBEDTLS_SSL_PROTO_TLS1_2) && \
275 defined(MBEDTLS_KEY_EXCHANGE__WITH_CERT__ENABLED)
276 /*
277 * Abstraction for a grid of allowed signature-hash-algorithm pairs.
278 */
279 struct mbedtls_ssl_sig_hash_set_t
280 {
281 /* At the moment, we only need to remember a single suitable
282 * hash algorithm per signature algorithm. As long as that's
283 * the case - and we don't need a general lookup function -
284 * we can implement the sig-hash-set as a map from signatures
285 * to hash algorithms. */
286 mbedtls_md_type_t rsa;
287 mbedtls_md_type_t ecdsa;
288 };
289 #endif /* MBEDTLS_SSL_PROTO_TLS1_2 &&
290 MBEDTLS_KEY_EXCHANGE__WITH_CERT__ENABLED */
291
292 /*
293 * This structure contains the parameters only needed during handshake.
294 */
295 struct mbedtls_ssl_handshake_params
296 {
297 /*
298 * Handshake specific crypto variables
299 */
300
301 #if defined(MBEDTLS_SSL_PROTO_TLS1_2) && \
302 defined(MBEDTLS_KEY_EXCHANGE__WITH_CERT__ENABLED)
303 mbedtls_ssl_sig_hash_set_t hash_algs; /*!< Set of suitable sig-hash pairs */
304 #endif
305 #if defined(MBEDTLS_DHM_C)
306 mbedtls_dhm_context dhm_ctx; /*!< DHM key exchange */
307 #endif
308 #if defined(MBEDTLS_ECDH_C)
309 mbedtls_ecdh_context ecdh_ctx; /*!< ECDH key exchange */
310 #endif
311 #if defined(MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED)
312 mbedtls_ecjpake_context ecjpake_ctx; /*!< EC J-PAKE key exchange */
313 #if defined(MBEDTLS_SSL_CLI_C)
314 unsigned char *ecjpake_cache; /*!< Cache for ClientHello ext */
315 size_t ecjpake_cache_len; /*!< Length of cached data */
316 #endif
317 #endif /* MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED */
318 #if defined(MBEDTLS_ECDH_C) || defined(MBEDTLS_ECDSA_C) || \
319 defined(MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED)
320 const mbedtls_ecp_curve_info **curves; /*!< Supported elliptic curves */
321 #endif
322 #if defined(MBEDTLS_KEY_EXCHANGE__SOME__PSK_ENABLED)
323 unsigned char *psk; /*!< PSK from the callback */
324 size_t psk_len; /*!< Length of PSK from callback */
325 #endif
326 #if defined(MBEDTLS_X509_CRT_PARSE_C)
327 mbedtls_ssl_key_cert *key_cert; /*!< chosen key/cert pair (server) */
328 #if defined(MBEDTLS_SSL_SERVER_NAME_INDICATION)
329 int sni_authmode; /*!< authmode from SNI callback */
330 mbedtls_ssl_key_cert *sni_key_cert; /*!< key/cert list from SNI */
331 mbedtls_x509_crt *sni_ca_chain; /*!< trusted CAs from SNI callback */
332 mbedtls_x509_crl *sni_ca_crl; /*!< trusted CAs CRLs from SNI */
333 #endif /* MBEDTLS_SSL_SERVER_NAME_INDICATION */
334 #endif /* MBEDTLS_X509_CRT_PARSE_C */
335 #if defined(MBEDTLS_SSL_PROTO_DTLS)
336 unsigned int out_msg_seq; /*!< Outgoing handshake sequence number */
337 unsigned int in_msg_seq; /*!< Incoming handshake sequence number */
338
339 unsigned char *verify_cookie; /*!< Cli: HelloVerifyRequest cookie
340 Srv: unused */
341 unsigned char verify_cookie_len; /*!< Cli: cookie length
342 Srv: flag for sending a cookie */
343
344 unsigned char *hs_msg; /*!< Reassembled handshake message */
345
346 uint32_t retransmit_timeout; /*!< Current value of timeout */
347 unsigned char retransmit_state; /*!< Retransmission state */
348 mbedtls_ssl_flight_item *flight; /*!< Current outgoing flight */
349 mbedtls_ssl_flight_item *cur_msg; /*!< Current message in flight */
350 unsigned int in_flight_start_seq; /*!< Minimum message sequence in the
351 flight being received */
352 mbedtls_ssl_transform *alt_transform_out; /*!< Alternative transform for
353 resending messages */
354 unsigned char alt_out_ctr[8]; /*!< Alternative record epoch/counter
355 for resending messages */
356 #endif /* MBEDTLS_SSL_PROTO_DTLS */
357
358 /*
359 * Checksum contexts
360 */
361 #if defined(MBEDTLS_SSL_PROTO_SSL3) || defined(MBEDTLS_SSL_PROTO_TLS1) || \
362 defined(MBEDTLS_SSL_PROTO_TLS1_1)
363 mbedtls_md5_context fin_md5;
364 mbedtls_sha1_context fin_sha1;
365 #endif
366 #if defined(MBEDTLS_SSL_PROTO_TLS1_2)
367 #if defined(MBEDTLS_SHA256_C)
368 mbedtls_sha256_context fin_sha256;
369 #endif
370 #if defined(MBEDTLS_SHA512_C)
371 mbedtls_sha512_context fin_sha512;
372 #endif
373 #endif /* MBEDTLS_SSL_PROTO_TLS1_2 */
374
375 void (*update_checksum)(mbedtls_ssl_context *, const unsigned char *, size_t);
376 void (*calc_verify)(mbedtls_ssl_context *, unsigned char *);
377 void (*calc_finished)(mbedtls_ssl_context *, unsigned char *, int);
378 int (*tls_prf)(const unsigned char *, size_t, const char *,
379 const unsigned char *, size_t,
380 unsigned char *, size_t);
381
382 size_t pmslen; /*!< premaster length */
383
384 unsigned char randbytes[64]; /*!< random bytes */
385 unsigned char premaster[MBEDTLS_PREMASTER_SIZE];
386 /*!< premaster secret */
387
388 int resume; /*!< session resume indicator*/
389 int max_major_ver; /*!< max. major version client*/
390 int max_minor_ver; /*!< max. minor version client*/
391 int cli_exts; /*!< client extension presence*/
392
393 #if defined(MBEDTLS_SSL_SESSION_TICKETS)
394 int new_session_ticket; /*!< use NewSessionTicket? */
395 #endif /* MBEDTLS_SSL_SESSION_TICKETS */
396 #if defined(MBEDTLS_SSL_EXTENDED_MASTER_SECRET)
397 int extended_ms; /*!< use Extended Master Secret? */
398 #endif
399 };
400
401 /*
402 * This structure contains a full set of runtime transform parameters
403 * either in negotiation or active.
404 */
405 struct mbedtls_ssl_transform
406 {
407 /*
408 * Session specific crypto layer
409 */
410 const mbedtls_ssl_ciphersuite_t *ciphersuite_info;
411 /*!< Chosen cipersuite_info */
412 unsigned int keylen; /*!< symmetric key length (bytes) */
413 size_t minlen; /*!< min. ciphertext length */
414 size_t ivlen; /*!< IV length */
415 size_t fixed_ivlen; /*!< Fixed part of IV (AEAD) */
416 size_t maclen; /*!< MAC length */
417
418 unsigned char iv_enc[16]; /*!< IV (encryption) */
419 unsigned char iv_dec[16]; /*!< IV (decryption) */
420
421 #if defined(MBEDTLS_SSL_PROTO_SSL3)
422 /* Needed only for SSL v3.0 secret */
423 unsigned char mac_enc[20]; /*!< SSL v3.0 secret (enc) */
424 unsigned char mac_dec[20]; /*!< SSL v3.0 secret (dec) */
425 #endif /* MBEDTLS_SSL_PROTO_SSL3 */
426
427 mbedtls_md_context_t md_ctx_enc; /*!< MAC (encryption) */
428 mbedtls_md_context_t md_ctx_dec; /*!< MAC (decryption) */
429
430 mbedtls_cipher_context_t cipher_ctx_enc; /*!< encryption context */
431 mbedtls_cipher_context_t cipher_ctx_dec; /*!< decryption context */
432
433 /*
434 * Session specific compression layer
435 */
436 #if defined(MBEDTLS_ZLIB_SUPPORT)
437 z_stream ctx_deflate; /*!< compression context */
438 z_stream ctx_inflate; /*!< decompression context */
439 #endif
440 };
441
442 #if defined(MBEDTLS_X509_CRT_PARSE_C)
443 /*
444 * List of certificate + private key pairs
445 */
446 struct mbedtls_ssl_key_cert
447 {
448 mbedtls_x509_crt *cert; /*!< cert */
449 mbedtls_pk_context *key; /*!< private key */
450 mbedtls_ssl_key_cert *next; /*!< next key/cert pair */
451 };
452 #endif /* MBEDTLS_X509_CRT_PARSE_C */
453
454 #if defined(MBEDTLS_SSL_PROTO_DTLS)
455 /*
456 * List of handshake messages kept around for resending
457 */
458 struct mbedtls_ssl_flight_item
459 {
460 unsigned char *p; /*!< message, including handshake headers */
461 size_t len; /*!< length of p */
462 unsigned char type; /*!< type of the message: handshake or CCS */
463 mbedtls_ssl_flight_item *next; /*!< next handshake message(s) */
464 };
465 #endif /* MBEDTLS_SSL_PROTO_DTLS */
466
467 #if defined(MBEDTLS_SSL_PROTO_TLS1_2) && \
468 defined(MBEDTLS_KEY_EXCHANGE__WITH_CERT__ENABLED)
469
470 /* Find an entry in a signature-hash set matching a given hash algorithm. */
471 mbedtls_md_type_t mbedtls_ssl_sig_hash_set_find( mbedtls_ssl_sig_hash_set_t *set,
472 mbedtls_pk_type_t sig_alg );
473 /* Add a signature-hash-pair to a signature-hash set */
474 void mbedtls_ssl_sig_hash_set_add( mbedtls_ssl_sig_hash_set_t *set,
475 mbedtls_pk_type_t sig_alg,
476 mbedtls_md_type_t md_alg );
477 /* Allow exactly one hash algorithm for each signature. */
478 void mbedtls_ssl_sig_hash_set_const_hash( mbedtls_ssl_sig_hash_set_t *set,
479 mbedtls_md_type_t md_alg );
480
481 /* Setup an empty signature-hash set */
mbedtls_ssl_sig_hash_set_init(mbedtls_ssl_sig_hash_set_t * set)482 static inline void mbedtls_ssl_sig_hash_set_init( mbedtls_ssl_sig_hash_set_t *set )
483 {
484 mbedtls_ssl_sig_hash_set_const_hash( set, MBEDTLS_MD_NONE );
485 }
486
487 #endif /* MBEDTLS_SSL_PROTO_TLS1_2) &&
488 MBEDTLS_KEY_EXCHANGE__WITH_CERT__ENABLED */
489
490 /**
491 * \brief Free referenced items in an SSL transform context and clear
492 * memory
493 *
494 * \param transform SSL transform context
495 */
496 void mbedtls_ssl_transform_free( mbedtls_ssl_transform *transform );
497
498 /**
499 * \brief Free referenced items in an SSL handshake context and clear
500 * memory
501 *
502 * \param handshake SSL handshake context
503 */
504 void mbedtls_ssl_handshake_free( mbedtls_ssl_handshake_params *handshake );
505
506 int mbedtls_ssl_handshake_client_step( mbedtls_ssl_context *ssl );
507 int mbedtls_ssl_handshake_server_step( mbedtls_ssl_context *ssl );
508 void mbedtls_ssl_handshake_wrapup( mbedtls_ssl_context *ssl );
509
510 int mbedtls_ssl_send_fatal_handshake_failure( mbedtls_ssl_context *ssl );
511
512 void mbedtls_ssl_reset_checksum( mbedtls_ssl_context *ssl );
513 int mbedtls_ssl_derive_keys( mbedtls_ssl_context *ssl );
514
515 int mbedtls_ssl_read_record_layer( mbedtls_ssl_context *ssl );
516 int mbedtls_ssl_handle_message_type( mbedtls_ssl_context *ssl );
517 int mbedtls_ssl_prepare_handshake_record( mbedtls_ssl_context *ssl );
518 void mbedtls_ssl_update_handshake_status( mbedtls_ssl_context *ssl );
519
520 /**
521 * \brief Update record layer
522 *
523 * This function roughly separates the implementation
524 * of the logic of (D)TLS from the implementation
525 * of the secure transport.
526 *
527 * \param ssl SSL context to use
528 *
529 * \return 0 or non-zero error code.
530 *
531 * \note A clarification on what is called 'record layer' here
532 * is in order, as many sensible definitions are possible:
533 *
534 * The record layer takes as input an untrusted underlying
535 * transport (stream or datagram) and transforms it into
536 * a serially multiplexed, secure transport, which
537 * conceptually provides the following:
538 *
539 * (1) Three datagram based, content-agnostic transports
540 * for handshake, alert and CCS messages.
541 * (2) One stream- or datagram-based transport
542 * for application data.
543 * (3) Functionality for changing the underlying transform
544 * securing the contents.
545 *
546 * The interface to this functionality is given as follows:
547 *
548 * a Updating
549 * [Currently implemented by mbedtls_ssl_read_record]
550 *
551 * Check if and on which of the four 'ports' data is pending:
552 * Nothing, a controlling datagram of type (1), or application
553 * data (2). In any case data is present, internal buffers
554 * provide access to the data for the user to process it.
555 * Consumption of type (1) datagrams is done automatically
556 * on the next update, invalidating that the internal buffers
557 * for previous datagrams, while consumption of application
558 * data (2) is user-controlled.
559 *
560 * b Reading of application data
561 * [Currently manual adaption of ssl->in_offt pointer]
562 *
563 * As mentioned in the last paragraph, consumption of data
564 * is different from the automatic consumption of control
565 * datagrams (1) because application data is treated as a stream.
566 *
567 * c Tracking availability of application data
568 * [Currently manually through decreasing ssl->in_msglen]
569 *
570 * For efficiency and to retain datagram semantics for
571 * application data in case of DTLS, the record layer
572 * provides functionality for checking how much application
573 * data is still available in the internal buffer.
574 *
575 * d Changing the transformation securing the communication.
576 *
577 * Given an opaque implementation of the record layer in the
578 * above sense, it should be possible to implement the logic
579 * of (D)TLS on top of it without the need to know anything
580 * about the record layer's internals. This is done e.g.
581 * in all the handshake handling functions, and in the
582 * application data reading function mbedtls_ssl_read.
583 *
584 * \note The above tries to give a conceptual picture of the
585 * record layer, but the current implementation deviates
586 * from it in some places. For example, our implementation of
587 * the update functionality through mbedtls_ssl_read_record
588 * discards datagrams depending on the current state, which
589 * wouldn't fall under the record layer's responsibility
590 * following the above definition.
591 *
592 */
593 int mbedtls_ssl_read_record( mbedtls_ssl_context *ssl );
594 int mbedtls_ssl_fetch_input( mbedtls_ssl_context *ssl, size_t nb_want );
595
596 int mbedtls_ssl_write_record( mbedtls_ssl_context *ssl );
597 int mbedtls_ssl_flush_output( mbedtls_ssl_context *ssl );
598
599 int mbedtls_ssl_parse_certificate( mbedtls_ssl_context *ssl );
600 int mbedtls_ssl_write_certificate( mbedtls_ssl_context *ssl );
601
602 int mbedtls_ssl_parse_change_cipher_spec( mbedtls_ssl_context *ssl );
603 int mbedtls_ssl_write_change_cipher_spec( mbedtls_ssl_context *ssl );
604
605 int mbedtls_ssl_parse_finished( mbedtls_ssl_context *ssl );
606 int mbedtls_ssl_write_finished( mbedtls_ssl_context *ssl );
607
608 void mbedtls_ssl_optimize_checksum( mbedtls_ssl_context *ssl,
609 const mbedtls_ssl_ciphersuite_t *ciphersuite_info );
610
611 #if defined(MBEDTLS_KEY_EXCHANGE__SOME__PSK_ENABLED)
612 int mbedtls_ssl_psk_derive_premaster( mbedtls_ssl_context *ssl, mbedtls_key_exchange_type_t key_ex );
613 #endif
614
615 #if defined(MBEDTLS_PK_C)
616 unsigned char mbedtls_ssl_sig_from_pk( mbedtls_pk_context *pk );
617 unsigned char mbedtls_ssl_sig_from_pk_alg( mbedtls_pk_type_t type );
618 mbedtls_pk_type_t mbedtls_ssl_pk_alg_from_sig( unsigned char sig );
619 #endif
620
621 mbedtls_md_type_t mbedtls_ssl_md_alg_from_hash( unsigned char hash );
622 unsigned char mbedtls_ssl_hash_from_md_alg( int md );
623 int mbedtls_ssl_set_calc_verify_md( mbedtls_ssl_context *ssl, int md );
624
625 #if defined(MBEDTLS_ECP_C)
626 int mbedtls_ssl_check_curve( const mbedtls_ssl_context *ssl, mbedtls_ecp_group_id grp_id );
627 #endif
628
629 #if defined(MBEDTLS_KEY_EXCHANGE__WITH_CERT__ENABLED)
630 int mbedtls_ssl_check_sig_hash( const mbedtls_ssl_context *ssl,
631 mbedtls_md_type_t md );
632 #endif
633
634 #if defined(MBEDTLS_X509_CRT_PARSE_C)
mbedtls_ssl_own_key(mbedtls_ssl_context * ssl)635 static inline mbedtls_pk_context *mbedtls_ssl_own_key( mbedtls_ssl_context *ssl )
636 {
637 mbedtls_ssl_key_cert *key_cert;
638
639 if( ssl->handshake != NULL && ssl->handshake->key_cert != NULL )
640 key_cert = ssl->handshake->key_cert;
641 else if ( ssl->conf->endpoint == MBEDTLS_SSL_IS_CLIENT
642 && ssl->handshake && ssl->handshake->sni_key_cert )
643 key_cert = ssl->handshake->sni_key_cert;
644 else
645 key_cert = ssl->conf->key_cert;
646
647 return( key_cert == NULL ? NULL : key_cert->key );
648 }
649
mbedtls_ssl_own_cert(mbedtls_ssl_context * ssl)650 static inline mbedtls_x509_crt *mbedtls_ssl_own_cert( mbedtls_ssl_context *ssl )
651 {
652 mbedtls_ssl_key_cert *key_cert;
653
654 if( ssl->handshake != NULL && ssl->handshake->key_cert != NULL )
655 key_cert = ssl->handshake->key_cert;
656 else if ( ssl->conf->endpoint == MBEDTLS_SSL_IS_CLIENT
657 && ssl->handshake && ssl->handshake->sni_key_cert )
658 key_cert = ssl->handshake->sni_key_cert;
659 else
660 key_cert = ssl->conf->key_cert;
661
662 return( key_cert == NULL ? NULL : key_cert->cert );
663 }
664
665 /*
666 * Check usage of a certificate wrt extensions:
667 * keyUsage, extendedKeyUsage (later), and nSCertType (later).
668 *
669 * Warning: cert_endpoint is the endpoint of the cert (ie, of our peer when we
670 * check a cert we received from them)!
671 *
672 * Return 0 if everything is OK, -1 if not.
673 */
674 int mbedtls_ssl_check_cert_usage( const mbedtls_x509_crt *cert,
675 const mbedtls_ssl_ciphersuite_t *ciphersuite,
676 int cert_endpoint,
677 uint32_t *flags );
678 #endif /* MBEDTLS_X509_CRT_PARSE_C */
679
680 void mbedtls_ssl_write_version( int major, int minor, int transport,
681 unsigned char ver[2] );
682 void mbedtls_ssl_read_version( int *major, int *minor, int transport,
683 const unsigned char ver[2] );
684
mbedtls_ssl_hdr_len(const mbedtls_ssl_context * ssl)685 static inline size_t mbedtls_ssl_hdr_len( const mbedtls_ssl_context *ssl )
686 {
687 #if defined(MBEDTLS_SSL_PROTO_DTLS)
688 if( ssl->conf->transport == MBEDTLS_SSL_TRANSPORT_DATAGRAM )
689 return( 13 );
690 #else
691 ((void) ssl);
692 #endif
693 return( 5 );
694 }
695
mbedtls_ssl_hs_hdr_len(const mbedtls_ssl_context * ssl)696 static inline size_t mbedtls_ssl_hs_hdr_len( const mbedtls_ssl_context *ssl )
697 {
698 #if defined(MBEDTLS_SSL_PROTO_DTLS)
699 if( ssl->conf->transport == MBEDTLS_SSL_TRANSPORT_DATAGRAM )
700 return( 12 );
701 #else
702 ((void) ssl);
703 #endif
704 return( 4 );
705 }
706
707 #if defined(MBEDTLS_SSL_PROTO_DTLS)
708 void mbedtls_ssl_send_flight_completed( mbedtls_ssl_context *ssl );
709 void mbedtls_ssl_recv_flight_completed( mbedtls_ssl_context *ssl );
710 int mbedtls_ssl_resend( mbedtls_ssl_context *ssl );
711 #endif
712
713 /* Visible for testing purposes only */
714 #if defined(MBEDTLS_SSL_DTLS_ANTI_REPLAY)
715 int mbedtls_ssl_dtls_replay_check( mbedtls_ssl_context *ssl );
716 void mbedtls_ssl_dtls_replay_update( mbedtls_ssl_context *ssl );
717 #endif
718
719 /* constant-time buffer comparison */
mbedtls_ssl_safer_memcmp(const void * a,const void * b,size_t n)720 static inline int mbedtls_ssl_safer_memcmp( const void *a, const void *b, size_t n )
721 {
722 size_t i;
723 volatile const unsigned char *A = (volatile const unsigned char *) a;
724 volatile const unsigned char *B = (volatile const unsigned char *) b;
725 volatile unsigned char diff = 0;
726
727 for( i = 0; i < n; i++ )
728 {
729 /* Read volatile data in order before computing diff.
730 * This avoids IAR compiler warning:
731 * 'the order of volatile accesses is undefined ..' */
732 unsigned char x = A[i], y = B[i];
733 diff |= x ^ y;
734 }
735
736 return( diff );
737 }
738
739 #if defined(MBEDTLS_SSL_PROTO_SSL3) || defined(MBEDTLS_SSL_PROTO_TLS1) || \
740 defined(MBEDTLS_SSL_PROTO_TLS1_1)
741 int mbedtls_ssl_get_key_exchange_md_ssl_tls( mbedtls_ssl_context *ssl,
742 unsigned char *output,
743 unsigned char *data, size_t data_len );
744 #endif /* MBEDTLS_SSL_PROTO_SSL3 || MBEDTLS_SSL_PROTO_TLS1 || \
745 MBEDTLS_SSL_PROTO_TLS1_1 */
746
747 #if defined(MBEDTLS_SSL_PROTO_TLS1) || defined(MBEDTLS_SSL_PROTO_TLS1_1) || \
748 defined(MBEDTLS_SSL_PROTO_TLS1_2)
749 int mbedtls_ssl_get_key_exchange_md_tls1_2( mbedtls_ssl_context *ssl,
750 unsigned char *output,
751 unsigned char *data, size_t data_len,
752 mbedtls_md_type_t md_alg );
753 #endif /* MBEDTLS_SSL_PROTO_TLS1 || MBEDTLS_SSL_PROTO_TLS1_1 || \
754 MBEDTLS_SSL_PROTO_TLS1_2 */
755
756 #if defined(MBEDTLS_SSL_SOME_SUITES_USE_TLS_CBC)
757 /** \brief Compute the HMAC of variable-length data with constant flow.
758 *
759 * This function computes the HMAC of the concatenation of \p add_data and \p
760 * data, and does with a code flow and memory access pattern that does not
761 * depend on \p data_len_secret, but only on \p min_data_len and \p
762 * max_data_len. In particular, this function always reads exactly \p
763 * max_data_len bytes from \p data.
764 *
765 * \param ctx The HMAC context. It must have keys configured
766 * with mbedtls_md_hmac_starts() and use one of the
767 * following hashes: SHA-384, SHA-256, SHA-1 or MD-5.
768 * It is reset using mbedtls_md_hmac_reset() after
769 * the computation is complete to prepare for the
770 * next computation.
771 * \param add_data The additional data prepended to \p data. This
772 * must point to a readable buffer of \p add_data_len
773 * bytes.
774 * \param add_data_len The length of \p add_data in bytes.
775 * \param data The data appended to \p add_data. This must point
776 * to a readable buffer of \p max_data_len bytes.
777 * \param data_len_secret The length of the data to process in \p data.
778 * This must be no less than \p min_data_len and no
779 * greater than \p max_data_len.
780 * \param min_data_len The minimal length of \p data in bytes.
781 * \param max_data_len The maximal length of \p data in bytes.
782 * \param output The HMAC will be written here. This must point to
783 * a writable buffer of sufficient size to hold the
784 * HMAC value.
785 *
786 * \retval 0
787 * Success.
788 * \retval non-zero
789 * Failure.
790 */
791 int mbedtls_ssl_cf_hmac(
792 mbedtls_md_context_t *ctx,
793 const unsigned char *add_data, size_t add_data_len,
794 const unsigned char *data, size_t data_len_secret,
795 size_t min_data_len, size_t max_data_len,
796 unsigned char *output );
797
798 /** \brief Copy data from a secret position with constant flow.
799 *
800 * This function copies \p len bytes from \p src_base + \p offset_secret to \p
801 * dst, with a code flow and memory access pattern that does not depend on \p
802 * offset_secret, but only on \p offset_min, \p offset_max and \p len.
803 *
804 * \param dst The destination buffer. This must point to a writable
805 * buffer of at least \p len bytes.
806 * \param src_base The base of the source buffer. This must point to a
807 * readable buffer of at least \p offset_max + \p len
808 * bytes.
809 * \param offset_secret The offset in the source buffer from which to copy.
810 * This must be no less than \p offset_min and no greater
811 * than \p offset_max.
812 * \param offset_min The minimal value of \p offset_secret.
813 * \param offset_max The maximal value of \p offset_secret.
814 * \param len The number of bytes to copy.
815 */
816 void mbedtls_ssl_cf_memcpy_offset( unsigned char *dst,
817 const unsigned char *src_base,
818 size_t offset_secret,
819 size_t offset_min, size_t offset_max,
820 size_t len );
821 #endif /* MBEDTLS_SSL_SOME_SUITES_USE_TLS_CBC */
822
823 #ifdef __cplusplus
824 }
825 #endif
826
827 #endif /* ssl_internal.h */
828