Update docs/use-psa-crypto.md
The scope of the option has been expanded, now it makes more sense to
describe it as "everything except ...".
Signed-off-by: Manuel Pégourié-Gonnard <manuel.pegourie-gonnard@arm.com>
diff --git a/docs/use-psa-crypto.md b/docs/use-psa-crypto.md
index 4058cb6..b9983b7 100644
--- a/docs/use-psa-crypto.md
+++ b/docs/use-psa-crypto.md
@@ -1,9 +1,5 @@
This document describes the compile-time configuration option
-`MBEDTLS_USE_PSA_CRYPTO` from a user's perspective, more specifically its
-current effects as well as the parts that aren't covered yet.
-
-Current effects
-===============
+`MBEDTLS_USE_PSA_CRYPTO` from a user's perspective.
General limitations
-------------------
@@ -20,17 +16,6 @@
New APIs / API extensions
-------------------------
-Some of these APIs are meant for the application to use in place of
-pre-existing APIs, in order to get access to the benefits; in the sub-sections
-below these are indicated by "Use in (X.509 and) TLS: opt-in", meaning that
-this requires changes to the application code for the (X.509 and) TLS layers
-to pick up the improvements.
-
-Some of these APIs are mostly meant for internal use by the TLS (and X.509)
-layers; they are indicated below by "Use in (X.509 and) TLS: automatic",
-meaning that no changes to the application code are required for the TLS (and
-X.509) layers to pick up the improvements.
-
### PSA-held (opaque) keys in the PK layer
There is a new API function `mbedtls_pk_setup_opaque()` that can be used to
@@ -39,12 +24,12 @@
Benefits: isolation of long-term secrets, use of PSA Crypto drivers.
-Limitations: only for private keys, only ECC. (That is, only ECDSA signature
-generation. Note: currently this will use randomized ECDSA while Mbed TLS uses
-deterministic ECDSA by default.) The following operations are not supported
+Limitations: can only wrap a keypair, can only use it for private key
+operations. (That is, signature generation, and for RSA decryption too.)
+Note: for ECDSA, currently this uses randomized ECDSA while Mbed TLS uses
+deterministic ECDSA by default. The following operations are not supported
with a context set this way, while they would be available with a normal
-`ECKEY` context: `mbedtls_pk_verify()`, `mbedtls_pk_check_pair()`,
-`mbedtls_pk_debug()`.
+`mbedtls_pk_check_pair()`, `mbedtls_pk_debug()`, all public key operations.
Use in X.509 and TLS: opt-in. The application needs to construct the PK context
using the new API in order to get the benefits; it can then pass the
@@ -55,10 +40,7 @@
this is supported on both sides, it's currently only tested client-side);
- `mbedtls_x509write_csr_set_key()` to generate a CSR (certificate signature
request).
-
-In the TLS and X.509 API, there's one other function which accepts a keypair
-as a PK context: `mbedtls_x509write_crt_set_issuer_key()`. Use of opaque
-contexts here probably works but is so far untested.
+- `mbedtls_x509write_crt_set_issuer_key()` to generate a certificate.
### PSA-held (opaque) keys for TLS pre-shared keys (PSK)
@@ -68,13 +50,7 @@
Benefits: isolation of long-term secrets.
-Limitations: the key can only be used with "pure"
-PSK key exchanges (ciphersuites starting with `TLS_PSK_WITH_`), to the
-exclusion of RSA-PSK, DHE-PSK and ECDHE-PSK key exchanges. It is the responsibility of
-the user to make sure that when provisioning an opaque pre-shared key, the
-only PSK ciphersuites that can be negotiated are "pure" PSK; other XXX-PSK key
-exchanges will result in a handshake failure with the handshake function
-returning `MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE`.
+Limitations: only TLS 1.2 for now.
Use in TLS: opt-in. The application needs to register the key using the new
APIs to get the benefits.
@@ -84,21 +60,12 @@
There is a new API function `mbedtls_cipher_setup_psa()` to set up a context
that will call PSA to store the key and perform the operations.
-Benefits: use of PSA Crypto drivers; partial isolation of short-term secrets
-(still generated outside of PSA, but then held by PSA).
+This function only worked for a small number of ciphers. It is now deprecated
+and it is recommended to use `psa_cipher_xxx()` or `psa_aead_xxx()` functions
+directly instead.
-Limitations: the key is still passed in the clear by the application. The
-multi-part APIs are not supported, only the one-shot APIs. The only modes
-supported are ECB, CBC without padding, GCM and CCM (this excludes stream
-ciphers and ChachaPoly); the only cipher supported is AES (this excludes Aria,
-Camellia, and ChachaPoly). (Note: ECB is currently not tested.) (Note: it is
-possible to perform multiple one-shot operations with the same context;
-however this is not unit-tested, only tested via usage in TLS.)
-
-Use in TLS: automatic. Used when the cipher and mode is supported (with
-gracious fallback to the legacy API otherwise) in all places where a cipher is
-used. There are two such places: in `ssl_tls.c` for record protection, and in
-`ssl_ticket.c` for protecting tickets we issue.
+This function will be removed in a future version of Mbed TLS. If you are using
+it and would like us to keep it, please let us know about your use case.
Internal changes
----------------
@@ -106,89 +73,34 @@
All of these internal changes are active as soon as `MBEDTLS_USE_PSA_CRYPTO`
is enabled, no change required on the application side.
-### TLS: cipher operations based on PSA
+### TLS: most crypto operations based on PSA
-See "PSA-based operations in the Cipher layer" above.
+Current exceptions:
-### PK layer: ECDSA verification based on PSA
+- EC J-PAKE (when `MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED`)
+- finite-field (non-EC) Diffie-Hellman (use in key exchanges: DHE-RSA,
+ DHE-PSK)
-Scope: `mbedtls_pk_verify()` will call to PSA for ECDSA signature
-verification.
+Other than the above exceptions, all crypto operations are based on PSA when
+`MBEDTLS_USE_PSA_CRYPTO` is enabled.
-Benefits: use of PSA Crypto drivers.
+### X.509: most crypto operations based on PSA
-Use in TLS and X.509: in all places where an ECDSA signature is verified.
+Current exception:
-### TLS: ECDHE computation based on PSA
+- verification of RSA-PSS signatures with a salt length that is different from
+ the hash length.
-Scope: Client-side, for ECDHE-RSA and ECDHE-ECDSA key exchanges, the
-computation of the ECDHE key exchange is done by PSA.
+Other than the above exceptions, all crypto operations are based on PSA when
+`MBEDTLS_USE_PSA_CRYPTO` is enabled.
-Limitations: client-side only, ECDHE-PSK not covered
+### PK layer: most crypto operations based on PSA
-Benefits: use of PSA Crypto drivers.
+Current exception:
-### TLS: handshake hashes and PRF computed with PSA
+- verification of RSA-PSS signatures with a salt length that is different from
+ the hash length.
-Scope: with TLS 1.2, the following are computed with PSA:
-- the running handshake hashes;
-- the hash of the ServerKeyExchange part that is signed;
-- the `verify_data` part of the Finished message;
-- the TLS PRF.
+Other than the above exceptions, all crypto operations are based on PSA when
+`MBEDTLS_USE_PSA_CRYPTO` is enabled.
-Benefits: use of PSA Crypto drivers.
-
-### X.509: some hashes computed with PSA
-
-Scope: the following hashes are computed with PSA:
-- when verifying a certificate chain, hash of the child for verifying the
- parent's signature;
-- when writing a CSR, hash of the request for self-signing the request.
-
-Benefits: use of PSA Crypto drivers.
-
-Parts that are not covered yet
-==============================
-
-This is only a high-level overview, grouped by theme
-
-TLS: key exchanges / asymmetric crypto
---------------------------------------
-
-The following key exchanges are not covered at all:
-
-- RSA
-- DHE-RSA
-- DHE-PSK
-- RSA-PSK
-- ECDHE-PSK
-- ECDH-RSA
-- ECDH-ECDSA
-- ECJPAKE
-
-The following key exchanges are only partially covered:
-
-- ECDHE-RSA: RSA operations are not covered and, server-side, the ECDHE
- operation isn't either
-- ECDHE-ECDSA: server-side, the ECDHE operation isn't covered. (ECDSA
- signature generation is only covered if using `mbedtls_pk_setup_opaque()`.)
-
-PSK if covered when the application uses `mbedtls_ssl_conf_psk_opaque()` or
-`mbedtls_ssl_set_hs_psk_opaque()`.
-
-TLS: symmetric crypto
----------------------
-
-- some ciphers not supported via PSA yet: ARIA, Camellia, ChachaPoly (silent
- fallback to the legacy APIs)
-- the HMAC part of the CBC and NULL ciphersuites
-- the HMAC computation in `ssl_cookie.c`
-
-X.509
------
-
-- most hash operations are still done via the legacy API, except the few that
- are documented above as using PSA
-- RSA PKCS#1 v1.5 signature generation (from PSA-held keys)
-- RSA PKCS#1 v1.5 signature verification
-- RSA-PSS signature verification
