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>
2022-10-04 15:48:06 +02:00 · 2022-10-04 15:48:06 +02:00 · d8d2ea5674
commit d8d2ea5674
parent 89ca977128
5 changed files with 100 additions and 5 deletions
--- 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
--- 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 */ || \
--- 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.
 */
--- 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
 *
--- 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',