Mbed TLS v4.0.0
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
ssl_ciphersuites.h
Go to the documentation of this file.
1 
6 /*
7  * Copyright The Mbed TLS Contributors
8  * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
9  */
10 #ifndef MBEDTLS_SSL_CIPHERSUITES_H
11 #define MBEDTLS_SSL_CIPHERSUITES_H
12 #include "mbedtls/private_access.h"
13 
14 #include "mbedtls/build_info.h"
15 
16 #include "mbedtls/pk.h"
17 #include "mbedtls/private/cipher.h"
18 #include "mbedtls/md.h"
19 
20 #ifdef __cplusplus
21 extern "C" {
22 #endif
23 
24 /*
25  * Supported ciphersuites (Official IANA names)
26  */
27 #define MBEDTLS_TLS_PSK_WITH_NULL_SHA 0x2C
29 #define MBEDTLS_TLS_PSK_WITH_AES_128_CBC_SHA 0x8C
30 #define MBEDTLS_TLS_PSK_WITH_AES_256_CBC_SHA 0x8D
31 
32 #define MBEDTLS_TLS_PSK_WITH_AES_128_GCM_SHA256 0xA8
33 #define MBEDTLS_TLS_PSK_WITH_AES_256_GCM_SHA384 0xA9
35 #define MBEDTLS_TLS_PSK_WITH_AES_128_CBC_SHA256 0xAE
36 #define MBEDTLS_TLS_PSK_WITH_AES_256_CBC_SHA384 0xAF
37 #define MBEDTLS_TLS_PSK_WITH_NULL_SHA256 0xB0
38 #define MBEDTLS_TLS_PSK_WITH_NULL_SHA384 0xB1
40 #define MBEDTLS_TLS_ECDHE_ECDSA_WITH_NULL_SHA 0xC006
41 #define MBEDTLS_TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA 0xC009
42 #define MBEDTLS_TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA 0xC00A
43 
44 #define MBEDTLS_TLS_ECDHE_RSA_WITH_NULL_SHA 0xC010
45 #define MBEDTLS_TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA 0xC013
46 #define MBEDTLS_TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA 0xC014
47 
48 #define MBEDTLS_TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 0xC023
49 #define MBEDTLS_TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 0xC024
50 #define MBEDTLS_TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 0xC027
51 #define MBEDTLS_TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 0xC028
53 #define MBEDTLS_TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 0xC02B
54 #define MBEDTLS_TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 0xC02C
55 #define MBEDTLS_TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 0xC02F
56 #define MBEDTLS_TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 0xC030
58 #define MBEDTLS_TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA 0xC035
59 #define MBEDTLS_TLS_ECDHE_PSK_WITH_AES_256_CBC_SHA 0xC036
60 #define MBEDTLS_TLS_ECDHE_PSK_WITH_AES_128_CBC_SHA256 0xC037
61 #define MBEDTLS_TLS_ECDHE_PSK_WITH_AES_256_CBC_SHA384 0xC038
62 #define MBEDTLS_TLS_ECDHE_PSK_WITH_NULL_SHA 0xC039
63 #define MBEDTLS_TLS_ECDHE_PSK_WITH_NULL_SHA256 0xC03A
64 #define MBEDTLS_TLS_ECDHE_PSK_WITH_NULL_SHA384 0xC03B
65 
66 #define MBEDTLS_TLS_ECDHE_ECDSA_WITH_ARIA_128_CBC_SHA256 0xC048
67 #define MBEDTLS_TLS_ECDHE_ECDSA_WITH_ARIA_256_CBC_SHA384 0xC049
68 #define MBEDTLS_TLS_ECDHE_RSA_WITH_ARIA_128_CBC_SHA256 0xC04C
69 #define MBEDTLS_TLS_ECDHE_RSA_WITH_ARIA_256_CBC_SHA384 0xC04D
70 #define MBEDTLS_TLS_ECDHE_ECDSA_WITH_ARIA_128_GCM_SHA256 0xC05C
71 #define MBEDTLS_TLS_ECDHE_ECDSA_WITH_ARIA_256_GCM_SHA384 0xC05D
72 #define MBEDTLS_TLS_ECDHE_RSA_WITH_ARIA_128_GCM_SHA256 0xC060
73 #define MBEDTLS_TLS_ECDHE_RSA_WITH_ARIA_256_GCM_SHA384 0xC061
74 #define MBEDTLS_TLS_PSK_WITH_ARIA_128_CBC_SHA256 0xC064
75 #define MBEDTLS_TLS_PSK_WITH_ARIA_256_CBC_SHA384 0xC065
76 #define MBEDTLS_TLS_PSK_WITH_ARIA_128_GCM_SHA256 0xC06A
77 #define MBEDTLS_TLS_PSK_WITH_ARIA_256_GCM_SHA384 0xC06B
78 #define MBEDTLS_TLS_ECDHE_PSK_WITH_ARIA_128_CBC_SHA256 0xC070
79 #define MBEDTLS_TLS_ECDHE_PSK_WITH_ARIA_256_CBC_SHA384 0xC071
81 #define MBEDTLS_TLS_ECDHE_ECDSA_WITH_CAMELLIA_128_CBC_SHA256 0xC072
82 #define MBEDTLS_TLS_ECDHE_ECDSA_WITH_CAMELLIA_256_CBC_SHA384 0xC073
83 #define MBEDTLS_TLS_ECDHE_RSA_WITH_CAMELLIA_128_CBC_SHA256 0xC076
84 #define MBEDTLS_TLS_ECDHE_RSA_WITH_CAMELLIA_256_CBC_SHA384 0xC077
85 
86 #define MBEDTLS_TLS_ECDHE_ECDSA_WITH_CAMELLIA_128_GCM_SHA256 0xC086
87 #define MBEDTLS_TLS_ECDHE_ECDSA_WITH_CAMELLIA_256_GCM_SHA384 0xC087
88 #define MBEDTLS_TLS_ECDHE_RSA_WITH_CAMELLIA_128_GCM_SHA256 0xC08A
89 #define MBEDTLS_TLS_ECDHE_RSA_WITH_CAMELLIA_256_GCM_SHA384 0xC08B
91 #define MBEDTLS_TLS_PSK_WITH_CAMELLIA_128_GCM_SHA256 0xC08E
92 #define MBEDTLS_TLS_PSK_WITH_CAMELLIA_256_GCM_SHA384 0xC08F
94 #define MBEDTLS_TLS_PSK_WITH_CAMELLIA_128_CBC_SHA256 0xC094
95 #define MBEDTLS_TLS_PSK_WITH_CAMELLIA_256_CBC_SHA384 0xC095
96 #define MBEDTLS_TLS_ECDHE_PSK_WITH_CAMELLIA_128_CBC_SHA256 0xC09A
97 #define MBEDTLS_TLS_ECDHE_PSK_WITH_CAMELLIA_256_CBC_SHA384 0xC09B
98 
99 #define MBEDTLS_TLS_PSK_WITH_AES_128_CCM 0xC0A4
100 #define MBEDTLS_TLS_PSK_WITH_AES_256_CCM 0xC0A5
101 #define MBEDTLS_TLS_PSK_WITH_AES_128_CCM_8 0xC0A8
102 #define MBEDTLS_TLS_PSK_WITH_AES_256_CCM_8 0xC0A9
103 /* The last two are named with PSK_DHE in the RFC, which looks like a typo */
104 
105 #define MBEDTLS_TLS_ECDHE_ECDSA_WITH_AES_128_CCM 0xC0AC
106 #define MBEDTLS_TLS_ECDHE_ECDSA_WITH_AES_256_CCM 0xC0AD
107 #define MBEDTLS_TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8 0xC0AE
108 #define MBEDTLS_TLS_ECDHE_ECDSA_WITH_AES_256_CCM_8 0xC0AF
110 #define MBEDTLS_TLS_ECJPAKE_WITH_AES_128_CCM_8 0xC0FF
112 /* RFC 7905 */
113 #define MBEDTLS_TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256 0xCCA8
114 #define MBEDTLS_TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256 0xCCA9
115 #define MBEDTLS_TLS_PSK_WITH_CHACHA20_POLY1305_SHA256 0xCCAB
116 #define MBEDTLS_TLS_ECDHE_PSK_WITH_CHACHA20_POLY1305_SHA256 0xCCAC
118 /* RFC 8446, Appendix B.4 */
119 #define MBEDTLS_TLS1_3_AES_128_GCM_SHA256 0x1301
120 #define MBEDTLS_TLS1_3_AES_256_GCM_SHA384 0x1302
121 #define MBEDTLS_TLS1_3_CHACHA20_POLY1305_SHA256 0x1303
122 #define MBEDTLS_TLS1_3_AES_128_CCM_SHA256 0x1304
123 #define MBEDTLS_TLS1_3_AES_128_CCM_8_SHA256 0x1305
125 /* Reminder: update mbedtls_ssl_premaster_secret when adding a new key exchange.
126  * Reminder: update MBEDTLS_KEY_EXCHANGE__xxx below
127  */
128 typedef enum {
129  MBEDTLS_KEY_EXCHANGE_NONE = 0,
130  MBEDTLS_KEY_EXCHANGE_ECDHE_RSA,
131  MBEDTLS_KEY_EXCHANGE_ECDHE_ECDSA,
132  MBEDTLS_KEY_EXCHANGE_PSK,
133  MBEDTLS_KEY_EXCHANGE_ECDHE_PSK,
134  MBEDTLS_KEY_EXCHANGE_ECJPAKE,
135 } mbedtls_key_exchange_type_t;
136 
137 /* Key exchanges using a certificate */
138 #if defined(MBEDTLS_KEY_EXCHANGE_ECDHE_RSA_ENABLED) || \
139  defined(MBEDTLS_KEY_EXCHANGE_ECDHE_ECDSA_ENABLED)
140 #define MBEDTLS_KEY_EXCHANGE_WITH_CERT_ENABLED
141 #endif
142 
143 /* Key exchanges in either TLS 1.2 or 1.3 which are using an ECDSA
144  * signature */
145 #if defined(MBEDTLS_KEY_EXCHANGE_ECDHE_ECDSA_ENABLED) || \
146  defined(MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_EPHEMERAL_ENABLED)
147 #define MBEDTLS_KEY_EXCHANGE_WITH_ECDSA_ANY_ENABLED
148 #endif
149 
150 #if defined(MBEDTLS_KEY_EXCHANGE_WITH_CERT_ENABLED) || \
151  defined(MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_EPHEMERAL_ENABLED)
152 #define MBEDTLS_SSL_HANDSHAKE_WITH_CERT_ENABLED
153 #endif
154 
155 /* Key exchanges allowing client certificate requests.
156  *
157  * This is now the same as MBEDTLS_KEY_EXCHANGE_WITH_CERT_ENABLED,
158  * and the two macros could be unified.
159  * Until Mbed TLS 3.x, the two sets were different because
160  * MBEDTLS_KEY_EXCHANGE_CERT_REQ_ALLOWED_ENABLED covers
161  * MBEDTLS_KEY_EXCHANGE_WITH_CERT_ENABLED plus RSA-PSK.
162  * But RSA-PSK was removed in Mbed TLS 4.0.
163  */
164 #if defined(MBEDTLS_KEY_EXCHANGE_WITH_CERT_ENABLED)
165 #define MBEDTLS_KEY_EXCHANGE_CERT_REQ_ALLOWED_ENABLED
166 #endif
167 
168 /* Helper to state that certificate-based client authentication through ECDSA
169  * is supported in TLS 1.2 */
170 #if defined(MBEDTLS_KEY_EXCHANGE_CERT_REQ_ALLOWED_ENABLED) && \
171  defined(PSA_HAVE_ALG_ECDSA_SIGN) && defined(PSA_HAVE_ALG_ECDSA_VERIFY)
172 #define MBEDTLS_KEY_EXCHANGE_ECDSA_CERT_REQ_ALLOWED_ENABLED
173 #endif
174 
175 /* ECDSA required for certificates in either TLS 1.2 or 1.3 */
176 #if defined(MBEDTLS_KEY_EXCHANGE_ECDSA_CERT_REQ_ALLOWED_ENABLED) || \
177  defined(MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_EPHEMERAL_ENABLED)
178 #define MBEDTLS_KEY_EXCHANGE_ECDSA_CERT_REQ_ANY_ALLOWED_ENABLED
179 #endif
180 
181 /* Key exchanges involving server signature in ServerKeyExchange */
182 #if defined(MBEDTLS_KEY_EXCHANGE_ECDHE_RSA_ENABLED) || \
183  defined(MBEDTLS_KEY_EXCHANGE_ECDHE_ECDSA_ENABLED)
184 #define MBEDTLS_KEY_EXCHANGE_WITH_SERVER_SIGNATURE_ENABLED
185 #endif
186 
187 /* Key exchanges that involve ephemeral keys */
188 #if defined(MBEDTLS_KEY_EXCHANGE_ECDHE_RSA_ENABLED) || \
189  defined(MBEDTLS_KEY_EXCHANGE_ECDHE_PSK_ENABLED) || \
190  defined(MBEDTLS_KEY_EXCHANGE_ECDHE_ECDSA_ENABLED) || \
191  defined(MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED)
192 #define MBEDTLS_KEY_EXCHANGE_SOME_PFS_ENABLED
193 #endif
194 
195 /* Key exchanges using a PSK */
196 #if defined(MBEDTLS_KEY_EXCHANGE_PSK_ENABLED) || \
197  defined(MBEDTLS_KEY_EXCHANGE_ECDHE_PSK_ENABLED)
198 #define MBEDTLS_KEY_EXCHANGE_SOME_PSK_ENABLED
199 #endif
200 
201 /* Key exchanges using ECDHE */
202 #if defined(MBEDTLS_KEY_EXCHANGE_ECDHE_RSA_ENABLED) || \
203  defined(MBEDTLS_KEY_EXCHANGE_ECDHE_ECDSA_ENABLED) || \
204  defined(MBEDTLS_KEY_EXCHANGE_ECDHE_PSK_ENABLED)
205 #define MBEDTLS_KEY_EXCHANGE_SOME_ECDHE_ENABLED
206 #endif
207 
208 /* TLS 1.2 key exchanges using ECDH or ECDHE*/
209 #if defined(MBEDTLS_KEY_EXCHANGE_SOME_ECDHE_ENABLED)
210 #define MBEDTLS_KEY_EXCHANGE_SOME_ECDH_OR_ECDHE_1_2_ENABLED
211 #endif
212 
213 /* TLS 1.3 PSK key exchanges */
214 #if defined(MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_ENABLED) || \
215  defined(MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_EPHEMERAL_ENABLED)
216 #define MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_SOME_PSK_ENABLED
217 #endif
218 
219 /* TLS 1.2 or 1.3 key exchanges with PSK */
220 #if defined(MBEDTLS_KEY_EXCHANGE_SOME_PSK_ENABLED) || \
221  defined(MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_SOME_PSK_ENABLED)
222 #define MBEDTLS_SSL_HANDSHAKE_WITH_PSK_ENABLED
223 #endif
224 
225 /* TLS 1.3 ephemeral key exchanges */
226 #if defined(MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_EPHEMERAL_ENABLED) || \
227  defined(MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_EPHEMERAL_ENABLED)
228 #define MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_SOME_EPHEMERAL_ENABLED
229 #endif
230 
231 /* TLS 1.3 key exchanges using ECDHE */
232 #if defined(MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_SOME_EPHEMERAL_ENABLED) && \
233  defined(PSA_WANT_ALG_ECDH)
234 #define MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_SOME_ECDHE_ENABLED
235 #endif
236 
237 /* TLS 1.2 or 1.3 key exchanges using ECDH or ECDHE */
238 #if defined(MBEDTLS_KEY_EXCHANGE_SOME_ECDH_OR_ECDHE_1_2_ENABLED) || \
239  defined(MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_SOME_ECDHE_ENABLED)
240 #define MBEDTLS_KEY_EXCHANGE_SOME_ECDH_OR_ECDHE_ANY_ENABLED
241 #endif
242 
243 /* The handshake params structure has a set of fields called xxdh_psa which are used:
244  * - by TLS 1.2 to do ECDH or ECDHE;
245  * - by TLS 1.3 to do ECDHE or FFDHE.
246  * The following macros can be used to guard their declaration and use.
247  */
248 #if defined(MBEDTLS_KEY_EXCHANGE_SOME_ECDH_OR_ECDHE_1_2_ENABLED)
249 #define MBEDTLS_KEY_EXCHANGE_SOME_XXDH_PSA_1_2_ENABLED
250 #endif
251 #if defined(MBEDTLS_KEY_EXCHANGE_SOME_XXDH_PSA_1_2_ENABLED) || \
252  defined(MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_SOME_EPHEMERAL_ENABLED)
253 #define MBEDTLS_KEY_EXCHANGE_SOME_XXDH_PSA_ANY_ENABLED
254 #endif
255 
256 typedef struct mbedtls_ssl_ciphersuite_t mbedtls_ssl_ciphersuite_t;
257 
258 #define MBEDTLS_CIPHERSUITE_WEAK 0x01
259 #define MBEDTLS_CIPHERSUITE_SHORT_TAG 0x02
261 #define MBEDTLS_CIPHERSUITE_NODTLS 0x04
270 struct mbedtls_ssl_ciphersuite_t {
271  int MBEDTLS_PRIVATE(id);
272  const char *MBEDTLS_PRIVATE(name);
273 
274  uint8_t MBEDTLS_PRIVATE(cipher); /* mbedtls_cipher_type_t */
275  uint8_t MBEDTLS_PRIVATE(mac); /* mbedtls_md_type_t */
276  uint8_t MBEDTLS_PRIVATE(key_exchange); /* mbedtls_key_exchange_type_t */
277  uint8_t MBEDTLS_PRIVATE(flags);
278 
279  uint16_t MBEDTLS_PRIVATE(min_tls_version); /* mbedtls_ssl_protocol_version */
280  uint16_t MBEDTLS_PRIVATE(max_tls_version); /* mbedtls_ssl_protocol_version */
281 };
282 
283 const int *mbedtls_ssl_list_ciphersuites(void);
284 
285 const mbedtls_ssl_ciphersuite_t *mbedtls_ssl_ciphersuite_from_string(const char *ciphersuite_name);
286 const mbedtls_ssl_ciphersuite_t *mbedtls_ssl_ciphersuite_from_id(int ciphersuite_id);
287 
288 static inline const char *mbedtls_ssl_ciphersuite_get_name(const mbedtls_ssl_ciphersuite_t *info)
289 {
290  return info->MBEDTLS_PRIVATE(name);
291 }
292 
293 static inline int mbedtls_ssl_ciphersuite_get_id(const mbedtls_ssl_ciphersuite_t *info)
294 {
295  return info->MBEDTLS_PRIVATE(id);
296 }
297 
298 size_t mbedtls_ssl_ciphersuite_get_cipher_key_bitlen(const mbedtls_ssl_ciphersuite_t *info);
299 
300 #ifdef __cplusplus
301 }
302 #endif
303 
304 #endif /* ssl_ciphersuites.h */
mbedtls_ssl_ciphersuite_from_id
const mbedtls_ssl_ciphersuite_t * mbedtls_ssl_ciphersuite_from_id(int ciphersuite_id)
mbedtls_ssl_ciphersuite_get_name
static const char * mbedtls_ssl_ciphersuite_get_name(const mbedtls_ssl_ciphersuite_t *info)
Definition: ssl_ciphersuites.h:289
mbedtls_ssl_ciphersuite_get_cipher_key_bitlen
size_t mbedtls_ssl_ciphersuite_get_cipher_key_bitlen(const mbedtls_ssl_ciphersuite_t *info)
MBEDTLS_KEY_EXCHANGE_NONE
Definition: ssl_ciphersuites.h:129
MBEDTLS_KEY_EXCHANGE_ECDHE_RSA
Definition: ssl_ciphersuites.h:130
mbedtls_ssl_ciphersuite_get_id
static int mbedtls_ssl_ciphersuite_get_id(const mbedtls_ssl_ciphersuite_t *info)
Definition: ssl_ciphersuites.h:294
mbedtls_ssl_list_ciphersuites
const int * mbedtls_ssl_list_ciphersuites(void)
pk.h
Public Key abstraction layer.
MBEDTLS_KEY_EXCHANGE_ECJPAKE
Definition: ssl_ciphersuites.h:134
mbedtls_key_exchange_type_t
mbedtls_key_exchange_type_t
Definition: ssl_ciphersuites.h:128
build_info.h
Build-time configuration info.
mbedtls_ssl_ciphersuite_t
This structure is used for storing ciphersuite information.
Definition: ssl_ciphersuites.h:271
md.h
This file contains the generic functions for message-digest (hashing) and HMAC.
MBEDTLS_KEY_EXCHANGE_ECDHE_PSK
Definition: ssl_ciphersuites.h:133
MBEDTLS_KEY_EXCHANGE_PSK
Definition: ssl_ciphersuites.h:132
MBEDTLS_KEY_EXCHANGE_ECDHE_ECDSA
Definition: ssl_ciphersuites.h:131
mbedtls_ssl_ciphersuite_from_string
const mbedtls_ssl_ciphersuite_t * mbedtls_ssl_ciphersuite_from_string(const char *ciphersuite_name)
Generated on Thu Feb 5 2026 15:22:17 for Mbed TLS v4.0.0 by   doxygen 1.8.6