blob: 0df7f96360c47a7e3c50e41b86694a0912de1333 [file] [log] [blame]
Manuel Pégourié-Gonnard5e94dde2015-05-26 11:57:05 +02001/**
Chris Jones84a773f2021-03-05 18:38:47 +00002 * \file ssl_misc.h
Manuel Pégourié-Gonnard5e94dde2015-05-26 11:57:05 +02003 *
4 * \brief Internal functions shared by the SSL modules
Darryl Greena40a1012018-01-05 15:33:17 +00005 */
6/*
Bence Szépkúti1e148272020-08-07 13:07:28 +02007 * Copyright The Mbed TLS Contributors
Dave Rodgman16799db2023-11-02 19:47:20 +00008 * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
Manuel Pégourié-Gonnard5e94dde2015-05-26 11:57:05 +02009 */
Chris Jones84a773f2021-03-05 18:38:47 +000010#ifndef MBEDTLS_SSL_MISC_H
11#define MBEDTLS_SSL_MISC_H
Manuel Pégourié-Gonnard5e94dde2015-05-26 11:57:05 +020012
Bence Szépkúti27125ce2025-07-18 19:10:04 +020013#include "tf_psa_crypto_common.h"
Ronald Cron51f228c2024-11-06 14:32:52 +010014#include "mbedtls/build_info.h"
Andrzej Kurekc470b6b2019-01-31 08:20:20 -050015
Manuel Pégourié-Gonnardd55d66f2023-06-20 10:14:58 +020016#include "mbedtls/error.h"
17
Jaeden Amero6609aef2019-07-04 20:01:14 +010018#include "mbedtls/ssl.h"
Gilles Peskinec67befe2025-03-07 20:45:29 +010019#include "mbedtls/debug.h"
20#include "debug_internal.h"
21
Anton Matkinbc487252025-06-16 13:37:03 +020022#include "mbedtls/private/cipher.h"
Manuel Pégourié-Gonnard5e94dde2015-05-26 11:57:05 +020023
Andrzej Kurekeb342242019-01-29 09:14:33 -050024#include "psa/crypto.h"
Manuel Pégourié-Gonnard2be8c632023-06-07 13:07:21 +020025#include "psa_util_internal.h"
Harry Ramsey2547ae92025-01-20 10:04:53 +000026extern const mbedtls_error_pair_t psa_to_ssl_errors[7];
Andrzej Kurekeb342242019-01-29 09:14:33 -050027
Elena Uziunaiteb66a9912024-05-10 14:25:58 +010028#if defined(PSA_WANT_ALG_MD5)
Anton Matkinbc487252025-06-16 13:37:03 +020029#include "mbedtls/private/md5.h"
Manuel Pégourié-Gonnard56273da2015-05-26 12:19:45 +020030#endif
31
Elena Uziunaite9fc5be02024-09-04 18:12:59 +010032#if defined(PSA_WANT_ALG_SHA_1)
Anton Matkinbc487252025-06-16 13:37:03 +020033#include "mbedtls/private/sha1.h"
Manuel Pégourié-Gonnard56273da2015-05-26 12:19:45 +020034#endif
35
Elena Uziunaite0916cd72024-05-23 17:01:07 +010036#if defined(PSA_WANT_ALG_SHA_256)
Anton Matkinbc487252025-06-16 13:37:03 +020037#include "mbedtls/private/sha256.h"
Manuel Pégourié-Gonnard56273da2015-05-26 12:19:45 +020038#endif
39
Gabor Mezeic15ef932024-06-13 12:53:54 +020040#if defined(PSA_WANT_ALG_SHA_512)
Anton Matkinbc487252025-06-16 13:37:03 +020041#include "mbedtls/private/sha512.h"
Manuel Pégourié-Gonnard56273da2015-05-26 12:19:45 +020042#endif
43
Valerio Setti2f1d9672023-03-07 18:14:34 +010044#include "mbedtls/pk.h"
Ben Taylor1030f802025-07-15 14:55:41 +010045#if defined(MBEDTLS_PK_HAVE_PRIVATE_HEADER)
46#include <mbedtls/private/pk_private.h>
47#endif /* MBEDTLS_PK_HAVE_PRIVATE_HEADER */
Valerio Settid9291062024-01-17 09:48:06 +010048#include "ssl_ciphersuites_internal.h"
Valerio Setti25b282e2024-01-17 10:55:32 +010049#include "x509_internal.h"
Valerio Setti3f00b842023-05-15 12:57:06 +020050#include "pk_internal.h"
Jerry Yu1bab3012022-01-19 17:43:22 +080051
Manuel Pégourié-Gonnard862cde52017-05-17 11:56:15 +020052/* Shorthand for restartable ECC */
Manuel Pégourié-Gonnard2350b4e2017-05-16 09:26:48 +020053#if defined(MBEDTLS_ECP_RESTARTABLE) && \
54 defined(MBEDTLS_SSL_CLI_C) && \
55 defined(MBEDTLS_SSL_PROTO_TLS1_2) && \
56 defined(MBEDTLS_KEY_EXCHANGE_ECDHE_ECDSA_ENABLED)
Gilles Peskineeccd8882020-03-10 12:19:08 +010057#define MBEDTLS_SSL_ECP_RESTARTABLE_ENABLED
Manuel Pégourié-Gonnard2350b4e2017-05-16 09:26:48 +020058#endif
59
Gilles Peskine434016e2025-02-20 18:49:59 +010060/** Flag values for mbedtls_ssl_context::flags. */
61typedef enum {
62 /** Set if mbedtls_ssl_set_hostname() has been called. */
63 MBEDTLS_SSL_CONTEXT_FLAG_HOSTNAME_SET = 1,
64} mbedtls_ssl_context_flags_t;
65
Gilles Peskinefd89acc2025-02-24 18:45:49 +010066/** Flags from ::mbedtls_ssl_context_flags_t to keep in
67 * mbedtls_ssl_session_reset().
68 *
69 * The flags that are in this list are kept until explicitly updated or
70 * until mbedtls_ssl_free(). The flags that are not listed here are
71 * reset to 0 in mbedtls_ssl_session_reset().
72 */
73#define MBEDTLS_SSL_CONTEXT_FLAGS_KEEP_AT_SESSION \
74 (MBEDTLS_SSL_CONTEXT_FLAG_HOSTNAME_SET)
75
Manuel Pégourié-Gonnard065122c2015-05-26 12:31:46 +020076#define MBEDTLS_SSL_INITIAL_HANDSHAKE 0
77#define MBEDTLS_SSL_RENEGOTIATION_IN_PROGRESS 1 /* In progress */
78#define MBEDTLS_SSL_RENEGOTIATION_DONE 2 /* Done or aborted */
79#define MBEDTLS_SSL_RENEGOTIATION_PENDING 3 /* Requested (server only) */
80
Jerry Yud25cab02022-10-31 12:48:30 +080081/* Faked handshake message identity for HelloRetryRequest. */
Gilles Peskine449bd832023-01-11 14:50:10 +010082#define MBEDTLS_SSL_TLS1_3_HS_HELLO_RETRY_REQUEST (-MBEDTLS_SSL_HS_SERVER_HELLO)
Jerry Yud25cab02022-10-31 12:48:30 +080083
Manuel Pégourié-Gonnard065122c2015-05-26 12:31:46 +020084/*
Jerry Yuea52ed92022-11-08 21:01:17 +080085 * Internal identity of handshake extensions
Jerry Yu8e7ca042021-08-26 15:31:37 +080086 */
Jerry Yu7a485c12022-10-31 13:08:18 +080087#define MBEDTLS_SSL_EXT_ID_UNRECOGNIZED 0
88#define MBEDTLS_SSL_EXT_ID_SERVERNAME 1
89#define MBEDTLS_SSL_EXT_ID_SERVERNAME_HOSTNAME 1
90#define MBEDTLS_SSL_EXT_ID_MAX_FRAGMENT_LENGTH 2
91#define MBEDTLS_SSL_EXT_ID_STATUS_REQUEST 3
92#define MBEDTLS_SSL_EXT_ID_SUPPORTED_GROUPS 4
93#define MBEDTLS_SSL_EXT_ID_SUPPORTED_ELLIPTIC_CURVES 4
94#define MBEDTLS_SSL_EXT_ID_SIG_ALG 5
95#define MBEDTLS_SSL_EXT_ID_USE_SRTP 6
96#define MBEDTLS_SSL_EXT_ID_HEARTBEAT 7
97#define MBEDTLS_SSL_EXT_ID_ALPN 8
98#define MBEDTLS_SSL_EXT_ID_SCT 9
99#define MBEDTLS_SSL_EXT_ID_CLI_CERT_TYPE 10
100#define MBEDTLS_SSL_EXT_ID_SERV_CERT_TYPE 11
101#define MBEDTLS_SSL_EXT_ID_PADDING 12
102#define MBEDTLS_SSL_EXT_ID_PRE_SHARED_KEY 13
103#define MBEDTLS_SSL_EXT_ID_EARLY_DATA 14
104#define MBEDTLS_SSL_EXT_ID_SUPPORTED_VERSIONS 15
105#define MBEDTLS_SSL_EXT_ID_COOKIE 16
106#define MBEDTLS_SSL_EXT_ID_PSK_KEY_EXCHANGE_MODES 17
107#define MBEDTLS_SSL_EXT_ID_CERT_AUTH 18
108#define MBEDTLS_SSL_EXT_ID_OID_FILTERS 19
109#define MBEDTLS_SSL_EXT_ID_POST_HANDSHAKE_AUTH 20
110#define MBEDTLS_SSL_EXT_ID_SIG_ALG_CERT 21
111#define MBEDTLS_SSL_EXT_ID_KEY_SHARE 22
112#define MBEDTLS_SSL_EXT_ID_TRUNCATED_HMAC 23
113#define MBEDTLS_SSL_EXT_ID_SUPPORTED_POINT_FORMATS 24
114#define MBEDTLS_SSL_EXT_ID_ENCRYPT_THEN_MAC 25
115#define MBEDTLS_SSL_EXT_ID_EXTENDED_MASTER_SECRET 26
116#define MBEDTLS_SSL_EXT_ID_SESSION_TICKET 27
Jan Bruckner151f6422023-02-10 12:45:19 +0100117#define MBEDTLS_SSL_EXT_ID_RECORD_SIZE_LIMIT 28
Jerry Yu8e7ca042021-08-26 15:31:37 +0800118
Jerry Yu7a485c12022-10-31 13:08:18 +0800119/* Utility for translating IANA extension type. */
Gilles Peskine449bd832023-01-11 14:50:10 +0100120uint32_t mbedtls_ssl_get_extension_id(unsigned int extension_type);
121uint32_t mbedtls_ssl_get_extension_mask(unsigned int extension_type);
Jerry Yu7a485c12022-10-31 13:08:18 +0800122/* Macros used to define mask constants */
Gilles Peskine449bd832023-01-11 14:50:10 +0100123#define MBEDTLS_SSL_EXT_MASK(id) (1ULL << (MBEDTLS_SSL_EXT_ID_##id))
Jerry Yu7a485c12022-10-31 13:08:18 +0800124/* Reset value of extension mask */
125#define MBEDTLS_SSL_EXT_MASK_NONE 0
Jerry Yu93bcd612021-08-18 12:47:24 +0800126
Jerry Yuc4bf5d62022-10-29 09:08:47 +0800127/* In messages containing extension requests, we should ignore unrecognized
128 * extensions. In messages containing extension responses, unrecognized
129 * extensions should result in handshake abortion. Messages containing
130 * extension requests include ClientHello, CertificateRequest and
131 * NewSessionTicket. Messages containing extension responses include
132 * ServerHello, HelloRetryRequest, EncryptedExtensions and Certificate.
Jerry Yue18dc7e2022-08-04 16:29:22 +0800133 *
Jerry Yud15992d2022-08-29 10:58:31 +0800134 * RFC 8446 section 4.1.3
Jerry Yue18dc7e2022-08-04 16:29:22 +0800135 *
136 * The ServerHello MUST only include extensions which are required to establish
137 * the cryptographic context and negotiate the protocol version.
138 *
Jerry Yud15992d2022-08-29 10:58:31 +0800139 * RFC 8446 section 4.2
Jerry Yue18dc7e2022-08-04 16:29:22 +0800140 *
141 * If an implementation receives an extension which it recognizes and which is
142 * not specified for the message in which it appears, it MUST abort the handshake
143 * with an "illegal_parameter" alert.
144 */
Jerry Yudf0ad652022-10-31 13:20:57 +0800145
Jerry Yuea52ed92022-11-08 21:01:17 +0800146/* Extensions that are not recognized by TLS 1.3 */
147#define MBEDTLS_SSL_TLS1_3_EXT_MASK_UNRECOGNIZED \
Gilles Peskine449bd832023-01-11 14:50:10 +0100148 (MBEDTLS_SSL_EXT_MASK(SUPPORTED_POINT_FORMATS) | \
149 MBEDTLS_SSL_EXT_MASK(ENCRYPT_THEN_MAC) | \
150 MBEDTLS_SSL_EXT_MASK(EXTENDED_MASTER_SECRET) | \
151 MBEDTLS_SSL_EXT_MASK(SESSION_TICKET) | \
152 MBEDTLS_SSL_EXT_MASK(TRUNCATED_HMAC) | \
153 MBEDTLS_SSL_EXT_MASK(UNRECOGNIZED))
Jerry Yue18dc7e2022-08-04 16:29:22 +0800154
Tom Cosgrove1797b052022-12-04 17:19:59 +0000155/* RFC 8446 section 4.2. Allowed extensions for ClientHello */
Jerry Yue18dc7e2022-08-04 16:29:22 +0800156#define MBEDTLS_SSL_TLS1_3_ALLOWED_EXTS_OF_CH \
Gilles Peskine449bd832023-01-11 14:50:10 +0100157 (MBEDTLS_SSL_EXT_MASK(SERVERNAME) | \
158 MBEDTLS_SSL_EXT_MASK(MAX_FRAGMENT_LENGTH) | \
159 MBEDTLS_SSL_EXT_MASK(STATUS_REQUEST) | \
160 MBEDTLS_SSL_EXT_MASK(SUPPORTED_GROUPS) | \
161 MBEDTLS_SSL_EXT_MASK(SIG_ALG) | \
162 MBEDTLS_SSL_EXT_MASK(USE_SRTP) | \
163 MBEDTLS_SSL_EXT_MASK(HEARTBEAT) | \
164 MBEDTLS_SSL_EXT_MASK(ALPN) | \
165 MBEDTLS_SSL_EXT_MASK(SCT) | \
166 MBEDTLS_SSL_EXT_MASK(CLI_CERT_TYPE) | \
167 MBEDTLS_SSL_EXT_MASK(SERV_CERT_TYPE) | \
168 MBEDTLS_SSL_EXT_MASK(PADDING) | \
169 MBEDTLS_SSL_EXT_MASK(KEY_SHARE) | \
170 MBEDTLS_SSL_EXT_MASK(PRE_SHARED_KEY) | \
171 MBEDTLS_SSL_EXT_MASK(PSK_KEY_EXCHANGE_MODES) | \
172 MBEDTLS_SSL_EXT_MASK(EARLY_DATA) | \
173 MBEDTLS_SSL_EXT_MASK(COOKIE) | \
174 MBEDTLS_SSL_EXT_MASK(SUPPORTED_VERSIONS) | \
175 MBEDTLS_SSL_EXT_MASK(CERT_AUTH) | \
176 MBEDTLS_SSL_EXT_MASK(POST_HANDSHAKE_AUTH) | \
177 MBEDTLS_SSL_EXT_MASK(SIG_ALG_CERT) | \
Jan Bruckner151f6422023-02-10 12:45:19 +0100178 MBEDTLS_SSL_EXT_MASK(RECORD_SIZE_LIMIT) | \
Gilles Peskine449bd832023-01-11 14:50:10 +0100179 MBEDTLS_SSL_TLS1_3_EXT_MASK_UNRECOGNIZED)
Jerry Yue18dc7e2022-08-04 16:29:22 +0800180
Jerry Yud15992d2022-08-29 10:58:31 +0800181/* RFC 8446 section 4.2. Allowed extensions for EncryptedExtensions */
Jerry Yue18dc7e2022-08-04 16:29:22 +0800182#define MBEDTLS_SSL_TLS1_3_ALLOWED_EXTS_OF_EE \
Gilles Peskine449bd832023-01-11 14:50:10 +0100183 (MBEDTLS_SSL_EXT_MASK(SERVERNAME) | \
184 MBEDTLS_SSL_EXT_MASK(MAX_FRAGMENT_LENGTH) | \
185 MBEDTLS_SSL_EXT_MASK(SUPPORTED_GROUPS) | \
186 MBEDTLS_SSL_EXT_MASK(USE_SRTP) | \
187 MBEDTLS_SSL_EXT_MASK(HEARTBEAT) | \
188 MBEDTLS_SSL_EXT_MASK(ALPN) | \
189 MBEDTLS_SSL_EXT_MASK(CLI_CERT_TYPE) | \
190 MBEDTLS_SSL_EXT_MASK(SERV_CERT_TYPE) | \
Jan Bruckner151f6422023-02-10 12:45:19 +0100191 MBEDTLS_SSL_EXT_MASK(EARLY_DATA) | \
192 MBEDTLS_SSL_EXT_MASK(RECORD_SIZE_LIMIT))
Jerry Yue18dc7e2022-08-04 16:29:22 +0800193
Jerry Yud15992d2022-08-29 10:58:31 +0800194/* RFC 8446 section 4.2. Allowed extensions for CertificateRequest */
Jerry Yue18dc7e2022-08-04 16:29:22 +0800195#define MBEDTLS_SSL_TLS1_3_ALLOWED_EXTS_OF_CR \
Gilles Peskine449bd832023-01-11 14:50:10 +0100196 (MBEDTLS_SSL_EXT_MASK(STATUS_REQUEST) | \
197 MBEDTLS_SSL_EXT_MASK(SIG_ALG) | \
198 MBEDTLS_SSL_EXT_MASK(SCT) | \
199 MBEDTLS_SSL_EXT_MASK(CERT_AUTH) | \
200 MBEDTLS_SSL_EXT_MASK(OID_FILTERS) | \
201 MBEDTLS_SSL_EXT_MASK(SIG_ALG_CERT) | \
202 MBEDTLS_SSL_TLS1_3_EXT_MASK_UNRECOGNIZED)
Jerry Yue18dc7e2022-08-04 16:29:22 +0800203
Jerry Yud15992d2022-08-29 10:58:31 +0800204/* RFC 8446 section 4.2. Allowed extensions for Certificate */
Jerry Yue18dc7e2022-08-04 16:29:22 +0800205#define MBEDTLS_SSL_TLS1_3_ALLOWED_EXTS_OF_CT \
Gilles Peskine449bd832023-01-11 14:50:10 +0100206 (MBEDTLS_SSL_EXT_MASK(STATUS_REQUEST) | \
207 MBEDTLS_SSL_EXT_MASK(SCT))
Jerry Yue18dc7e2022-08-04 16:29:22 +0800208
Jerry Yud15992d2022-08-29 10:58:31 +0800209/* RFC 8446 section 4.2. Allowed extensions for ServerHello */
Jerry Yue18dc7e2022-08-04 16:29:22 +0800210#define MBEDTLS_SSL_TLS1_3_ALLOWED_EXTS_OF_SH \
Gilles Peskine449bd832023-01-11 14:50:10 +0100211 (MBEDTLS_SSL_EXT_MASK(KEY_SHARE) | \
212 MBEDTLS_SSL_EXT_MASK(PRE_SHARED_KEY) | \
213 MBEDTLS_SSL_EXT_MASK(SUPPORTED_VERSIONS))
Jerry Yue18dc7e2022-08-04 16:29:22 +0800214
Jerry Yud15992d2022-08-29 10:58:31 +0800215/* RFC 8446 section 4.2. Allowed extensions for HelloRetryRequest */
Jerry Yue18dc7e2022-08-04 16:29:22 +0800216#define MBEDTLS_SSL_TLS1_3_ALLOWED_EXTS_OF_HRR \
Gilles Peskine449bd832023-01-11 14:50:10 +0100217 (MBEDTLS_SSL_EXT_MASK(KEY_SHARE) | \
218 MBEDTLS_SSL_EXT_MASK(COOKIE) | \
219 MBEDTLS_SSL_EXT_MASK(SUPPORTED_VERSIONS))
Jerry Yue18dc7e2022-08-04 16:29:22 +0800220
Jerry Yud15992d2022-08-29 10:58:31 +0800221/* RFC 8446 section 4.2. Allowed extensions for NewSessionTicket */
Jerry Yue18dc7e2022-08-04 16:29:22 +0800222#define MBEDTLS_SSL_TLS1_3_ALLOWED_EXTS_OF_NST \
Gilles Peskine449bd832023-01-11 14:50:10 +0100223 (MBEDTLS_SSL_EXT_MASK(EARLY_DATA) | \
224 MBEDTLS_SSL_TLS1_3_EXT_MASK_UNRECOGNIZED)
Jerry Yue18dc7e2022-08-04 16:29:22 +0800225
Jerry Yu5cc8f0a2021-08-27 17:21:44 +0800226/*
Jerry Yu8c02bb42021-09-03 21:09:22 +0800227 * Helper macros for function call with return check.
Jerry Yu5cc8f0a2021-08-27 17:21:44 +0800228 */
Jerry Yu5cc8f0a2021-08-27 17:21:44 +0800229/*
Jerry Yu8c02bb42021-09-03 21:09:22 +0800230 * Exit when return non-zero value
Jerry Yu5cc8f0a2021-08-27 17:21:44 +0800231 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100232#define MBEDTLS_SSL_PROC_CHK(f) \
Jerry Yu65dd2cc2021-08-18 16:38:40 +0800233 do { \
Gilles Peskine449bd832023-01-11 14:50:10 +0100234 ret = (f); \
235 if (ret != 0) \
Jerry Yu65dd2cc2021-08-18 16:38:40 +0800236 { \
Jerry Yu65dd2cc2021-08-18 16:38:40 +0800237 goto cleanup; \
238 } \
Gilles Peskine449bd832023-01-11 14:50:10 +0100239 } while (0)
Jerry Yu5cc8f0a2021-08-27 17:21:44 +0800240/*
Jerry Yu8c02bb42021-09-03 21:09:22 +0800241 * Exit when return negative value
Jerry Yu5cc8f0a2021-08-27 17:21:44 +0800242 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100243#define MBEDTLS_SSL_PROC_CHK_NEG(f) \
Jerry Yu65dd2cc2021-08-18 16:38:40 +0800244 do { \
Gilles Peskine449bd832023-01-11 14:50:10 +0100245 ret = (f); \
246 if (ret < 0) \
Jerry Yu65dd2cc2021-08-18 16:38:40 +0800247 { \
Jerry Yu65dd2cc2021-08-18 16:38:40 +0800248 goto cleanup; \
249 } \
Gilles Peskine449bd832023-01-11 14:50:10 +0100250 } while (0)
Jerry Yu65dd2cc2021-08-18 16:38:40 +0800251
Manuel Pégourié-Gonnard065122c2015-05-26 12:31:46 +0200252/*
253 * DTLS retransmission states, see RFC 6347 4.2.4
254 *
255 * The SENDING state is merged in PREPARING for initial sends,
256 * but is distinct for resends.
257 *
258 * Note: initial state is wrong for server, but is not used anyway.
259 */
260#define MBEDTLS_SSL_RETRANS_PREPARING 0
261#define MBEDTLS_SSL_RETRANS_SENDING 1
262#define MBEDTLS_SSL_RETRANS_WAITING 2
263#define MBEDTLS_SSL_RETRANS_FINISHED 3
264
265/*
266 * Allow extra bytes for record, authentication and encryption overhead:
Mateusz Starzyka3a99842021-02-19 14:27:22 +0100267 * counter (8) + header (5) + IV(16) + MAC (16-48) + padding (0-256).
Manuel Pégourié-Gonnard065122c2015-05-26 12:31:46 +0200268 */
Manuel Pégourié-Gonnard065122c2015-05-26 12:31:46 +0200269
TRodziewicz4ca18aa2021-05-20 14:46:20 +0200270#if defined(MBEDTLS_SSL_PROTO_TLS1_2)
Hanno Becker0cc46612020-11-30 08:56:52 +0000271
Manuel Pégourié-Gonnard05579c42020-07-31 12:53:39 +0200272/* This macro determines whether CBC is supported. */
Elena Uziunaite74342c72024-07-05 11:31:29 +0100273#if defined(PSA_WANT_ALG_CBC_NO_PADDING) && \
Elena Uziunaite6121a342024-07-05 11:16:53 +0100274 (defined(PSA_WANT_KEY_TYPE_AES) || \
Elena Uziunaiteda41b602024-07-05 11:27:21 +0100275 defined(PSA_WANT_KEY_TYPE_CAMELLIA) || \
Elena Uziunaite51c85a02024-07-05 11:20:17 +0100276 defined(PSA_WANT_KEY_TYPE_ARIA))
Manuel Pégourié-Gonnard2df1f1f2020-07-09 12:11:39 +0200277#define MBEDTLS_SSL_SOME_SUITES_USE_CBC
278#endif
279
Hanno Becker0cc46612020-11-30 08:56:52 +0000280/* This macro determines whether a ciphersuite using a
281 * stream cipher can be used. */
Ronald Cron0dd31fe2025-09-10 09:37:46 +0200282#if defined(MBEDTLS_SSL_NULL_CIPHERSUITES)
Hanno Becker0cc46612020-11-30 08:56:52 +0000283#define MBEDTLS_SSL_SOME_SUITES_USE_STREAM
284#endif
285
TRodziewicz0f82ec62021-05-12 17:49:18 +0200286/* This macro determines whether the CBC construct used in TLS 1.2 is supported. */
Manuel Pégourié-Gonnarded0e8642020-07-21 11:20:30 +0200287#if defined(MBEDTLS_SSL_SOME_SUITES_USE_CBC) && \
Gilles Peskine449bd832023-01-11 14:50:10 +0100288 defined(MBEDTLS_SSL_PROTO_TLS1_2)
Manuel Pégourié-Gonnarded0e8642020-07-21 11:20:30 +0200289#define MBEDTLS_SSL_SOME_SUITES_USE_TLS_CBC
290#endif
291
Hanno Becker31351ce2021-03-22 11:05:58 +0000292#if defined(MBEDTLS_SSL_SOME_SUITES_USE_STREAM) || \
Manuel Pégourié-Gonnard2df1f1f2020-07-09 12:11:39 +0200293 defined(MBEDTLS_SSL_SOME_SUITES_USE_CBC)
Hanno Beckerfd86ca82020-11-30 08:54:23 +0000294#define MBEDTLS_SSL_SOME_SUITES_USE_MAC
Hanno Becker52344c22018-01-03 15:24:20 +0000295#endif
296
Neil Armstrongf2c82f02022-04-05 11:16:53 +0200297/* This macro determines whether a ciphersuite uses Encrypt-then-MAC with CBC */
298#if defined(MBEDTLS_SSL_SOME_SUITES_USE_CBC) && \
299 defined(MBEDTLS_SSL_ENCRYPT_THEN_MAC)
300#define MBEDTLS_SSL_SOME_SUITES_USE_CBC_ETM
301#endif
302
TRodziewicz4ca18aa2021-05-20 14:46:20 +0200303#endif /* MBEDTLS_SSL_PROTO_TLS1_2 */
Hanno Becker0cc46612020-11-30 08:56:52 +0000304
Hanno Beckerfd86ca82020-11-30 08:54:23 +0000305#if defined(MBEDTLS_SSL_SOME_SUITES_USE_MAC)
Manuel Pégourié-Gonnard065122c2015-05-26 12:31:46 +0200306/* Ciphersuites using HMAC */
Elena Uziunaiteb476d4b2024-05-23 15:33:41 +0100307#if defined(PSA_WANT_ALG_SHA_384)
Manuel Pégourié-Gonnard065122c2015-05-26 12:31:46 +0200308#define MBEDTLS_SSL_MAC_ADD 48 /* SHA-384 used for HMAC */
Elena Uziunaite0916cd72024-05-23 17:01:07 +0100309#elif defined(PSA_WANT_ALG_SHA_256)
Manuel Pégourié-Gonnard065122c2015-05-26 12:31:46 +0200310#define MBEDTLS_SSL_MAC_ADD 32 /* SHA-256 used for HMAC */
311#else
312#define MBEDTLS_SSL_MAC_ADD 20 /* SHA-1 used for HMAC */
313#endif
Hanno Beckerfd86ca82020-11-30 08:54:23 +0000314#else /* MBEDTLS_SSL_SOME_SUITES_USE_MAC */
Manuel Pégourié-Gonnard065122c2015-05-26 12:31:46 +0200315/* AEAD ciphersuites: GCM and CCM use a 128 bits tag */
316#define MBEDTLS_SSL_MAC_ADD 16
317#endif
318
Elena Uziunaite74342c72024-07-05 11:31:29 +0100319#if defined(PSA_WANT_ALG_CBC_NO_PADDING)
Manuel Pégourié-Gonnard065122c2015-05-26 12:31:46 +0200320#define MBEDTLS_SSL_PADDING_ADD 256
321#else
322#define MBEDTLS_SSL_PADDING_ADD 0
323#endif
324
Hanno Beckera0e20d02019-05-15 14:03:01 +0100325#if defined(MBEDTLS_SSL_DTLS_CONNECTION_ID)
TRodziewicze8dd7092021-05-12 14:19:11 +0200326#define MBEDTLS_SSL_MAX_CID_EXPANSION MBEDTLS_SSL_CID_TLS1_3_PADDING_GRANULARITY
Hanno Becker6cbad552019-05-08 15:40:11 +0100327#else
328#define MBEDTLS_SSL_MAX_CID_EXPANSION 0
329#endif
330
Gilles Peskine449bd832023-01-11 14:50:10 +0100331#define MBEDTLS_SSL_PAYLOAD_OVERHEAD (MBEDTLS_MAX_IV_LENGTH + \
332 MBEDTLS_SSL_MAC_ADD + \
333 MBEDTLS_SSL_PADDING_ADD + \
334 MBEDTLS_SSL_MAX_CID_EXPANSION \
335 )
Angus Grattond8213d02016-05-25 20:56:48 +1000336
Gilles Peskine449bd832023-01-11 14:50:10 +0100337#define MBEDTLS_SSL_IN_PAYLOAD_LEN (MBEDTLS_SSL_PAYLOAD_OVERHEAD + \
338 (MBEDTLS_SSL_IN_CONTENT_LEN))
Angus Grattond8213d02016-05-25 20:56:48 +1000339
Gilles Peskine449bd832023-01-11 14:50:10 +0100340#define MBEDTLS_SSL_OUT_PAYLOAD_LEN (MBEDTLS_SSL_PAYLOAD_OVERHEAD + \
341 (MBEDTLS_SSL_OUT_CONTENT_LEN))
Angus Grattond8213d02016-05-25 20:56:48 +1000342
Hanno Becker0271f962018-08-16 13:23:47 +0100343/* The maximum number of buffered handshake messages. */
Hanno Beckerd488b9e2018-08-16 16:35:37 +0100344#define MBEDTLS_SSL_MAX_BUFFERED_HS 4
Hanno Becker0271f962018-08-16 13:23:47 +0100345
Angus Grattond8213d02016-05-25 20:56:48 +1000346/* Maximum length we can advertise as our max content length for
347 RFC 6066 max_fragment_length extension negotiation purposes
348 (the lesser of both sizes, if they are unequal.)
349 */
350#define MBEDTLS_TLS_EXT_ADV_CONTENT_LEN ( \
351 (MBEDTLS_SSL_IN_CONTENT_LEN > MBEDTLS_SSL_OUT_CONTENT_LEN) \
Gilles Peskine449bd832023-01-11 14:50:10 +0100352 ? (MBEDTLS_SSL_OUT_CONTENT_LEN) \
353 : (MBEDTLS_SSL_IN_CONTENT_LEN) \
Angus Grattond8213d02016-05-25 20:56:48 +1000354 )
Manuel Pégourié-Gonnard065122c2015-05-26 12:31:46 +0200355
Jerry Yu4131ec12022-01-19 10:36:30 +0800356/* Maximum size in bytes of list in signature algorithms ext., RFC 5246/8446 */
357#define MBEDTLS_SSL_MAX_SIG_ALG_LIST_LEN 65534
358
Jerry Yu8afd6e42022-01-20 15:54:26 +0800359/* Minimum size in bytes of list in signature algorithms ext., RFC 5246/8446 */
Jerry Yu4131ec12022-01-19 10:36:30 +0800360#define MBEDTLS_SSL_MIN_SIG_ALG_LIST_LEN 2
Hanno Beckere131bfe2017-04-12 14:54:42 +0100361
362/* Maximum size in bytes of list in supported elliptic curve ext., RFC 4492 */
363#define MBEDTLS_SSL_MAX_CURVE_LIST_LEN 65535
364
Xiaofei Baif5b4d252022-01-28 06:37:15 +0000365#define MBEDTLS_RECEIVED_SIG_ALGS_SIZE 20
Xiaofei Bai82f0a9a2022-01-26 09:21:54 +0000366
Ronald Crone68ab4f2022-10-05 12:46:29 +0200367#if defined(MBEDTLS_SSL_HANDSHAKE_WITH_CERT_ENABLED)
Gabor Mezei15b95a62022-05-09 16:37:58 +0200368
Gabor Mezei24c7c2b2022-05-10 12:51:14 +0200369#define MBEDTLS_TLS_SIG_NONE MBEDTLS_TLS1_3_SIG_NONE
370
Gabor Mezei15b95a62022-05-09 16:37:58 +0200371#if defined(MBEDTLS_SSL_PROTO_TLS1_2)
Gilles Peskine449bd832023-01-11 14:50:10 +0100372#define MBEDTLS_SSL_TLS12_SIG_AND_HASH_ALG(sig, hash) ((hash << 8) | sig)
Gabor Mezei3631cf62022-05-10 12:59:00 +0200373#define MBEDTLS_SSL_TLS12_SIG_ALG_FROM_SIG_AND_HASH_ALG(alg) (alg & 0xFF)
374#define MBEDTLS_SSL_TLS12_HASH_ALG_FROM_SIG_AND_HASH_ALG(alg) (alg >> 8)
Gabor Mezei15b95a62022-05-09 16:37:58 +0200375#endif /* MBEDTLS_SSL_PROTO_TLS1_2 */
376
Ronald Crone68ab4f2022-10-05 12:46:29 +0200377#endif /* MBEDTLS_SSL_HANDSHAKE_WITH_CERT_ENABLED */
Gabor Mezei15b95a62022-05-09 16:37:58 +0200378
Manuel Pégourié-Gonnard065122c2015-05-26 12:31:46 +0200379/*
Hanno Beckera8434e82017-09-18 10:54:39 +0100380 * Check that we obey the standard's message size bounds
381 */
382
David Horstmann95d516f2021-05-04 18:36:56 +0100383#if MBEDTLS_SSL_IN_CONTENT_LEN > 16384
384#error "Bad configuration - incoming record content too large."
Hanno Beckera8434e82017-09-18 10:54:39 +0100385#endif
386
David Horstmann95d516f2021-05-04 18:36:56 +0100387#if MBEDTLS_SSL_OUT_CONTENT_LEN > 16384
388#error "Bad configuration - outgoing record content too large."
Hanno Beckera8434e82017-09-18 10:54:39 +0100389#endif
390
David Horstmann95d516f2021-05-04 18:36:56 +0100391#if MBEDTLS_SSL_IN_PAYLOAD_LEN > MBEDTLS_SSL_IN_CONTENT_LEN + 2048
Angus Grattond8213d02016-05-25 20:56:48 +1000392#error "Bad configuration - incoming protected record payload too large."
393#endif
394
David Horstmann95d516f2021-05-04 18:36:56 +0100395#if MBEDTLS_SSL_OUT_PAYLOAD_LEN > MBEDTLS_SSL_OUT_CONTENT_LEN + 2048
Angus Grattond8213d02016-05-25 20:56:48 +1000396#error "Bad configuration - outgoing protected record payload too large."
397#endif
398
399/* Calculate buffer sizes */
400
Hanno Becker25d6d1a2017-12-07 08:22:51 +0000401/* Note: Even though the TLS record header is only 5 bytes
402 long, we're internally using 8 bytes to store the
403 implicit sequence number. */
Hanno Beckerd25d4442017-10-04 13:56:42 +0100404#define MBEDTLS_SSL_HEADER_LEN 13
Hanno Beckera8434e82017-09-18 10:54:39 +0100405
Andrzej Kurek033c42a2020-03-03 05:57:59 -0500406#if !defined(MBEDTLS_SSL_DTLS_CONNECTION_ID)
Angus Grattond8213d02016-05-25 20:56:48 +1000407#define MBEDTLS_SSL_IN_BUFFER_LEN \
Gilles Peskine449bd832023-01-11 14:50:10 +0100408 ((MBEDTLS_SSL_HEADER_LEN) + (MBEDTLS_SSL_IN_PAYLOAD_LEN))
Hanno Becker6cbad552019-05-08 15:40:11 +0100409#else
410#define MBEDTLS_SSL_IN_BUFFER_LEN \
Gilles Peskine449bd832023-01-11 14:50:10 +0100411 ((MBEDTLS_SSL_HEADER_LEN) + (MBEDTLS_SSL_IN_PAYLOAD_LEN) \
412 + (MBEDTLS_SSL_CID_IN_LEN_MAX))
Hanno Becker6cbad552019-05-08 15:40:11 +0100413#endif
Angus Grattond8213d02016-05-25 20:56:48 +1000414
Andrzej Kurek033c42a2020-03-03 05:57:59 -0500415#if !defined(MBEDTLS_SSL_DTLS_CONNECTION_ID)
Angus Grattond8213d02016-05-25 20:56:48 +1000416#define MBEDTLS_SSL_OUT_BUFFER_LEN \
Gilles Peskine449bd832023-01-11 14:50:10 +0100417 ((MBEDTLS_SSL_HEADER_LEN) + (MBEDTLS_SSL_OUT_PAYLOAD_LEN))
Hanno Becker6cbad552019-05-08 15:40:11 +0100418#else
419#define MBEDTLS_SSL_OUT_BUFFER_LEN \
Gilles Peskine449bd832023-01-11 14:50:10 +0100420 ((MBEDTLS_SSL_HEADER_LEN) + (MBEDTLS_SSL_OUT_PAYLOAD_LEN) \
421 + (MBEDTLS_SSL_CID_OUT_LEN_MAX))
Hanno Becker6cbad552019-05-08 15:40:11 +0100422#endif
Angus Grattond8213d02016-05-25 20:56:48 +1000423
Jerry Yue6d7e5c2021-10-26 10:44:32 +0800424#define MBEDTLS_CLIENT_HELLO_RANDOM_LEN 32
425#define MBEDTLS_SERVER_HELLO_RANDOM_LEN 32
426
Hanno Becker9752aad2021-04-21 05:54:33 +0100427#if defined(MBEDTLS_SSL_MAX_FRAGMENT_LENGTH)
428/**
429 * \brief Return the maximum fragment length (payload, in bytes) for
430 * the output buffer. For the client, this is the configured
431 * value. For the server, it is the minimum of two - the
432 * configured value and the negotiated one.
433 *
434 * \sa mbedtls_ssl_conf_max_frag_len()
435 * \sa mbedtls_ssl_get_max_out_record_payload()
436 *
437 * \param ssl SSL context
438 *
439 * \return Current maximum fragment length for the output buffer.
440 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100441size_t mbedtls_ssl_get_output_max_frag_len(const mbedtls_ssl_context *ssl);
Hanno Becker9752aad2021-04-21 05:54:33 +0100442
443/**
444 * \brief Return the maximum fragment length (payload, in bytes) for
445 * the input buffer. This is the negotiated maximum fragment
Hanno Beckerdf3b8632021-06-08 05:30:45 +0100446 * length, or, if there is none, MBEDTLS_SSL_IN_CONTENT_LEN.
Hanno Becker9752aad2021-04-21 05:54:33 +0100447 * If it is not defined either, the value is 2^14. This function
448 * works as its predecessor, \c mbedtls_ssl_get_max_frag_len().
449 *
450 * \sa mbedtls_ssl_conf_max_frag_len()
451 * \sa mbedtls_ssl_get_max_in_record_payload()
452 *
453 * \param ssl SSL context
454 *
455 * \return Current maximum fragment length for the output buffer.
456 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100457size_t mbedtls_ssl_get_input_max_frag_len(const mbedtls_ssl_context *ssl);
Hanno Becker9752aad2021-04-21 05:54:33 +0100458#endif /* MBEDTLS_SSL_MAX_FRAGMENT_LENGTH */
459
Jan Brucknerf482dcc2023-03-15 09:09:06 +0100460#if defined(MBEDTLS_SSL_RECORD_SIZE_LIMIT)
461/**
Waleed-Ziad Maamoun-Elmelegye2d3db52024-01-05 14:19:16 +0000462 * \brief Get the size limit in bytes for the protected outgoing records
463 * as defined in RFC 8449
Jan Brucknerf482dcc2023-03-15 09:09:06 +0100464 *
465 * \param ssl SSL context
466 *
Waleed-Ziad Maamoun-Elmelegye2d3db52024-01-05 14:19:16 +0000467 * \return The size limit in bytes for the protected outgoing
468 * records as defined in RFC 8449.
Jan Brucknerf482dcc2023-03-15 09:09:06 +0100469 */
470size_t mbedtls_ssl_get_output_record_size_limit(const mbedtls_ssl_context *ssl);
471#endif /* MBEDTLS_SSL_RECORD_SIZE_LIMIT */
472
Andrzej Kurek0afa2a12020-03-03 10:39:58 -0500473#if defined(MBEDTLS_SSL_VARIABLE_BUFFER_LENGTH)
Gilles Peskine449bd832023-01-11 14:50:10 +0100474static inline size_t mbedtls_ssl_get_output_buflen(const mbedtls_ssl_context *ctx)
Andrzej Kurek0afa2a12020-03-03 10:39:58 -0500475{
Gilles Peskine449bd832023-01-11 14:50:10 +0100476#if defined(MBEDTLS_SSL_DTLS_CONNECTION_ID)
477 return mbedtls_ssl_get_output_max_frag_len(ctx)
478 + MBEDTLS_SSL_HEADER_LEN + MBEDTLS_SSL_PAYLOAD_OVERHEAD
479 + MBEDTLS_SSL_CID_OUT_LEN_MAX;
Andrzej Kurek0afa2a12020-03-03 10:39:58 -0500480#else
Gilles Peskine449bd832023-01-11 14:50:10 +0100481 return mbedtls_ssl_get_output_max_frag_len(ctx)
482 + MBEDTLS_SSL_HEADER_LEN + MBEDTLS_SSL_PAYLOAD_OVERHEAD;
Andrzej Kurek0afa2a12020-03-03 10:39:58 -0500483#endif
484}
485
Gilles Peskine449bd832023-01-11 14:50:10 +0100486static inline size_t mbedtls_ssl_get_input_buflen(const mbedtls_ssl_context *ctx)
Andrzej Kurek0afa2a12020-03-03 10:39:58 -0500487{
Gilles Peskine449bd832023-01-11 14:50:10 +0100488#if defined(MBEDTLS_SSL_DTLS_CONNECTION_ID)
489 return mbedtls_ssl_get_input_max_frag_len(ctx)
490 + MBEDTLS_SSL_HEADER_LEN + MBEDTLS_SSL_PAYLOAD_OVERHEAD
491 + MBEDTLS_SSL_CID_IN_LEN_MAX;
Andrzej Kurek0afa2a12020-03-03 10:39:58 -0500492#else
Gilles Peskine449bd832023-01-11 14:50:10 +0100493 return mbedtls_ssl_get_input_max_frag_len(ctx)
494 + MBEDTLS_SSL_HEADER_LEN + MBEDTLS_SSL_PAYLOAD_OVERHEAD;
Andrzej Kurek0afa2a12020-03-03 10:39:58 -0500495#endif
496}
497#endif
498
Hanno Beckera8434e82017-09-18 10:54:39 +0100499/*
Manuel Pégourié-Gonnard065122c2015-05-26 12:31:46 +0200500 * TLS extension flags (for extensions with outgoing ServerHello content
501 * that need it (e.g. for RENEGOTIATION_INFO the server already knows because
502 * of state of the renegotiation flag, so no indicator is required)
503 */
504#define MBEDTLS_TLS_EXT_SUPPORTED_POINT_FORMATS_PRESENT (1 << 0)
Manuel Pégourié-Gonnardbf57be62015-09-16 15:04:01 +0200505#define MBEDTLS_TLS_EXT_ECJPAKE_KKPP_OK (1 << 1)
Manuel Pégourié-Gonnard065122c2015-05-26 12:31:46 +0200506
Hanno Becker51018aa2017-04-12 14:54:42 +0100507/**
508 * \brief This function checks if the remaining size in a buffer is
509 * greater or equal than a needed space.
510 *
511 * \param cur Pointer to the current position in the buffer.
512 * \param end Pointer to one past the end of the buffer.
513 * \param need Needed space in bytes.
514 *
Ronald Cronb7b35e12020-06-11 09:50:51 +0200515 * \return Zero if the needed space is available in the buffer, non-zero
Hanno Becker51018aa2017-04-12 14:54:42 +0100516 * otherwise.
517 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100518#if !defined(MBEDTLS_TEST_HOOKS)
519static inline int mbedtls_ssl_chk_buf_ptr(const uint8_t *cur,
520 const uint8_t *end, size_t need)
Hanno Becker51018aa2017-04-12 14:54:42 +0100521{
Gilles Peskine449bd832023-01-11 14:50:10 +0100522 return (cur > end) || (need > (size_t) (end - cur));
Hanno Becker51018aa2017-04-12 14:54:42 +0100523}
Ronald Cronad8c17b2022-06-10 17:18:09 +0200524#else
Gilles Peskine449bd832023-01-11 14:50:10 +0100525typedef struct {
Ronald Cronad8c17b2022-06-10 17:18:09 +0200526 const uint8_t *cur;
527 const uint8_t *end;
528 size_t need;
529} mbedtls_ssl_chk_buf_ptr_args;
530
531void mbedtls_ssl_set_chk_buf_ptr_fail_args(
Gilles Peskine449bd832023-01-11 14:50:10 +0100532 const uint8_t *cur, const uint8_t *end, size_t need);
533void mbedtls_ssl_reset_chk_buf_ptr_fail_args(void);
Ronald Cronce7d76e2022-07-08 18:56:49 +0200534
535MBEDTLS_CHECK_RETURN_CRITICAL
Gilles Peskine449bd832023-01-11 14:50:10 +0100536int mbedtls_ssl_cmp_chk_buf_ptr_fail_args(mbedtls_ssl_chk_buf_ptr_args *args);
Ronald Cronad8c17b2022-06-10 17:18:09 +0200537
Gilles Peskine449bd832023-01-11 14:50:10 +0100538static inline int mbedtls_ssl_chk_buf_ptr(const uint8_t *cur,
539 const uint8_t *end, size_t need)
Ronald Cronad8c17b2022-06-10 17:18:09 +0200540{
Gilles Peskine449bd832023-01-11 14:50:10 +0100541 if ((cur > end) || (need > (size_t) (end - cur))) {
542 mbedtls_ssl_set_chk_buf_ptr_fail_args(cur, end, need);
543 return 1;
Ronald Cronad8c17b2022-06-10 17:18:09 +0200544 }
Gilles Peskine449bd832023-01-11 14:50:10 +0100545 return 0;
Ronald Cronad8c17b2022-06-10 17:18:09 +0200546}
Ronald Croncf600bc2022-06-17 15:54:16 +0200547#endif /* MBEDTLS_TEST_HOOKS */
Hanno Becker51018aa2017-04-12 14:54:42 +0100548
549/**
550 * \brief This macro checks if the remaining size in a buffer is
551 * greater or equal than a needed space. If it is not the case,
552 * it returns an SSL_BUFFER_TOO_SMALL error.
553 *
554 * \param cur Pointer to the current position in the buffer.
555 * \param end Pointer to one past the end of the buffer.
556 * \param need Needed space in bytes.
557 *
558 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100559#define MBEDTLS_SSL_CHK_BUF_PTR(cur, end, need) \
Hanno Becker51018aa2017-04-12 14:54:42 +0100560 do { \
Gilles Peskine449bd832023-01-11 14:50:10 +0100561 if (mbedtls_ssl_chk_buf_ptr((cur), (end), (need)) != 0) \
Hanno Becker51018aa2017-04-12 14:54:42 +0100562 { \
Gilles Peskine449bd832023-01-11 14:50:10 +0100563 return MBEDTLS_ERR_SSL_BUFFER_TOO_SMALL; \
Hanno Becker51018aa2017-04-12 14:54:42 +0100564 } \
Gilles Peskine449bd832023-01-11 14:50:10 +0100565 } while (0)
Hanno Becker51018aa2017-04-12 14:54:42 +0100566
Jerry Yu34da3722021-09-19 18:05:08 +0800567/**
Jerry Yue15e6652021-09-28 21:06:07 +0800568 * \brief This macro checks if the remaining length in an input buffer is
569 * greater or equal than a needed length. If it is not the case, it
Jerry Yu205fd822021-10-08 16:16:24 +0800570 * returns #MBEDTLS_ERR_SSL_DECODE_ERROR error and pends a
Jerry Yudca3d5d2021-10-08 14:19:29 +0800571 * #MBEDTLS_SSL_ALERT_MSG_DECODE_ERROR alert message.
Jerry Yue4eefc72021-10-09 10:40:40 +0800572 *
573 * This is a function-like macro. It is guaranteed to evaluate each
574 * argument exactly once.
Jerry Yu34da3722021-09-19 18:05:08 +0800575 *
576 * \param cur Pointer to the current position in the buffer.
577 * \param end Pointer to one past the end of the buffer.
Jerry Yue15e6652021-09-28 21:06:07 +0800578 * \param need Needed length in bytes.
Jerry Yu34da3722021-09-19 18:05:08 +0800579 *
580 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100581#define MBEDTLS_SSL_CHK_BUF_READ_PTR(cur, end, need) \
Jerry Yu34da3722021-09-19 18:05:08 +0800582 do { \
Gilles Peskine449bd832023-01-11 14:50:10 +0100583 if (mbedtls_ssl_chk_buf_ptr((cur), (end), (need)) != 0) \
Jerry Yu34da3722021-09-19 18:05:08 +0800584 { \
Gilles Peskine449bd832023-01-11 14:50:10 +0100585 MBEDTLS_SSL_DEBUG_MSG(1, \
586 ("missing input data in %s", __func__)); \
587 MBEDTLS_SSL_PEND_FATAL_ALERT(MBEDTLS_SSL_ALERT_MSG_DECODE_ERROR, \
588 MBEDTLS_ERR_SSL_DECODE_ERROR); \
589 return MBEDTLS_ERR_SSL_DECODE_ERROR; \
Jerry Yu34da3722021-09-19 18:05:08 +0800590 } \
Gilles Peskine449bd832023-01-11 14:50:10 +0100591 } while (0)
Jerry Yu34da3722021-09-19 18:05:08 +0800592
Manuel Pégourié-Gonnard5e94dde2015-05-26 11:57:05 +0200593#ifdef __cplusplus
594extern "C" {
595#endif
596
Gilles Peskine449bd832023-01-11 14:50:10 +0100597typedef int mbedtls_ssl_tls_prf_cb(const unsigned char *secret, size_t slen,
598 const char *label,
599 const unsigned char *random, size_t rlen,
600 unsigned char *dstbuf, size_t dlen);
Hanno Becker3385a4d2020-08-21 13:03:34 +0100601
Hanno Becker61baae72020-09-16 09:24:14 +0100602/* cipher.h exports the maximum IV, key and block length from
Hanno Becker15889832020-09-08 11:29:11 +0100603 * all ciphers enabled in the config, regardless of whether those
604 * ciphers are actually usable in SSL/TLS. Notably, XTS is enabled
605 * in the default configuration and uses 64 Byte keys, but it is
606 * not used for record protection in SSL/TLS.
607 *
608 * In order to prevent unnecessary inflation of key structures,
609 * we introduce SSL-specific variants of the max-{key,block,IV}
610 * macros here which are meant to only take those ciphers into
611 * account which can be negotiated in SSL/TLS.
612 *
613 * Since the current definitions of MBEDTLS_MAX_{KEY|BLOCK|IV}_LENGTH
614 * in cipher.h are rough overapproximations of the real maxima, here
Hanno Becker9a7a2ac2020-09-09 09:24:54 +0100615 * we content ourselves with replicating those overapproximations
Hanno Becker15889832020-09-08 11:29:11 +0100616 * for the maximum block and IV length, and excluding XTS from the
617 * computation of the maximum key length. */
618#define MBEDTLS_SSL_MAX_BLOCK_LENGTH 16
619#define MBEDTLS_SSL_MAX_IV_LENGTH 16
620#define MBEDTLS_SSL_MAX_KEY_LENGTH 32
621
Hanno Becker3385a4d2020-08-21 13:03:34 +0100622/**
623 * \brief The data structure holding the cryptographic material (key and IV)
624 * used for record protection in TLS 1.3.
625 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100626struct mbedtls_ssl_key_set {
Hanno Becker3385a4d2020-08-21 13:03:34 +0100627 /*! The key for client->server records. */
Gilles Peskine449bd832023-01-11 14:50:10 +0100628 unsigned char client_write_key[MBEDTLS_SSL_MAX_KEY_LENGTH];
Hanno Becker3385a4d2020-08-21 13:03:34 +0100629 /*! The key for server->client records. */
Gilles Peskine449bd832023-01-11 14:50:10 +0100630 unsigned char server_write_key[MBEDTLS_SSL_MAX_KEY_LENGTH];
Hanno Becker3385a4d2020-08-21 13:03:34 +0100631 /*! The IV for client->server records. */
Gilles Peskine449bd832023-01-11 14:50:10 +0100632 unsigned char client_write_iv[MBEDTLS_SSL_MAX_IV_LENGTH];
Hanno Becker3385a4d2020-08-21 13:03:34 +0100633 /*! The IV for server->client records. */
Gilles Peskine449bd832023-01-11 14:50:10 +0100634 unsigned char server_write_iv[MBEDTLS_SSL_MAX_IV_LENGTH];
Hanno Becker3385a4d2020-08-21 13:03:34 +0100635
Hanno Becker493ea7f2020-09-08 11:01:00 +0100636 size_t key_len; /*!< The length of client_write_key and
637 * server_write_key, in Bytes. */
638 size_t iv_len; /*!< The length of client_write_iv and
639 * server_write_iv, in Bytes. */
Hanno Becker3385a4d2020-08-21 13:03:34 +0100640};
641typedef struct mbedtls_ssl_key_set mbedtls_ssl_key_set;
Hanno Becker3385a4d2020-08-21 13:03:34 +0100642
Gilles Peskine449bd832023-01-11 14:50:10 +0100643typedef struct {
644 unsigned char binder_key[MBEDTLS_TLS1_3_MD_MAX_SIZE];
645 unsigned char client_early_traffic_secret[MBEDTLS_TLS1_3_MD_MAX_SIZE];
646 unsigned char early_exporter_master_secret[MBEDTLS_TLS1_3_MD_MAX_SIZE];
Xiaofei Bai746f9482021-11-12 08:53:56 +0000647} mbedtls_ssl_tls13_early_secrets;
Jerry Yu61e35e02021-09-16 18:59:08 +0800648
Gilles Peskine449bd832023-01-11 14:50:10 +0100649typedef struct {
650 unsigned char client_handshake_traffic_secret[MBEDTLS_TLS1_3_MD_MAX_SIZE];
651 unsigned char server_handshake_traffic_secret[MBEDTLS_TLS1_3_MD_MAX_SIZE];
Xiaofei Bai746f9482021-11-12 08:53:56 +0000652} mbedtls_ssl_tls13_handshake_secrets;
Jerry Yu61e35e02021-09-16 18:59:08 +0800653
Manuel Pégourié-Gonnardcd4fcc62015-05-26 12:11:48 +0200654/*
655 * This structure contains the parameters only needed during handshake.
656 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100657struct mbedtls_ssl_handshake_params {
Gilles Peskineec45c1e2021-11-29 12:18:09 +0100658 /* Frequently-used boolean or byte fields (placed early to take
659 * advantage of smaller code size for indirect access on Arm Thumb) */
Gilles Peskineec45c1e2021-11-29 12:18:09 +0100660 uint8_t resume; /*!< session resume indicator*/
661 uint8_t cli_exts; /*!< client extension presence*/
662
Glenn Straussbbdc83b2022-04-12 07:31:46 -0400663#if defined(MBEDTLS_SSL_SERVER_NAME_INDICATION)
664 uint8_t sni_authmode; /*!< authmode from SNI callback */
665#endif
666
XiaokangQian189ded22022-05-10 08:12:17 +0000667#if defined(MBEDTLS_SSL_SRV_C)
XiaokangQianc3017f62022-05-13 05:55:41 +0000668 /* Flag indicating if a CertificateRequest message has been sent
669 * to the client or not. */
XiaokangQian63e713e2022-05-15 04:26:57 +0000670 uint8_t certificate_request_sent;
Ronald Cron78a38f62024-02-01 18:30:31 +0100671#if defined(MBEDTLS_SSL_EARLY_DATA)
672 /* Flag indicating if the server has accepted early data or not. */
673 uint8_t early_data_accepted;
674#endif
XiaokangQian189ded22022-05-10 08:12:17 +0000675#endif /* MBEDTLS_SSL_SRV_C */
676
Glenn Straussbbdc83b2022-04-12 07:31:46 -0400677#if defined(MBEDTLS_SSL_SESSION_TICKETS)
678 uint8_t new_session_ticket; /*!< use NewSessionTicket? */
679#endif /* MBEDTLS_SSL_SESSION_TICKETS */
680
Ronald Cron82c785f2022-03-31 15:44:41 +0200681#if defined(MBEDTLS_SSL_CLI_C)
Ronald Cron217d6992022-04-04 10:23:22 +0200682 /** Minimum TLS version to be negotiated.
Ronald Cronbdb4f582022-03-31 15:37:44 +0200683 *
Ronald Cronb9a9b1f2024-02-14 11:28:05 +0100684 * It is set up in the ClientHello writing preparation stage and used
685 * throughout the ClientHello writing. Not relevant anymore as soon as
686 * the protocol version has been negotiated thus as soon as the
687 * ServerHello is received.
688 * For a fresh handshake not linked to any previous handshake, it is
689 * equal to the configured minimum minor version to be negotiated. When
690 * renegotiating or resuming a session, it is equal to the previously
691 * negotiated minor version.
Ronald Cronbdb4f582022-03-31 15:37:44 +0200692 *
Ronald Cronb9a9b1f2024-02-14 11:28:05 +0100693 * There is no maximum TLS version field in this handshake context.
694 * From the start of the handshake, we need to define a current protocol
695 * version for the record layer which we define as the maximum TLS
696 * version to be negotiated. The `tls_version` field of the SSL context is
697 * used to store this maximum value until it contains the actual
698 * negotiated value.
Ronald Cronbdb4f582022-03-31 15:37:44 +0200699 */
Glenn Straussbbdc83b2022-04-12 07:31:46 -0400700 mbedtls_ssl_protocol_version min_tls_version;
Ronald Cron82c785f2022-03-31 15:44:41 +0200701#endif
Ronald Cron86a477f2022-02-18 17:45:10 +0100702
Gilles Peskineec45c1e2021-11-29 12:18:09 +0100703#if defined(MBEDTLS_SSL_EXTENDED_MASTER_SECRET)
704 uint8_t extended_ms; /*!< use Extended Master Secret? */
705#endif
706
707#if defined(MBEDTLS_SSL_ASYNC_PRIVATE)
708 uint8_t async_in_progress; /*!< an asynchronous operation is in progress */
709#endif /* MBEDTLS_SSL_ASYNC_PRIVATE */
710
711#if defined(MBEDTLS_SSL_PROTO_DTLS)
712 unsigned char retransmit_state; /*!< Retransmission state */
713#endif
714
715#if defined(MBEDTLS_SSL_ECP_RESTARTABLE_ENABLED)
716 uint8_t ecrs_enabled; /*!< Handshake supports EC restart? */
Gilles Peskineec45c1e2021-11-29 12:18:09 +0100717 enum { /* this complements ssl->state with info on intra-state operations */
718 ssl_ecrs_none = 0, /*!< nothing going on (yet) */
719 ssl_ecrs_crt_verify, /*!< Certificate: crt_verify() */
720 ssl_ecrs_ske_start_processing, /*!< ServerKeyExchange: pk_verify() */
721 ssl_ecrs_cke_ecdh_calc_secret, /*!< ClientKeyExchange: ECDH step 2 */
722 ssl_ecrs_crt_vrfy_sign, /*!< CertificateVerify: pk_sign() */
723 } ecrs_state; /*!< current (or last) operation */
724 mbedtls_x509_crt *ecrs_peer_cert; /*!< The peer's CRT chain. */
725 size_t ecrs_n; /*!< place for saving a length */
726#endif
727
Gilles Peskineec45c1e2021-11-29 12:18:09 +0100728 mbedtls_ssl_ciphersuite_t const *ciphersuite_info;
729
Manuel Pégourié-Gonnardb8b07aa2023-02-06 00:34:21 +0100730 MBEDTLS_CHECK_RETURN_CRITICAL
Manuel Pégourié-Gonnard226aa152023-02-05 09:46:59 +0100731 int (*update_checksum)(mbedtls_ssl_context *, const unsigned char *, size_t);
Manuel Pégourié-Gonnardb8b07aa2023-02-06 00:34:21 +0100732 MBEDTLS_CHECK_RETURN_CRITICAL
Manuel Pégourié-Gonnard226aa152023-02-05 09:46:59 +0100733 int (*calc_verify)(const mbedtls_ssl_context *, unsigned char *, size_t *);
Manuel Pégourié-Gonnardb8b07aa2023-02-06 00:34:21 +0100734 MBEDTLS_CHECK_RETURN_CRITICAL
Manuel Pégourié-Gonnard226aa152023-02-05 09:46:59 +0100735 int (*calc_finished)(mbedtls_ssl_context *, unsigned char *, int);
Gilles Peskineec45c1e2021-11-29 12:18:09 +0100736 mbedtls_ssl_tls_prf_cb *tls_prf;
737
Manuel Pégourié-Gonnardcd4fcc62015-05-26 12:11:48 +0200738 /*
739 * Handshake specific crypto variables
740 */
Ronald Cron6f135e12021-12-08 16:57:54 +0100741#if defined(MBEDTLS_SSL_PROTO_TLS1_3)
Ronald Cron85385492022-07-20 16:44:00 +0200742 uint8_t key_exchange_mode; /*!< Selected key exchange mode */
Hanno Becker7e5437a2017-04-28 17:15:26 +0100743
Ronald Cron5fbd2702024-02-14 10:03:36 +0100744 /**
745 * Flag indicating if, in the course of the current handshake, an
746 * HelloRetryRequest message has been sent by the server or received by
747 * the client (<> 0) or not (0).
748 */
749 uint8_t hello_retry_request_flag;
Ronald Cronfe59ff72024-01-24 14:31:50 +0100750
751#if defined(MBEDTLS_SSL_TLS1_3_COMPATIBILITY_MODE)
752 /**
Ronald Cron5fbd2702024-02-14 10:03:36 +0100753 * Flag indicating if, in the course of the current handshake, a dummy
754 * change_cipher_spec (CCS) record has already been sent. Used to send only
755 * one CCS per handshake while not complicating the handshake state
756 * transitions for that purpose.
Ronald Cronfe59ff72024-01-24 14:31:50 +0100757 */
Ronald Cron5fbd2702024-02-14 10:03:36 +0100758 uint8_t ccs_sent;
Ronald Cronfe59ff72024-01-24 14:31:50 +0100759#endif
Ronald Cronbc817ba2022-07-21 09:35:20 +0200760
XiaokangQian08037552022-04-20 07:16:41 +0000761#if defined(MBEDTLS_SSL_SRV_C)
Ronald Cron41a443a2022-10-04 16:38:25 +0200762#if defined(MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_SOME_PSK_ENABLED)
Ronald Cronbc817ba2022-07-21 09:35:20 +0200763 uint8_t tls13_kex_modes; /*!< Key exchange modes supported by the client */
764#endif
Ronald Cronfe59ff72024-01-24 14:31:50 +0100765 /** selected_group of key_share extension in HelloRetryRequest message. */
766 uint16_t hrr_selected_group;
Jerry Yud4e75002022-08-09 13:33:50 +0800767#if defined(MBEDTLS_SSL_SESSION_TICKETS)
Jerry Yuf3bdf9d2022-09-22 23:30:49 +0800768 uint16_t new_session_tickets_count; /*!< number of session tickets */
Jerry Yud4e75002022-08-09 13:33:50 +0800769#endif
XiaokangQian08037552022-04-20 07:16:41 +0000770#endif /* MBEDTLS_SSL_SRV_C */
Ronald Cronbc817ba2022-07-21 09:35:20 +0200771
Jerry Yu582dd062022-04-22 21:59:01 +0800772#endif /* MBEDTLS_SSL_PROTO_TLS1_3 */
XiaokangQian08037552022-04-20 07:16:41 +0000773
Ronald Crone68ab4f2022-10-05 12:46:29 +0200774#if defined(MBEDTLS_SSL_HANDSHAKE_WITH_CERT_ENABLED)
Xiaofei Baif5b4d252022-01-28 06:37:15 +0000775 uint16_t received_sig_algs[MBEDTLS_RECEIVED_SIG_ALGS_SIZE];
776#endif
777
Valerio Settiea59c432023-07-25 11:14:03 +0200778#if defined(MBEDTLS_KEY_EXCHANGE_SOME_XXDH_PSA_ANY_ENABLED)
Przemek Stekiel7ac93be2023-07-04 10:02:38 +0200779 psa_key_type_t xxdh_psa_type;
Valerio Settiea59c432023-07-25 11:14:03 +0200780 size_t xxdh_psa_bits;
Przemek Stekiel7ac93be2023-07-04 10:02:38 +0200781 mbedtls_svc_key_id_t xxdh_psa_privkey;
782 uint8_t xxdh_psa_privkey_is_external;
Valerio Settida403b72023-07-10 14:31:39 +0200783 unsigned char xxdh_psa_peerkey[PSA_EXPORT_PUBLIC_KEY_MAX_SIZE];
Przemek Stekiel7ac93be2023-07-04 10:02:38 +0200784 size_t xxdh_psa_peerkey_len;
Valerio Settiea59c432023-07-25 11:14:03 +0200785#endif /* MBEDTLS_KEY_EXCHANGE_SOME_XXDH_PSA_ANY_ENABLED */
Hanno Beckerdf51dbe2019-02-18 16:41:55 +0000786
Manuel Pégourié-Gonnardeef142d2015-09-16 10:05:04 +0200787#if defined(MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED)
Neil Armstrongca7d5062022-05-31 14:43:23 +0200788 psa_pake_operation_t psa_pake_ctx; /*!< EC J-PAKE key exchange */
789 mbedtls_svc_key_id_t psa_pake_password;
790 uint8_t psa_pake_ctx_is_ok;
Manuel Pégourié-Gonnard77c06462015-09-17 13:59:49 +0200791#if defined(MBEDTLS_SSL_CLI_C)
792 unsigned char *ecjpake_cache; /*!< Cache for ClientHello ext */
793 size_t ecjpake_cache_len; /*!< Length of cached data */
794#endif
Hanno Becker1aa267c2017-04-28 17:08:27 +0100795#endif /* MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED */
Gilles Peskine8716f172021-11-16 15:21:44 +0100796
Valerio Settic2232ea2023-07-05 18:57:52 +0200797#if defined(MBEDTLS_KEY_EXCHANGE_SOME_ECDH_OR_ECDHE_ANY_ENABLED) || \
Valerio Settie9646ec2023-08-02 20:02:28 +0200798 defined(MBEDTLS_KEY_EXCHANGE_ECDSA_CERT_REQ_ANY_ALLOWED_ENABLED) || \
Manuel Pégourié-Gonnardeef142d2015-09-16 10:05:04 +0200799 defined(MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED)
Valerio Setti18c9fed2022-12-30 17:44:24 +0100800 uint16_t *curves_tls_id; /*!< List of TLS IDs of supported elliptic curves */
Manuel Pégourié-Gonnardcd4fcc62015-05-26 12:11:48 +0200801#endif
Gilles Peskine8716f172021-11-16 15:21:44 +0100802
Ronald Cron73fe8df2022-10-05 14:31:43 +0200803#if defined(MBEDTLS_SSL_HANDSHAKE_WITH_PSK_ENABLED)
Andrzej Kurek03e01462022-01-03 12:53:24 +0100804 mbedtls_svc_key_id_t psk_opaque; /*!< Opaque PSK from the callback */
Neil Armstrong501c9322022-05-03 09:35:09 +0200805 uint8_t psk_opaque_is_internal;
Jerry Yu96a2e362022-07-21 15:11:34 +0800806 uint16_t selected_identity;
Ronald Cron73fe8df2022-10-05 14:31:43 +0200807#endif /* MBEDTLS_SSL_HANDSHAKE_WITH_PSK_ENABLED */
Gilles Peskine8716f172021-11-16 15:21:44 +0100808
Gilles Peskinecfe74a32021-12-08 18:38:51 +0100809#if defined(MBEDTLS_SSL_ECP_RESTARTABLE_ENABLED)
810 mbedtls_x509_crt_restart_ctx ecrs_ctx; /*!< restart context */
811#endif
812
Manuel Pégourié-Gonnardcd4fcc62015-05-26 12:11:48 +0200813#if defined(MBEDTLS_X509_CRT_PARSE_C)
814 mbedtls_ssl_key_cert *key_cert; /*!< chosen key/cert pair (server) */
815#if defined(MBEDTLS_SSL_SERVER_NAME_INDICATION)
816 mbedtls_ssl_key_cert *sni_key_cert; /*!< key/cert list from SNI */
817 mbedtls_x509_crt *sni_ca_chain; /*!< trusted CAs from SNI callback */
818 mbedtls_x509_crl *sni_ca_crl; /*!< trusted CAs CRLs from SNI */
Hanno Becker1aa267c2017-04-28 17:08:27 +0100819#endif /* MBEDTLS_SSL_SERVER_NAME_INDICATION */
Manuel Pégourié-Gonnardcd4fcc62015-05-26 12:11:48 +0200820#endif /* MBEDTLS_X509_CRT_PARSE_C */
Gilles Peskine8716f172021-11-16 15:21:44 +0100821
Gilles Peskine8716f172021-11-16 15:21:44 +0100822#if defined(MBEDTLS_X509_CRT_PARSE_C) && \
Hanno Becker75173122019-02-06 16:18:31 +0000823 !defined(MBEDTLS_SSL_KEEP_PEER_CERTIFICATE)
824 mbedtls_pk_context peer_pubkey; /*!< The public key from the peer. */
825#endif /* MBEDTLS_X509_CRT_PARSE_C && !MBEDTLS_SSL_KEEP_PEER_CERTIFICATE */
Hanno Becker2f28c102019-04-25 15:46:59 +0100826
Gilles Peskine449bd832023-01-11 14:50:10 +0100827 struct {
Hanno Beckere0b150f2018-08-21 15:51:03 +0100828 size_t total_bytes_buffered; /*!< Cumulative size of heap allocated
829 * buffers used for message buffering. */
830
Hanno Beckerd7f8ae22018-08-16 09:45:56 +0100831 uint8_t seen_ccs; /*!< Indicates if a CCS message has
Hanno Becker2ed6bcc2018-08-15 15:11:57 +0100832 * been seen in the current flight. */
Hanno Beckerd7f8ae22018-08-16 09:45:56 +0100833
Gilles Peskine449bd832023-01-11 14:50:10 +0100834 struct mbedtls_ssl_hs_buffer {
Hanno Becker98081a02018-08-22 13:32:50 +0100835 unsigned is_valid : 1;
836 unsigned is_fragmented : 1;
837 unsigned is_complete : 1;
Hanno Becker0271f962018-08-16 13:23:47 +0100838 unsigned char *data;
Hanno Beckere0b150f2018-08-21 15:51:03 +0100839 size_t data_len;
Hanno Becker0271f962018-08-16 13:23:47 +0100840 } hs[MBEDTLS_SSL_MAX_BUFFERED_HS];
841
Gilles Peskine449bd832023-01-11 14:50:10 +0100842 struct {
Hanno Becker5f066e72018-08-16 14:56:31 +0100843 unsigned char *data;
844 size_t len;
845 unsigned epoch;
846 } future_record;
847
Hanno Beckerd7f8ae22018-08-16 09:45:56 +0100848 } buffering;
Hanno Becker35462012018-08-22 10:25:40 +0100849
XiaokangQian9b93c0d2022-02-09 06:02:25 +0000850#if defined(MBEDTLS_SSL_CLI_C) && \
Gilles Peskine449bd832023-01-11 14:50:10 +0100851 (defined(MBEDTLS_SSL_PROTO_DTLS) || \
852 defined(MBEDTLS_SSL_PROTO_TLS1_3))
Jerry Yuac5ca5a2022-03-04 12:50:46 +0800853 unsigned char *cookie; /*!< HelloVerifyRequest cookie for DTLS
854 * HelloRetryRequest cookie for TLS 1.3 */
855#if !defined(MBEDTLS_SSL_PROTO_TLS1_3)
856 /* RFC 6347 page 15
857 ...
858 opaque cookie<0..2^8-1>;
859 ...
860 */
861 uint8_t cookie_len;
862#else
863 /* RFC 8446 page 39
864 ...
865 opaque cookie<0..2^16-1>;
866 ...
867 If TLS1_3 is enabled, the max length is 2^16 - 1
868 */
869 uint16_t cookie_len; /*!< DTLS: HelloVerifyRequest cookie length
870 * TLS1_3: HelloRetryRequest cookie length */
871#endif
XiaokangQian9b93c0d2022-02-09 06:02:25 +0000872#endif /* MBEDTLS_SSL_CLI_C &&
Jerry Yuac5ca5a2022-03-04 12:50:46 +0800873 ( MBEDTLS_SSL_PROTO_DTLS ||
874 MBEDTLS_SSL_PROTO_TLS1_3 ) */
875#if defined(MBEDTLS_SSL_SRV_C) && defined(MBEDTLS_SSL_PROTO_DTLS)
876 unsigned char cookie_verify_result; /*!< Srv: flag for sending a cookie */
877#endif /* MBEDTLS_SSL_SRV_C && MBEDTLS_SSL_PROTO_DTLS */
XiaokangQian52da5582022-01-26 09:49:29 +0000878
879#if defined(MBEDTLS_SSL_PROTO_DTLS)
880 unsigned int out_msg_seq; /*!< Outgoing handshake sequence number */
881 unsigned int in_msg_seq; /*!< Incoming handshake sequence number */
Gilles Peskineec45c1e2021-11-29 12:18:09 +0100882
883 uint32_t retransmit_timeout; /*!< Current value of timeout */
884 mbedtls_ssl_flight_item *flight; /*!< Current outgoing flight */
885 mbedtls_ssl_flight_item *cur_msg; /*!< Current message in flight */
886 unsigned char *cur_msg_p; /*!< Position in current message */
887 unsigned int in_flight_start_seq; /*!< Minimum message sequence in the
888 flight being received */
889 mbedtls_ssl_transform *alt_transform_out; /*!< Alternative transform for
Gilles Peskine449bd832023-01-11 14:50:10 +0100890 resending messages */
Gilles Peskineec45c1e2021-11-29 12:18:09 +0100891 unsigned char alt_out_ctr[MBEDTLS_SSL_SEQUENCE_NUMBER_LEN]; /*!< Alternative record epoch/counter
892 for resending messages */
893
894#if defined(MBEDTLS_SSL_DTLS_CONNECTION_ID)
895 /* The state of CID configuration in this handshake. */
896
897 uint8_t cid_in_use; /*!< This indicates whether the use of the CID extension
898 * has been negotiated. Possible values are
899 * #MBEDTLS_SSL_CID_ENABLED and
900 * #MBEDTLS_SSL_CID_DISABLED. */
Gilles Peskine449bd832023-01-11 14:50:10 +0100901 unsigned char peer_cid[MBEDTLS_SSL_CID_OUT_LEN_MAX]; /*! The peer's CID */
Gilles Peskineec45c1e2021-11-29 12:18:09 +0100902 uint8_t peer_cid_len; /*!< The length of
903 * \c peer_cid. */
904#endif /* MBEDTLS_SSL_DTLS_CONNECTION_ID */
905
Manuel Pégourié-Gonnardf47a4af2018-08-22 10:38:52 +0200906 uint16_t mtu; /*!< Handshake mtu, used to fragment outgoing messages */
Hanno Becker1aa267c2017-04-28 17:08:27 +0100907#endif /* MBEDTLS_SSL_PROTO_DTLS */
Manuel Pégourié-Gonnardcd4fcc62015-05-26 12:11:48 +0200908
909 /*
910 * Checksum contexts
911 */
Elena Uziunaite0916cd72024-05-23 17:01:07 +0100912#if defined(PSA_WANT_ALG_SHA_256)
Andrzej Kurekeb342242019-01-29 09:14:33 -0500913 psa_hash_operation_t fin_sha256_psa;
Andrzej Kurekeb342242019-01-29 09:14:33 -0500914#endif
Elena Uziunaiteb476d4b2024-05-23 15:33:41 +0100915#if defined(PSA_WANT_ALG_SHA_384)
Andrzej Kurek972fba52019-01-30 03:29:12 -0500916 psa_hash_operation_t fin_sha384_psa;
Andrzej Kurekeb342242019-01-29 09:14:33 -0500917#endif
Manuel Pégourié-Gonnardcd4fcc62015-05-26 12:11:48 +0200918
Ronald Cron6f135e12021-12-08 16:57:54 +0100919#if defined(MBEDTLS_SSL_PROTO_TLS1_3)
Jerry Yu56fc07f2021-09-01 17:48:49 +0800920 uint16_t offered_group_id; /* The NamedGroup value for the group
921 * that is being used for ephemeral
922 * key exchange.
923 *
924 * On the client: Defaults to the first
925 * entry in the client's group list,
926 * but can be overwritten by the HRR. */
Ronald Cron6f135e12021-12-08 16:57:54 +0100927#endif /* MBEDTLS_SSL_PROTO_TLS1_3 */
Jerry Yu56fc07f2021-09-01 17:48:49 +0800928
Jerry Yufb28b882022-01-28 11:05:58 +0800929#if defined(MBEDTLS_SSL_CLI_C)
Jerry Yu2d9a6942022-02-08 21:07:10 +0800930 uint8_t client_auth; /*!< used to check if CertificateRequest has been
Jerry Yu5c7d1cc2022-02-08 21:08:29 +0800931 received from server side. If CertificateRequest
Jerry Yu0ff8ac82022-02-08 10:10:48 +0800932 has been received, Certificate and CertificateVerify
Jerry Yufb28b882022-01-28 11:05:58 +0800933 should be sent to server */
934#endif /* MBEDTLS_SSL_CLI_C */
XiaokangQianaa5f5c12021-09-18 06:20:25 +0000935 /*
936 * State-local variables used during the processing
937 * of a specific handshake state.
938 */
Gilles Peskine449bd832023-01-11 14:50:10 +0100939 union {
XiaokangQianaa5f5c12021-09-18 06:20:25 +0000940 /* Outgoing Finished message */
Gilles Peskine449bd832023-01-11 14:50:10 +0100941 struct {
XiaokangQianaa5f5c12021-09-18 06:20:25 +0000942 uint8_t preparation_done;
943
944 /* Buffer holding digest of the handshake up to
945 * but excluding the outgoing finished message. */
XiaokangQianc5c39d52021-11-09 11:55:10 +0000946 unsigned char digest[MBEDTLS_TLS1_3_MD_MAX_SIZE];
XiaokangQianaa5f5c12021-09-18 06:20:25 +0000947 size_t digest_len;
948 } finished_out;
949
950 /* Incoming Finished message */
Gilles Peskine449bd832023-01-11 14:50:10 +0100951 struct {
XiaokangQian57b2aff2021-11-10 03:12:11 +0000952 uint8_t preparation_done;
953
XiaokangQianaa5f5c12021-09-18 06:20:25 +0000954 /* Buffer holding digest of the handshake up to but
955 * excluding the peer's incoming finished message. */
XiaokangQianc5c39d52021-11-09 11:55:10 +0000956 unsigned char digest[MBEDTLS_TLS1_3_MD_MAX_SIZE];
XiaokangQianaa5f5c12021-09-18 06:20:25 +0000957 size_t digest_len;
958 } finished_in;
959
XiaokangQianaa5f5c12021-09-18 06:20:25 +0000960 } state_local;
961
962 /* End of state-local variables. */
963
Jerry Yue6d7e5c2021-10-26 10:44:32 +0800964 unsigned char randbytes[MBEDTLS_CLIENT_HELLO_RANDOM_LEN +
965 MBEDTLS_SERVER_HELLO_RANDOM_LEN];
Gilles Peskine449bd832023-01-11 14:50:10 +0100966 /*!< random bytes */
Ronald Cron3b056202022-10-05 17:20:21 +0200967#if defined(MBEDTLS_SSL_PROTO_TLS1_2)
Manuel Pégourié-Gonnardcd4fcc62015-05-26 12:11:48 +0200968 unsigned char premaster[MBEDTLS_PREMASTER_SIZE];
Gilles Peskine449bd832023-01-11 14:50:10 +0100969 /*!< premaster secret */
Ronald Cron3b056202022-10-05 17:20:21 +0200970 size_t pmslen; /*!< premaster length */
971#endif
Manuel Pégourié-Gonnardcd4fcc62015-05-26 12:11:48 +0200972
Ronald Cron6f135e12021-12-08 16:57:54 +0100973#if defined(MBEDTLS_SSL_PROTO_TLS1_3)
Jerry Yu0c354a22022-08-29 15:25:36 +0800974 uint32_t sent_extensions; /*!< extensions sent by endpoint */
975 uint32_t received_extensions; /*!< extensions received by endpoint */
Jerry Yu89ea3212021-09-09 14:31:24 +0800976
Ronald Crone68ab4f2022-10-05 12:46:29 +0200977#if defined(MBEDTLS_SSL_HANDSHAKE_WITH_CERT_ENABLED)
Xiaofei Baia0ab7772022-01-16 12:14:45 +0000978 unsigned char certificate_request_context_len;
979 unsigned char *certificate_request_context;
Xiaofei Baie1e34422021-12-23 12:09:05 +0000980#endif
981
Jerry Yu3d9b5902022-11-04 14:07:25 +0800982 /** TLS 1.3 transform for encrypted handshake messages. */
983 mbedtls_ssl_transform *transform_handshake;
Gilles Peskine449bd832023-01-11 14:50:10 +0100984 union {
985 unsigned char early[MBEDTLS_TLS1_3_MD_MAX_SIZE];
Jerry Yud1ab2622021-10-08 15:36:57 +0800986 unsigned char handshake[MBEDTLS_TLS1_3_MD_MAX_SIZE];
Gilles Peskine449bd832023-01-11 14:50:10 +0100987 unsigned char app[MBEDTLS_TLS1_3_MD_MAX_SIZE];
Xiaofei Baid25fab62021-12-02 06:36:27 +0000988 } tls13_master_secrets;
Jerry Yu61e35e02021-09-16 18:59:08 +0800989
Xiaofei Bai746f9482021-11-12 08:53:56 +0000990 mbedtls_ssl_tls13_handshake_secrets tls13_hs_secrets;
Jerry Yu3d9b5902022-11-04 14:07:25 +0800991#if defined(MBEDTLS_SSL_EARLY_DATA)
Jerry Yu3ce61ff2022-11-21 22:45:58 +0800992 /** TLS 1.3 transform for early data and handshake messages. */
Jerry Yu3d9b5902022-11-04 14:07:25 +0800993 mbedtls_ssl_transform *transform_earlydata;
994#endif
Ronald Cron6f135e12021-12-08 16:57:54 +0100995#endif /* MBEDTLS_SSL_PROTO_TLS1_3 */
Manuel Pégourié-Gonnardcd4fcc62015-05-26 12:11:48 +0200996
Gilles Peskinedf13d5c2018-04-25 20:39:48 +0200997#if defined(MBEDTLS_SSL_ASYNC_PRIVATE)
998 /** Asynchronous operation context. This field is meant for use by the
999 * asynchronous operation callbacks (mbedtls_ssl_config::f_async_sign_start,
Gilles Peskinedf13d5c2018-04-25 20:39:48 +02001000 * mbedtls_ssl_config::f_async_resume, mbedtls_ssl_config::f_async_cancel).
1001 * The library does not use it internally. */
1002 void *user_async_ctx;
1003#endif /* MBEDTLS_SSL_ASYNC_PRIVATE */
Glenn Strauss69894072022-01-24 12:58:00 -05001004
1005#if defined(MBEDTLS_SSL_SERVER_NAME_INDICATION)
1006 const unsigned char *sni_name; /*!< raw SNI */
1007 size_t sni_name_len; /*!< raw SNI len */
Glenn Strauss999ef702022-03-11 01:37:23 -05001008#if defined(MBEDTLS_KEY_EXCHANGE_CERT_REQ_ALLOWED_ENABLED)
1009 const mbedtls_x509_crt *dn_hints; /*!< acceptable client cert issuers */
1010#endif
Glenn Strauss69894072022-01-24 12:58:00 -05001011#endif /* MBEDTLS_SSL_SERVER_NAME_INDICATION */
Manuel Pégourié-Gonnardcd4fcc62015-05-26 12:11:48 +02001012};
1013
Hanno Becker0271f962018-08-16 13:23:47 +01001014typedef struct mbedtls_ssl_hs_buffer mbedtls_ssl_hs_buffer;
1015
Manuel Pégourié-Gonnardcd4fcc62015-05-26 12:11:48 +02001016/*
Hanno Beckerd362dc52018-01-03 15:23:11 +00001017 * Representation of decryption/encryption transformations on records
1018 *
1019 * There are the following general types of record transformations:
TRodziewicz2abf03c2021-06-25 14:40:09 +02001020 * - Stream transformations (TLS versions == 1.2 only)
Hanno Beckerd362dc52018-01-03 15:23:11 +00001021 * Transformation adding a MAC and applying a stream-cipher
1022 * to the authenticated message.
TRodziewicz2abf03c2021-06-25 14:40:09 +02001023 * - CBC block cipher transformations ([D]TLS versions == 1.2 only)
1024 * For TLS 1.2, no IV is generated at key extraction time, but every
1025 * encrypted record is explicitly prefixed by the IV with which it was
1026 * encrypted.
1027 * - AEAD transformations ([D]TLS versions == 1.2 only)
Hanno Beckerd362dc52018-01-03 15:23:11 +00001028 * These come in two fundamentally different versions, the first one
1029 * used in TLS 1.2, excluding ChaChaPoly ciphersuites, and the second
1030 * one used for ChaChaPoly ciphersuites in TLS 1.2 as well as for TLS 1.3.
1031 * In the first transformation, the IV to be used for a record is obtained
1032 * as the concatenation of an explicit, static 4-byte IV and the 8-byte
1033 * record sequence number, and explicitly prepending this sequence number
1034 * to the encrypted record. In contrast, in the second transformation
1035 * the IV is obtained by XOR'ing a static IV obtained at key extraction
1036 * time with the 8-byte record sequence number, without prepending the
1037 * latter to the encrypted record.
1038 *
Hanno Becker7d343ec2020-05-04 12:29:05 +01001039 * Additionally, DTLS 1.2 + CID as well as TLS 1.3 use an inner plaintext
1040 * which allows to add flexible length padding and to hide a record's true
1041 * content type.
1042 *
Hanno Beckerd362dc52018-01-03 15:23:11 +00001043 * In addition to type and version, the following parameters are relevant:
1044 * - The symmetric cipher algorithm to be used.
1045 * - The (static) encryption/decryption keys for the cipher.
1046 * - For stream/CBC, the type of message digest to be used.
1047 * - For stream/CBC, (static) encryption/decryption keys for the digest.
Hanno Becker0db7e0c2018-10-18 15:39:53 +01001048 * - For AEAD transformations, the size (potentially 0) of an explicit,
1049 * random initialization vector placed in encrypted records.
TRodziewicz299510e2021-07-09 16:55:11 +02001050 * - For some transformations (currently AEAD) an implicit IV. It is static
Hanno Beckerd362dc52018-01-03 15:23:11 +00001051 * and (if present) is combined with the explicit IV in a transformation-
TRodziewicz299510e2021-07-09 16:55:11 +02001052 * -dependent way (e.g. appending in TLS 1.2 and XOR'ing in TLS 1.3).
Hanno Beckerd362dc52018-01-03 15:23:11 +00001053 * - For stream/CBC, a flag determining the order of encryption and MAC.
1054 * - The details of the transformation depend on the SSL/TLS version.
1055 * - The length of the authentication tag.
1056 *
1057 * The struct below refines this abstract view as follows:
1058 * - The cipher underlying the transformation is managed in
1059 * cipher contexts cipher_ctx_{enc/dec}, which must have the
1060 * same cipher type. The mode of these cipher contexts determines
1061 * the type of the transformation in the sense above: e.g., if
1062 * the type is MBEDTLS_CIPHER_AES_256_CBC resp. MBEDTLS_CIPHER_AES_192_GCM
1063 * then the transformation has type CBC resp. AEAD.
1064 * - The cipher keys are never stored explicitly but
1065 * are maintained within cipher_ctx_{enc/dec}.
1066 * - For stream/CBC transformations, the message digest contexts
1067 * used for the MAC's are stored in md_ctx_{enc/dec}. These contexts
1068 * are unused for AEAD transformations.
TRodziewicz2abf03c2021-06-25 14:40:09 +02001069 * - For stream/CBC transformations, the MAC keys are not stored explicitly
1070 * but maintained within md_ctx_{enc/dec}.
1071 * - The mac_enc and mac_dec fields are unused for EAD transformations.
Hanno Beckerd362dc52018-01-03 15:23:11 +00001072 * - For transformations using an implicit IV maintained within
1073 * the transformation context, its contents are stored within
1074 * iv_{enc/dec}.
1075 * - The value of ivlen indicates the length of the IV.
1076 * This is redundant in case of stream/CBC transformations
1077 * which always use 0 resp. the cipher's block length as the
1078 * IV length, but is needed for AEAD ciphers and may be
1079 * different from the underlying cipher's block length
1080 * in this case.
1081 * - The field fixed_ivlen is nonzero for AEAD transformations only
1082 * and indicates the length of the static part of the IV which is
1083 * constant throughout the communication, and which is stored in
1084 * the first fixed_ivlen bytes of the iv_{enc/dec} arrays.
Glenn Strauss07c64162022-03-14 12:34:51 -04001085 * - tls_version denotes the 2-byte TLS version
Hanno Beckerd362dc52018-01-03 15:23:11 +00001086 * - For stream/CBC transformations, maclen denotes the length of the
1087 * authentication tag, while taglen is unused and 0.
1088 * - For AEAD transformations, taglen denotes the length of the
1089 * authentication tag, while maclen is unused and 0.
1090 * - For CBC transformations, encrypt_then_mac determines the
1091 * order of encryption and authentication. This field is unused
1092 * in other transformations.
1093 *
Manuel Pégourié-Gonnardcd4fcc62015-05-26 12:11:48 +02001094 */
Gilles Peskine449bd832023-01-11 14:50:10 +01001095struct mbedtls_ssl_transform {
Manuel Pégourié-Gonnardcd4fcc62015-05-26 12:11:48 +02001096 /*
1097 * Session specific crypto layer
1098 */
Manuel Pégourié-Gonnardcd4fcc62015-05-26 12:11:48 +02001099 size_t minlen; /*!< min. ciphertext length */
1100 size_t ivlen; /*!< IV length */
1101 size_t fixed_ivlen; /*!< Fixed part of IV (AEAD) */
Hanno Beckere694c3e2017-12-27 21:34:08 +00001102 size_t maclen; /*!< MAC(CBC) len */
1103 size_t taglen; /*!< TAG(AEAD) len */
Manuel Pégourié-Gonnardcd4fcc62015-05-26 12:11:48 +02001104
1105 unsigned char iv_enc[16]; /*!< IV (encryption) */
1106 unsigned char iv_dec[16]; /*!< IV (decryption) */
1107
Hanno Beckerfd86ca82020-11-30 08:54:23 +00001108#if defined(MBEDTLS_SSL_SOME_SUITES_USE_MAC)
Hanno Beckerd56ed242018-01-03 15:32:51 +00001109
Neil Armstrong39b8e7d2022-02-23 09:24:45 +01001110 mbedtls_svc_key_id_t psa_mac_enc; /*!< MAC (encryption) */
1111 mbedtls_svc_key_id_t psa_mac_dec; /*!< MAC (decryption) */
1112 psa_algorithm_t psa_mac_alg; /*!< psa MAC algorithm */
Manuel Pégourié-Gonnardcd4fcc62015-05-26 12:11:48 +02001113
Hanno Becker9eddaeb2017-12-27 21:37:21 +00001114#if defined(MBEDTLS_SSL_ENCRYPT_THEN_MAC)
1115 int encrypt_then_mac; /*!< flag for EtM activation */
1116#endif
1117
Hanno Beckerfd86ca82020-11-30 08:54:23 +00001118#endif /* MBEDTLS_SSL_SOME_SUITES_USE_MAC */
Hanno Beckerd56ed242018-01-03 15:32:51 +00001119
Glenn Strauss07c64162022-03-14 12:34:51 -04001120 mbedtls_ssl_protocol_version tls_version;
Hanno Becker9eddaeb2017-12-27 21:37:21 +00001121
Przemyslaw Stekiel44187d72022-01-11 08:25:29 +01001122 mbedtls_svc_key_id_t psa_key_enc; /*!< psa encryption key */
1123 mbedtls_svc_key_id_t psa_key_dec; /*!< psa decryption key */
1124 psa_algorithm_t psa_alg; /*!< psa algorithm */
Przemyslaw Stekiel44187d72022-01-11 08:25:29 +01001125
Hanno Beckera0e20d02019-05-15 14:03:01 +01001126#if defined(MBEDTLS_SSL_DTLS_CONNECTION_ID)
Hanno Becker1327fa72019-04-25 15:54:02 +01001127 uint8_t in_cid_len;
1128 uint8_t out_cid_len;
Gilles Peskine449bd832023-01-11 14:50:10 +01001129 unsigned char in_cid[MBEDTLS_SSL_CID_IN_LEN_MAX];
1130 unsigned char out_cid[MBEDTLS_SSL_CID_OUT_LEN_MAX];
Hanno Beckera0e20d02019-05-15 14:03:01 +01001131#endif /* MBEDTLS_SSL_DTLS_CONNECTION_ID */
Hanno Becker1327fa72019-04-25 15:54:02 +01001132
Max Fillinger2fe35f62024-10-25 00:52:24 +02001133#if defined(MBEDTLS_SSL_KEEP_RANDBYTES)
Manuel Pégourié-Gonnard96fb0ee2019-07-09 12:54:17 +02001134 /* We need the Hello random bytes in order to re-derive keys from the
Max Fillinger2fe35f62024-10-25 00:52:24 +02001135 * Master Secret and other session info and for the keying material
1136 * exporter in TLS 1.2.
1137 * See ssl_tls12_populate_transform() */
Jerry Yue6d7e5c2021-10-26 10:44:32 +08001138 unsigned char randbytes[MBEDTLS_SERVER_HELLO_RANDOM_LEN +
1139 MBEDTLS_CLIENT_HELLO_RANDOM_LEN];
Gilles Peskine449bd832023-01-11 14:50:10 +01001140 /*!< ServerHello.random+ClientHello.random */
Max Fillinger07473882024-10-28 14:44:25 +01001141#endif /* defined(MBEDTLS_SSL_KEEP_RANDBYTES) */
Manuel Pégourié-Gonnardcd4fcc62015-05-26 12:11:48 +02001142};
1143
Hanno Becker12a3a862018-01-05 15:42:50 +00001144/*
Manuel Pégourié-Gonnard1aaf6692019-07-10 14:14:05 +02001145 * Return 1 if the transform uses an AEAD cipher, 0 otherwise.
1146 * Equivalently, return 0 if a separate MAC is used, 1 otherwise.
1147 */
1148static inline int mbedtls_ssl_transform_uses_aead(
Gilles Peskine449bd832023-01-11 14:50:10 +01001149 const mbedtls_ssl_transform *transform)
Manuel Pégourié-Gonnard1aaf6692019-07-10 14:14:05 +02001150{
Hanno Beckerfd86ca82020-11-30 08:54:23 +00001151#if defined(MBEDTLS_SSL_SOME_SUITES_USE_MAC)
Gilles Peskine449bd832023-01-11 14:50:10 +01001152 return transform->maclen == 0 && transform->taglen != 0;
Manuel Pégourié-Gonnard1aaf6692019-07-10 14:14:05 +02001153#else
1154 (void) transform;
Gilles Peskine449bd832023-01-11 14:50:10 +01001155 return 1;
Manuel Pégourié-Gonnard1aaf6692019-07-10 14:14:05 +02001156#endif
1157}
1158
1159/*
Hanno Becker12a3a862018-01-05 15:42:50 +00001160 * Internal representation of record frames
1161 *
Hanno Becker12a3a862018-01-05 15:42:50 +00001162 * Instances come in two flavors:
1163 * (1) Encrypted
1164 * These always have data_offset = 0
1165 * (2) Unencrypted
Hanno Beckercd430bc2019-04-04 16:29:48 +01001166 * These have data_offset set to the amount of
1167 * pre-expansion during record protection. Concretely,
1168 * this is the length of the fixed part of the explicit IV
1169 * used for encryption, or 0 if no explicit IV is used
TRodziewicz2abf03c2021-06-25 14:40:09 +02001170 * (e.g. for stream ciphers).
Hanno Becker12a3a862018-01-05 15:42:50 +00001171 *
1172 * The reason for the data_offset in the unencrypted case
1173 * is to allow for in-place conversion of an unencrypted to
1174 * an encrypted record. If the offset wasn't included, the
1175 * encrypted content would need to be shifted afterwards to
1176 * make space for the fixed IV.
1177 *
1178 */
Hanno Beckerf2ed4482019-04-29 13:45:54 +01001179#if MBEDTLS_SSL_CID_OUT_LEN_MAX > MBEDTLS_SSL_CID_IN_LEN_MAX
Hanno Becker75f080f2019-04-30 15:01:51 +01001180#define MBEDTLS_SSL_CID_LEN_MAX MBEDTLS_SSL_CID_OUT_LEN_MAX
Hanno Beckerf2ed4482019-04-29 13:45:54 +01001181#else
Hanno Becker75f080f2019-04-30 15:01:51 +01001182#define MBEDTLS_SSL_CID_LEN_MAX MBEDTLS_SSL_CID_IN_LEN_MAX
Hanno Beckerf2ed4482019-04-29 13:45:54 +01001183#endif
1184
Gilles Peskine449bd832023-01-11 14:50:10 +01001185typedef struct {
Jerry Yuae0b2e22021-10-08 15:21:19 +08001186 uint8_t ctr[MBEDTLS_SSL_SEQUENCE_NUMBER_LEN]; /* In TLS: The implicit record sequence number.
1187 * In DTLS: The 2-byte epoch followed by
1188 * the 6-byte sequence number.
1189 * This is stored as a raw big endian byte array
1190 * as opposed to a uint64_t because we rarely
1191 * need to perform arithmetic on this, but do
1192 * need it as a Byte array for the purpose of
1193 * MAC computations. */
Hanno Beckerd840cea2019-07-11 09:24:36 +01001194 uint8_t type; /* The record content type. */
1195 uint8_t ver[2]; /* SSL/TLS version as present on the wire.
1196 * Convert to internal presentation of versions
1197 * using mbedtls_ssl_read_version() and
1198 * mbedtls_ssl_write_version().
1199 * Keep wire-format for MAC computations. */
Hanno Becker12a3a862018-01-05 15:42:50 +00001200
Hanno Beckerd840cea2019-07-11 09:24:36 +01001201 unsigned char *buf; /* Memory buffer enclosing the record content */
1202 size_t buf_len; /* Buffer length */
1203 size_t data_offset; /* Offset of record content */
1204 size_t data_len; /* Length of record content */
Hanno Becker12a3a862018-01-05 15:42:50 +00001205
Hanno Beckera0e20d02019-05-15 14:03:01 +01001206#if defined(MBEDTLS_SSL_DTLS_CONNECTION_ID)
Hanno Beckerd840cea2019-07-11 09:24:36 +01001207 uint8_t cid_len; /* Length of the CID (0 if not present) */
Gilles Peskine449bd832023-01-11 14:50:10 +01001208 unsigned char cid[MBEDTLS_SSL_CID_LEN_MAX]; /* The CID */
Hanno Beckera0e20d02019-05-15 14:03:01 +01001209#endif /* MBEDTLS_SSL_DTLS_CONNECTION_ID */
Hanno Becker12a3a862018-01-05 15:42:50 +00001210} mbedtls_record;
1211
Manuel Pégourié-Gonnardcd4fcc62015-05-26 12:11:48 +02001212#if defined(MBEDTLS_X509_CRT_PARSE_C)
1213/*
1214 * List of certificate + private key pairs
1215 */
Gilles Peskine449bd832023-01-11 14:50:10 +01001216struct mbedtls_ssl_key_cert {
Manuel Pégourié-Gonnardcd4fcc62015-05-26 12:11:48 +02001217 mbedtls_x509_crt *cert; /*!< cert */
1218 mbedtls_pk_context *key; /*!< private key */
1219 mbedtls_ssl_key_cert *next; /*!< next key/cert pair */
1220};
1221#endif /* MBEDTLS_X509_CRT_PARSE_C */
1222
1223#if defined(MBEDTLS_SSL_PROTO_DTLS)
1224/*
1225 * List of handshake messages kept around for resending
1226 */
Gilles Peskine449bd832023-01-11 14:50:10 +01001227struct mbedtls_ssl_flight_item {
Manuel Pégourié-Gonnardcd4fcc62015-05-26 12:11:48 +02001228 unsigned char *p; /*!< message, including handshake headers */
1229 size_t len; /*!< length of p */
1230 unsigned char type; /*!< type of the message: handshake or CCS */
1231 mbedtls_ssl_flight_item *next; /*!< next handshake message(s) */
1232};
1233#endif /* MBEDTLS_SSL_PROTO_DTLS */
1234
Ronald Cron4079abc2022-02-20 10:35:26 +01001235#if defined(MBEDTLS_SSL_PROTO_TLS1_2)
1236/**
1237 * \brief Given an SSL context and its associated configuration, write the TLS
1238 * 1.2 specific extensions of the ClientHello message.
1239 *
1240 * \param[in] ssl SSL context
1241 * \param[in] buf Base address of the buffer where to write the extensions
1242 * \param[in] end End address of the buffer where to write the extensions
1243 * \param uses_ec Whether one proposed ciphersuite uses an elliptic curve
1244 * (<> 0) or not ( 0 ).
1245 * \param[out] out_len Length of the data written into the buffer \p buf
1246 */
Manuel Pégourié-Gonnarda82a8b92022-06-17 10:53:58 +02001247MBEDTLS_CHECK_RETURN_CRITICAL
Gilles Peskine449bd832023-01-11 14:50:10 +01001248int mbedtls_ssl_tls12_write_client_hello_exts(mbedtls_ssl_context *ssl,
1249 unsigned char *buf,
1250 const unsigned char *end,
1251 int uses_ec,
1252 size_t *out_len);
Ronald Cron4079abc2022-02-20 10:35:26 +01001253#endif
1254
Hanno Becker7e5437a2017-04-28 17:15:26 +01001255#if defined(MBEDTLS_SSL_PROTO_TLS1_2) && \
Gilles Peskineeccd8882020-03-10 12:19:08 +01001256 defined(MBEDTLS_KEY_EXCHANGE_WITH_CERT_ENABLED)
Hanno Becker7e5437a2017-04-28 17:15:26 +01001257
Gabor Mezeia3d016c2022-05-10 12:44:09 +02001258/**
1259 * \brief Find the preferred hash for a given signature algorithm.
1260 *
1261 * \param[in] ssl SSL context
1262 * \param[in] sig_alg A signature algorithm identifier as defined in the
1263 * TLS 1.2 SignatureAlgorithm enumeration.
1264 *
1265 * \return The preferred hash algorithm for \p sig_alg. It is a hash algorithm
1266 * identifier as defined in the TLS 1.2 HashAlgorithm enumeration.
1267 */
1268unsigned int mbedtls_ssl_tls12_get_preferred_hash_for_sig_alg(
Gilles Peskine449bd832023-01-11 14:50:10 +01001269 mbedtls_ssl_context *ssl,
1270 unsigned int sig_alg);
Hanno Becker7e5437a2017-04-28 17:15:26 +01001271
Gabor Mezei078e8032022-04-27 21:17:56 +02001272#endif /* MBEDTLS_SSL_PROTO_TLS1_2 &&
Gilles Peskineeccd8882020-03-10 12:19:08 +01001273 MBEDTLS_KEY_EXCHANGE_WITH_CERT_ENABLED */
Manuel Pégourié-Gonnardcd4fcc62015-05-26 12:11:48 +02001274
1275/**
1276 * \brief Free referenced items in an SSL transform context and clear
1277 * memory
1278 *
1279 * \param transform SSL transform context
1280 */
Gilles Peskine449bd832023-01-11 14:50:10 +01001281void mbedtls_ssl_transform_free(mbedtls_ssl_transform *transform);
Manuel Pégourié-Gonnardcd4fcc62015-05-26 12:11:48 +02001282
1283/**
1284 * \brief Free referenced items in an SSL handshake context and clear
1285 * memory
1286 *
Gilles Peskine9b562d52018-04-25 20:32:43 +02001287 * \param ssl SSL context
Manuel Pégourié-Gonnardcd4fcc62015-05-26 12:11:48 +02001288 */
Gilles Peskine449bd832023-01-11 14:50:10 +01001289void mbedtls_ssl_handshake_free(mbedtls_ssl_context *ssl);
Manuel Pégourié-Gonnardcd4fcc62015-05-26 12:11:48 +02001290
Jerry Yuc7875b52021-09-05 21:05:50 +08001291/* set inbound transform of ssl context */
Gilles Peskine449bd832023-01-11 14:50:10 +01001292void mbedtls_ssl_set_inbound_transform(mbedtls_ssl_context *ssl,
1293 mbedtls_ssl_transform *transform);
Jerry Yuc7875b52021-09-05 21:05:50 +08001294
1295/* set outbound transform of ssl context */
Gilles Peskine449bd832023-01-11 14:50:10 +01001296void mbedtls_ssl_set_outbound_transform(mbedtls_ssl_context *ssl,
1297 mbedtls_ssl_transform *transform);
Jerry Yuc7875b52021-09-05 21:05:50 +08001298
Manuel Pégourié-Gonnarda82a8b92022-06-17 10:53:58 +02001299MBEDTLS_CHECK_RETURN_CRITICAL
Gilles Peskine449bd832023-01-11 14:50:10 +01001300int mbedtls_ssl_handshake_client_step(mbedtls_ssl_context *ssl);
Manuel Pégourié-Gonnarda82a8b92022-06-17 10:53:58 +02001301MBEDTLS_CHECK_RETURN_CRITICAL
Gilles Peskine449bd832023-01-11 14:50:10 +01001302int mbedtls_ssl_handshake_server_step(mbedtls_ssl_context *ssl);
1303void mbedtls_ssl_handshake_wrapup(mbedtls_ssl_context *ssl);
Gilles Peskinef670ba52025-03-07 15:09:32 +01001304
Gilles Peskinec67befe2025-03-07 20:45:29 +01001305#if defined(MBEDTLS_DEBUG_C)
1306/* Declared in "ssl_debug_helpers.h". We can't include this file from
1307 * "ssl_misc.h" because it includes "ssl_misc.h" because it needs some
1308 * type definitions. TODO: split the type definitions and the helper
1309 * functions into different headers.
1310 */
1311const char *mbedtls_ssl_states_str(mbedtls_ssl_states state);
1312#endif
1313
Gilles Peskine449bd832023-01-11 14:50:10 +01001314static inline void mbedtls_ssl_handshake_set_state(mbedtls_ssl_context *ssl,
1315 mbedtls_ssl_states state)
Ronald Cron8f6d39a2022-03-10 18:56:50 +01001316{
Gilles Peskinec67befe2025-03-07 20:45:29 +01001317 MBEDTLS_SSL_DEBUG_MSG(3, ("handshake state: %d (%s) -> %d (%s)",
1318 ssl->state, mbedtls_ssl_states_str(ssl->state),
Gilles Peskinebc694b32025-03-07 22:28:23 +01001319 (int) state, mbedtls_ssl_states_str(state)));
Gilles Peskine449bd832023-01-11 14:50:10 +01001320 ssl->state = (int) state;
Ronald Cron8f6d39a2022-03-10 18:56:50 +01001321}
Manuel Pégourié-Gonnard5e94dde2015-05-26 11:57:05 +02001322
Gilles Peskinef670ba52025-03-07 15:09:32 +01001323static inline void mbedtls_ssl_handshake_increment_state(mbedtls_ssl_context *ssl)
1324{
1325 mbedtls_ssl_handshake_set_state(ssl, ssl->state + 1);
1326}
1327
Manuel Pégourié-Gonnarda82a8b92022-06-17 10:53:58 +02001328MBEDTLS_CHECK_RETURN_CRITICAL
Gilles Peskine449bd832023-01-11 14:50:10 +01001329int mbedtls_ssl_send_fatal_handshake_failure(mbedtls_ssl_context *ssl);
Manuel Pégourié-Gonnard5e94dde2015-05-26 11:57:05 +02001330
Manuel Pégourié-Gonnardb8b07aa2023-02-06 00:34:21 +01001331MBEDTLS_CHECK_RETURN_CRITICAL
Manuel Pégourié-Gonnard226aa152023-02-05 09:46:59 +01001332int mbedtls_ssl_reset_checksum(mbedtls_ssl_context *ssl);
Jerry Yubef175d2022-01-28 10:52:05 +08001333
1334#if defined(MBEDTLS_SSL_PROTO_TLS1_2)
Manuel Pégourié-Gonnarda82a8b92022-06-17 10:53:58 +02001335MBEDTLS_CHECK_RETURN_CRITICAL
Gilles Peskine449bd832023-01-11 14:50:10 +01001336int mbedtls_ssl_derive_keys(mbedtls_ssl_context *ssl);
Jerry Yubef175d2022-01-28 10:52:05 +08001337#endif /* MBEDTLS_SSL_PROTO_TLS1_2 */
Manuel Pégourié-Gonnard5e94dde2015-05-26 11:57:05 +02001338
Manuel Pégourié-Gonnarda82a8b92022-06-17 10:53:58 +02001339MBEDTLS_CHECK_RETURN_CRITICAL
Gilles Peskine449bd832023-01-11 14:50:10 +01001340int mbedtls_ssl_handle_message_type(mbedtls_ssl_context *ssl);
Manuel Pégourié-Gonnarda82a8b92022-06-17 10:53:58 +02001341MBEDTLS_CHECK_RETURN_CRITICAL
Gilles Peskine449bd832023-01-11 14:50:10 +01001342int mbedtls_ssl_prepare_handshake_record(mbedtls_ssl_context *ssl);
Manuel Pégourié-Gonnardb8b07aa2023-02-06 00:34:21 +01001343MBEDTLS_CHECK_RETURN_CRITICAL
1344int mbedtls_ssl_update_handshake_status(mbedtls_ssl_context *ssl);
Simon Butcher99000142016-10-13 17:21:01 +01001345
Hanno Becker4a810fb2017-05-24 16:27:30 +01001346/**
1347 * \brief Update record layer
1348 *
1349 * This function roughly separates the implementation
1350 * of the logic of (D)TLS from the implementation
1351 * of the secure transport.
1352 *
Hanno Becker3a0aad12018-08-20 09:44:02 +01001353 * \param ssl The SSL context to use.
1354 * \param update_hs_digest This indicates if the handshake digest
1355 * should be automatically updated in case
1356 * a handshake message is found.
Hanno Becker4a810fb2017-05-24 16:27:30 +01001357 *
1358 * \return 0 or non-zero error code.
1359 *
1360 * \note A clarification on what is called 'record layer' here
1361 * is in order, as many sensible definitions are possible:
1362 *
1363 * The record layer takes as input an untrusted underlying
1364 * transport (stream or datagram) and transforms it into
1365 * a serially multiplexed, secure transport, which
1366 * conceptually provides the following:
1367 *
1368 * (1) Three datagram based, content-agnostic transports
1369 * for handshake, alert and CCS messages.
1370 * (2) One stream- or datagram-based transport
1371 * for application data.
1372 * (3) Functionality for changing the underlying transform
1373 * securing the contents.
1374 *
1375 * The interface to this functionality is given as follows:
1376 *
1377 * a Updating
1378 * [Currently implemented by mbedtls_ssl_read_record]
1379 *
1380 * Check if and on which of the four 'ports' data is pending:
1381 * Nothing, a controlling datagram of type (1), or application
1382 * data (2). In any case data is present, internal buffers
1383 * provide access to the data for the user to process it.
1384 * Consumption of type (1) datagrams is done automatically
1385 * on the next update, invalidating that the internal buffers
1386 * for previous datagrams, while consumption of application
1387 * data (2) is user-controlled.
1388 *
1389 * b Reading of application data
1390 * [Currently manual adaption of ssl->in_offt pointer]
1391 *
1392 * As mentioned in the last paragraph, consumption of data
1393 * is different from the automatic consumption of control
1394 * datagrams (1) because application data is treated as a stream.
1395 *
1396 * c Tracking availability of application data
1397 * [Currently manually through decreasing ssl->in_msglen]
1398 *
1399 * For efficiency and to retain datagram semantics for
1400 * application data in case of DTLS, the record layer
1401 * provides functionality for checking how much application
1402 * data is still available in the internal buffer.
1403 *
1404 * d Changing the transformation securing the communication.
1405 *
1406 * Given an opaque implementation of the record layer in the
1407 * above sense, it should be possible to implement the logic
1408 * of (D)TLS on top of it without the need to know anything
1409 * about the record layer's internals. This is done e.g.
1410 * in all the handshake handling functions, and in the
1411 * application data reading function mbedtls_ssl_read.
1412 *
1413 * \note The above tries to give a conceptual picture of the
1414 * record layer, but the current implementation deviates
1415 * from it in some places. For example, our implementation of
1416 * the update functionality through mbedtls_ssl_read_record
1417 * discards datagrams depending on the current state, which
1418 * wouldn't fall under the record layer's responsibility
1419 * following the above definition.
1420 *
1421 */
Manuel Pégourié-Gonnarda82a8b92022-06-17 10:53:58 +02001422MBEDTLS_CHECK_RETURN_CRITICAL
Gilles Peskine449bd832023-01-11 14:50:10 +01001423int mbedtls_ssl_read_record(mbedtls_ssl_context *ssl,
1424 unsigned update_hs_digest);
Manuel Pégourié-Gonnarda82a8b92022-06-17 10:53:58 +02001425MBEDTLS_CHECK_RETURN_CRITICAL
Gilles Peskine449bd832023-01-11 14:50:10 +01001426int mbedtls_ssl_fetch_input(mbedtls_ssl_context *ssl, size_t nb_want);
Manuel Pégourié-Gonnard5e94dde2015-05-26 11:57:05 +02001427
Ronald Cron8f6d39a2022-03-10 18:56:50 +01001428/*
1429 * Write handshake message header
1430 */
Manuel Pégourié-Gonnarda82a8b92022-06-17 10:53:58 +02001431MBEDTLS_CHECK_RETURN_CRITICAL
Dave Rodgmanc37ad442023-11-03 23:36:06 +00001432int mbedtls_ssl_start_handshake_msg(mbedtls_ssl_context *ssl, unsigned char hs_type,
Gilles Peskine449bd832023-01-11 14:50:10 +01001433 unsigned char **buf, size_t *buf_len);
Ronald Cron8f6d39a2022-03-10 18:56:50 +01001434
Manuel Pégourié-Gonnarda82a8b92022-06-17 10:53:58 +02001435MBEDTLS_CHECK_RETURN_CRITICAL
Gilles Peskine449bd832023-01-11 14:50:10 +01001436int mbedtls_ssl_write_handshake_msg_ext(mbedtls_ssl_context *ssl,
1437 int update_checksum,
1438 int force_flush);
1439static inline int mbedtls_ssl_write_handshake_msg(mbedtls_ssl_context *ssl)
Hanno Beckerf3cce8b2021-08-07 14:29:49 +01001440{
Gilles Peskine449bd832023-01-11 14:50:10 +01001441 return mbedtls_ssl_write_handshake_msg_ext(ssl, 1 /* update checksum */, 1 /* force flush */);
Hanno Beckerf3cce8b2021-08-07 14:29:49 +01001442}
1443
Ronald Cron8f6d39a2022-03-10 18:56:50 +01001444/*
1445 * Write handshake message tail
1446 */
Manuel Pégourié-Gonnarda82a8b92022-06-17 10:53:58 +02001447MBEDTLS_CHECK_RETURN_CRITICAL
Gilles Peskine449bd832023-01-11 14:50:10 +01001448int mbedtls_ssl_finish_handshake_msg(mbedtls_ssl_context *ssl,
1449 size_t buf_len, size_t msg_len);
Ronald Cron8f6d39a2022-03-10 18:56:50 +01001450
Manuel Pégourié-Gonnarda82a8b92022-06-17 10:53:58 +02001451MBEDTLS_CHECK_RETURN_CRITICAL
Gilles Peskine449bd832023-01-11 14:50:10 +01001452int mbedtls_ssl_write_record(mbedtls_ssl_context *ssl, int force_flush);
Manuel Pégourié-Gonnarda82a8b92022-06-17 10:53:58 +02001453MBEDTLS_CHECK_RETURN_CRITICAL
Gilles Peskine449bd832023-01-11 14:50:10 +01001454int mbedtls_ssl_flush_output(mbedtls_ssl_context *ssl);
Manuel Pégourié-Gonnard5e94dde2015-05-26 11:57:05 +02001455
Manuel Pégourié-Gonnarda82a8b92022-06-17 10:53:58 +02001456MBEDTLS_CHECK_RETURN_CRITICAL
Gilles Peskine449bd832023-01-11 14:50:10 +01001457int mbedtls_ssl_parse_certificate(mbedtls_ssl_context *ssl);
Manuel Pégourié-Gonnarda82a8b92022-06-17 10:53:58 +02001458MBEDTLS_CHECK_RETURN_CRITICAL
Gilles Peskine449bd832023-01-11 14:50:10 +01001459int mbedtls_ssl_write_certificate(mbedtls_ssl_context *ssl);
Manuel Pégourié-Gonnard5e94dde2015-05-26 11:57:05 +02001460
Manuel Pégourié-Gonnarda82a8b92022-06-17 10:53:58 +02001461MBEDTLS_CHECK_RETURN_CRITICAL
Gilles Peskine449bd832023-01-11 14:50:10 +01001462int mbedtls_ssl_parse_change_cipher_spec(mbedtls_ssl_context *ssl);
Manuel Pégourié-Gonnarda82a8b92022-06-17 10:53:58 +02001463MBEDTLS_CHECK_RETURN_CRITICAL
Gilles Peskine449bd832023-01-11 14:50:10 +01001464int mbedtls_ssl_write_change_cipher_spec(mbedtls_ssl_context *ssl);
Manuel Pégourié-Gonnard5e94dde2015-05-26 11:57:05 +02001465
Manuel Pégourié-Gonnarda82a8b92022-06-17 10:53:58 +02001466MBEDTLS_CHECK_RETURN_CRITICAL
Gilles Peskine449bd832023-01-11 14:50:10 +01001467int mbedtls_ssl_parse_finished(mbedtls_ssl_context *ssl);
Manuel Pégourié-Gonnarda82a8b92022-06-17 10:53:58 +02001468MBEDTLS_CHECK_RETURN_CRITICAL
Gilles Peskine449bd832023-01-11 14:50:10 +01001469int mbedtls_ssl_write_finished(mbedtls_ssl_context *ssl);
Manuel Pégourié-Gonnard5e94dde2015-05-26 11:57:05 +02001470
Gilles Peskine449bd832023-01-11 14:50:10 +01001471void mbedtls_ssl_optimize_checksum(mbedtls_ssl_context *ssl,
1472 const mbedtls_ssl_ciphersuite_t *ciphersuite_info);
Manuel Pégourié-Gonnard5e94dde2015-05-26 11:57:05 +02001473
Ronald Cron8f6d39a2022-03-10 18:56:50 +01001474/*
1475 * Update checksum of handshake messages.
1476 */
Manuel Pégourié-Gonnardb8b07aa2023-02-06 00:34:21 +01001477MBEDTLS_CHECK_RETURN_CRITICAL
1478int mbedtls_ssl_add_hs_msg_to_checksum(mbedtls_ssl_context *ssl,
Manuel Pégourié-Gonnard43cc1272023-02-06 11:48:19 +01001479 unsigned hs_type,
1480 unsigned char const *msg,
1481 size_t msg_len);
Ronald Cron8f6d39a2022-03-10 18:56:50 +01001482
Manuel Pégourié-Gonnardb8b07aa2023-02-06 00:34:21 +01001483MBEDTLS_CHECK_RETURN_CRITICAL
1484int mbedtls_ssl_add_hs_hdr_to_checksum(mbedtls_ssl_context *ssl,
Manuel Pégourié-Gonnard43cc1272023-02-06 11:48:19 +01001485 unsigned hs_type,
1486 size_t total_hs_len);
XiaokangQian86981952022-07-19 09:51:50 +00001487
Ronald Cron73fe8df2022-10-05 14:31:43 +02001488#if defined(MBEDTLS_SSL_HANDSHAKE_WITH_PSK_ENABLED)
Michael Schuster43940672024-05-27 19:59:21 +02001489#if defined(MBEDTLS_SSL_CLI_C) || defined(MBEDTLS_SSL_SRV_C)
Manuel Pégourié-Gonnarda82a8b92022-06-17 10:53:58 +02001490MBEDTLS_CHECK_RETURN_CRITICAL
Gilles Peskine449bd832023-01-11 14:50:10 +01001491int mbedtls_ssl_conf_has_static_psk(mbedtls_ssl_config const *conf);
Ronald Crond491c2d2022-02-19 18:30:46 +01001492#endif
Neil Armstrong044a32c2022-05-03 10:35:56 +02001493/**
1494 * Get the first defined opaque PSK by order of precedence:
1495 * 1. handshake PSK set by \c mbedtls_ssl_set_hs_psk_opaque() in the PSK
1496 * callback
1497 * 2. static PSK configured by \c mbedtls_ssl_conf_psk_opaque()
1498 * Return an opaque PSK
1499 */
1500static inline mbedtls_svc_key_id_t mbedtls_ssl_get_opaque_psk(
Gilles Peskine449bd832023-01-11 14:50:10 +01001501 const mbedtls_ssl_context *ssl)
Neil Armstrong044a32c2022-05-03 10:35:56 +02001502{
Gilles Peskine449bd832023-01-11 14:50:10 +01001503 if (!mbedtls_svc_key_id_is_null(ssl->handshake->psk_opaque)) {
1504 return ssl->handshake->psk_opaque;
1505 }
Neil Armstrong044a32c2022-05-03 10:35:56 +02001506
Gilles Peskine449bd832023-01-11 14:50:10 +01001507 if (!mbedtls_svc_key_id_is_null(ssl->conf->psk_opaque)) {
1508 return ssl->conf->psk_opaque;
1509 }
Neil Armstrong044a32c2022-05-03 10:35:56 +02001510
Gilles Peskine449bd832023-01-11 14:50:10 +01001511 return MBEDTLS_SVC_KEY_ID_INIT;
Neil Armstrong044a32c2022-05-03 10:35:56 +02001512}
Guilhem Bryantd511ac32020-03-25 17:06:37 +00001513
Ronald Cron73fe8df2022-10-05 14:31:43 +02001514#endif /* MBEDTLS_SSL_HANDSHAKE_WITH_PSK_ENABLED */
Manuel Pégourié-Gonnard5e94dde2015-05-26 11:57:05 +02001515
1516#if defined(MBEDTLS_PK_C)
Gilles Peskine449bd832023-01-11 14:50:10 +01001517unsigned char mbedtls_ssl_sig_from_pk(mbedtls_pk_context *pk);
1518unsigned char mbedtls_ssl_sig_from_pk_alg(mbedtls_pk_type_t type);
1519mbedtls_pk_type_t mbedtls_ssl_pk_alg_from_sig(unsigned char sig);
Manuel Pégourié-Gonnard5e94dde2015-05-26 11:57:05 +02001520#endif
1521
Gilles Peskine449bd832023-01-11 14:50:10 +01001522mbedtls_md_type_t mbedtls_ssl_md_alg_from_hash(unsigned char hash);
1523unsigned char mbedtls_ssl_hash_from_md_alg(int md);
Ronald Cron4dcbca92022-03-07 10:21:40 +01001524
1525#if defined(MBEDTLS_SSL_PROTO_TLS1_2)
Manuel Pégourié-Gonnarda82a8b92022-06-17 10:53:58 +02001526MBEDTLS_CHECK_RETURN_CRITICAL
Gilles Peskine449bd832023-01-11 14:50:10 +01001527int mbedtls_ssl_set_calc_verify_md(mbedtls_ssl_context *ssl, int md);
Ronald Cron4dcbca92022-03-07 10:21:40 +01001528#endif
Manuel Pégourié-Gonnard5e94dde2015-05-26 11:57:05 +02001529
Manuel Pégourié-Gonnarda82a8b92022-06-17 10:53:58 +02001530MBEDTLS_CHECK_RETURN_CRITICAL
Gilles Peskine449bd832023-01-11 14:50:10 +01001531int mbedtls_ssl_check_curve_tls_id(const mbedtls_ssl_context *ssl, uint16_t tls_id);
Elena Uziunaite8dde3b32024-07-05 12:10:21 +01001532#if defined(PSA_WANT_KEY_TYPE_ECC_PUBLIC_KEY)
Manuel Pégourié-Gonnarda82a8b92022-06-17 10:53:58 +02001533MBEDTLS_CHECK_RETURN_CRITICAL
Gilles Peskine449bd832023-01-11 14:50:10 +01001534int mbedtls_ssl_check_curve(const mbedtls_ssl_context *ssl, mbedtls_ecp_group_id grp_id);
Elena Uziunaite8dde3b32024-07-05 12:10:21 +01001535#endif /* PSA_WANT_KEY_TYPE_ECC_PUBLIC_KEY */
Manuel Pégourié-Gonnard5e94dde2015-05-26 11:57:05 +02001536
Valerio Setti18c9fed2022-12-30 17:44:24 +01001537/**
1538 * \brief Return PSA EC info for the specified TLS ID.
1539 *
1540 * \param tls_id The TLS ID to look for
Przemek Stekielda4fba62023-06-02 14:52:28 +02001541 * \param type If the TLD ID is supported, then proper \c psa_key_type_t
Valerio Setti18c9fed2022-12-30 17:44:24 +01001542 * value is returned here. Can be NULL.
1543 * \param bits If the TLD ID is supported, then proper bit size is returned
1544 * here. Can be NULL.
1545 * \return PSA_SUCCESS if the TLS ID is supported,
1546 * PSA_ERROR_NOT_SUPPORTED otherwise
1547 *
1548 * \note If either \c family or \c bits parameters are NULL, then
1549 * the corresponding value is not returned.
1550 * The function can be called with both parameters as NULL
1551 * simply to check if a specific TLS ID is supported.
1552 */
Gilles Peskine449bd832023-01-11 14:50:10 +01001553int mbedtls_ssl_get_psa_curve_info_from_tls_id(uint16_t tls_id,
Przemek Stekielda4fba62023-06-02 14:52:28 +02001554 psa_key_type_t *type,
Gilles Peskine449bd832023-01-11 14:50:10 +01001555 size_t *bits);
Valerio Setti18c9fed2022-12-30 17:44:24 +01001556
1557/**
1558 * \brief Return \c mbedtls_ecp_group_id for the specified TLS ID.
1559 *
1560 * \param tls_id The TLS ID to look for
1561 * \return Proper \c mbedtls_ecp_group_id if the TLS ID is supported,
1562 * or MBEDTLS_ECP_DP_NONE otherwise
1563 */
Gilles Peskine449bd832023-01-11 14:50:10 +01001564mbedtls_ecp_group_id mbedtls_ssl_get_ecp_group_id_from_tls_id(uint16_t tls_id);
Valerio Setti18c9fed2022-12-30 17:44:24 +01001565
1566/**
1567 * \brief Return TLS ID for the specified \c mbedtls_ecp_group_id.
1568 *
1569 * \param grp_id The \c mbedtls_ecp_group_id ID to look for
1570 * \return Proper TLS ID if the \c mbedtls_ecp_group_id is supported,
1571 * or 0 otherwise
1572 */
Gilles Peskine449bd832023-01-11 14:50:10 +01001573uint16_t mbedtls_ssl_get_tls_id_from_ecp_group_id(mbedtls_ecp_group_id grp_id);
Valerio Setti18c9fed2022-12-30 17:44:24 +01001574
Valerio Setti67419f02023-01-04 16:12:42 +01001575#if defined(MBEDTLS_DEBUG_C)
Valerio Setti18c9fed2022-12-30 17:44:24 +01001576/**
1577 * \brief Return EC's name for the specified TLS ID.
1578 *
1579 * \param tls_id The TLS ID to look for
1580 * \return A pointer to a const string with the proper name. If TLS
Valerio Setti1e868cc2023-01-09 17:30:01 +01001581 * ID is not supported, a NULL pointer is returned instead.
Valerio Setti18c9fed2022-12-30 17:44:24 +01001582 */
Gilles Peskine449bd832023-01-11 14:50:10 +01001583const char *mbedtls_ssl_get_curve_name_from_tls_id(uint16_t tls_id);
Valerio Setti67419f02023-01-04 16:12:42 +01001584#endif
Valerio Setti18c9fed2022-12-30 17:44:24 +01001585
Ron Eldor089c9fe2018-12-06 17:12:49 +02001586#if defined(MBEDTLS_SSL_DTLS_SRTP)
Johan Pascal43f94902020-09-22 12:25:52 +02001587static inline mbedtls_ssl_srtp_profile mbedtls_ssl_check_srtp_profile_value
Gilles Peskine449bd832023-01-11 14:50:10 +01001588 (const uint16_t srtp_profile_value)
Ron Eldor089c9fe2018-12-06 17:12:49 +02001589{
Gilles Peskine449bd832023-01-11 14:50:10 +01001590 switch (srtp_profile_value) {
Johan Pascal85269572020-08-25 10:01:54 +02001591 case MBEDTLS_TLS_SRTP_AES128_CM_HMAC_SHA1_80:
Johan Pascal85269572020-08-25 10:01:54 +02001592 case MBEDTLS_TLS_SRTP_AES128_CM_HMAC_SHA1_32:
Johan Pascal85269572020-08-25 10:01:54 +02001593 case MBEDTLS_TLS_SRTP_NULL_HMAC_SHA1_80:
Johan Pascal85269572020-08-25 10:01:54 +02001594 case MBEDTLS_TLS_SRTP_NULL_HMAC_SHA1_32:
Johan Pascal43f94902020-09-22 12:25:52 +02001595 return srtp_profile_value;
Ron Eldor089c9fe2018-12-06 17:12:49 +02001596 default: break;
1597 }
Gilles Peskine449bd832023-01-11 14:50:10 +01001598 return MBEDTLS_TLS_SRTP_UNSET;
Ron Eldor089c9fe2018-12-06 17:12:49 +02001599}
1600#endif
1601
Manuel Pégourié-Gonnard5e94dde2015-05-26 11:57:05 +02001602#if defined(MBEDTLS_X509_CRT_PARSE_C)
Gilles Peskine449bd832023-01-11 14:50:10 +01001603static inline mbedtls_pk_context *mbedtls_ssl_own_key(mbedtls_ssl_context *ssl)
Manuel Pégourié-Gonnard5e94dde2015-05-26 11:57:05 +02001604{
1605 mbedtls_ssl_key_cert *key_cert;
1606
Gilles Peskine449bd832023-01-11 14:50:10 +01001607 if (ssl->handshake != NULL && ssl->handshake->key_cert != NULL) {
Manuel Pégourié-Gonnard5e94dde2015-05-26 11:57:05 +02001608 key_cert = ssl->handshake->key_cert;
Gilles Peskine449bd832023-01-11 14:50:10 +01001609 } else {
Manuel Pégourié-Gonnard5e94dde2015-05-26 11:57:05 +02001610 key_cert = ssl->conf->key_cert;
Gilles Peskine449bd832023-01-11 14:50:10 +01001611 }
Manuel Pégourié-Gonnard5e94dde2015-05-26 11:57:05 +02001612
Gilles Peskine449bd832023-01-11 14:50:10 +01001613 return key_cert == NULL ? NULL : key_cert->key;
Manuel Pégourié-Gonnard5e94dde2015-05-26 11:57:05 +02001614}
1615
Gilles Peskine449bd832023-01-11 14:50:10 +01001616static inline mbedtls_x509_crt *mbedtls_ssl_own_cert(mbedtls_ssl_context *ssl)
Manuel Pégourié-Gonnard5e94dde2015-05-26 11:57:05 +02001617{
1618 mbedtls_ssl_key_cert *key_cert;
1619
Gilles Peskine449bd832023-01-11 14:50:10 +01001620 if (ssl->handshake != NULL && ssl->handshake->key_cert != NULL) {
Manuel Pégourié-Gonnard5e94dde2015-05-26 11:57:05 +02001621 key_cert = ssl->handshake->key_cert;
Gilles Peskine449bd832023-01-11 14:50:10 +01001622 } else {
Manuel Pégourié-Gonnard5e94dde2015-05-26 11:57:05 +02001623 key_cert = ssl->conf->key_cert;
Gilles Peskine449bd832023-01-11 14:50:10 +01001624 }
Manuel Pégourié-Gonnard5e94dde2015-05-26 11:57:05 +02001625
Gilles Peskine449bd832023-01-11 14:50:10 +01001626 return key_cert == NULL ? NULL : key_cert->cert;
Manuel Pégourié-Gonnard5e94dde2015-05-26 11:57:05 +02001627}
1628
1629/*
Manuel Pégourié-Gonnard19dd9f52024-08-16 11:03:42 +02001630 * Verify a certificate.
Manuel Pégourié-Gonnard5e94dde2015-05-26 11:57:05 +02001631 *
Manuel Pégourié-Gonnard19dd9f52024-08-16 11:03:42 +02001632 * [in/out] ssl: misc. things read
1633 * ssl->session_negotiate->verify_result updated
1634 * [in] authmode: one of MBEDTLS_SSL_VERIFY_{NONE,OPTIONAL,REQUIRED}
1635 * [in] chain: the certificate chain to verify (ie the peer's chain)
1636 * [in] ciphersuite_info: For TLS 1.2, this session's ciphersuite;
1637 * for TLS 1.3, may be left NULL.
1638 * [in] rs_ctx: restart context if restartable ECC is in use;
1639 * leave NULL for no restartable behaviour.
1640 *
1641 * Return:
Manuel Pégourié-Gonnard9e3e9912024-08-20 10:58:20 +02001642 * - 0 if the handshake should continue. Depending on the
Manuel Pégourié-Gonnard19dd9f52024-08-16 11:03:42 +02001643 * authmode it means:
1644 * - REQUIRED: the certificate was found to be valid, trusted & acceptable.
1645 * ssl->session_negotiate->verify_result is 0.
1646 * - OPTIONAL: the certificate may or may not be acceptable, but
1647 * ssl->session_negotiate->verify_result was updated with the result.
1648 * - NONE: the certificate wasn't even checked.
1649 * - MBEDTLS_ERR_X509_CERT_VERIFY_FAILED or MBEDTLS_ERR_SSL_BAD_CERTIFICATE if
1650 * the certificate was found to be invalid/untrusted/unacceptable and the
1651 * handshake should be aborted (can only happen with REQUIRED).
1652 * - another error code if another error happened (out-of-memory, etc.)
1653 */
1654MBEDTLS_CHECK_RETURN_CRITICAL
1655int mbedtls_ssl_verify_certificate(mbedtls_ssl_context *ssl,
1656 int authmode,
1657 mbedtls_x509_crt *chain,
1658 const mbedtls_ssl_ciphersuite_t *ciphersuite_info,
1659 void *rs_ctx);
1660
1661/*
Manuel Pégourié-Gonnard94f70222024-08-09 11:26:25 +02001662 * Check usage of a certificate wrt usage extensions:
1663 * keyUsage and extendedKeyUsage.
1664 * (Note: nSCertType is deprecated and not standard, we don't check it.)
Manuel Pégourié-Gonnard5e94dde2015-05-26 11:57:05 +02001665 *
Manuel Pégourié-Gonnard7a4aa4d2024-08-09 11:49:12 +02001666 * Note: if tls_version is 1.3, ciphersuite is ignored and can be NULL.
1667 *
Manuel Pégourié-Gonnard94f70222024-08-09 11:26:25 +02001668 * Note: recv_endpoint is the receiver's endpoint.
Manuel Pégourié-Gonnard5e94dde2015-05-26 11:57:05 +02001669 *
1670 * Return 0 if everything is OK, -1 if not.
1671 */
Manuel Pégourié-Gonnarda82a8b92022-06-17 10:53:58 +02001672MBEDTLS_CHECK_RETURN_CRITICAL
Gilles Peskine449bd832023-01-11 14:50:10 +01001673int mbedtls_ssl_check_cert_usage(const mbedtls_x509_crt *cert,
1674 const mbedtls_ssl_ciphersuite_t *ciphersuite,
Manuel Pégourié-Gonnard94f70222024-08-09 11:26:25 +02001675 int recv_endpoint,
Manuel Pégourié-Gonnard7a4aa4d2024-08-09 11:49:12 +02001676 mbedtls_ssl_protocol_version tls_version,
Gilles Peskine449bd832023-01-11 14:50:10 +01001677 uint32_t *flags);
Manuel Pégourié-Gonnard5e94dde2015-05-26 11:57:05 +02001678#endif /* MBEDTLS_X509_CRT_PARSE_C */
1679
Gilles Peskine449bd832023-01-11 14:50:10 +01001680void mbedtls_ssl_write_version(unsigned char version[2], int transport,
1681 mbedtls_ssl_protocol_version tls_version);
1682uint16_t mbedtls_ssl_read_version(const unsigned char version[2],
1683 int transport);
Manuel Pégourié-Gonnard5e94dde2015-05-26 11:57:05 +02001684
Gilles Peskine449bd832023-01-11 14:50:10 +01001685static inline size_t mbedtls_ssl_in_hdr_len(const mbedtls_ssl_context *ssl)
Manuel Pégourié-Gonnard5e94dde2015-05-26 11:57:05 +02001686{
Hanno Becker47be7682019-07-12 09:55:46 +01001687#if !defined(MBEDTLS_SSL_PROTO_DTLS)
1688 ((void) ssl);
1689#endif
1690
1691#if defined(MBEDTLS_SSL_PROTO_DTLS)
Gilles Peskine449bd832023-01-11 14:50:10 +01001692 if (ssl->conf->transport == MBEDTLS_SSL_TRANSPORT_DATAGRAM) {
1693 return 13;
1694 } else
Hanno Becker47be7682019-07-12 09:55:46 +01001695#endif /* MBEDTLS_SSL_PROTO_DTLS */
1696 {
Gilles Peskine449bd832023-01-11 14:50:10 +01001697 return 5;
Hanno Becker47be7682019-07-12 09:55:46 +01001698 }
Hanno Becker5903de42019-05-03 14:46:38 +01001699}
1700
Gilles Peskine449bd832023-01-11 14:50:10 +01001701static inline size_t mbedtls_ssl_out_hdr_len(const mbedtls_ssl_context *ssl)
Hanno Becker5903de42019-05-03 14:46:38 +01001702{
Gilles Peskine449bd832023-01-11 14:50:10 +01001703 return (size_t) (ssl->out_iv - ssl->out_hdr);
Manuel Pégourié-Gonnard5e94dde2015-05-26 11:57:05 +02001704}
1705
Gilles Peskine449bd832023-01-11 14:50:10 +01001706static inline size_t mbedtls_ssl_hs_hdr_len(const mbedtls_ssl_context *ssl)
Manuel Pégourié-Gonnard5e94dde2015-05-26 11:57:05 +02001707{
1708#if defined(MBEDTLS_SSL_PROTO_DTLS)
Gilles Peskine449bd832023-01-11 14:50:10 +01001709 if (ssl->conf->transport == MBEDTLS_SSL_TRANSPORT_DATAGRAM) {
1710 return 12;
1711 }
Manuel Pégourié-Gonnard5e94dde2015-05-26 11:57:05 +02001712#else
1713 ((void) ssl);
1714#endif
Gilles Peskine449bd832023-01-11 14:50:10 +01001715 return 4;
Manuel Pégourié-Gonnard5e94dde2015-05-26 11:57:05 +02001716}
1717
1718#if defined(MBEDTLS_SSL_PROTO_DTLS)
Gilles Peskine449bd832023-01-11 14:50:10 +01001719void mbedtls_ssl_send_flight_completed(mbedtls_ssl_context *ssl);
1720void mbedtls_ssl_recv_flight_completed(mbedtls_ssl_context *ssl);
Manuel Pégourié-Gonnarda82a8b92022-06-17 10:53:58 +02001721MBEDTLS_CHECK_RETURN_CRITICAL
Gilles Peskine449bd832023-01-11 14:50:10 +01001722int mbedtls_ssl_resend(mbedtls_ssl_context *ssl);
Manuel Pégourié-Gonnarda82a8b92022-06-17 10:53:58 +02001723MBEDTLS_CHECK_RETURN_CRITICAL
Gilles Peskine449bd832023-01-11 14:50:10 +01001724int mbedtls_ssl_flight_transmit(mbedtls_ssl_context *ssl);
Manuel Pégourié-Gonnard5e94dde2015-05-26 11:57:05 +02001725#endif
1726
1727/* Visible for testing purposes only */
1728#if defined(MBEDTLS_SSL_DTLS_ANTI_REPLAY)
Manuel Pégourié-Gonnarda82a8b92022-06-17 10:53:58 +02001729MBEDTLS_CHECK_RETURN_CRITICAL
Gilles Peskine449bd832023-01-11 14:50:10 +01001730int mbedtls_ssl_dtls_replay_check(mbedtls_ssl_context const *ssl);
1731void mbedtls_ssl_dtls_replay_update(mbedtls_ssl_context *ssl);
Manuel Pégourié-Gonnard5e94dde2015-05-26 11:57:05 +02001732#endif
1733
Manuel Pégourié-Gonnarda82a8b92022-06-17 10:53:58 +02001734MBEDTLS_CHECK_RETURN_CRITICAL
Gilles Peskine449bd832023-01-11 14:50:10 +01001735int mbedtls_ssl_session_copy(mbedtls_ssl_session *dst,
1736 const mbedtls_ssl_session *src);
Hanno Becker52055ae2019-02-06 14:30:46 +00001737
TRodziewicz0f82ec62021-05-12 17:49:18 +02001738#if defined(MBEDTLS_SSL_PROTO_TLS1_2)
Andrzej Kurek814feff2019-01-14 04:35:19 -05001739/* The hash buffer must have at least MBEDTLS_MD_MAX_SIZE bytes of length. */
Manuel Pégourié-Gonnarda82a8b92022-06-17 10:53:58 +02001740MBEDTLS_CHECK_RETURN_CRITICAL
Gilles Peskine449bd832023-01-11 14:50:10 +01001741int mbedtls_ssl_get_key_exchange_md_tls1_2(mbedtls_ssl_context *ssl,
1742 unsigned char *hash, size_t *hashlen,
1743 unsigned char *data, size_t data_len,
1744 mbedtls_md_type_t md_alg);
TRodziewicz0f82ec62021-05-12 17:49:18 +02001745#endif /* MBEDTLS_SSL_PROTO_TLS1_2 */
Andres Amaya Garcia46f5a3e2017-07-20 16:17:51 +01001746
Manuel Pégourié-Gonnard5e94dde2015-05-26 11:57:05 +02001747#ifdef __cplusplus
1748}
1749#endif
1750
Gilles Peskine449bd832023-01-11 14:50:10 +01001751void mbedtls_ssl_transform_init(mbedtls_ssl_transform *transform);
Manuel Pégourié-Gonnarda82a8b92022-06-17 10:53:58 +02001752MBEDTLS_CHECK_RETURN_CRITICAL
Gilles Peskine449bd832023-01-11 14:50:10 +01001753int mbedtls_ssl_encrypt_buf(mbedtls_ssl_context *ssl,
1754 mbedtls_ssl_transform *transform,
Ben Taylor602b2962025-03-07 15:52:50 +00001755 mbedtls_record *rec);
Manuel Pégourié-Gonnarda82a8b92022-06-17 10:53:58 +02001756MBEDTLS_CHECK_RETURN_CRITICAL
Gilles Peskine449bd832023-01-11 14:50:10 +01001757int mbedtls_ssl_decrypt_buf(mbedtls_ssl_context const *ssl,
1758 mbedtls_ssl_transform *transform,
1759 mbedtls_record *rec);
Hanno Beckera18d1322018-01-03 14:27:32 +00001760
Hanno Beckerdd772292020-02-05 10:38:31 +00001761/* Length of the "epoch" field in the record header */
Gilles Peskine449bd832023-01-11 14:50:10 +01001762static inline size_t mbedtls_ssl_ep_len(const mbedtls_ssl_context *ssl)
Hanno Beckerdd772292020-02-05 10:38:31 +00001763{
1764#if defined(MBEDTLS_SSL_PROTO_DTLS)
Gilles Peskine449bd832023-01-11 14:50:10 +01001765 if (ssl->conf->transport == MBEDTLS_SSL_TRANSPORT_DATAGRAM) {
1766 return 2;
1767 }
Hanno Beckerdd772292020-02-05 10:38:31 +00001768#else
1769 ((void) ssl);
1770#endif
Gilles Peskine449bd832023-01-11 14:50:10 +01001771 return 0;
Hanno Beckerdd772292020-02-05 10:38:31 +00001772}
1773
Hanno Becker08f09132020-02-11 15:40:07 +00001774#if defined(MBEDTLS_SSL_PROTO_DTLS)
Manuel Pégourié-Gonnarda82a8b92022-06-17 10:53:58 +02001775MBEDTLS_CHECK_RETURN_CRITICAL
Gilles Peskine449bd832023-01-11 14:50:10 +01001776int mbedtls_ssl_resend_hello_request(mbedtls_ssl_context *ssl);
Hanno Becker08f09132020-02-11 15:40:07 +00001777#endif /* MBEDTLS_SSL_PROTO_DTLS */
Hanno Becker0f57a652020-02-05 10:37:26 +00001778
Gilles Peskine449bd832023-01-11 14:50:10 +01001779void mbedtls_ssl_set_timer(mbedtls_ssl_context *ssl, uint32_t millisecs);
Manuel Pégourié-Gonnarda82a8b92022-06-17 10:53:58 +02001780MBEDTLS_CHECK_RETURN_CRITICAL
Gilles Peskine449bd832023-01-11 14:50:10 +01001781int mbedtls_ssl_check_timer(mbedtls_ssl_context *ssl);
Hanno Becker7876d122020-02-05 10:39:31 +00001782
Deomid rojer Ryabkovac2cf1f2024-03-10 02:11:03 +00001783void mbedtls_ssl_reset_in_pointers(mbedtls_ssl_context *ssl);
Deomid rojer Ryabkov3dfe75e2025-01-26 10:43:42 +02001784void mbedtls_ssl_update_in_pointers(mbedtls_ssl_context *ssl);
Deomid rojer Ryabkovac2cf1f2024-03-10 02:11:03 +00001785void mbedtls_ssl_reset_out_pointers(mbedtls_ssl_context *ssl);
Gilles Peskine449bd832023-01-11 14:50:10 +01001786void mbedtls_ssl_update_out_pointers(mbedtls_ssl_context *ssl,
1787 mbedtls_ssl_transform *transform);
Hanno Becker3e6f8ab2020-02-05 10:40:57 +00001788
Manuel Pégourié-Gonnarda82a8b92022-06-17 10:53:58 +02001789MBEDTLS_CHECK_RETURN_CRITICAL
Gilles Peskine449bd832023-01-11 14:50:10 +01001790int mbedtls_ssl_session_reset_int(mbedtls_ssl_context *ssl, int partial);
1791void mbedtls_ssl_session_reset_msg_layer(mbedtls_ssl_context *ssl,
1792 int partial);
Hanno Becker43aefe22020-02-05 10:44:56 +00001793
Jerry Yue7047812021-09-13 19:26:39 +08001794/*
Jerry Yu394ece62021-09-14 22:17:21 +08001795 * Send pending alert
Jerry Yue7047812021-09-13 19:26:39 +08001796 */
Manuel Pégourié-Gonnarda82a8b92022-06-17 10:53:58 +02001797MBEDTLS_CHECK_RETURN_CRITICAL
Gilles Peskine449bd832023-01-11 14:50:10 +01001798int mbedtls_ssl_handle_pending_alert(mbedtls_ssl_context *ssl);
Jerry Yue7047812021-09-13 19:26:39 +08001799
Jerry Yu394ece62021-09-14 22:17:21 +08001800/*
1801 * Set pending fatal alert flag.
1802 */
Gilles Peskine449bd832023-01-11 14:50:10 +01001803void mbedtls_ssl_pend_fatal_alert(mbedtls_ssl_context *ssl,
1804 unsigned char alert_type,
1805 int alert_reason);
Jerry Yu394ece62021-09-14 22:17:21 +08001806
1807/* Alias of mbedtls_ssl_pend_fatal_alert */
Gilles Peskine449bd832023-01-11 14:50:10 +01001808#define MBEDTLS_SSL_PEND_FATAL_ALERT(type, user_return_value) \
1809 mbedtls_ssl_pend_fatal_alert(ssl, type, user_return_value)
Jerry Yu394ece62021-09-14 22:17:21 +08001810
Hanno Becker7e8e6a62020-02-05 10:45:48 +00001811#if defined(MBEDTLS_SSL_DTLS_ANTI_REPLAY)
Gilles Peskine449bd832023-01-11 14:50:10 +01001812void mbedtls_ssl_dtls_replay_reset(mbedtls_ssl_context *ssl);
Hanno Becker7e8e6a62020-02-05 10:45:48 +00001813#endif
1814
Gilles Peskine449bd832023-01-11 14:50:10 +01001815void mbedtls_ssl_handshake_wrapup_free_hs_transform(mbedtls_ssl_context *ssl);
Hanno Beckerce5f5fd2020-02-05 10:47:44 +00001816
Hanno Becker08f09132020-02-11 15:40:07 +00001817#if defined(MBEDTLS_SSL_RENEGOTIATION)
Manuel Pégourié-Gonnarda82a8b92022-06-17 10:53:58 +02001818MBEDTLS_CHECK_RETURN_CRITICAL
Gilles Peskine449bd832023-01-11 14:50:10 +01001819int mbedtls_ssl_start_renegotiation(mbedtls_ssl_context *ssl);
Hanno Becker08f09132020-02-11 15:40:07 +00001820#endif /* MBEDTLS_SSL_RENEGOTIATION */
Hanno Becker89490712020-02-05 10:50:12 +00001821
Hanno Becker533ab5f2020-02-05 10:49:13 +00001822#if defined(MBEDTLS_SSL_PROTO_DTLS)
Gilles Peskine449bd832023-01-11 14:50:10 +01001823size_t mbedtls_ssl_get_current_mtu(const mbedtls_ssl_context *ssl);
1824void mbedtls_ssl_buffering_free(mbedtls_ssl_context *ssl);
1825void mbedtls_ssl_flight_free(mbedtls_ssl_flight_item *flight);
Hanno Becker533ab5f2020-02-05 10:49:13 +00001826#endif /* MBEDTLS_SSL_PROTO_DTLS */
1827
Jerry Yu60835a82021-08-04 10:13:52 +08001828/**
1829 * ssl utils functions for checking configuration.
1830 */
1831
Ronald Cron6f135e12021-12-08 16:57:54 +01001832#if defined(MBEDTLS_SSL_PROTO_TLS1_3)
Gilles Peskine449bd832023-01-11 14:50:10 +01001833static inline int mbedtls_ssl_conf_is_tls13_only(const mbedtls_ssl_config *conf)
Jerry Yu60835a82021-08-04 10:13:52 +08001834{
Gilles Peskine449bd832023-01-11 14:50:10 +01001835 return conf->min_tls_version == MBEDTLS_SSL_VERSION_TLS1_3 &&
1836 conf->max_tls_version == MBEDTLS_SSL_VERSION_TLS1_3;
Jerry Yu60835a82021-08-04 10:13:52 +08001837}
Jerry Yu3ad14ac2022-01-11 17:13:16 +08001838
Ronald Cron6f135e12021-12-08 16:57:54 +01001839#endif /* MBEDTLS_SSL_PROTO_TLS1_3 */
Jerry Yu60835a82021-08-04 10:13:52 +08001840
1841#if defined(MBEDTLS_SSL_PROTO_TLS1_2)
Gilles Peskine449bd832023-01-11 14:50:10 +01001842static inline int mbedtls_ssl_conf_is_tls12_only(const mbedtls_ssl_config *conf)
Jerry Yu60835a82021-08-04 10:13:52 +08001843{
Gilles Peskine449bd832023-01-11 14:50:10 +01001844 return conf->min_tls_version == MBEDTLS_SSL_VERSION_TLS1_2 &&
1845 conf->max_tls_version == MBEDTLS_SSL_VERSION_TLS1_2;
Jerry Yu60835a82021-08-04 10:13:52 +08001846}
Jerry Yu3ad14ac2022-01-11 17:13:16 +08001847
Jerry Yu60835a82021-08-04 10:13:52 +08001848#endif /* MBEDTLS_SSL_PROTO_TLS1_2 */
1849
Gilles Peskine449bd832023-01-11 14:50:10 +01001850static inline int mbedtls_ssl_conf_is_tls13_enabled(const mbedtls_ssl_config *conf)
Jerry Yu3ad14ac2022-01-11 17:13:16 +08001851{
1852#if defined(MBEDTLS_SSL_PROTO_TLS1_3)
Gilles Peskine449bd832023-01-11 14:50:10 +01001853 return conf->min_tls_version <= MBEDTLS_SSL_VERSION_TLS1_3 &&
1854 conf->max_tls_version >= MBEDTLS_SSL_VERSION_TLS1_3;
Jerry Yu3ad14ac2022-01-11 17:13:16 +08001855#else
1856 ((void) conf);
Gilles Peskine449bd832023-01-11 14:50:10 +01001857 return 0;
Jerry Yu3ad14ac2022-01-11 17:13:16 +08001858#endif
1859}
1860
Gilles Peskine449bd832023-01-11 14:50:10 +01001861static inline int mbedtls_ssl_conf_is_tls12_enabled(const mbedtls_ssl_config *conf)
Jerry Yu3ad14ac2022-01-11 17:13:16 +08001862{
1863#if defined(MBEDTLS_SSL_PROTO_TLS1_2)
Gilles Peskine449bd832023-01-11 14:50:10 +01001864 return conf->min_tls_version <= MBEDTLS_SSL_VERSION_TLS1_2 &&
1865 conf->max_tls_version >= MBEDTLS_SSL_VERSION_TLS1_2;
Jerry Yu3ad14ac2022-01-11 17:13:16 +08001866#else
1867 ((void) conf);
Gilles Peskine449bd832023-01-11 14:50:10 +01001868 return 0;
Jerry Yu3ad14ac2022-01-11 17:13:16 +08001869#endif
1870}
1871
Ronald Cron6f135e12021-12-08 16:57:54 +01001872#if defined(MBEDTLS_SSL_PROTO_TLS1_2) && defined(MBEDTLS_SSL_PROTO_TLS1_3)
Gilles Peskine449bd832023-01-11 14:50:10 +01001873static inline int mbedtls_ssl_conf_is_hybrid_tls12_tls13(const mbedtls_ssl_config *conf)
Jerry Yu60835a82021-08-04 10:13:52 +08001874{
Gilles Peskine449bd832023-01-11 14:50:10 +01001875 return conf->min_tls_version == MBEDTLS_SSL_VERSION_TLS1_2 &&
1876 conf->max_tls_version == MBEDTLS_SSL_VERSION_TLS1_3;
Jerry Yu60835a82021-08-04 10:13:52 +08001877}
Ronald Cron6f135e12021-12-08 16:57:54 +01001878#endif /* MBEDTLS_SSL_PROTO_TLS1_2 && MBEDTLS_SSL_PROTO_TLS1_3 */
Jerry Yu60835a82021-08-04 10:13:52 +08001879
Ronald Cron6f135e12021-12-08 16:57:54 +01001880#if defined(MBEDTLS_SSL_PROTO_TLS1_3)
Jerry Yufbe3e642022-04-25 19:31:51 +08001881extern const uint8_t mbedtls_ssl_tls13_hello_retry_request_magic[
Gilles Peskine449bd832023-01-11 14:50:10 +01001882 MBEDTLS_SERVER_HELLO_RANDOM_LEN];
Manuel Pégourié-Gonnarda82a8b92022-06-17 10:53:58 +02001883MBEDTLS_CHECK_RETURN_CRITICAL
Gilles Peskine449bd832023-01-11 14:50:10 +01001884int mbedtls_ssl_tls13_process_finished_message(mbedtls_ssl_context *ssl);
Manuel Pégourié-Gonnarda82a8b92022-06-17 10:53:58 +02001885MBEDTLS_CHECK_RETURN_CRITICAL
Gilles Peskine449bd832023-01-11 14:50:10 +01001886int mbedtls_ssl_tls13_write_finished_message(mbedtls_ssl_context *ssl);
1887void mbedtls_ssl_tls13_handshake_wrapup(mbedtls_ssl_context *ssl);
Jerry Yua6e6c272021-11-17 17:54:13 +08001888
1889/**
Ronald Cron3d580bf2022-02-18 17:24:56 +01001890 * \brief Given an SSL context and its associated configuration, write the TLS
1891 * 1.3 specific extensions of the ClientHello message.
1892 *
1893 * \param[in] ssl SSL context
1894 * \param[in] buf Base address of the buffer where to write the extensions
1895 * \param[in] end End address of the buffer where to write the extensions
1896 * \param[out] out_len Length of the data written into the buffer \p buf
1897 */
Manuel Pégourié-Gonnarda82a8b92022-06-17 10:53:58 +02001898MBEDTLS_CHECK_RETURN_CRITICAL
Gilles Peskine449bd832023-01-11 14:50:10 +01001899int mbedtls_ssl_tls13_write_client_hello_exts(mbedtls_ssl_context *ssl,
1900 unsigned char *buf,
1901 unsigned char *end,
1902 size_t *out_len);
Ronald Cron3d580bf2022-02-18 17:24:56 +01001903
1904/**
Jerry Yua6e6c272021-11-17 17:54:13 +08001905 * \brief TLS 1.3 client side state machine entry
1906 *
1907 * \param ssl SSL context
1908 */
Manuel Pégourié-Gonnarda82a8b92022-06-17 10:53:58 +02001909MBEDTLS_CHECK_RETURN_CRITICAL
Gilles Peskine449bd832023-01-11 14:50:10 +01001910int mbedtls_ssl_tls13_handshake_client_step(mbedtls_ssl_context *ssl);
Jerry Yua6e6c272021-11-17 17:54:13 +08001911
1912/**
1913 * \brief TLS 1.3 server side state machine entry
1914 *
1915 * \param ssl SSL context
1916 */
Manuel Pégourié-Gonnarda82a8b92022-06-17 10:53:58 +02001917MBEDTLS_CHECK_RETURN_CRITICAL
Gilles Peskine449bd832023-01-11 14:50:10 +01001918int mbedtls_ssl_tls13_handshake_server_step(mbedtls_ssl_context *ssl);
Jerry Yua6e6c272021-11-17 17:54:13 +08001919
Jerry Yu26f4d152021-08-23 17:42:37 +08001920
1921/*
1922 * Helper functions around key exchange modes.
1923 */
Pengyu Lvfc2cb962023-11-10 10:22:36 +08001924static inline int mbedtls_ssl_conf_tls13_is_kex_mode_enabled(mbedtls_ssl_context *ssl,
1925 int kex_mode_mask)
Jerry Yu26f4d152021-08-23 17:42:37 +08001926{
Gilles Peskine449bd832023-01-11 14:50:10 +01001927 return (ssl->conf->tls13_kex_modes & kex_mode_mask) != 0;
Jerry Yu26f4d152021-08-23 17:42:37 +08001928}
1929
Pengyu Lv0a1ff2b2023-11-14 11:03:32 +08001930static inline int mbedtls_ssl_conf_tls13_is_psk_enabled(mbedtls_ssl_context *ssl)
Jerry Yu26f4d152021-08-23 17:42:37 +08001931{
Pengyu Lvfc2cb962023-11-10 10:22:36 +08001932 return mbedtls_ssl_conf_tls13_is_kex_mode_enabled(ssl,
1933 MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK);
Jerry Yu26f4d152021-08-23 17:42:37 +08001934}
1935
Pengyu Lv0a1ff2b2023-11-14 11:03:32 +08001936static inline int mbedtls_ssl_conf_tls13_is_psk_ephemeral_enabled(mbedtls_ssl_context *ssl)
Jerry Yu26f4d152021-08-23 17:42:37 +08001937{
Pengyu Lvfc2cb962023-11-10 10:22:36 +08001938 return mbedtls_ssl_conf_tls13_is_kex_mode_enabled(ssl,
1939 MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_EPHEMERAL);
Jerry Yu26f4d152021-08-23 17:42:37 +08001940}
1941
Pengyu Lv0a1ff2b2023-11-14 11:03:32 +08001942static inline int mbedtls_ssl_conf_tls13_is_ephemeral_enabled(mbedtls_ssl_context *ssl)
Jerry Yu26f4d152021-08-23 17:42:37 +08001943{
Pengyu Lvfc2cb962023-11-10 10:22:36 +08001944 return mbedtls_ssl_conf_tls13_is_kex_mode_enabled(ssl,
1945 MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_EPHEMERAL);
Jerry Yu26f4d152021-08-23 17:42:37 +08001946}
1947
Pengyu Lv0a1ff2b2023-11-14 11:03:32 +08001948static inline int mbedtls_ssl_conf_tls13_is_some_ephemeral_enabled(mbedtls_ssl_context *ssl)
Jerry Yu26f4d152021-08-23 17:42:37 +08001949{
Pengyu Lvfc2cb962023-11-10 10:22:36 +08001950 return mbedtls_ssl_conf_tls13_is_kex_mode_enabled(ssl,
1951 MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_EPHEMERAL_ALL);
Jerry Yu26f4d152021-08-23 17:42:37 +08001952}
1953
Pengyu Lv0a1ff2b2023-11-14 11:03:32 +08001954static inline int mbedtls_ssl_conf_tls13_is_some_psk_enabled(mbedtls_ssl_context *ssl)
Jerry Yu26f4d152021-08-23 17:42:37 +08001955{
Pengyu Lvfc2cb962023-11-10 10:22:36 +08001956 return mbedtls_ssl_conf_tls13_is_kex_mode_enabled(ssl,
1957 MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_ALL);
Jerry Yu26f4d152021-08-23 17:42:37 +08001958}
1959
Ronald Cron41a443a2022-10-04 16:38:25 +02001960#if defined(MBEDTLS_SSL_SRV_C) && \
1961 defined(MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_SOME_PSK_ENABLED)
Jerry Yuadf861a2021-09-29 21:22:08 +08001962/**
1963 * Given a list of key exchange modes, check if at least one of them is
Pengyu Lv2333b822023-11-14 12:03:49 +08001964 * supported by peer.
Jerry Yuadf861a2021-09-29 21:22:08 +08001965 *
1966 * \param[in] ssl SSL context
Jerry Yu0cabad32021-09-30 09:52:35 +08001967 * \param kex_modes_mask Mask of the key exchange modes to check
Jerry Yuadf861a2021-09-29 21:22:08 +08001968 *
Pengyu Lvabd844f2023-12-05 15:28:58 +08001969 * \return Non-zero if at least one of the key exchange modes is supported by
1970 * the peer, otherwise \c 0.
Jerry Yuadf861a2021-09-29 21:22:08 +08001971 */
Pengyu Lv2333b822023-11-14 12:03:49 +08001972static inline int mbedtls_ssl_tls13_is_kex_mode_supported(mbedtls_ssl_context *ssl,
1973 int kex_modes_mask)
Jerry Yu1b7c4a42021-09-09 17:09:12 +08001974{
Pengyu Lv2333b822023-11-14 12:03:49 +08001975 return (ssl->handshake->tls13_kex_modes & kex_modes_mask) != 0;
Jerry Yu1b7c4a42021-09-09 17:09:12 +08001976}
1977
Pengyu Lvb2cfafb2023-11-14 13:56:13 +08001978static inline int mbedtls_ssl_tls13_is_psk_supported(mbedtls_ssl_context *ssl)
Jerry Yu1b7c4a42021-09-09 17:09:12 +08001979{
Pengyu Lv2333b822023-11-14 12:03:49 +08001980 return mbedtls_ssl_tls13_is_kex_mode_supported(ssl,
1981 MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK);
Jerry Yu1b7c4a42021-09-09 17:09:12 +08001982}
1983
Pengyu Lvb2cfafb2023-11-14 13:56:13 +08001984static inline int mbedtls_ssl_tls13_is_psk_ephemeral_supported(
Gilles Peskine449bd832023-01-11 14:50:10 +01001985 mbedtls_ssl_context *ssl)
Jerry Yu1b7c4a42021-09-09 17:09:12 +08001986{
Pengyu Lv2333b822023-11-14 12:03:49 +08001987 return mbedtls_ssl_tls13_is_kex_mode_supported(ssl,
1988 MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_EPHEMERAL);
Jerry Yu1b7c4a42021-09-09 17:09:12 +08001989}
1990
Pengyu Lvb2cfafb2023-11-14 13:56:13 +08001991static inline int mbedtls_ssl_tls13_is_ephemeral_supported(mbedtls_ssl_context *ssl)
Jerry Yu1b7c4a42021-09-09 17:09:12 +08001992{
Pengyu Lv2333b822023-11-14 12:03:49 +08001993 return mbedtls_ssl_tls13_is_kex_mode_supported(ssl,
1994 MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_EPHEMERAL);
Jerry Yu1b7c4a42021-09-09 17:09:12 +08001995}
1996
Pengyu Lvb2cfafb2023-11-14 13:56:13 +08001997static inline int mbedtls_ssl_tls13_is_some_ephemeral_supported(mbedtls_ssl_context *ssl)
Jerry Yu1b7c4a42021-09-09 17:09:12 +08001998{
Pengyu Lv2333b822023-11-14 12:03:49 +08001999 return mbedtls_ssl_tls13_is_kex_mode_supported(ssl,
2000 MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_EPHEMERAL_ALL);
Jerry Yu1b7c4a42021-09-09 17:09:12 +08002001}
2002
Pengyu Lvb2cfafb2023-11-14 13:56:13 +08002003static inline int mbedtls_ssl_tls13_is_some_psk_supported(mbedtls_ssl_context *ssl)
Jerry Yu1b7c4a42021-09-09 17:09:12 +08002004{
Pengyu Lv2333b822023-11-14 12:03:49 +08002005 return mbedtls_ssl_tls13_is_kex_mode_supported(ssl,
2006 MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_ALL);
Jerry Yu1b7c4a42021-09-09 17:09:12 +08002007}
Ronald Cron41a443a2022-10-04 16:38:25 +02002008#endif /* MBEDTLS_SSL_SRV_C &&
2009 MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_SOME_PSK_ENABLED */
Jerry Yu1b7c4a42021-09-09 17:09:12 +08002010
Jerry Yu5cc8f0a2021-08-27 17:21:44 +08002011/*
Jerry Yuea52ed92022-11-08 21:01:17 +08002012 * Helper functions for extensions checking.
Jerry Yue18dc7e2022-08-04 16:29:22 +08002013 */
Jerry Yue18dc7e2022-08-04 16:29:22 +08002014
Jerry Yu0c354a22022-08-29 15:25:36 +08002015MBEDTLS_CHECK_RETURN_CRITICAL
Jerry Yuc4bf5d62022-10-29 09:08:47 +08002016int mbedtls_ssl_tls13_check_received_extension(
Gilles Peskine449bd832023-01-11 14:50:10 +01002017 mbedtls_ssl_context *ssl,
2018 int hs_msg_type,
2019 unsigned int received_extension_type,
2020 uint32_t hs_msg_allowed_extensions_mask);
Jerry Yu0c354a22022-08-29 15:25:36 +08002021
Jerry Yuc4bf5d62022-10-29 09:08:47 +08002022static inline void mbedtls_ssl_tls13_set_hs_sent_ext_mask(
Gilles Peskine449bd832023-01-11 14:50:10 +01002023 mbedtls_ssl_context *ssl, unsigned int extension_type)
Jerry Yu0c354a22022-08-29 15:25:36 +08002024{
2025 ssl->handshake->sent_extensions |=
Gilles Peskine449bd832023-01-11 14:50:10 +01002026 mbedtls_ssl_get_extension_mask(extension_type);
Jerry Yu0c354a22022-08-29 15:25:36 +08002027}
Jerry Yue18dc7e2022-08-04 16:29:22 +08002028
2029/*
Ronald Cron85385492022-07-20 16:44:00 +02002030 * Helper functions to check the selected key exchange mode.
2031 */
2032static inline int mbedtls_ssl_tls13_key_exchange_mode_check(
Gilles Peskine449bd832023-01-11 14:50:10 +01002033 mbedtls_ssl_context *ssl, int kex_mask)
Ronald Cron85385492022-07-20 16:44:00 +02002034{
Gilles Peskine449bd832023-01-11 14:50:10 +01002035 return (ssl->handshake->key_exchange_mode & kex_mask) != 0;
Ronald Cron85385492022-07-20 16:44:00 +02002036}
2037
2038static inline int mbedtls_ssl_tls13_key_exchange_mode_with_psk(
Gilles Peskine449bd832023-01-11 14:50:10 +01002039 mbedtls_ssl_context *ssl)
Ronald Cron85385492022-07-20 16:44:00 +02002040{
Gilles Peskine449bd832023-01-11 14:50:10 +01002041 return mbedtls_ssl_tls13_key_exchange_mode_check(ssl,
2042 MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_ALL);
Ronald Cron85385492022-07-20 16:44:00 +02002043}
2044
2045static inline int mbedtls_ssl_tls13_key_exchange_mode_with_ephemeral(
Gilles Peskine449bd832023-01-11 14:50:10 +01002046 mbedtls_ssl_context *ssl)
Ronald Cron85385492022-07-20 16:44:00 +02002047{
Gilles Peskine449bd832023-01-11 14:50:10 +01002048 return mbedtls_ssl_tls13_key_exchange_mode_check(ssl,
2049 MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_EPHEMERAL_ALL);
Ronald Cron85385492022-07-20 16:44:00 +02002050}
2051
2052/*
XiaokangQian6b226b02021-09-24 07:51:16 +00002053 * Fetch TLS 1.3 handshake message header
2054 */
Manuel Pégourié-Gonnarda82a8b92022-06-17 10:53:58 +02002055MBEDTLS_CHECK_RETURN_CRITICAL
Gilles Peskine449bd832023-01-11 14:50:10 +01002056int mbedtls_ssl_tls13_fetch_handshake_msg(mbedtls_ssl_context *ssl,
2057 unsigned hs_type,
2058 unsigned char **buf,
2059 size_t *buf_len);
XiaokangQian6b226b02021-09-24 07:51:16 +00002060
Ronald Cron47dce632023-02-08 17:38:29 +01002061/**
2062 * \brief Detect if a list of extensions contains a supported_versions
2063 * extension or not.
2064 *
2065 * \param[in] ssl SSL context
2066 * \param[in] buf Address of the first byte of the extensions vector.
2067 * \param[in] end End of the buffer containing the list of extensions.
Ronald Croneff56732023-04-03 17:36:31 +02002068 * \param[out] supported_versions_data If the extension is present, address of
2069 * its first byte of data, NULL otherwise.
2070 * \param[out] supported_versions_data_end If the extension is present, address
2071 * of the first byte immediately
2072 * following the extension data, NULL
2073 * otherwise.
Ronald Cron47dce632023-02-08 17:38:29 +01002074 * \return 0 if the list of extensions does not contain a supported_versions
2075 * extension.
2076 * \return 1 if the list of extensions contains a supported_versions
2077 * extension.
2078 * \return A negative value if an error occurred while parsing the
2079 * extensions.
2080 */
2081MBEDTLS_CHECK_RETURN_CRITICAL
2082int mbedtls_ssl_tls13_is_supported_versions_ext_present_in_exts(
2083 mbedtls_ssl_context *ssl,
2084 const unsigned char *buf, const unsigned char *end,
Ronald Croneff56732023-04-03 17:36:31 +02002085 const unsigned char **supported_versions_data,
2086 const unsigned char **supported_versions_data_end);
Ronald Cron47dce632023-02-08 17:38:29 +01002087
XiaokangQian6b226b02021-09-24 07:51:16 +00002088/*
Xiaofei Bai947571e2021-09-29 09:12:03 +00002089 * Handler of TLS 1.3 server certificate message
2090 */
Manuel Pégourié-Gonnarda82a8b92022-06-17 10:53:58 +02002091MBEDTLS_CHECK_RETURN_CRITICAL
Gilles Peskine449bd832023-01-11 14:50:10 +01002092int mbedtls_ssl_tls13_process_certificate(mbedtls_ssl_context *ssl);
Xiaofei Bai947571e2021-09-29 09:12:03 +00002093
Ronald Cron928cbd32022-10-04 16:14:26 +02002094#if defined(MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_EPHEMERAL_ENABLED)
Jerry Yu5cc8f0a2021-08-27 17:21:44 +08002095/*
Jerry Yu3e536442022-02-15 11:05:59 +08002096 * Handler of TLS 1.3 write Certificate message
Jerry Yu5cc35062022-01-28 16:16:08 +08002097 */
Manuel Pégourié-Gonnarda82a8b92022-06-17 10:53:58 +02002098MBEDTLS_CHECK_RETURN_CRITICAL
Gilles Peskine449bd832023-01-11 14:50:10 +01002099int mbedtls_ssl_tls13_write_certificate(mbedtls_ssl_context *ssl);
Jerry Yu5cc35062022-01-28 16:16:08 +08002100
2101/*
Jerry Yu3e536442022-02-15 11:05:59 +08002102 * Handler of TLS 1.3 write Certificate Verify message
Jerry Yu8511f122022-01-29 10:01:04 +08002103 */
Manuel Pégourié-Gonnarda82a8b92022-06-17 10:53:58 +02002104MBEDTLS_CHECK_RETURN_CRITICAL
Gilles Peskine449bd832023-01-11 14:50:10 +01002105int mbedtls_ssl_tls13_write_certificate_verify(mbedtls_ssl_context *ssl);
Jerry Yu90f152d2022-01-29 22:12:42 +08002106
Ronald Cron928cbd32022-10-04 16:14:26 +02002107#endif /* MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_EPHEMERAL_ENABLED */
Jerry Yu90f152d2022-01-29 22:12:42 +08002108
Jerry Yu8511f122022-01-29 10:01:04 +08002109/*
Jerry Yu30b071c2021-09-12 20:16:03 +08002110 * Generic handler of Certificate Verify
2111 */
Manuel Pégourié-Gonnarda82a8b92022-06-17 10:53:58 +02002112MBEDTLS_CHECK_RETURN_CRITICAL
Gilles Peskine449bd832023-01-11 14:50:10 +01002113int mbedtls_ssl_tls13_process_certificate_verify(mbedtls_ssl_context *ssl);
Jerry Yu30b071c2021-09-12 20:16:03 +08002114
2115/*
Ronald Cron49ad6192021-11-24 16:25:31 +01002116 * Write of dummy-CCS's for middlebox compatibility
2117 */
Manuel Pégourié-Gonnarda82a8b92022-06-17 10:53:58 +02002118MBEDTLS_CHECK_RETURN_CRITICAL
Gilles Peskine449bd832023-01-11 14:50:10 +01002119int mbedtls_ssl_tls13_write_change_cipher_spec(mbedtls_ssl_context *ssl);
Ronald Cron49ad6192021-11-24 16:25:31 +01002120
Manuel Pégourié-Gonnarda82a8b92022-06-17 10:53:58 +02002121MBEDTLS_CHECK_RETURN_CRITICAL
Gilles Peskine449bd832023-01-11 14:50:10 +01002122int mbedtls_ssl_reset_transcript_for_hrr(mbedtls_ssl_context *ssl);
XiaokangQian647719a2021-12-07 09:16:29 +00002123
Przemek Stekiel29c219c2023-05-31 15:21:04 +02002124#if defined(PSA_WANT_ALG_ECDH) || defined(PSA_WANT_ALG_FFDH)
Manuel Pégourié-Gonnarda82a8b92022-06-17 10:53:58 +02002125MBEDTLS_CHECK_RETURN_CRITICAL
Przemek Stekiel408569f2023-07-06 11:26:44 +02002126int mbedtls_ssl_tls13_generate_and_write_xxdh_key_exchange(
Gilles Peskine449bd832023-01-11 14:50:10 +01002127 mbedtls_ssl_context *ssl,
2128 uint16_t named_group,
2129 unsigned char *buf,
2130 unsigned char *end,
2131 size_t *out_len);
Przemek Stekiel29c219c2023-05-31 15:21:04 +02002132#endif /* PSA_WANT_ALG_ECDH || PSA_WANT_ALG_FFDH */
Jerry Yu89e103c2022-03-30 22:43:29 +08002133
Xiaokang Qian0e97d4d2022-10-24 11:12:51 +00002134#if defined(MBEDTLS_SSL_EARLY_DATA)
Gilles Peskine449bd832023-01-11 14:50:10 +01002135int mbedtls_ssl_tls13_write_early_data_ext(mbedtls_ssl_context *ssl,
Jerry Yuc59c5862023-12-05 10:40:49 +08002136 int in_new_session_ticket,
Gilles Peskine449bd832023-01-11 14:50:10 +01002137 unsigned char *buf,
2138 const unsigned char *end,
Jerry Yuc59c5862023-12-05 10:40:49 +08002139 size_t *out_len);
Ronald Cron85718042024-02-22 10:22:09 +01002140
2141int mbedtls_ssl_tls13_check_early_data_len(mbedtls_ssl_context *ssl,
2142 size_t early_data_len);
Ronald Cronaa359312024-03-11 17:24:39 +01002143
2144typedef enum {
2145/*
2146 * The client has not sent the first ClientHello yet, the negotiation of early
2147 * data has not started yet.
2148 */
2149 MBEDTLS_SSL_EARLY_DATA_STATE_IDLE,
2150
2151/*
2152 * In its ClientHello, the client has not included an early data indication
2153 * extension.
2154 */
2155 MBEDTLS_SSL_EARLY_DATA_STATE_NO_IND_SENT,
2156
2157/*
2158 * The client has sent an early data indication extension in its first
2159 * ClientHello, it has not received the response (ServerHello or
2160 * HelloRetryRequest) from the server yet. The transform to protect early data
Ronald Cronfd4c0c82024-03-11 17:28:44 +01002161 * is not set either as for middlebox compatibility a dummy CCS may have to be
Ronald Cronaa359312024-03-11 17:24:39 +01002162 * sent in clear. Early data cannot be sent to the server yet.
2163 */
2164 MBEDTLS_SSL_EARLY_DATA_STATE_IND_SENT,
2165
2166/*
2167 * The client has sent an early data indication extension in its first
2168 * ClientHello, it has not received the response (ServerHello or
2169 * HelloRetryRequest) from the server yet. The transform to protect early data
2170 * has been set and early data can be written now.
2171 */
2172 MBEDTLS_SSL_EARLY_DATA_STATE_CAN_WRITE,
2173
2174/*
2175 * The client has indicated the use of early data and the server has accepted
2176 * it.
2177 */
2178 MBEDTLS_SSL_EARLY_DATA_STATE_ACCEPTED,
2179
2180/*
2181 * The client has indicated the use of early data but the server has rejected
2182 * it.
2183 */
2184 MBEDTLS_SSL_EARLY_DATA_STATE_REJECTED,
2185
2186/*
2187 * The client has sent an early data indication extension in its first
2188 * ClientHello, the server has accepted them and the client has received the
2189 * server Finished message. It cannot send early data to the server anymore.
2190 */
2191 MBEDTLS_SSL_EARLY_DATA_STATE_SERVER_FINISHED_RECEIVED,
2192
2193} mbedtls_ssl_early_data_state;
Xiaokang Qian0e97d4d2022-10-24 11:12:51 +00002194#endif /* MBEDTLS_SSL_EARLY_DATA */
Jerry Yu89e103c2022-03-30 22:43:29 +08002195
Jerry Yuf017ee42022-01-12 15:49:48 +08002196#endif /* MBEDTLS_SSL_PROTO_TLS1_3 */
2197
Ronald Crone68ab4f2022-10-05 12:46:29 +02002198#if defined(MBEDTLS_SSL_HANDSHAKE_WITH_CERT_ENABLED)
Jerry Yu5cc8f0a2021-08-27 17:21:44 +08002199/*
Jerry Yuddda0502022-12-01 19:43:12 +08002200 * Write Signature Algorithm extension
2201 */
2202MBEDTLS_CHECK_RETURN_CRITICAL
Gilles Peskine449bd832023-01-11 14:50:10 +01002203int mbedtls_ssl_write_sig_alg_ext(mbedtls_ssl_context *ssl, unsigned char *buf,
2204 const unsigned char *end, size_t *out_len);
Jerry Yuddda0502022-12-01 19:43:12 +08002205/*
Gabor Mezei53a3b142022-05-10 13:20:55 +02002206 * Parse TLS Signature Algorithm extension
Xiaofei Bai69fcd392022-01-20 08:25:00 +00002207 */
Manuel Pégourié-Gonnarda82a8b92022-06-17 10:53:58 +02002208MBEDTLS_CHECK_RETURN_CRITICAL
Gilles Peskine449bd832023-01-11 14:50:10 +01002209int mbedtls_ssl_parse_sig_alg_ext(mbedtls_ssl_context *ssl,
2210 const unsigned char *buf,
2211 const unsigned char *end);
Ronald Crone68ab4f2022-10-05 12:46:29 +02002212#endif /* MBEDTLS_SSL_HANDSHAKE_WITH_CERT_ENABLED */
Jerry Yu65dd2cc2021-08-18 16:38:40 +08002213
Jerry Yu000f9762021-09-14 11:12:51 +08002214/* Get handshake transcript */
Manuel Pégourié-Gonnarda82a8b92022-06-17 10:53:58 +02002215MBEDTLS_CHECK_RETURN_CRITICAL
Gilles Peskine449bd832023-01-11 14:50:10 +01002216int mbedtls_ssl_get_handshake_transcript(mbedtls_ssl_context *ssl,
2217 const mbedtls_md_type_t md,
2218 unsigned char *dst,
2219 size_t dst_len,
2220 size_t *olen);
Jerry Yu000f9762021-09-14 11:12:51 +08002221
Brett Warrene0edc842021-08-17 09:53:13 +01002222/*
Jerry Yuba073422021-12-20 22:22:15 +08002223 * Helper functions for NamedGroup.
2224 */
Gilles Peskine449bd832023-01-11 14:50:10 +01002225static inline int mbedtls_ssl_tls12_named_group_is_ecdhe(uint16_t named_group)
Jerry Yuba073422021-12-20 22:22:15 +08002226{
2227 /*
Jerry Yu3ad14ac2022-01-11 17:13:16 +08002228 * RFC 8422 section 5.1.1
Jerry Yuba073422021-12-20 22:22:15 +08002229 */
Gilles Peskine449bd832023-01-11 14:50:10 +01002230 return named_group == MBEDTLS_SSL_IANA_TLS_GROUP_X25519 ||
2231 named_group == MBEDTLS_SSL_IANA_TLS_GROUP_BP256R1 ||
2232 named_group == MBEDTLS_SSL_IANA_TLS_GROUP_BP384R1 ||
2233 named_group == MBEDTLS_SSL_IANA_TLS_GROUP_BP512R1 ||
2234 named_group == MBEDTLS_SSL_IANA_TLS_GROUP_X448 ||
2235 /* Below deprecated curves should be removed with notice to users */
Gilles Peskine449bd832023-01-11 14:50:10 +01002236 named_group == MBEDTLS_SSL_IANA_TLS_GROUP_SECP256K1 ||
2237 named_group == MBEDTLS_SSL_IANA_TLS_GROUP_SECP256R1 ||
2238 named_group == MBEDTLS_SSL_IANA_TLS_GROUP_SECP384R1 ||
2239 named_group == MBEDTLS_SSL_IANA_TLS_GROUP_SECP521R1;
Jerry Yuba073422021-12-20 22:22:15 +08002240}
2241
Gilles Peskine449bd832023-01-11 14:50:10 +01002242static inline int mbedtls_ssl_tls13_named_group_is_ecdhe(uint16_t named_group)
Jerry Yuba073422021-12-20 22:22:15 +08002243{
Gilles Peskine449bd832023-01-11 14:50:10 +01002244 return named_group == MBEDTLS_SSL_IANA_TLS_GROUP_X25519 ||
2245 named_group == MBEDTLS_SSL_IANA_TLS_GROUP_SECP256R1 ||
2246 named_group == MBEDTLS_SSL_IANA_TLS_GROUP_SECP384R1 ||
2247 named_group == MBEDTLS_SSL_IANA_TLS_GROUP_SECP521R1 ||
2248 named_group == MBEDTLS_SSL_IANA_TLS_GROUP_X448;
Jerry Yuba073422021-12-20 22:22:15 +08002249}
2250
Przemek Stekield5f79e72023-06-29 09:08:43 +02002251static inline int mbedtls_ssl_tls13_named_group_is_ffdh(uint16_t named_group)
Jerry Yuba073422021-12-20 22:22:15 +08002252{
Gilles Peskine449bd832023-01-11 14:50:10 +01002253 return named_group >= MBEDTLS_SSL_IANA_TLS_GROUP_FFDHE2048 &&
2254 named_group <= MBEDTLS_SSL_IANA_TLS_GROUP_FFDHE8192;
Jerry Yuba073422021-12-20 22:22:15 +08002255}
2256
XiaokangQian08037552022-04-20 07:16:41 +00002257static inline int mbedtls_ssl_named_group_is_offered(
Gilles Peskine449bd832023-01-11 14:50:10 +01002258 const mbedtls_ssl_context *ssl, uint16_t named_group)
XiaokangQian08037552022-04-20 07:16:41 +00002259{
Manuel Pégourié-Gonnard6402c352025-01-14 12:23:56 +01002260 const uint16_t *group_list = ssl->conf->group_list;
XiaokangQian08037552022-04-20 07:16:41 +00002261
Gilles Peskine449bd832023-01-11 14:50:10 +01002262 if (group_list == NULL) {
2263 return 0;
XiaokangQian08037552022-04-20 07:16:41 +00002264 }
2265
Gilles Peskine449bd832023-01-11 14:50:10 +01002266 for (; *group_list != 0; group_list++) {
2267 if (*group_list == named_group) {
2268 return 1;
2269 }
2270 }
2271
2272 return 0;
XiaokangQian08037552022-04-20 07:16:41 +00002273}
2274
Gilles Peskine449bd832023-01-11 14:50:10 +01002275static inline int mbedtls_ssl_named_group_is_supported(uint16_t named_group)
XiaokangQian08037552022-04-20 07:16:41 +00002276{
Valerio Setti080a22b2023-03-20 15:22:47 +01002277#if defined(PSA_WANT_ALG_ECDH)
Gilles Peskine449bd832023-01-11 14:50:10 +01002278 if (mbedtls_ssl_tls13_named_group_is_ecdhe(named_group)) {
2279 if (mbedtls_ssl_get_ecp_group_id_from_tls_id(named_group) !=
2280 MBEDTLS_ECP_DP_NONE) {
2281 return 1;
2282 }
XiaokangQian08037552022-04-20 07:16:41 +00002283 }
Przemek Stekielcceb9332023-05-18 14:31:10 +02002284#endif
2285#if defined(PSA_WANT_ALG_FFDH)
Przemek Stekield5f79e72023-06-29 09:08:43 +02002286 if (mbedtls_ssl_tls13_named_group_is_ffdh(named_group)) {
Przemek Stekielcceb9332023-05-18 14:31:10 +02002287 return 1;
2288 }
2289#endif
2290#if !defined(PSA_WANT_ALG_ECDH) && !defined(PSA_WANT_ALG_FFDH)
2291 (void) named_group;
2292#endif
Gilles Peskine449bd832023-01-11 14:50:10 +01002293 return 0;
XiaokangQian08037552022-04-20 07:16:41 +00002294}
2295
Jerry Yuafdfed12021-12-22 10:49:02 +08002296/*
Jerry Yu713013f2022-01-17 18:16:35 +08002297 * Return supported signature algorithms.
Jerry Yuafdfed12021-12-22 10:49:02 +08002298 */
Jerry Yu713013f2022-01-17 18:16:35 +08002299static inline const void *mbedtls_ssl_get_sig_algs(
Gilles Peskine449bd832023-01-11 14:50:10 +01002300 const mbedtls_ssl_context *ssl)
Jerry Yuafdfed12021-12-22 10:49:02 +08002301{
Ronald Crone68ab4f2022-10-05 12:46:29 +02002302#if defined(MBEDTLS_SSL_HANDSHAKE_WITH_CERT_ENABLED)
Manuel Pégourié-Gonnardf7d704d2022-01-28 10:05:56 +01002303
Gilles Peskine449bd832023-01-11 14:50:10 +01002304 return ssl->conf->sig_algs;
Manuel Pégourié-Gonnardf7d704d2022-01-28 10:05:56 +01002305
Ronald Crone68ab4f2022-10-05 12:46:29 +02002306#else /* MBEDTLS_SSL_HANDSHAKE_WITH_CERT_ENABLED */
Jerry Yuafdfed12021-12-22 10:49:02 +08002307
Jerry Yu6106fdc2022-01-12 16:36:14 +08002308 ((void) ssl);
Gilles Peskine449bd832023-01-11 14:50:10 +01002309 return NULL;
Ronald Crone68ab4f2022-10-05 12:46:29 +02002310#endif /* MBEDTLS_SSL_HANDSHAKE_WITH_CERT_ENABLED */
Jerry Yuafdfed12021-12-22 10:49:02 +08002311}
Jerry Yuba073422021-12-20 22:22:15 +08002312
Ronald Cron928cbd32022-10-04 16:14:26 +02002313#if defined(MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_EPHEMERAL_ENABLED)
Gilles Peskine449bd832023-01-11 14:50:10 +01002314static inline int mbedtls_ssl_sig_alg_is_received(const mbedtls_ssl_context *ssl,
2315 uint16_t own_sig_alg)
Jerry Yu8511f122022-01-29 10:01:04 +08002316{
Jerry Yu1bb5a1f2022-01-30 10:52:11 +08002317 const uint16_t *sig_alg = ssl->handshake->received_sig_algs;
Gilles Peskine449bd832023-01-11 14:50:10 +01002318 if (sig_alg == NULL) {
2319 return 0;
Jerry Yu1bb5a1f2022-01-30 10:52:11 +08002320 }
Gilles Peskine449bd832023-01-11 14:50:10 +01002321
2322 for (; *sig_alg != MBEDTLS_TLS_SIG_NONE; sig_alg++) {
2323 if (*sig_alg == own_sig_alg) {
2324 return 1;
2325 }
2326 }
2327 return 0;
Jerry Yu8511f122022-01-29 10:01:04 +08002328}
2329
Jerry Yua1255e62022-06-24 10:10:47 +08002330static inline int mbedtls_ssl_tls13_sig_alg_for_cert_verify_is_supported(
Gilles Peskine449bd832023-01-11 14:50:10 +01002331 const uint16_t sig_alg)
Jerry Yu0ebce952022-06-16 13:54:47 +08002332{
Gilles Peskine449bd832023-01-11 14:50:10 +01002333 switch (sig_alg) {
Elena Uziunaitea6950b82024-07-30 13:55:59 +01002334#if defined(PSA_HAVE_ALG_SOME_ECDSA)
Valerio Setticf29c5d2023-09-01 09:03:41 +02002335#if defined(PSA_WANT_ALG_SHA_256) && defined(PSA_WANT_ECC_SECP_R1_256)
Jerry Yu96ee23e2022-06-21 16:34:57 +08002336 case MBEDTLS_TLS1_3_SIG_ECDSA_SECP256R1_SHA256:
2337 break;
Ronald Cronfeb5e262025-09-15 18:36:39 +02002338#endif /* PSA_WANT_ALG_SHA_256 && PSA_WANT_ECC_SECP_R1_256 */
Valerio Setticf29c5d2023-09-01 09:03:41 +02002339#if defined(PSA_WANT_ALG_SHA_384) && defined(PSA_WANT_ECC_SECP_R1_384)
Jerry Yu96ee23e2022-06-21 16:34:57 +08002340 case MBEDTLS_TLS1_3_SIG_ECDSA_SECP384R1_SHA384:
2341 break;
Ronald Cronfeb5e262025-09-15 18:36:39 +02002342#endif /* PSA_WANT_ALG_SHA_384 && PSA_WANT_ECC_SECP_R1_384 */
Valerio Setticf29c5d2023-09-01 09:03:41 +02002343#if defined(PSA_WANT_ALG_SHA_512) && defined(PSA_WANT_ECC_SECP_R1_521)
Jerry Yu96ee23e2022-06-21 16:34:57 +08002344 case MBEDTLS_TLS1_3_SIG_ECDSA_SECP521R1_SHA512:
2345 break;
Ronald Cronfeb5e262025-09-15 18:36:39 +02002346#endif /* PSA_WANT_ALG_SHA_512 && PSA_WANT_ECC_SECP_R1_521 */
Elena Uziunaitea6950b82024-07-30 13:55:59 +01002347#endif /* PSA_HAVE_ALG_SOME_ECDSA */
Jerry Yu96ee23e2022-06-21 16:34:57 +08002348
Ronald Cron8719c2f2025-07-22 11:27:39 +02002349#if defined(PSA_WANT_ALG_RSA_PSS)
Przemyslaw Stekiel004c2182022-09-14 09:09:16 +02002350#if defined(PSA_WANT_ALG_SHA_256)
Jerry Yu96ee23e2022-06-21 16:34:57 +08002351 case MBEDTLS_TLS1_3_SIG_RSA_PSS_RSAE_SHA256:
2352 break;
Przemyslaw Stekiel004c2182022-09-14 09:09:16 +02002353#endif /* PSA_WANT_ALG_SHA_256 */
2354#if defined(PSA_WANT_ALG_SHA_384)
Jerry Yu96ee23e2022-06-21 16:34:57 +08002355 case MBEDTLS_TLS1_3_SIG_RSA_PSS_RSAE_SHA384:
2356 break;
Przemyslaw Stekiel004c2182022-09-14 09:09:16 +02002357#endif /* PSA_WANT_ALG_SHA_384 */
2358#if defined(PSA_WANT_ALG_SHA_512)
Jerry Yu96ee23e2022-06-21 16:34:57 +08002359 case MBEDTLS_TLS1_3_SIG_RSA_PSS_RSAE_SHA512:
2360 break;
Przemyslaw Stekiel004c2182022-09-14 09:09:16 +02002361#endif /* PSA_WANT_ALG_SHA_512 */
Ronald Cron8719c2f2025-07-22 11:27:39 +02002362#endif /* PSA_WANT_ALG_RSA_PSS */
Jerry Yu96ee23e2022-06-21 16:34:57 +08002363 default:
Gilles Peskine449bd832023-01-11 14:50:10 +01002364 return 0;
Jerry Yu96ee23e2022-06-21 16:34:57 +08002365 }
Gilles Peskine449bd832023-01-11 14:50:10 +01002366 return 1;
Jerry Yu80dd5db2022-06-22 19:30:32 +08002367
2368}
2369
2370static inline int mbedtls_ssl_tls13_sig_alg_is_supported(
Gilles Peskine449bd832023-01-11 14:50:10 +01002371 const uint16_t sig_alg)
Jerry Yu80dd5db2022-06-22 19:30:32 +08002372{
Gilles Peskine449bd832023-01-11 14:50:10 +01002373 switch (sig_alg) {
Ronald Cron8719c2f2025-07-22 11:27:39 +02002374#if defined(PSA_WANT_ALG_RSA_PKCS1V15_SIGN)
Elena Uziunaite0916cd72024-05-23 17:01:07 +01002375#if defined(PSA_WANT_ALG_SHA_256)
Jerry Yu80dd5db2022-06-22 19:30:32 +08002376 case MBEDTLS_TLS1_3_SIG_RSA_PKCS1_SHA256:
2377 break;
Elena Uziunaite0916cd72024-05-23 17:01:07 +01002378#endif /* PSA_WANT_ALG_SHA_256 */
Elena Uziunaiteb476d4b2024-05-23 15:33:41 +01002379#if defined(PSA_WANT_ALG_SHA_384)
Jerry Yu80dd5db2022-06-22 19:30:32 +08002380 case MBEDTLS_TLS1_3_SIG_RSA_PKCS1_SHA384:
2381 break;
Elena Uziunaiteb476d4b2024-05-23 15:33:41 +01002382#endif /* PSA_WANT_ALG_SHA_384 */
Gabor Mezeic15ef932024-06-13 12:53:54 +02002383#if defined(PSA_WANT_ALG_SHA_512)
Jerry Yu80dd5db2022-06-22 19:30:32 +08002384 case MBEDTLS_TLS1_3_SIG_RSA_PKCS1_SHA512:
2385 break;
Gabor Mezeic15ef932024-06-13 12:53:54 +02002386#endif /* PSA_WANT_ALG_SHA_512 */
Ronald Cron8719c2f2025-07-22 11:27:39 +02002387#endif /* PSA_WANT_ALG_RSA_PKCS1V15_SIGN */
Jerry Yu80dd5db2022-06-22 19:30:32 +08002388 default:
Gilles Peskine449bd832023-01-11 14:50:10 +01002389 return mbedtls_ssl_tls13_sig_alg_for_cert_verify_is_supported(
2390 sig_alg);
Jerry Yu80dd5db2022-06-22 19:30:32 +08002391 }
Gilles Peskine449bd832023-01-11 14:50:10 +01002392 return 1;
Jerry Yu0ebce952022-06-16 13:54:47 +08002393}
Xiaokang Qiana3b451f2022-10-11 06:20:56 +00002394
Ronald Cron928cbd32022-10-04 16:14:26 +02002395MBEDTLS_CHECK_RETURN_CRITICAL
Gilles Peskine449bd832023-01-11 14:50:10 +01002396int mbedtls_ssl_tls13_check_sig_alg_cert_key_match(uint16_t sig_alg,
2397 mbedtls_pk_context *key);
Ronald Cron928cbd32022-10-04 16:14:26 +02002398#endif /* MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_EPHEMERAL_ENABLED */
2399
Ronald Crone68ab4f2022-10-05 12:46:29 +02002400#if defined(MBEDTLS_SSL_HANDSHAKE_WITH_CERT_ENABLED)
Gilles Peskine449bd832023-01-11 14:50:10 +01002401static inline int mbedtls_ssl_sig_alg_is_offered(const mbedtls_ssl_context *ssl,
2402 uint16_t proposed_sig_alg)
Ronald Cron928cbd32022-10-04 16:14:26 +02002403{
Gilles Peskine449bd832023-01-11 14:50:10 +01002404 const uint16_t *sig_alg = mbedtls_ssl_get_sig_algs(ssl);
2405 if (sig_alg == NULL) {
2406 return 0;
Ronald Cron928cbd32022-10-04 16:14:26 +02002407 }
Gilles Peskine449bd832023-01-11 14:50:10 +01002408
2409 for (; *sig_alg != MBEDTLS_TLS_SIG_NONE; sig_alg++) {
2410 if (*sig_alg == proposed_sig_alg) {
2411 return 1;
2412 }
2413 }
2414 return 0;
Ronald Cron928cbd32022-10-04 16:14:26 +02002415}
2416
2417static inline int mbedtls_ssl_get_pk_type_and_md_alg_from_sig_alg(
Gilles Peskine449bd832023-01-11 14:50:10 +01002418 uint16_t sig_alg, mbedtls_pk_type_t *pk_type, mbedtls_md_type_t *md_alg)
Ronald Cron928cbd32022-10-04 16:14:26 +02002419{
Gilles Peskine449bd832023-01-11 14:50:10 +01002420 *pk_type = mbedtls_ssl_pk_alg_from_sig(sig_alg & 0xff);
2421 *md_alg = mbedtls_ssl_md_alg_from_hash((sig_alg >> 8) & 0xff);
Ronald Cron928cbd32022-10-04 16:14:26 +02002422
Gilles Peskine449bd832023-01-11 14:50:10 +01002423 if (*pk_type != MBEDTLS_PK_NONE && *md_alg != MBEDTLS_MD_NONE) {
2424 return 0;
2425 }
Ronald Cron928cbd32022-10-04 16:14:26 +02002426
Gilles Peskine449bd832023-01-11 14:50:10 +01002427 switch (sig_alg) {
Ronald Cron8719c2f2025-07-22 11:27:39 +02002428#if defined(PSA_WANT_ALG_RSA_PSS)
Elena Uziunaite0916cd72024-05-23 17:01:07 +01002429#if defined(PSA_WANT_ALG_SHA_256)
Ronald Cron928cbd32022-10-04 16:14:26 +02002430 case MBEDTLS_TLS1_3_SIG_RSA_PSS_RSAE_SHA256:
2431 *md_alg = MBEDTLS_MD_SHA256;
2432 *pk_type = MBEDTLS_PK_RSASSA_PSS;
2433 break;
Elena Uziunaite0916cd72024-05-23 17:01:07 +01002434#endif /* PSA_WANT_ALG_SHA_256 */
Elena Uziunaiteb476d4b2024-05-23 15:33:41 +01002435#if defined(PSA_WANT_ALG_SHA_384)
Ronald Cron928cbd32022-10-04 16:14:26 +02002436 case MBEDTLS_TLS1_3_SIG_RSA_PSS_RSAE_SHA384:
2437 *md_alg = MBEDTLS_MD_SHA384;
2438 *pk_type = MBEDTLS_PK_RSASSA_PSS;
2439 break;
Elena Uziunaiteb476d4b2024-05-23 15:33:41 +01002440#endif /* PSA_WANT_ALG_SHA_384 */
Gabor Mezeic15ef932024-06-13 12:53:54 +02002441#if defined(PSA_WANT_ALG_SHA_512)
Ronald Cron928cbd32022-10-04 16:14:26 +02002442 case MBEDTLS_TLS1_3_SIG_RSA_PSS_RSAE_SHA512:
2443 *md_alg = MBEDTLS_MD_SHA512;
2444 *pk_type = MBEDTLS_PK_RSASSA_PSS;
2445 break;
Gabor Mezeic15ef932024-06-13 12:53:54 +02002446#endif /* PSA_WANT_ALG_SHA_512 */
Ronald Cron8719c2f2025-07-22 11:27:39 +02002447#endif /* PSA_WANT_ALG_RSA_PSS */
Gilles Peskine449bd832023-01-11 14:50:10 +01002448 default:
2449 return MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE;
2450 }
2451 return 0;
Ronald Cron928cbd32022-10-04 16:14:26 +02002452}
Jerry Yu8c338862022-03-23 13:34:04 +08002453
Jerry Yu0ebce952022-06-16 13:54:47 +08002454#if defined(MBEDTLS_SSL_PROTO_TLS1_2)
2455static inline int mbedtls_ssl_tls12_sig_alg_is_supported(
Gilles Peskine449bd832023-01-11 14:50:10 +01002456 const uint16_t sig_alg)
Jerry Yu0ebce952022-06-16 13:54:47 +08002457{
2458 /* High byte is hash */
Gilles Peskine449bd832023-01-11 14:50:10 +01002459 unsigned char hash = MBEDTLS_BYTE_1(sig_alg);
2460 unsigned char sig = MBEDTLS_BYTE_0(sig_alg);
Jerry Yu0ebce952022-06-16 13:54:47 +08002461
Gilles Peskine449bd832023-01-11 14:50:10 +01002462 switch (hash) {
Elena Uziunaiteb66a9912024-05-10 14:25:58 +01002463#if defined(PSA_WANT_ALG_MD5)
Jerry Yu0ebce952022-06-16 13:54:47 +08002464 case MBEDTLS_SSL_HASH_MD5:
2465 break;
2466#endif
2467
Elena Uziunaite9fc5be02024-09-04 18:12:59 +01002468#if defined(PSA_WANT_ALG_SHA_1)
Jerry Yu0ebce952022-06-16 13:54:47 +08002469 case MBEDTLS_SSL_HASH_SHA1:
2470 break;
2471#endif
2472
Elena Uziunaitefcc9afa2024-05-23 14:43:22 +01002473#if defined(PSA_WANT_ALG_SHA_224)
Jerry Yu0ebce952022-06-16 13:54:47 +08002474 case MBEDTLS_SSL_HASH_SHA224:
2475 break;
2476#endif
2477
Elena Uziunaite0916cd72024-05-23 17:01:07 +01002478#if defined(PSA_WANT_ALG_SHA_256)
Jerry Yu0ebce952022-06-16 13:54:47 +08002479 case MBEDTLS_SSL_HASH_SHA256:
2480 break;
2481#endif
2482
Elena Uziunaiteb476d4b2024-05-23 15:33:41 +01002483#if defined(PSA_WANT_ALG_SHA_384)
Jerry Yu0ebce952022-06-16 13:54:47 +08002484 case MBEDTLS_SSL_HASH_SHA384:
2485 break;
2486#endif
2487
Gabor Mezeic15ef932024-06-13 12:53:54 +02002488#if defined(PSA_WANT_ALG_SHA_512)
Jerry Yu0ebce952022-06-16 13:54:47 +08002489 case MBEDTLS_SSL_HASH_SHA512:
2490 break;
2491#endif
2492
2493 default:
Gilles Peskine449bd832023-01-11 14:50:10 +01002494 return 0;
Jerry Yu0ebce952022-06-16 13:54:47 +08002495 }
2496
Gilles Peskine449bd832023-01-11 14:50:10 +01002497 switch (sig) {
Jerry Yu0ebce952022-06-16 13:54:47 +08002498#if defined(MBEDTLS_RSA_C)
2499 case MBEDTLS_SSL_SIG_RSA:
2500 break;
2501#endif
2502
Valerio Settie9646ec2023-08-02 20:02:28 +02002503#if defined(MBEDTLS_KEY_EXCHANGE_ECDSA_CERT_REQ_ALLOWED_ENABLED)
Jerry Yu0ebce952022-06-16 13:54:47 +08002504 case MBEDTLS_SSL_SIG_ECDSA:
2505 break;
2506#endif
2507
Gilles Peskine449bd832023-01-11 14:50:10 +01002508 default:
2509 return 0;
Jerry Yu0ebce952022-06-16 13:54:47 +08002510 }
2511
Gilles Peskine449bd832023-01-11 14:50:10 +01002512 return 1;
Jerry Yu0ebce952022-06-16 13:54:47 +08002513}
2514#endif /* MBEDTLS_SSL_PROTO_TLS1_2 */
2515
Jerry Yu1bab3012022-01-19 17:43:22 +08002516static inline int mbedtls_ssl_sig_alg_is_supported(
Gilles Peskine449bd832023-01-11 14:50:10 +01002517 const mbedtls_ssl_context *ssl,
2518 const uint16_t sig_alg)
Jerry Yu1bab3012022-01-19 17:43:22 +08002519{
2520
2521#if defined(MBEDTLS_SSL_PROTO_TLS1_2)
Gilles Peskine449bd832023-01-11 14:50:10 +01002522 if (ssl->tls_version == MBEDTLS_SSL_VERSION_TLS1_2) {
2523 return mbedtls_ssl_tls12_sig_alg_is_supported(sig_alg);
Jerry Yu1bab3012022-01-19 17:43:22 +08002524 }
2525#endif /* MBEDTLS_SSL_PROTO_TLS1_2 */
2526
Ronald Cron928cbd32022-10-04 16:14:26 +02002527#if defined(MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_EPHEMERAL_ENABLED)
Gilles Peskine449bd832023-01-11 14:50:10 +01002528 if (ssl->tls_version == MBEDTLS_SSL_VERSION_TLS1_3) {
2529 return mbedtls_ssl_tls13_sig_alg_is_supported(sig_alg);
Jerry Yu1bab3012022-01-19 17:43:22 +08002530 }
Ronald Cron928cbd32022-10-04 16:14:26 +02002531#endif
Jerry Yu1bab3012022-01-19 17:43:22 +08002532 ((void) ssl);
2533 ((void) sig_alg);
Gilles Peskine449bd832023-01-11 14:50:10 +01002534 return 0;
Jerry Yu1bab3012022-01-19 17:43:22 +08002535}
Ronald Crone68ab4f2022-10-05 12:46:29 +02002536#endif /* MBEDTLS_SSL_HANDSHAKE_WITH_CERT_ENABLED */
Jerry Yu1bab3012022-01-19 17:43:22 +08002537
Przemyslaw Stekiele5c22382022-01-25 00:56:34 +01002538/* Corresponding PSA algorithm for MBEDTLS_CIPHER_NULL.
Andrzej Kurek5c65c572022-04-13 14:28:52 -04002539 * Same value is used for PSA_ALG_CATEGORY_CIPHER, hence it is
Przemyslaw Stekiele5c22382022-01-25 00:56:34 +01002540 * guaranteed to not be a valid PSA algorithm identifier.
2541 */
2542#define MBEDTLS_SSL_NULL_CIPHER 0x04000000
2543
2544/**
2545 * \brief Translate mbedtls cipher type/taglen pair to psa:
2546 * algorithm, key type and key size.
2547 *
2548 * \param mbedtls_cipher_type [in] given mbedtls cipher type
2549 * \param taglen [in] given tag length
2550 * 0 - default tag length
2551 * \param alg [out] corresponding PSA alg
2552 * There is no corresponding PSA
Przemyslaw Stekiel8c010eb2022-02-03 10:44:02 +01002553 * alg for MBEDTLS_CIPHER_NULL, so
2554 * in this case MBEDTLS_SSL_NULL_CIPHER
2555 * is returned via this parameter
Przemyslaw Stekiele5c22382022-01-25 00:56:34 +01002556 * \param key_type [out] corresponding PSA key type
2557 * \param key_size [out] corresponding PSA key size
2558 *
2559 * \return PSA_SUCCESS on success or PSA_ERROR_NOT_SUPPORTED if
2560 * conversion is not supported.
2561 */
Gilles Peskine449bd832023-01-11 14:50:10 +01002562psa_status_t mbedtls_ssl_cipher_to_psa(mbedtls_cipher_type_t mbedtls_cipher_type,
2563 size_t taglen,
2564 psa_algorithm_t *alg,
2565 psa_key_type_t *key_type,
2566 size_t *key_size);
Przemyslaw Stekiele5c22382022-01-25 00:56:34 +01002567
Manuel Pégourié-Gonnard615914b2025-01-22 13:03:55 +01002568#if defined(MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED)
Valerio Settifbbc1f32022-11-15 16:39:55 +01002569
Valerio Setti6b3dab02022-11-17 17:14:54 +01002570typedef enum {
2571 MBEDTLS_ECJPAKE_ROUND_ONE,
2572 MBEDTLS_ECJPAKE_ROUND_TWO
2573} mbedtls_ecjpake_rounds_t;
2574
Valerio Setti02c25b52022-11-15 14:08:42 +01002575/**
2576 * \brief Parse the provided input buffer for getting the first round
2577 * of key exchange. This code is common between server and client
2578 *
2579 * \param pake_ctx [in] the PAKE's operation/context structure
2580 * \param buf [in] input buffer to parse
2581 * \param len [in] length of the input buffer
Valerio Setti6b3dab02022-11-17 17:14:54 +01002582 * \param round [in] either MBEDTLS_ECJPAKE_ROUND_ONE or
2583 * MBEDTLS_ECJPAKE_ROUND_TWO
Valerio Setti02c25b52022-11-15 14:08:42 +01002584 *
2585 * \return 0 on success or a negative error code in case of failure
2586 */
Valerio Setti6b3dab02022-11-17 17:14:54 +01002587int mbedtls_psa_ecjpake_read_round(
Gilles Peskine449bd832023-01-11 14:50:10 +01002588 psa_pake_operation_t *pake_ctx,
2589 const unsigned char *buf,
2590 size_t len, mbedtls_ecjpake_rounds_t round);
Valerio Setti02c25b52022-11-15 14:08:42 +01002591
2592/**
2593 * \brief Write the first round of key exchange into the provided output
2594 * buffer. This code is common between server and client
2595 *
2596 * \param pake_ctx [in] the PAKE's operation/context structure
2597 * \param buf [out] the output buffer in which data will be written to
2598 * \param len [in] length of the output buffer
2599 * \param olen [out] the length of the data really written on the buffer
Valerio Setti6b3dab02022-11-17 17:14:54 +01002600 * \param round [in] either MBEDTLS_ECJPAKE_ROUND_ONE or
2601 * MBEDTLS_ECJPAKE_ROUND_TWO
Valerio Setti02c25b52022-11-15 14:08:42 +01002602 *
2603 * \return 0 on success or a negative error code in case of failure
2604 */
Valerio Setti6b3dab02022-11-17 17:14:54 +01002605int mbedtls_psa_ecjpake_write_round(
Gilles Peskine449bd832023-01-11 14:50:10 +01002606 psa_pake_operation_t *pake_ctx,
2607 unsigned char *buf,
2608 size_t len, size_t *olen,
2609 mbedtls_ecjpake_rounds_t round);
Valerio Setti02c25b52022-11-15 14:08:42 +01002610
Manuel Pégourié-Gonnard615914b2025-01-22 13:03:55 +01002611#endif /* MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED */
Valerio Setti02c25b52022-11-15 14:08:42 +01002612
Neil Armstrong8a0f3e82022-03-30 10:57:37 +02002613/**
2614 * \brief TLS record protection modes
2615 */
2616typedef enum {
2617 MBEDTLS_SSL_MODE_STREAM = 0,
2618 MBEDTLS_SSL_MODE_CBC,
2619 MBEDTLS_SSL_MODE_CBC_ETM,
2620 MBEDTLS_SSL_MODE_AEAD
2621} mbedtls_ssl_mode_t;
2622
Neil Armstrongab555e02022-04-04 11:07:59 +02002623mbedtls_ssl_mode_t mbedtls_ssl_get_mode_from_transform(
Gilles Peskine449bd832023-01-11 14:50:10 +01002624 const mbedtls_ssl_transform *transform);
Neil Armstrong8a0f3e82022-03-30 10:57:37 +02002625
Neil Armstrongf2c82f02022-04-05 11:16:53 +02002626#if defined(MBEDTLS_SSL_SOME_SUITES_USE_CBC_ETM)
Neil Armstrongab555e02022-04-04 11:07:59 +02002627mbedtls_ssl_mode_t mbedtls_ssl_get_mode_from_ciphersuite(
Gilles Peskine449bd832023-01-11 14:50:10 +01002628 int encrypt_then_mac,
2629 const mbedtls_ssl_ciphersuite_t *suite);
Neil Armstrong4bf4c862022-04-01 10:35:48 +02002630#else
Neil Armstrongab555e02022-04-04 11:07:59 +02002631mbedtls_ssl_mode_t mbedtls_ssl_get_mode_from_ciphersuite(
Gilles Peskine449bd832023-01-11 14:50:10 +01002632 const mbedtls_ssl_ciphersuite_t *suite);
Neil Armstrongf2c82f02022-04-05 11:16:53 +02002633#endif /* MBEDTLS_SSL_SOME_SUITES_USE_CBC_ETM */
Neil Armstrong4bf4c862022-04-01 10:35:48 +02002634
Przemek Stekiel63706622023-05-23 16:31:56 +02002635#if defined(PSA_WANT_ALG_ECDH) || defined(PSA_WANT_ALG_FFDH)
XiaokangQian9b5d04b2022-04-10 10:20:43 +00002636
Manuel Pégourié-Gonnarda82a8b92022-06-17 10:53:58 +02002637MBEDTLS_CHECK_RETURN_CRITICAL
Przemek Stekiel7ac93be2023-07-04 10:02:38 +02002638int mbedtls_ssl_tls13_read_public_xxdhe_share(mbedtls_ssl_context *ssl,
Gilles Peskine449bd832023-01-11 14:50:10 +01002639 const unsigned char *buf,
2640 size_t buf_len);
XiaokangQian9b5d04b2022-04-10 10:20:43 +00002641
Przemek Stekiel63706622023-05-23 16:31:56 +02002642#endif /* PSA_WANT_ALG_ECDH || PSA_WANT_ALG_FFDH */
XiaokangQian9b5d04b2022-04-10 10:20:43 +00002643
XiaokangQian0a1b54e2022-04-21 03:01:38 +00002644static inline int mbedtls_ssl_tls13_cipher_suite_is_offered(
Gilles Peskine449bd832023-01-11 14:50:10 +01002645 mbedtls_ssl_context *ssl, int cipher_suite)
XiaokangQian0a1b54e2022-04-21 03:01:38 +00002646{
2647 const int *ciphersuite_list = ssl->conf->ciphersuite_list;
2648
2649 /* Check whether we have offered this ciphersuite */
Gilles Peskine449bd832023-01-11 14:50:10 +01002650 for (size_t i = 0; ciphersuite_list[i] != 0; i++) {
2651 if (ciphersuite_list[i] == cipher_suite) {
2652 return 1;
XiaokangQian0a1b54e2022-04-21 03:01:38 +00002653 }
2654 }
Gilles Peskine449bd832023-01-11 14:50:10 +01002655 return 0;
XiaokangQian0a1b54e2022-04-21 03:01:38 +00002656}
2657
2658/**
2659 * \brief Validate cipher suite against config in SSL context.
2660 *
2661 * \param ssl SSL context
2662 * \param suite_info Cipher suite to validate
2663 * \param min_tls_version Minimal TLS version to accept a cipher suite
2664 * \param max_tls_version Maximal TLS version to accept a cipher suite
2665 *
2666 * \return 0 if valid, negative value otherwise.
2667 */
Manuel Pégourié-Gonnarda82a8b92022-06-17 10:53:58 +02002668MBEDTLS_CHECK_RETURN_CRITICAL
XiaokangQian0a1b54e2022-04-21 03:01:38 +00002669int mbedtls_ssl_validate_ciphersuite(
2670 const mbedtls_ssl_context *ssl,
2671 const mbedtls_ssl_ciphersuite_t *suite_info,
2672 mbedtls_ssl_protocol_version min_tls_version,
Gilles Peskine449bd832023-01-11 14:50:10 +01002673 mbedtls_ssl_protocol_version max_tls_version);
XiaokangQian08037552022-04-20 07:16:41 +00002674
XiaokangQian40a35232022-05-07 09:02:40 +00002675#if defined(MBEDTLS_SSL_SERVER_NAME_INDICATION)
Ronald Cronce7d76e2022-07-08 18:56:49 +02002676MBEDTLS_CHECK_RETURN_CRITICAL
Gilles Peskine449bd832023-01-11 14:50:10 +01002677int mbedtls_ssl_parse_server_name_ext(mbedtls_ssl_context *ssl,
2678 const unsigned char *buf,
2679 const unsigned char *end);
XiaokangQian40a35232022-05-07 09:02:40 +00002680#endif /* MBEDTLS_SSL_SERVER_NAME_INDICATION */
2681
Jan Bruckner151f6422023-02-10 12:45:19 +01002682#if defined(MBEDTLS_SSL_RECORD_SIZE_LIMIT)
Jan Brucknera0589e72023-03-15 11:04:45 +01002683#define MBEDTLS_SSL_RECORD_SIZE_LIMIT_EXTENSION_DATA_LENGTH (2)
Waleed Elmelegyf0ccf462024-01-12 10:52:45 +00002684#define MBEDTLS_SSL_RECORD_SIZE_LIMIT_MIN (64) /* As defined in RFC 8449 */
Jan Brucknera0589e72023-03-15 11:04:45 +01002685
Jan Bruckner151f6422023-02-10 12:45:19 +01002686MBEDTLS_CHECK_RETURN_CRITICAL
2687int mbedtls_ssl_tls13_parse_record_size_limit_ext(mbedtls_ssl_context *ssl,
2688 const unsigned char *buf,
2689 const unsigned char *end);
Yanray Wanga8b42912023-11-08 11:10:47 +08002690
2691MBEDTLS_CHECK_RETURN_CRITICAL
2692int mbedtls_ssl_tls13_write_record_size_limit_ext(mbedtls_ssl_context *ssl,
Yanray Wanga8b42912023-11-08 11:10:47 +08002693 unsigned char *buf,
2694 const unsigned char *end,
2695 size_t *out_len);
Jan Bruckner151f6422023-02-10 12:45:19 +01002696#endif /* MBEDTLS_SSL_RECORD_SIZE_LIMIT */
2697
XiaokangQianacb39922022-06-17 10:18:48 +00002698#if defined(MBEDTLS_SSL_ALPN)
Ronald Cronce7d76e2022-07-08 18:56:49 +02002699MBEDTLS_CHECK_RETURN_CRITICAL
Gilles Peskine449bd832023-01-11 14:50:10 +01002700int mbedtls_ssl_parse_alpn_ext(mbedtls_ssl_context *ssl,
2701 const unsigned char *buf,
2702 const unsigned char *end);
XiaokangQianacb39922022-06-17 10:18:48 +00002703
2704
Ronald Cronce7d76e2022-07-08 18:56:49 +02002705MBEDTLS_CHECK_RETURN_CRITICAL
Gilles Peskine449bd832023-01-11 14:50:10 +01002706int mbedtls_ssl_write_alpn_ext(mbedtls_ssl_context *ssl,
2707 unsigned char *buf,
2708 unsigned char *end,
2709 size_t *out_len);
XiaokangQianacb39922022-06-17 10:18:48 +00002710#endif /* MBEDTLS_SSL_ALPN */
2711
Andrzej Kurekcfb01942022-06-06 13:08:23 -04002712#if defined(MBEDTLS_TEST_HOOKS)
Andrzej Kurek078e9bc2022-06-08 11:47:33 -04002713int mbedtls_ssl_check_dtls_clihlo_cookie(
Gilles Peskine449bd832023-01-11 14:50:10 +01002714 mbedtls_ssl_context *ssl,
2715 const unsigned char *cli_id, size_t cli_id_len,
2716 const unsigned char *in, size_t in_len,
2717 unsigned char *obuf, size_t buf_len, size_t *olen);
Andrzej Kurekcfb01942022-06-06 13:08:23 -04002718#endif
2719
Ronald Cron41a443a2022-10-04 16:38:25 +02002720#if defined(MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_SOME_PSK_ENABLED)
XiaokangQianeb69aee2022-07-05 08:21:43 +00002721/**
2722 * \brief Given an SSL context and its associated configuration, write the TLS
2723 * 1.3 specific Pre-Shared key extension.
2724 *
2725 * \param[in] ssl SSL context
2726 * \param[in] buf Base address of the buffer where to write the extension
2727 * \param[in] end End address of the buffer where to write the extension
XiaokangQian008d2bf2022-07-14 07:54:01 +00002728 * \param[out] out_len Length in bytes of the Pre-Shared key extension: data
2729 * written into the buffer \p buf by this function plus
2730 * the length of the binders to be written.
XiaokangQianeb69aee2022-07-05 08:21:43 +00002731 * \param[out] binders_len Length of the binders to be written at the end of
XiaokangQian008d2bf2022-07-14 07:54:01 +00002732 * the extension.
XiaokangQianeb69aee2022-07-05 08:21:43 +00002733 */
XiaokangQian86981952022-07-19 09:51:50 +00002734MBEDTLS_CHECK_RETURN_CRITICAL
XiaokangQian3ad67bf2022-07-21 02:26:21 +00002735int mbedtls_ssl_tls13_write_identities_of_pre_shared_key_ext(
XiaokangQianeb69aee2022-07-05 08:21:43 +00002736 mbedtls_ssl_context *ssl,
2737 unsigned char *buf, unsigned char *end,
Gilles Peskine449bd832023-01-11 14:50:10 +01002738 size_t *out_len, size_t *binders_len);
XiaokangQianeb69aee2022-07-05 08:21:43 +00002739
2740/**
2741 * \brief Given an SSL context and its associated configuration, write the TLS
2742 * 1.3 specific Pre-Shared key extension binders at the end of the
2743 * ClientHello.
2744 *
2745 * \param[in] ssl SSL context
XiaokangQian008d2bf2022-07-14 07:54:01 +00002746 * \param[in] buf Base address of the buffer where to write the binders
2747 * \param[in] end End address of the buffer where to write the binders
XiaokangQianeb69aee2022-07-05 08:21:43 +00002748 */
XiaokangQian86981952022-07-19 09:51:50 +00002749MBEDTLS_CHECK_RETURN_CRITICAL
2750int mbedtls_ssl_tls13_write_binders_of_pre_shared_key_ext(
XiaokangQianeb69aee2022-07-05 08:21:43 +00002751 mbedtls_ssl_context *ssl,
Gilles Peskine449bd832023-01-11 14:50:10 +01002752 unsigned char *buf, unsigned char *end);
Ronald Cron41a443a2022-10-04 16:38:25 +02002753#endif /* MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_SOME_PSK_ENABLED */
XiaokangQianeb69aee2022-07-05 08:21:43 +00002754
Xiaokang Qiana3b451f2022-10-11 06:20:56 +00002755#if defined(MBEDTLS_SSL_PROTO_TLS1_3) && \
Xiaokang Qian03409292022-10-12 02:49:52 +00002756 defined(MBEDTLS_SSL_SESSION_TICKETS) && \
Xiaokang Qianed0620c2022-10-12 06:58:13 +00002757 defined(MBEDTLS_SSL_SERVER_NAME_INDICATION) && \
Xiaokang Qianed3afcd2022-10-12 08:31:11 +00002758 defined(MBEDTLS_SSL_CLI_C)
Xiaokang Qian03409292022-10-12 02:49:52 +00002759MBEDTLS_CHECK_RETURN_CRITICAL
Gilles Peskine449bd832023-01-11 14:50:10 +01002760int mbedtls_ssl_session_set_hostname(mbedtls_ssl_session *session,
2761 const char *hostname);
Xiaokang Qiana3b451f2022-10-11 06:20:56 +00002762#endif
2763
Waleed Elmelegy883f77c2024-03-06 19:09:41 +00002764#if defined(MBEDTLS_SSL_SRV_C) && defined(MBEDTLS_SSL_EARLY_DATA) && \
2765 defined(MBEDTLS_SSL_ALPN)
2766MBEDTLS_CHECK_RETURN_CRITICAL
Waleed Elmelegy5bc52632024-03-12 16:25:08 +00002767int mbedtls_ssl_session_set_ticket_alpn(mbedtls_ssl_session *session,
2768 const char *alpn);
Waleed Elmelegy883f77c2024-03-06 19:09:41 +00002769#endif
2770
Pengyu Lvb7d50ac2022-11-17 15:14:12 +08002771#if defined(MBEDTLS_SSL_PROTO_TLS1_3) && defined(MBEDTLS_SSL_SESSION_TICKETS)
Jerry Yu46c79262023-11-10 13:58:16 +08002772
Jerry Yu8e0174a2023-11-10 13:58:16 +08002773#define MBEDTLS_SSL_TLS1_3_MAX_ALLOWED_TICKET_LIFETIME (604800)
2774
Pengyu Lv94a42cc2023-12-06 10:04:17 +08002775static inline unsigned int mbedtls_ssl_tls13_session_get_ticket_flags(
Pengyu Lvacecf9c2023-01-16 11:23:24 +08002776 mbedtls_ssl_session *session, unsigned int flags)
Pengyu Lvb7d50ac2022-11-17 15:14:12 +08002777{
2778 return session->ticket_flags &
2779 (flags & MBEDTLS_SSL_TLS1_3_TICKET_FLAGS_MASK);
2780}
2781
Pengyu Lv4f537f72023-11-13 18:07:22 +08002782/**
2783 * Check if at least one of the given flags is set in
2784 * the session ticket. See the definition of
2785 * `MBEDTLS_SSL_TLS1_3_TICKET_FLAGS_MASK` to get all
2786 * permitted flags.
2787 */
Pengyu Lv94a42cc2023-12-06 10:04:17 +08002788static inline int mbedtls_ssl_tls13_session_ticket_has_flags(
Pengyu Lv7b711712023-10-24 17:07:14 +08002789 mbedtls_ssl_session *session, unsigned int flags)
2790{
Pengyu Lv94a42cc2023-12-06 10:04:17 +08002791 return mbedtls_ssl_tls13_session_get_ticket_flags(session, flags) != 0;
Pengyu Lv7b711712023-10-24 17:07:14 +08002792}
2793
Pengyu Lv94a42cc2023-12-06 10:04:17 +08002794static inline int mbedtls_ssl_tls13_session_ticket_allow_psk(
Pengyu Lvdbd1e0d2023-10-31 10:08:10 +08002795 mbedtls_ssl_session *session)
2796{
Pengyu Lv94a42cc2023-12-06 10:04:17 +08002797 return mbedtls_ssl_tls13_session_ticket_has_flags(
2798 session, MBEDTLS_SSL_TLS1_3_TICKET_ALLOW_PSK_RESUMPTION);
Pengyu Lvdbd1e0d2023-10-31 10:08:10 +08002799}
2800
Pengyu Lv94a42cc2023-12-06 10:04:17 +08002801static inline int mbedtls_ssl_tls13_session_ticket_allow_psk_ephemeral(
Pengyu Lvdbd1e0d2023-10-31 10:08:10 +08002802 mbedtls_ssl_session *session)
2803{
Pengyu Lv94a42cc2023-12-06 10:04:17 +08002804 return mbedtls_ssl_tls13_session_ticket_has_flags(
2805 session, MBEDTLS_SSL_TLS1_3_TICKET_ALLOW_PSK_EPHEMERAL_RESUMPTION);
Pengyu Lvdbd1e0d2023-10-31 10:08:10 +08002806}
2807
Pengyu Lv94a42cc2023-12-06 10:04:17 +08002808static inline unsigned int mbedtls_ssl_tls13_session_ticket_allow_early_data(
Jerry Yu4da7c222023-11-21 17:30:43 +08002809 mbedtls_ssl_session *session)
2810{
Pengyu Lv94a42cc2023-12-06 10:04:17 +08002811 return mbedtls_ssl_tls13_session_ticket_has_flags(
2812 session, MBEDTLS_SSL_TLS1_3_TICKET_ALLOW_EARLY_DATA);
Jerry Yu4da7c222023-11-21 17:30:43 +08002813}
2814
Pengyu Lv94a42cc2023-12-06 10:04:17 +08002815static inline void mbedtls_ssl_tls13_session_set_ticket_flags(
Pengyu Lvacecf9c2023-01-16 11:23:24 +08002816 mbedtls_ssl_session *session, unsigned int flags)
Pengyu Lvb7d50ac2022-11-17 15:14:12 +08002817{
2818 session->ticket_flags |= (flags & MBEDTLS_SSL_TLS1_3_TICKET_FLAGS_MASK);
2819}
2820
Pengyu Lv94a42cc2023-12-06 10:04:17 +08002821static inline void mbedtls_ssl_tls13_session_clear_ticket_flags(
Pengyu Lvacecf9c2023-01-16 11:23:24 +08002822 mbedtls_ssl_session *session, unsigned int flags)
Pengyu Lvb7d50ac2022-11-17 15:14:12 +08002823{
2824 session->ticket_flags &= ~(flags & MBEDTLS_SSL_TLS1_3_TICKET_FLAGS_MASK);
2825}
Pengyu Lva1aa31b2022-12-13 13:49:59 +08002826#endif /* MBEDTLS_SSL_PROTO_TLS1_3 && MBEDTLS_SSL_SESSION_TICKETS */
Pengyu Lvb7d50ac2022-11-17 15:14:12 +08002827
Xiaokang Qianb46275c2023-01-04 07:38:50 +00002828#if defined(MBEDTLS_SSL_CLI_C) && defined(MBEDTLS_SSL_PROTO_TLS1_3)
Xiaokang Qian934ce6f2023-02-06 10:23:04 +00002829int mbedtls_ssl_tls13_finalize_client_hello(mbedtls_ssl_context *ssl);
Xiaokang Qianb46275c2023-01-04 07:38:50 +00002830#endif
Xiaokang Qian126929f2023-01-03 10:29:41 +00002831
Dave Rodgman2801f7f2023-05-09 11:00:07 +01002832#if defined(MBEDTLS_TEST_HOOKS) && defined(MBEDTLS_SSL_SOME_SUITES_USE_MAC)
2833
2834/** Compute the HMAC of variable-length data with constant flow.
2835 *
2836 * This function computes the HMAC of the concatenation of \p add_data and \p
2837 * data, and does with a code flow and memory access pattern that does not
2838 * depend on \p data_len_secret, but only on \p min_data_len and \p
2839 * max_data_len. In particular, this function always reads exactly \p
2840 * max_data_len bytes from \p data.
2841 *
Manuel Pégourié-Gonnard53fe26c2025-01-24 09:38:29 +01002842 * \param key The HMAC key.
2843 * \param mac_alg The hash algorithm.
2844 * Must be one of SHA-384, SHA-256, SHA-1 or MD-5.
Dave Rodgman2801f7f2023-05-09 11:00:07 +01002845 * \param add_data The first part of the message whose HMAC is being
2846 * calculated. This must point to a readable buffer
2847 * of \p add_data_len bytes.
2848 * \param add_data_len The length of \p add_data in bytes.
2849 * \param data The buffer containing the second part of the
2850 * message. This must point to a readable buffer
2851 * of \p max_data_len bytes.
2852 * \param data_len_secret The length of the data to process in \p data.
2853 * This must be no less than \p min_data_len and no
2854 * greater than \p max_data_len.
2855 * \param min_data_len The minimal length of the second part of the
2856 * message, read from \p data.
2857 * \param max_data_len The maximal length of the second part of the
2858 * message, read from \p data.
2859 * \param output The HMAC will be written here. This must point to
2860 * a writable buffer of sufficient size to hold the
2861 * HMAC value.
2862 *
2863 * \retval 0 on success.
2864 * \retval #MBEDTLS_ERR_PLATFORM_HW_ACCEL_FAILED
2865 * The hardware accelerator failed.
2866 */
Dave Rodgman2801f7f2023-05-09 11:00:07 +01002867int mbedtls_ct_hmac(mbedtls_svc_key_id_t key,
2868 psa_algorithm_t mac_alg,
2869 const unsigned char *add_data,
2870 size_t add_data_len,
2871 const unsigned char *data,
2872 size_t data_len_secret,
2873 size_t min_data_len,
2874 size_t max_data_len,
2875 unsigned char *output);
Dave Rodgman2801f7f2023-05-09 11:00:07 +01002876#endif /* MBEDTLS_TEST_HOOKS && defined(MBEDTLS_SSL_SOME_SUITES_USE_MAC) */
2877
Chris Jones84a773f2021-03-05 18:38:47 +00002878#endif /* ssl_misc.h */