From 2ca08c84091429876e9440a7481f338cd9ecd436 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Manuel=20P=C3=A9gouri=C3=A9-Gonnard?= Date: Fri, 24 Mar 2023 09:21:46 +0100 Subject: [PATCH] Try again to clarify USE_PSA_CRYPTO 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 | 56 ++++++++++++++++++++++---------- include/mbedtls/mbedtls_config.h | 13 +++++--- 2 files changed, 47 insertions(+), 22 deletions(-) diff --git a/docs/use-psa-crypto.md b/docs/use-psa-crypto.md index e0e9d1500b..f46d36ec1e 100644 --- a/docs/use-psa-crypto.md +++ b/docs/use-psa-crypto.md @@ -1,8 +1,12 @@ This document describes the compile-time configuration option `MBEDTLS_USE_PSA_CRYPTO` from a user's perspective. -This option makes the X.509 and TLS library use PSA for cryptographic -operations, and enables new APIs for using keys handled by PSA Crypto. +This option: +- makes the X.509 and TLS libraries use PSA for cryptographic operations as + much as possible, see "Internal changes" below; +- enables new APIs for using keys handled by PSA Crypto, such as + `mbedtls_pk_setup_opaque()` and `mbedtls_ssl_conf_psk_opaque()`, see +"New APIs / API extensions" below. General considerations ---------------------- @@ -11,9 +15,25 @@ General considerations `psa_crypto_init()` before calling any function from the SSL/TLS, X.509 or PK module. -**Scope:** `MBEDTLS_USE_PSA_CRYPTO` has no effect on the most of the TLS 1.3 -code, which always uses PSA crypto. The parts of the TLS 1.3 code that will -use PSA Crypto or not depending on the value of this option are: +**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. + When it is enabled, `psa_xxx()` APIs are available and you must call +`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). +- `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 +exceptions). When it is enabled, you need to call `psa_crypto_init()` before +calling any function from PK, X.509 or TLS; however it doesn't change anything +for the rest of the library. + +**Scope:** `MBEDTLS_USE_PSA_CRYPTO` has no effect on modules other than PK, +X.509 and TLS. It also has no effect on most of the TLS 1.3 code, which always +uses PSA crypto. The parts of the TLS 1.3 code that will use PSA Crypto or not +depending on this option being set or not are: - record protection; - running handshake hash; - asymmetric signature verification & generation; @@ -21,18 +41,20 @@ use PSA Crypto or not depending on the value of this option are: You need to enable `MBEDTLS_USE_PSA_CRYPTO` if you want TLS 1.3 to use PSA everywhere. -**Important note:** Even with this option disabled, some modules may still use -PSA Crypto. However, it is then their responsibility to make sure it's safe to -do so; in particular those modules do not require `psa_crypto_init()` to be -called. So, enabling `MBEDTLS_USE_PSA_CRYPTO` basically means: -- as a user, you promise to call `psa_crypto_init()` before using any function - from PK, X.509 or TLS; -- in return, those modules will use PSA Crypto as much as possible (see - exceptions belos). -Conversely, not enabling this option means you have no obligation to call -`psa_crypto_init()` (unless as documented by other options such as TLS 1.3), -but modules can still decide to use PSA if they can determine it is available -and initialized. +**Historical note:** This option was introduced at a time when PSA Crypto was +still beta and not ready for production, so we made its use in X.509 and TLS +opt-in: by default, these modules would keep using the stable, +production-ready legacy (pre-PSA) crypto APIs. So, the scope of was X.509 and +TLS, as well as some of PK for technical reasons. Nowadays PSA Crypto is no +longer beta, and production quality, so there's no longer any reason to make +its use in other modules opt-in. However, PSA Crypto functions require that +`psa_crypto_init()` has been called before their use, and for backwards +compatibility reasons we can't impose this requirement on non-PSA functions +that didn't have such a requirement before. So, nowadays the main meaning of +`MBEDTLS_USE_PSA_CRYPTO` is that the user promises to call `psa_crypto_init()` +before calling any PK, X.509 or TLS functions. For the same compatibility +reasons, we can't extend its scope. However, new modules in the library, such +as TLS 1.3, can be introduced with a requirement to call `psa_crypto_init()`. New APIs / API extensions ------------------------- diff --git a/include/mbedtls/mbedtls_config.h b/include/mbedtls/mbedtls_config.h index f47fdc4673..da48cc4600 100644 --- a/include/mbedtls/mbedtls_config.h +++ b/include/mbedtls/mbedtls_config.h @@ -1922,20 +1922,23 @@ /** * \def MBEDTLS_USE_PSA_CRYPTO * - * Make the X.509 and TLS library use PSA for cryptographic operations, and - * enable new APIs for using keys handled by PSA Crypto. + * Make the X.509 and TLS libraries use PSA for cryptographic operations as + * much as possible, and enable new APIs for using keys handled by PSA Crypto. * * \note Development of this option is currently in progress, and parts of Mbed * TLS's X.509 and TLS modules are not ported to PSA yet. However, these parts * will still continue to work as usual, so enabling this option should not * break backwards compatibility. * - * \note See docs/use-psa-crypto.md for a complete description of what this - * option currently does, and of parts that are not affected by it so far. - * * \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 See docs/use-psa-crypto.md for a complete description this option. + * * Requires: MBEDTLS_PSA_CRYPTO_C. * * Uncomment this to enable internal use of PSA Crypto and new associated APIs.