From b2bd34ecdc9573ec45ab4c5941c76db954566da1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Manuel=20P=C3=A9gouri=C3=A9-Gonnard?= Date: Wed, 20 Apr 2022 15:58:00 +0200 Subject: [PATCH] Update docs/use-psa-crypto.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- docs/use-psa-crypto.md | 152 +++++++++-------------------------------- 1 file changed, 32 insertions(+), 120 deletions(-) diff --git a/docs/use-psa-crypto.md b/docs/use-psa-crypto.md index 4058cb65f..b9983b724 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 @@ is currently just the record protection code). 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 @@ operations and its public part can be exported. 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 @@ resulting context to the following existing APIs: 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 @@ register a PSA key for use with a PSK key exchange. 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 @@ APIs to get the benefits. 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 @@ Internal changes 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