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