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. *