From d8d2ea5674871f3d708626c33d5342921b3ef266 Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Tue, 4 Oct 2022 15:48:06 +0200 Subject: [PATCH] Add TLS 1.3 key exchange mode config options Add TLS 1.3 specific configuration options to enable/disable the support for TLS 1.3 key exchange modes. These configurations are introduced to move away from the aforementioned enablement/disablement based on MBEDTLS_KEY_EXCHANGE_xxx_ENABLED options that relate to group of TLS 1.2 ciphersuites. Signed-off-by: Ronald Cron --- docs/architecture/tls13-support.md | 31 +++++++++++++++++++--- include/mbedtls/build_info.h | 16 ++++++++++++ include/mbedtls/check_config.h | 13 ++++++++++ include/mbedtls/mbedtls_config.h | 41 ++++++++++++++++++++++++++++++ tests/scripts/depends.py | 4 ++- 5 files changed, 100 insertions(+), 5 deletions(-) diff --git a/docs/architecture/tls13-support.md b/docs/architecture/tls13-support.md index fc0087ff8..30185f4e1 100644 --- a/docs/architecture/tls13-support.md +++ b/docs/architecture/tls13-support.md @@ -141,10 +141,33 @@ Support description | MBEDTLS_USE_PSA_CRYPTO | yes | (1) These options must remain in their default state of enabled. - (2) Key exchange configuration options for TLS 1.3 will likely to be - organized around the notion of key exchange mode along the line - of the MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_NONE/PSK/PSK_EPHEMERAL/EPHEMERAL - runtime configuration macros. + (2) See the TLS 1.3 specific build options section below. + +- TLS 1.3 specific build options: + + - MBEDTLS_SSL_TLS1_3_COMPATIBILITY_MODE enables the support for middlebox + compatibility mode as defined in section D.4 of RFC 8446. + + - MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_EPHEMERAL_ENABLED enables the + support of the ephemeral key exchange mode. If it is the only key exchange + mode enabled, the TLS 1.3 implementation does not contain any code related + to PSK based key exchange. The ephemeral key exchange mode requires at least + one of the key exchange protocol allowed by the TLS 1.3 specification, the + parsing and validation of x509 certificates and at least one signature + algorithm allowed by the TLS 1.3 specification for signature computing and + verification. + + - MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_ENABLED enables the support for + the PSK key exchange mode as defined by RFC 8446. If it is the only key + exchange mode enabled, the TLS 1.3 implementation does not contain any code + related to key exchange protocols, certificates and signatures. + + - MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_EPHEMERAL_ENABLED enables the support + for the PSK ephemeral key exchange mode. If it is the only key exchange + mode enabled, the TLS 1.3 implementation does not contain any code + related to certificates and signatures. The PSK ephemeral key exchange + mode requirss at least one of the key exchange protocol allowed by the + TLS 1.3 specification. Prototype upstreaming status diff --git a/include/mbedtls/build_info.h b/include/mbedtls/build_info.h index 6195ac979..041c5b61e 100644 --- a/include/mbedtls/build_info.h +++ b/include/mbedtls/build_info.h @@ -78,6 +78,22 @@ #define MBEDTLS_PK_WRITE_C #endif +#if !defined(MBEDTLS_SSL_PROTO_TLS1_3) +#undef MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_ENABLED +#undef MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_EPHEMERAL_ENABLED +#undef MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_EPHEMERAL_ENABLED +#endif + +#if defined(MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_ENABLED) || \ + defined(MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_EPHEMERAL_ENABLED) +#define MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_SOME_PSK_ENABLED +#endif + +#if defined(MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_EPHEMERAL_ENABLED) || \ + defined(MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_EPHEMERAL_ENABLED) +#define MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_SOME_EPHEMERAL_ENABLED +#endif + /* Make sure all configuration symbols are set before including check_config.h, * even the ones that are calculated programmatically. */ #if defined(MBEDTLS_PSA_CRYPTO_CONFIG) /* PSA_WANT_xxx influences MBEDTLS_xxx */ || \ diff --git a/include/mbedtls/check_config.h b/include/mbedtls/check_config.h index 0081ca3d6..6a9647994 100644 --- a/include/mbedtls/check_config.h +++ b/include/mbedtls/check_config.h @@ -806,6 +806,19 @@ #endif /* !MBEDTLS_USE_PSA_CRYPTO */ #endif /* MBEDTLS_SSL_PROTO_TLS1_3 */ +#if defined(MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_EPHEMERAL_ENABLED) +#if !( defined(MBEDTLS_ECDH_C) && defined(MBEDTLS_X509_CRT_PARSE_C) && \ + ( defined(MBEDTLS_ECDSA_C) || defined(MBEDTLS_PKCS1_V21) ) ) +#error "MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_EPHEMERAL_ENABLED defined, but not all prerequisites" +#endif +#endif + +#if defined(MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_EPHEMERAL_ENABLED) +#if !( defined(MBEDTLS_ECDH_C) ) +#error "MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_EPHEMERAL_ENABLED defined, but not all prerequisites" +#endif +#endif + /* * The current implementation of TLS 1.3 requires MBEDTLS_SSL_KEEP_PEER_CERTIFICATE. */ diff --git a/include/mbedtls/mbedtls_config.h b/include/mbedtls/mbedtls_config.h index 61007d801..9588ca4b4 100644 --- a/include/mbedtls/mbedtls_config.h +++ b/include/mbedtls/mbedtls_config.h @@ -1552,6 +1552,47 @@ */ //#define MBEDTLS_SSL_TLS1_3_COMPATIBILITY_MODE +/** + * \def MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_ENABLED + * + * Enable TLS 1.3 PSK key exchange mode. + * + * Comment to disable support for the PSK key exchange mode in TLS 1.3. If + * MBEDTLS_SSL_PROTO_TLS1_3 is not enabled, this option does not have any + * effect on the build. + * + */ +#define MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_ENABLED + +/** + * \def MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_EPHEMERAL_ENABLED + * + * Enable TLS 1.3 ephemeral key exchange mode. + * + * Requires: MBEDTLS_ECDH_C, MBEDTLS_X509_CRT_PARSE_C, MBEDTLS_ECDSA_C or + * MBEDTLS_PKCS1_V21 + * + * Comment to disable support for the ephemeral key exchange mode in TLS 1.3. + * If MBEDTLS_SSL_PROTO_TLS1_3 is not enabled, this option does not have any + * effect on the build. + * + */ +#define MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_EPHEMERAL_ENABLED + +/** + * \def MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_EPHEMERAL_ENABLED + * + * Enable TLS 1.3 PSK ephemeral key exchange mode. + * + * Requires: MBEDTLS_ECDH_C + * + * Comment to disable support for the PSK ephemeral key exchange mode in + * TLS 1.3. If MBEDTLS_SSL_PROTO_TLS1_3 is not enabled, this option does not + * have any effect on the build. + * + */ +#define MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_EPHEMERAL_ENABLED + /** * \def MBEDTLS_SSL_TLS1_3_TICKET_AGE_TOLERANCE * diff --git a/tests/scripts/depends.py b/tests/scripts/depends.py index ce7fee65c..f2396ee96 100755 --- a/tests/scripts/depends.py +++ b/tests/scripts/depends.py @@ -237,7 +237,9 @@ REVERSE_DEPENDENCIES = { 'MBEDTLS_KEY_EXCHANGE_ECDHE_PSK_ENABLED', 'MBEDTLS_KEY_EXCHANGE_ECDHE_RSA_ENABLED', 'MBEDTLS_KEY_EXCHANGE_ECDHE_ECDSA_ENABLED', - 'MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED'], + 'MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED', + 'MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_EPHEMERAL_ENABLED', + 'MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_EPHEMERAL_ENABLED'], 'MBEDTLS_ECP_DP_SECP256R1_ENABLED': ['MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED'], 'MBEDTLS_PKCS1_V21': ['MBEDTLS_X509_RSASSA_PSS_SUPPORT'], 'MBEDTLS_PKCS1_V15': ['MBEDTLS_KEY_EXCHANGE_DHE_RSA_ENABLED',