4 * \brief Internal functions shared by the SSL modules
6 * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
7 * SPDX-License-Identifier: GPL-2.0
9 * This program is free software; you can redistribute it and/or modify
10 * it under the terms of the GNU General Public License as published by
11 * the Free Software Foundation; either version 2 of the License, or
12 * (at your option) any later version.
14 * This program is distributed in the hope that it will be useful,
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 * GNU General Public License for more details.
19 * You should have received a copy of the GNU General Public License along
20 * with this program; if not, write to the Free Software Foundation, Inc.,
21 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
23 * This file is part of mbed TLS (https://tls.mbed.org)
25 #ifndef MBEDTLS_SSL_INTERNAL_H
26 #define MBEDTLS_SSL_INTERNAL_H
30 #if defined(MBEDTLS_MD5_C)
34 #if defined(MBEDTLS_SHA1_C)
38 #if defined(MBEDTLS_SHA256_C)
42 #if defined(MBEDTLS_SHA512_C)
46 #if defined(MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED)
50 #if ( defined(__ARMCC_VERSION) || defined(_MSC_VER) ) && \
51 !defined(inline) && !defined(__cplusplus)
52 #define inline __inline
55 /* Determine minimum supported version */
56 #define MBEDTLS_SSL_MIN_MAJOR_VERSION MBEDTLS_SSL_MAJOR_VERSION_3
58 #if defined(MBEDTLS_SSL_PROTO_SSL3)
59 #define MBEDTLS_SSL_MIN_MINOR_VERSION MBEDTLS_SSL_MINOR_VERSION_0
61 #if defined(MBEDTLS_SSL_PROTO_TLS1)
62 #define MBEDTLS_SSL_MIN_MINOR_VERSION MBEDTLS_SSL_MINOR_VERSION_1
64 #if defined(MBEDTLS_SSL_PROTO_TLS1_1)
65 #define MBEDTLS_SSL_MIN_MINOR_VERSION MBEDTLS_SSL_MINOR_VERSION_2
67 #if defined(MBEDTLS_SSL_PROTO_TLS1_2)
68 #define MBEDTLS_SSL_MIN_MINOR_VERSION MBEDTLS_SSL_MINOR_VERSION_3
69 #endif /* MBEDTLS_SSL_PROTO_TLS1_2 */
70 #endif /* MBEDTLS_SSL_PROTO_TLS1_1 */
71 #endif /* MBEDTLS_SSL_PROTO_TLS1 */
72 #endif /* MBEDTLS_SSL_PROTO_SSL3 */
74 /* Determine maximum supported version */
75 #define MBEDTLS_SSL_MAX_MAJOR_VERSION MBEDTLS_SSL_MAJOR_VERSION_3
77 #if defined(MBEDTLS_SSL_PROTO_TLS1_2)
78 #define MBEDTLS_SSL_MAX_MINOR_VERSION MBEDTLS_SSL_MINOR_VERSION_3
80 #if defined(MBEDTLS_SSL_PROTO_TLS1_1)
81 #define MBEDTLS_SSL_MAX_MINOR_VERSION MBEDTLS_SSL_MINOR_VERSION_2
83 #if defined(MBEDTLS_SSL_PROTO_TLS1)
84 #define MBEDTLS_SSL_MAX_MINOR_VERSION MBEDTLS_SSL_MINOR_VERSION_1
86 #if defined(MBEDTLS_SSL_PROTO_SSL3)
87 #define MBEDTLS_SSL_MAX_MINOR_VERSION MBEDTLS_SSL_MINOR_VERSION_0
88 #endif /* MBEDTLS_SSL_PROTO_SSL3 */
89 #endif /* MBEDTLS_SSL_PROTO_TLS1 */
90 #endif /* MBEDTLS_SSL_PROTO_TLS1_1 */
91 #endif /* MBEDTLS_SSL_PROTO_TLS1_2 */
93 #define MBEDTLS_SSL_INITIAL_HANDSHAKE 0
94 #define MBEDTLS_SSL_RENEGOTIATION_IN_PROGRESS 1 /* In progress */
95 #define MBEDTLS_SSL_RENEGOTIATION_DONE 2 /* Done or aborted */
96 #define MBEDTLS_SSL_RENEGOTIATION_PENDING 3 /* Requested (server only) */
99 * DTLS retransmission states, see RFC 6347 4.2.4
101 * The SENDING state is merged in PREPARING for initial sends,
102 * but is distinct for resends.
104 * Note: initial state is wrong for server, but is not used anyway.
106 #define MBEDTLS_SSL_RETRANS_PREPARING 0
107 #define MBEDTLS_SSL_RETRANS_SENDING 1
108 #define MBEDTLS_SSL_RETRANS_WAITING 2
109 #define MBEDTLS_SSL_RETRANS_FINISHED 3
112 * Allow extra bytes for record, authentication and encryption overhead:
113 * counter (8) + header (5) + IV(16) + MAC (16-48) + padding (0-256)
114 * and allow for a maximum of 1024 of compression expansion if
117 #if defined(MBEDTLS_ZLIB_SUPPORT)
118 #define MBEDTLS_SSL_COMPRESSION_ADD 1024
120 #define MBEDTLS_SSL_COMPRESSION_ADD 0
123 #if defined(MBEDTLS_ARC4_C) || defined(MBEDTLS_CIPHER_MODE_CBC)
124 /* Ciphersuites using HMAC */
125 #if defined(MBEDTLS_SHA512_C)
126 #define MBEDTLS_SSL_MAC_ADD 48 /* SHA-384 used for HMAC */
127 #elif defined(MBEDTLS_SHA256_C)
128 #define MBEDTLS_SSL_MAC_ADD 32 /* SHA-256 used for HMAC */
130 #define MBEDTLS_SSL_MAC_ADD 20 /* SHA-1 used for HMAC */
133 /* AEAD ciphersuites: GCM and CCM use a 128 bits tag */
134 #define MBEDTLS_SSL_MAC_ADD 16
137 #if defined(MBEDTLS_CIPHER_MODE_CBC)
138 #define MBEDTLS_SSL_PADDING_ADD 256
140 #define MBEDTLS_SSL_PADDING_ADD 0
143 #define MBEDTLS_SSL_BUFFER_LEN ( MBEDTLS_SSL_MAX_CONTENT_LEN \
144 + MBEDTLS_SSL_COMPRESSION_ADD \
145 + 29 /* counter + header + IV */ \
146 + MBEDTLS_SSL_MAC_ADD \
147 + MBEDTLS_SSL_PADDING_ADD \
151 * TLS extension flags (for extensions with outgoing ServerHello content
152 * that need it (e.g. for RENEGOTIATION_INFO the server already knows because
153 * of state of the renegotiation flag, so no indicator is required)
155 #define MBEDTLS_TLS_EXT_SUPPORTED_POINT_FORMATS_PRESENT (1 << 0)
156 #define MBEDTLS_TLS_EXT_ECJPAKE_KKPP_OK (1 << 1)
163 * This structure contains the parameters only needed during handshake.
165 struct mbedtls_ssl_handshake_params
168 * Handshake specific crypto variables
170 int sig_alg
; /*!< Hash algorithm for signature */
171 int verify_sig_alg
; /*!< Signature algorithm for verify */
172 #if defined(MBEDTLS_DHM_C)
173 mbedtls_dhm_context dhm_ctx
; /*!< DHM key exchange */
175 #if defined(MBEDTLS_ECDH_C)
176 mbedtls_ecdh_context ecdh_ctx
; /*!< ECDH key exchange */
178 #if defined(MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED)
179 mbedtls_ecjpake_context ecjpake_ctx
; /*!< EC J-PAKE key exchange */
180 #if defined(MBEDTLS_SSL_CLI_C)
181 unsigned char *ecjpake_cache
; /*!< Cache for ClientHello ext */
182 size_t ecjpake_cache_len
; /*!< Length of cached data */
185 #if defined(MBEDTLS_ECDH_C) || defined(MBEDTLS_ECDSA_C) || \
186 defined(MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED)
187 const mbedtls_ecp_curve_info
**curves
; /*!< Supported elliptic curves */
189 #if defined(MBEDTLS_KEY_EXCHANGE__SOME__PSK_ENABLED)
190 unsigned char *psk
; /*!< PSK from the callback */
191 size_t psk_len
; /*!< Length of PSK from callback */
193 #if defined(MBEDTLS_X509_CRT_PARSE_C)
194 mbedtls_ssl_key_cert
*key_cert
; /*!< chosen key/cert pair (server) */
195 #if defined(MBEDTLS_SSL_SERVER_NAME_INDICATION)
196 int sni_authmode
; /*!< authmode from SNI callback */
197 mbedtls_ssl_key_cert
*sni_key_cert
; /*!< key/cert list from SNI */
198 mbedtls_x509_crt
*sni_ca_chain
; /*!< trusted CAs from SNI callback */
199 mbedtls_x509_crl
*sni_ca_crl
; /*!< trusted CAs CRLs from SNI */
201 #endif /* MBEDTLS_X509_CRT_PARSE_C */
202 #if defined(MBEDTLS_SSL_PROTO_DTLS)
203 unsigned int out_msg_seq
; /*!< Outgoing handshake sequence number */
204 unsigned int in_msg_seq
; /*!< Incoming handshake sequence number */
206 unsigned char *verify_cookie
; /*!< Cli: HelloVerifyRequest cookie
208 unsigned char verify_cookie_len
; /*!< Cli: cookie length
209 Srv: flag for sending a cookie */
211 unsigned char *hs_msg
; /*!< Reassembled handshake message */
213 uint32_t retransmit_timeout
; /*!< Current value of timeout */
214 unsigned char retransmit_state
; /*!< Retransmission state */
215 mbedtls_ssl_flight_item
*flight
; /*!< Current outgoing flight */
216 mbedtls_ssl_flight_item
*cur_msg
; /*!< Current message in flight */
217 unsigned int in_flight_start_seq
; /*!< Minimum message sequence in the
218 flight being received */
219 mbedtls_ssl_transform
*alt_transform_out
; /*!< Alternative transform for
220 resending messages */
221 unsigned char alt_out_ctr
[8]; /*!< Alternative record epoch/counter
222 for resending messages */
228 #if defined(MBEDTLS_SSL_PROTO_SSL3) || defined(MBEDTLS_SSL_PROTO_TLS1) || \
229 defined(MBEDTLS_SSL_PROTO_TLS1_1)
230 mbedtls_md5_context fin_md5
;
231 mbedtls_sha1_context fin_sha1
;
233 #if defined(MBEDTLS_SSL_PROTO_TLS1_2)
234 #if defined(MBEDTLS_SHA256_C)
235 mbedtls_sha256_context fin_sha256
;
237 #if defined(MBEDTLS_SHA512_C)
238 mbedtls_sha512_context fin_sha512
;
240 #endif /* MBEDTLS_SSL_PROTO_TLS1_2 */
242 void (*update_checksum
)(mbedtls_ssl_context
*, const unsigned char *, size_t);
243 void (*calc_verify
)(mbedtls_ssl_context
*, unsigned char *);
244 void (*calc_finished
)(mbedtls_ssl_context
*, unsigned char *, int);
245 int (*tls_prf
)(const unsigned char *, size_t, const char *,
246 const unsigned char *, size_t,
247 unsigned char *, size_t);
249 size_t pmslen
; /*!< premaster length */
251 unsigned char randbytes
[64]; /*!< random bytes */
252 unsigned char premaster
[MBEDTLS_PREMASTER_SIZE
];
253 /*!< premaster secret */
255 int resume
; /*!< session resume indicator*/
256 int max_major_ver
; /*!< max. major version client*/
257 int max_minor_ver
; /*!< max. minor version client*/
258 int cli_exts
; /*!< client extension presence*/
260 #if defined(MBEDTLS_SSL_SESSION_TICKETS)
261 int new_session_ticket
; /*!< use NewSessionTicket? */
262 #endif /* MBEDTLS_SSL_SESSION_TICKETS */
263 #if defined(MBEDTLS_SSL_EXTENDED_MASTER_SECRET)
264 int extended_ms
; /*!< use Extended Master Secret? */
269 * This structure contains a full set of runtime transform parameters
270 * either in negotiation or active.
272 struct mbedtls_ssl_transform
275 * Session specific crypto layer
277 const mbedtls_ssl_ciphersuite_t
*ciphersuite_info
;
278 /*!< Chosen cipersuite_info */
279 unsigned int keylen
; /*!< symmetric key length (bytes) */
280 size_t minlen
; /*!< min. ciphertext length */
281 size_t ivlen
; /*!< IV length */
282 size_t fixed_ivlen
; /*!< Fixed part of IV (AEAD) */
283 size_t maclen
; /*!< MAC length */
285 unsigned char iv_enc
[16]; /*!< IV (encryption) */
286 unsigned char iv_dec
[16]; /*!< IV (decryption) */
288 #if defined(MBEDTLS_SSL_PROTO_SSL3)
289 /* Needed only for SSL v3.0 secret */
290 unsigned char mac_enc
[20]; /*!< SSL v3.0 secret (enc) */
291 unsigned char mac_dec
[20]; /*!< SSL v3.0 secret (dec) */
292 #endif /* MBEDTLS_SSL_PROTO_SSL3 */
294 mbedtls_md_context_t md_ctx_enc
; /*!< MAC (encryption) */
295 mbedtls_md_context_t md_ctx_dec
; /*!< MAC (decryption) */
297 mbedtls_cipher_context_t cipher_ctx_enc
; /*!< encryption context */
298 mbedtls_cipher_context_t cipher_ctx_dec
; /*!< decryption context */
301 * Session specific compression layer
303 #if defined(MBEDTLS_ZLIB_SUPPORT)
304 z_stream ctx_deflate
; /*!< compression context */
305 z_stream ctx_inflate
; /*!< decompression context */
309 #if defined(MBEDTLS_X509_CRT_PARSE_C)
311 * List of certificate + private key pairs
313 struct mbedtls_ssl_key_cert
315 mbedtls_x509_crt
*cert
; /*!< cert */
316 mbedtls_pk_context
*key
; /*!< private key */
317 mbedtls_ssl_key_cert
*next
; /*!< next key/cert pair */
319 #endif /* MBEDTLS_X509_CRT_PARSE_C */
321 #if defined(MBEDTLS_SSL_PROTO_DTLS)
323 * List of handshake messages kept around for resending
325 struct mbedtls_ssl_flight_item
327 unsigned char *p
; /*!< message, including handshake headers */
328 size_t len
; /*!< length of p */
329 unsigned char type
; /*!< type of the message: handshake or CCS */
330 mbedtls_ssl_flight_item
*next
; /*!< next handshake message(s) */
332 #endif /* MBEDTLS_SSL_PROTO_DTLS */
336 * \brief Free referenced items in an SSL transform context and clear
339 * \param transform SSL transform context
341 void mbedtls_ssl_transform_free( mbedtls_ssl_transform
*transform
);
344 * \brief Free referenced items in an SSL handshake context and clear
347 * \param handshake SSL handshake context
349 void mbedtls_ssl_handshake_free( mbedtls_ssl_handshake_params
*handshake
);
351 int mbedtls_ssl_handshake_client_step( mbedtls_ssl_context
*ssl
);
352 int mbedtls_ssl_handshake_server_step( mbedtls_ssl_context
*ssl
);
353 void mbedtls_ssl_handshake_wrapup( mbedtls_ssl_context
*ssl
);
355 int mbedtls_ssl_send_fatal_handshake_failure( mbedtls_ssl_context
*ssl
);
357 void mbedtls_ssl_reset_checksum( mbedtls_ssl_context
*ssl
);
358 int mbedtls_ssl_derive_keys( mbedtls_ssl_context
*ssl
);
360 int mbedtls_ssl_read_record_layer( mbedtls_ssl_context
*ssl
);
361 int mbedtls_ssl_handle_message_type( mbedtls_ssl_context
*ssl
);
362 int mbedtls_ssl_prepare_handshake_record( mbedtls_ssl_context
*ssl
);
363 void mbedtls_ssl_update_handshake_status( mbedtls_ssl_context
*ssl
);
365 int mbedtls_ssl_read_record( mbedtls_ssl_context
*ssl
);
366 int mbedtls_ssl_fetch_input( mbedtls_ssl_context
*ssl
, size_t nb_want
);
368 int mbedtls_ssl_write_record( mbedtls_ssl_context
*ssl
);
369 int mbedtls_ssl_flush_output( mbedtls_ssl_context
*ssl
);
371 int mbedtls_ssl_parse_certificate( mbedtls_ssl_context
*ssl
);
372 int mbedtls_ssl_write_certificate( mbedtls_ssl_context
*ssl
);
374 int mbedtls_ssl_parse_change_cipher_spec( mbedtls_ssl_context
*ssl
);
375 int mbedtls_ssl_write_change_cipher_spec( mbedtls_ssl_context
*ssl
);
377 int mbedtls_ssl_parse_finished( mbedtls_ssl_context
*ssl
);
378 int mbedtls_ssl_write_finished( mbedtls_ssl_context
*ssl
);
380 void mbedtls_ssl_optimize_checksum( mbedtls_ssl_context
*ssl
,
381 const mbedtls_ssl_ciphersuite_t
*ciphersuite_info
);
383 #if defined(MBEDTLS_KEY_EXCHANGE__SOME__PSK_ENABLED)
384 int mbedtls_ssl_psk_derive_premaster( mbedtls_ssl_context
*ssl
, mbedtls_key_exchange_type_t key_ex
);
387 #if defined(MBEDTLS_PK_C)
388 unsigned char mbedtls_ssl_sig_from_pk( mbedtls_pk_context
*pk
);
389 mbedtls_pk_type_t
mbedtls_ssl_pk_alg_from_sig( unsigned char sig
);
392 mbedtls_md_type_t
mbedtls_ssl_md_alg_from_hash( unsigned char hash
);
393 unsigned char mbedtls_ssl_hash_from_md_alg( int md
);
394 int mbedtls_ssl_set_calc_verify_md( mbedtls_ssl_context
*ssl
, int md
);
396 #if defined(MBEDTLS_ECP_C)
397 int mbedtls_ssl_check_curve( const mbedtls_ssl_context
*ssl
, mbedtls_ecp_group_id grp_id
);
400 #if defined(MBEDTLS_KEY_EXCHANGE__WITH_CERT__ENABLED)
401 int mbedtls_ssl_check_sig_hash( const mbedtls_ssl_context
*ssl
,
402 mbedtls_md_type_t md
);
405 #if defined(MBEDTLS_X509_CRT_PARSE_C)
406 static inline mbedtls_pk_context
*mbedtls_ssl_own_key( mbedtls_ssl_context
*ssl
)
408 mbedtls_ssl_key_cert
*key_cert
;
410 if( ssl
->handshake
!= NULL
&& ssl
->handshake
->key_cert
!= NULL
)
411 key_cert
= ssl
->handshake
->key_cert
;
413 key_cert
= ssl
->conf
->key_cert
;
415 return( key_cert
== NULL
? NULL
: key_cert
->key
);
418 static inline mbedtls_x509_crt
*mbedtls_ssl_own_cert( mbedtls_ssl_context
*ssl
)
420 mbedtls_ssl_key_cert
*key_cert
;
422 if( ssl
->handshake
!= NULL
&& ssl
->handshake
->key_cert
!= NULL
)
423 key_cert
= ssl
->handshake
->key_cert
;
425 key_cert
= ssl
->conf
->key_cert
;
427 return( key_cert
== NULL
? NULL
: key_cert
->cert
);
431 * Check usage of a certificate wrt extensions:
432 * keyUsage, extendedKeyUsage (later), and nSCertType (later).
434 * Warning: cert_endpoint is the endpoint of the cert (ie, of our peer when we
435 * check a cert we received from them)!
437 * Return 0 if everything is OK, -1 if not.
439 int mbedtls_ssl_check_cert_usage( const mbedtls_x509_crt
*cert
,
440 const mbedtls_ssl_ciphersuite_t
*ciphersuite
,
443 #endif /* MBEDTLS_X509_CRT_PARSE_C */
445 void mbedtls_ssl_write_version( int major
, int minor
, int transport
,
446 unsigned char ver
[2] );
447 void mbedtls_ssl_read_version( int *major
, int *minor
, int transport
,
448 const unsigned char ver
[2] );
450 static inline size_t mbedtls_ssl_hdr_len( const mbedtls_ssl_context
*ssl
)
452 #if defined(MBEDTLS_SSL_PROTO_DTLS)
453 if( ssl
->conf
->transport
== MBEDTLS_SSL_TRANSPORT_DATAGRAM
)
461 static inline size_t mbedtls_ssl_hs_hdr_len( const mbedtls_ssl_context
*ssl
)
463 #if defined(MBEDTLS_SSL_PROTO_DTLS)
464 if( ssl
->conf
->transport
== MBEDTLS_SSL_TRANSPORT_DATAGRAM
)
472 #if defined(MBEDTLS_SSL_PROTO_DTLS)
473 void mbedtls_ssl_send_flight_completed( mbedtls_ssl_context
*ssl
);
474 void mbedtls_ssl_recv_flight_completed( mbedtls_ssl_context
*ssl
);
475 int mbedtls_ssl_resend( mbedtls_ssl_context
*ssl
);
478 /* Visible for testing purposes only */
479 #if defined(MBEDTLS_SSL_DTLS_ANTI_REPLAY)
480 int mbedtls_ssl_dtls_replay_check( mbedtls_ssl_context
*ssl
);
481 void mbedtls_ssl_dtls_replay_update( mbedtls_ssl_context
*ssl
);
484 /* constant-time buffer comparison */
485 static inline int mbedtls_ssl_safer_memcmp( const void *a
, const void *b
, size_t n
)
488 const unsigned char *A
= (const unsigned char *) a
;
489 const unsigned char *B
= (const unsigned char *) b
;
490 unsigned char diff
= 0;
492 for( i
= 0; i
< n
; i
++ )
502 #endif /* ssl_internal.h */