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 <ronald.cron@arm.com>
diff --git a/docs/architecture/tls13-support.md b/docs/architecture/tls13-support.md
index fc0087f..30185f4 100644
--- a/docs/architecture/tls13-support.md
+++ b/docs/architecture/tls13-support.md
@@ -141,10 +141,33 @@
| 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 6195ac9..041c5b6 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 0081ca3..6a96479 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 61007d8..9588ca4 100644
--- a/include/mbedtls/mbedtls_config.h
+++ b/include/mbedtls/mbedtls_config.h
@@ -1553,6 +1553,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
*
* Maximum time difference in milliseconds tolerated between the age of a
diff --git a/tests/scripts/depends.py b/tests/scripts/depends.py
index ce7fee6..f2396ee 100755
--- a/tests/scripts/depends.py
+++ b/tests/scripts/depends.py
@@ -237,7 +237,9 @@
'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',