Remove USE_PSA from use-psa-crypto.md
MBED_TLS_USE_PSA_CRYPTO is now always enabled we need to remove
documentation discussing cases when it is disabled.
Signed-off-by: Janos Follath <janos.follath@arm.com>
diff --git a/docs/use-psa-crypto.md b/docs/use-psa-crypto.md
index f2983bd..458b815 100644
--- a/docs/use-psa-crypto.md
+++ b/docs/use-psa-crypto.md
@@ -1,77 +1,28 @@
-This document describes the compile-time configuration option
-`MBEDTLS_USE_PSA_CRYPTO` from a user's perspective.
+This document describes how PSA Crypto is used in the X.509 and TLS libraries
+from a user's perspective.
-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
+In particular:
+- X.509 and TLS libraries use PSA for cryptographic operations as much as
+ possible, see "Internal changes" below;
+- 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.
+"PSA key APIs" below.
General considerations
----------------------
-**Application code:** when this option is enabled, you need to call
-`psa_crypto_init()` before calling any function from the SSL/TLS, X.509 or PK
-modules, except for the various mbedtls_xxx_init() functions which can be called
-at any time.
+**Application code:** you need to call `psa_crypto_init()` before calling any
+function from the SSL/TLS, X.509 or PK modules, except for the various
+mbedtls_xxx_init() functions which can be called at any time.
-**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.
- 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 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;
-- X.509 certificate chain verification.
-You need to enable `MBEDTLS_USE_PSA_CRYPTO` if you want TLS 1.3 to use PSA
-everywhere.
-
-**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
+PSA Key APIs
-------------------------
### PSA-held (opaque) keys in the PK layer
-**New API function:** `mbedtls_pk_setup_opaque()` - can be used to
-wrap a PSA key pair into a PK context. The key can be used for private-key
-operations and its public part can be exported.
+**API function:** `mbedtls_pk_setup_opaque()` - can be used to wrap a PSA key
+pair into a PK context. The key can be used for private-key operations and its
+public part can be exported.
**Benefits:** isolation of long-term secrets, use of PSA Crypto drivers.
@@ -90,7 +41,7 @@
### PSA-held (opaque) keys for TLS pre-shared keys (PSK)
-**New API functions:** `mbedtls_ssl_conf_psk_opaque()` and
+**API functions:** `mbedtls_ssl_conf_psk_opaque()` and
`mbedtls_ssl_set_hs_psk_opaque()`. Call one of these from an application to
register a PSA key for use with a PSK key exchange.
@@ -99,24 +50,24 @@
**Limitations:** none.
**Use in TLS:** opt-in. The application needs to register the key using one of
-the new APIs to get the benefits.
+the above APIs to get the benefits.
### PSA-held (opaque) keys for TLS 1.2 EC J-PAKE key exchange
-**New API function:** `mbedtls_ssl_set_hs_ecjpake_password_opaque()`.
-Call this function from an application to register a PSA key for use with the
-TLS 1.2 EC J-PAKE key exchange.
+**API function:** `mbedtls_ssl_set_hs_ecjpake_password_opaque()`. Call this
+function from an application to register a PSA key for use with the TLS 1.2 EC
+J-PAKE key exchange.
**Benefits:** isolation of long-term secrets.
**Limitations:** none.
**Use in TLS:** opt-in. The application needs to register the key using one of
-the new APIs to get the benefits.
+the above APIs to get the benefits.
### PSA-based operations in the Cipher layer
-There is a new API function `mbedtls_cipher_setup_psa()` to set up a context
+There is an API function `mbedtls_cipher_setup_psa()` to set up a context
that will call PSA to store the key and perform the operations.
This function only worked for a small number of ciphers. It is now deprecated
@@ -127,11 +78,10 @@
you are using it and would like us to keep it, please let us know about your
use case.
-Internal changes
+Internal uses
----------------
-All of these internal changes are active as soon as `MBEDTLS_USE_PSA_CRYPTO`
-is enabled, no change required on the application side.
+All of these internal uses are relying on PSA Crypto.
### TLS: most crypto operations based on PSA
@@ -142,8 +92,7 @@
- Restartable operations when `MBEDTLS_ECP_RESTARTABLE` is also enabled (see
the documentation of that option).
-Other than the above exceptions, all crypto operations are based on PSA when
-`MBEDTLS_USE_PSA_CRYPTO` is enabled.
+Other than the above exceptions, all crypto operations are based on PSA.
### X.509: most crypto operations based on PSA
@@ -152,8 +101,7 @@
- Restartable operations when `MBEDTLS_ECP_RESTARTABLE` is also enabled (see
the documentation of that option).
-Other than the above exception, all crypto operations are based on PSA when
-`MBEDTLS_USE_PSA_CRYPTO` is enabled.
+Other than the above exception, all crypto operations are based on PSA.
### PK layer: most crypto operations based on PSA
@@ -164,6 +112,5 @@
- Restartable operations when `MBEDTLS_ECP_RESTARTABLE` is also enabled (see
the documentation of that option).
-Other than the above exceptions, all crypto operations are based on PSA when
-`MBEDTLS_USE_PSA_CRYPTO` is enabled.
+Other than the above exceptions, all crypto operations are based on PSA.