Try again to clarify USE_PSA_CRYPTO

Signed-off-by: Manuel Pégourié-Gonnard <manuel.pegourie-gonnard@arm.com>

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
+This option:
-operations, and enables new APIs for using keys handled by PSA Crypto.
+- 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
+**Relationship with other options:** This option depends on
-code, which always uses PSA crypto. The parts of the TLS 1.3 code that will
+`MBEDTLS_PSA_CRYPTO_C`. These two options differ in the following way:
-use PSA Crypto or not depending on the value of this option are:
+- `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
+**Historical note:** This option was introduced at a time when PSA Crypto was
-PSA Crypto. However, it is then their responsibility to make sure it's safe to
+still beta and not ready for production, so we made its use in X.509 and TLS
-do so; in particular those modules do not require `psa_crypto_init()` to be
+opt-in: by default, these modules would keep using the stable,
-called. So, enabling `MBEDTLS_USE_PSA_CRYPTO` basically means:
+production-ready legacy (pre-PSA) crypto APIs. So, the scope of was X.509 and
-- as a user, you promise to call `psa_crypto_init()` before using any function
+TLS, as well as some of PK for technical reasons. Nowadays PSA Crypto is no
-  from PK, X.509 or TLS;
+longer beta, and production quality, so there's no longer any reason to make
-- in return, those modules will use PSA Crypto as much as possible (see
+its use in other modules opt-in. However, PSA Crypto functions require that
-  exceptions belos).
+`psa_crypto_init()` has been called before their use, and for backwards
-Conversely, not enabling this option means you have no obligation to call
+compatibility reasons we can't impose this requirement on non-PSA functions
-`psa_crypto_init()` (unless as documented by other options  such as TLS 1.3),
+that didn't have such a requirement before. So, nowadays the main meaning of
-but modules can still decide to use PSA if they can determine it is available
+`MBEDTLS_USE_PSA_CRYPTO` is that the user promises to call `psa_crypto_init()`
-and initialized.
+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
 -------------------------

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
+ * Make the X.509 and TLS libraries use PSA for cryptographic operations as
- * enable new APIs for using keys handled by PSA Crypto.
+ * 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.