From 93b21e74f928cae31c01894481cd0d76bd84beac Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Manuel=20P=C3=A9gouri=C3=A9-Gonnard?= Date: Wed, 29 Mar 2023 10:30:26 +0200 Subject: [PATCH 1/5] Update documentation to mention ECC drivers MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Manuel Pégourié-Gonnard --- docs/use-psa-crypto.md | 7 +++++++ include/mbedtls/mbedtls_config.h | 9 ++++++--- 2 files changed, 13 insertions(+), 3 deletions(-) diff --git a/docs/use-psa-crypto.md b/docs/use-psa-crypto.md index 4d72f990d7..305dd736b3 100644 --- a/docs/use-psa-crypto.md +++ b/docs/use-psa-crypto.md @@ -15,6 +15,13 @@ General considerations `psa_crypto_init()` before calling any function from the SSL/TLS, X.509 or PK module. +**Why enable this option:** to fully take advantage of PSA drivers in PK, +X.509 and TLS. For example, enabling this option is what allows use of drivers +for ECDSA, ECDH and EC J-PAKE in those modules. However, note that ven with +this option disabled, some code in PK, X.509, TLS or the crypto library might +still use PSA drivers, if it can determine it's safe to do so; currently +that's the case for hashes. + **Relationship with other options:** This option depends on `MBEDTLS_PSA_CRYPTO_C`. These two options differ in the following way: - `MBEDTLS_PSA_CRYPTO_C` enables the implementation of the PSA Crypto API. diff --git a/include/mbedtls/mbedtls_config.h b/include/mbedtls/mbedtls_config.h index ef3cf2408b..3209281ade 100644 --- a/include/mbedtls/mbedtls_config.h +++ b/include/mbedtls/mbedtls_config.h @@ -1933,9 +1933,12 @@ * \warning If you enable this option, you need to call `psa_crypto_init()` * before calling any function from the SSL/TLS, X.509 or PK modules. * - * \note Even with this option disabled, some code in PK, X.509, TLS or the - * crypto library might still use PSA drivers, if it can determine it's safe - * to do so. + * \note An important and desirable effect of this option is that it allows + * PK, X.509 and TLS to take advantage of PSA drivers. For example, enabling + * this option is what allows use of drivers for ECDSA, ECDH and EC J-PAKE in + * those modules. However, note that ven with this option disabled, some code + * in PK, X.509, TLS or the crypto library might still use PSA drivers, if it + * can determine it's safe to do so; currently that's the case for hashes. * * \note See docs/use-psa-crypto.md for a complete description this option. * From 5c8c9e068e16b704f8fd9e2eb3a9f97046733401 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Manuel=20P=C3=A9gouri=C3=A9-Gonnard?= Date: Wed, 29 Mar 2023 10:33:03 +0200 Subject: [PATCH 2/5] Minor improvements MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Manuel Pégourié-Gonnard --- docs/architecture/psa-migration/psa-limitations.md | 2 +- docs/use-psa-crypto.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/architecture/psa-migration/psa-limitations.md b/docs/architecture/psa-migration/psa-limitations.md index b81aeb47af..29d7c53303 100644 --- a/docs/architecture/psa-migration/psa-limitations.md +++ b/docs/architecture/psa-migration/psa-limitations.md @@ -15,7 +15,7 @@ Restartable (aka interruptible) ECC operations ---------------------------------------------- Support for interruptible ECDSA sign/verify was added to PSA in Mbed TLS 3.4. -However support for interruptible ECDH is not present yet. Also, PK, X.509 and +However, support for interruptible ECDH is not present yet. Also, PK, X.509 and TLS have not yet been adapted to take advantage of the new PSA APIs. See: - ; - ; diff --git a/docs/use-psa-crypto.md b/docs/use-psa-crypto.md index 305dd736b3..7c0397f62c 100644 --- a/docs/use-psa-crypto.md +++ b/docs/use-psa-crypto.md @@ -29,7 +29,7 @@ that's the case for hashes. `psa_crypto_init()` before you call any other `psa_xxx()` function. Other modules in the library (non-PSA crypto APIs, X.509, TLS) may or may not use PSA Crypto but you're not required to call `psa_crypto_init()` before calling -non-PSA functions, unless when explicitly documented (TLS 1.3). +non-PSA functions, unless explicitly documented (TLS 1.3). - `MBEDTLS_USE_PSA_CRYPTO` means that X.509 and TLS will use PSA Crypto as much as possible (that is, everywhere except for features that are not supported by PSA Crypto, see "Internal Changes" below for a complete list of From 4fa702ae79a7e36a57df73ea4ee80cefb6fda7d0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Manuel=20P=C3=A9gouri=C3=A9-Gonnard?= Date: Wed, 29 Mar 2023 12:15:24 +0200 Subject: [PATCH 3/5] Update documented dependencies on ECC algs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Previous PRs update check_config.h correctly, but forgot the documentation in mbedtls_config.h. Signed-off-by: Manuel Pégourié-Gonnard --- include/mbedtls/mbedtls_config.h | 29 ++++++++++++++++++++--------- 1 file changed, 20 insertions(+), 9 deletions(-) diff --git a/include/mbedtls/mbedtls_config.h b/include/mbedtls/mbedtls_config.h index 3209281ade..b16e1fcbbb 100644 --- a/include/mbedtls/mbedtls_config.h +++ b/include/mbedtls/mbedtls_config.h @@ -801,7 +801,7 @@ * * Enable the ECDHE-PSK based ciphersuite modes in SSL / TLS. * - * Requires: MBEDTLS_ECDH_C + * Requires: MBEDTLS_ECDH_C or (MBEDTLS_USE_PSA_CRYPTO and PSA_WANT_ALG_ECDH) * * This enables the following ciphersuites (if other requisites are * enabled as well): @@ -899,7 +899,9 @@ * * Enable the ECDHE-RSA based ciphersuite modes in SSL / TLS. * - * Requires: MBEDTLS_ECDH_C, MBEDTLS_RSA_C, MBEDTLS_PKCS1_V15, + * Requires: MBEDTLS_ECDH_C or (MBEDTLS_USE_PSA_CRYPTO and PSA_WANT_ALG_ECDH) + * MBEDTLS_RSA_C + * MBEDTLS_PKCS1_V15 * MBEDTLS_X509_CRT_PARSE_C * * This enables the following ciphersuites (if other requisites are @@ -922,7 +924,9 @@ * * Enable the ECDHE-ECDSA based ciphersuite modes in SSL / TLS. * - * Requires: MBEDTLS_ECDH_C, MBEDTLS_ECDSA_C, MBEDTLS_X509_CRT_PARSE_C, + * Requires: MBEDTLS_ECDH_C or (MBEDTLS_USE_PSA_CRYPTO and PSA_WANT_ALG_ECDH) + * MBEDTLS_ECDSA_C or (MBEDTLS_USE_PSA_CRYPTO and PSA_WANT_ALG_ECDSA) + * MBEDTLS_X509_CRT_PARSE_C * * This enables the following ciphersuites (if other requisites are * enabled as well): @@ -944,7 +948,9 @@ * * Enable the ECDH-ECDSA based ciphersuite modes in SSL / TLS. * - * Requires: MBEDTLS_ECDH_C, MBEDTLS_ECDSA_C, MBEDTLS_X509_CRT_PARSE_C + * Requires: MBEDTLS_ECDH_C or (MBEDTLS_USE_PSA_CRYPTO and PSA_WANT_ALG_ECDH) + * MBEDTLS_ECDSA_C or (MBEDTLS_USE_PSA_CRYPTO and PSA_WANT_ALG_ECDSA) + * MBEDTLS_X509_CRT_PARSE_C * * This enables the following ciphersuites (if other requisites are * enabled as well): @@ -966,7 +972,9 @@ * * Enable the ECDH-RSA based ciphersuite modes in SSL / TLS. * - * Requires: MBEDTLS_ECDH_C, MBEDTLS_RSA_C, MBEDTLS_X509_CRT_PARSE_C + * Requires: MBEDTLS_ECDH_C or (MBEDTLS_USE_PSA_CRYPTO and PSA_WANT_ALG_ECDH) + * MBEDTLS_RSA_C + * MBEDTLS_X509_CRT_PARSE_C * * This enables the following ciphersuites (if other requisites are * enabled as well): @@ -992,7 +1000,7 @@ * Thread v1.0.0 specification; incompatible changes to the specification * might still happen. For this reason, this is disabled by default. * - * Requires: MBEDTLS_ECJPAKE_C + * Requires: MBEDTLS_ECJPAKE_C or (MBEDTLS_USE_PSA_CRYPTO and PSA_WANT_ALG_JPAKE) * SHA-256 (via MBEDTLS_SHA256_C or a PSA driver) * MBEDTLS_ECP_DP_SECP256R1_ENABLED * @@ -1645,8 +1653,11 @@ * * Enable TLS 1.3 ephemeral key exchange mode. * - * Requires: MBEDTLS_ECDH_C, MBEDTLS_X509_CRT_PARSE_C, MBEDTLS_ECDSA_C or - * MBEDTLS_PKCS1_V21 + * Requires: PSA_WANT_ALG_ECDH + * MBEDTLS_X509_CRT_PARSE_C + * and at least one of: + * MBEDTLS_ECDSA_C or (MBEDTLS_USE_PSA_CRYPTO and PSA_WANT_ALG_ECDSA) + * 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 @@ -1660,7 +1671,7 @@ * * Enable TLS 1.3 PSK ephemeral key exchange mode. * - * Requires: MBEDTLS_ECDH_C + * Requires: PSA_WANT_ALG_ECDH * * 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 From 59b61da7c45a16f69af062e389995e14fd057c16 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Manuel=20P=C3=A9gouri=C3=A9-Gonnard?= Date: Thu, 30 Mar 2023 09:35:41 +0200 Subject: [PATCH 4/5] Fix dependency check for TLS 1.3 ECDH MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This part is specific to 1.3 and directly calls PSA APIs regardless of whether MBEDTLS_USE_PSA_CRYPTO is defined, so use PSA_WANT. Note: the code is already using PSA_WANT everywhere in ssl_tls13*.c. Signed-off-by: Manuel Pégourié-Gonnard --- include/mbedtls/check_config.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/include/mbedtls/check_config.h b/include/mbedtls/check_config.h index 5eadc0cae8..ec0e23a8a4 100644 --- a/include/mbedtls/check_config.h +++ b/include/mbedtls/check_config.h @@ -798,14 +798,14 @@ #endif #if defined(MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_EPHEMERAL_ENABLED) -#if !( defined(MBEDTLS_PK_HAVE_ECDH) && defined(MBEDTLS_X509_CRT_PARSE_C) && \ +#if !( defined(PSA_WANT_ALG_ECDH) && defined(MBEDTLS_X509_CRT_PARSE_C) && \ ( defined(MBEDTLS_PK_HAVE_ECDSA) || 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_PK_HAVE_ECDH) ) +#if !( defined(PSA_WANT_ALG_ECDH) ) #error "MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_EPHEMERAL_ENABLED defined, but not all prerequisites" #endif #endif From 9463e780c6f3500824be656079e77413c7b3ff12 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Manuel=20P=C3=A9gouri=C3=A9-Gonnard?= Date: Thu, 30 Mar 2023 09:37:39 +0200 Subject: [PATCH 5/5] Fix a typo MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Manuel Pégourié-Gonnard --- docs/use-psa-crypto.md | 2 +- include/mbedtls/mbedtls_config.h | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/use-psa-crypto.md b/docs/use-psa-crypto.md index 7c0397f62c..9d783d5c83 100644 --- a/docs/use-psa-crypto.md +++ b/docs/use-psa-crypto.md @@ -17,7 +17,7 @@ module. **Why enable this option:** to fully take advantage of PSA drivers in PK, X.509 and TLS. For example, enabling this option is what allows use of drivers -for ECDSA, ECDH and EC J-PAKE in those modules. However, note that ven with +for ECDSA, ECDH and EC J-PAKE in those modules. However, note that even with this option disabled, some code in PK, X.509, TLS or the crypto library might still use PSA drivers, if it can determine it's safe to do so; currently that's the case for hashes. diff --git a/include/mbedtls/mbedtls_config.h b/include/mbedtls/mbedtls_config.h index b16e1fcbbb..0ad6dccb99 100644 --- a/include/mbedtls/mbedtls_config.h +++ b/include/mbedtls/mbedtls_config.h @@ -1947,7 +1947,7 @@ * \note An important and desirable effect of this option is that it allows * PK, X.509 and TLS to take advantage of PSA drivers. For example, enabling * this option is what allows use of drivers for ECDSA, ECDH and EC J-PAKE in - * those modules. However, note that ven with this option disabled, some code + * those modules. However, note that even with this option disabled, some code * in PK, X.509, TLS or the crypto library might still use PSA drivers, if it * can determine it's safe to do so; currently that's the case for hashes. *