Inaccurate documentation of crypto dependencies between configuration options in 3.6

[gilles-peskine-arm]

In mbedtls_config.h, as of Mbed TLS 3.6.2, the documentation of many “Requires” statement is inaccurate because it doesn't take into account all possible variations of MBEDTLS_PSA_CRYPTO_CONFIG and MBEDTLS_USE_PSA_CRYPTO. At least some of these inaccuracies have been present since the 2.x days, but in this issue I'll focus on 3.6.

For functionality that is provided by the PK, X.509 and SSL modules, each cryptographic mechanism must be available through the PSA API when MBEDTLS_USE_PSA_CRYPTO is enabled, and must be available through the legacy API when MBEDTLS_USE_PSA_CRYPTO is disabled. Thus, for example, for MBEDTLS_KEY_EXCHANGE_ECDHE_PSK_ENABLED, the requirements are:

(!MBEDTLS_USE_PSA_CRYPTO && MBEDTLS_ECDH_C) ||
(MBEDTLS_USE_PSA_CRYPTO && PSA_WANT_ALG_ECDH)

(Actually there's also a requirement on PSA_WANT_KEY_TYPE_ECC_KEY_PAIR_GENERATE in the PSA case, but that's a different issue.)

MBEDTLS_PSA_CRYPTO_CONFIG matters because when it's enabled, users are generally expected to use PSA_WANT_xxx options to decide which cryptographic mechanisms are enabled. When it's disabled, users are expected to use MBEDTLS_xxx options. So while the requirements above are correct, they aren't in a form that's helpful. The complete story is:

• If MBEDTLS_USE_PSA_CRYPTO is enabled, you must ensure that PSA_WANT_ALG_ECDH is enabled, which can be done in two ways:
  • By enabling it explicitly if MBEDTLS_PSA_CRYPTO_CONFIG is enabled.
  • By enabling MBEDTLS_ECDH_C if MBEDTLS_PSA_CRYPTO_CONFIG is disabled.
• If MBEDTLS_USE_PSA_CRYPTO is disabled, you must ensure that MBEDTLS_ECDH_C is enabled, which can be done in two ways:
  • By enabling it explicitly.
  • By enabling PSA_WANT_ALG_ECDH without enabling a suitable driver, if MBEDTLS_PSA_CRYPTO_CONFIG is enabled.

Note that there are exceptions to use-PSA support, see use-psa-crypto.md.

For hashes and elliptic curves, the situation is simpler, because we guarantee that any hash/curve that is available in the legacy API is also available in the PSA API. There is no such guarantee for other mechanisms (RSA, ECDH, ECDSA, ciphers, etc.).