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 4d72f990d7..9d783d5c83 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 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. + **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. @@ -22,7 +29,7 @@ module. `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 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 diff --git a/include/mbedtls/mbedtls_config.h b/include/mbedtls/mbedtls_config.h index ef3cf2408b..0ad6dccb99 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 @@ -1933,9 +1944,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 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. * * \note See docs/use-psa-crypto.md for a complete description this option. *