From 04bc6875a00a15e3c118d0d5b5e7ba97bf958203 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Manuel=20P=C3=A9gouri=C3=A9-Gonnard?= Date: Tue, 21 Sep 2021 11:21:23 +0200 Subject: [PATCH] Document current effects of 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 | 144 ++++++++++++++++++++++++++++++++++++++++- 1 file changed, 141 insertions(+), 3 deletions(-) diff --git a/docs/use-psa-crypto.md b/docs/use-psa-crypto.md index a4f43b783..d1298af2b 100644 --- a/docs/use-psa-crypto.md +++ b/docs/use-psa-crypto.md @@ -5,10 +5,148 @@ considerations and plans for the future. Current effects =============== -(To be written.) +General limitations +------------------- -Parts that are not affected yet -=============================== +Compile-time: enabling `MBEDTLS_USE_PSA_CRYPTO` requires +`MBEDTLS_ECP_RESTARTABLE` and +`MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER` to be disabled. + +Effect: `MBEDTLS_USE_PSA_CRYPTO` currently has no effect on TLS 1.3 (which is +itself experimental and only partially supported so far): TLS 1.3 always uses +the legacy APIs even when this option is set. + +Stability: any API that's only available when `MBEDTLS_USE_PSA_CRYPTO` is +defined is considered experimental and may change in incompatible ways at any +time. Said otherwise, these APIs are explicitly excluded from the usual API +stability promises. + +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 + +Add `mbedtls_pk_setup_opaque()` to wrap a PSA keypair into a PK context. The key +can be used for private-key operations and its public part can be written out. + +Benefits: isolation of long-term secrets, use of PSA Crypto drivers. + +Limitations: only for private keys, only ECC. (That is, only ECDSA signature +generation.) 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()`. + +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 +resulting context to the following existing APIs: + +- `mbedtls_ssl_conf_own_cert()` or `mbedtls_ssl_set_hs_own_cert()` to use the + key together with a certificate for ECDSA-based key exchanges; +- `mbedtls_x509write_csr_set_key()` to generate a CSR (certificate signature + request). + +In the TLS and X.509 API, there's two other function which accept a key or +keypair as a PK context: `mbedtls_x509write_crt_set_subject_key()` and +`mbedtls_x509write_crt_set_issuer_key()`. Use of opaque contexts here probably +works but is so far untested. + +### PSA-held (opaque) keys for TLS 1.2 pre-shared keys (PSK) + +Add `mbedtls_ssl_conf_psk_opaque()` and `mbedtls_ssl_set_hs_psk_opaque()` to +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 with TLS 1.2, and only 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`. + +Use in TLS: opt-in. The application needs to register the key using the new +APIs to get the benefits. + +### PSA-based operations in the Cipher layer + +Add `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). + +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). + +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. + +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 + +See "PSA-based operations in the Cipher layer" above. + +### PK layer: ECDSA verification based on PSA + +Scope: `mbedtls_pk_verify()` will call to PSA for ECDSA signature +verification. + +Benefits: use of PSA Crypto drivers. + +Use in TLS and X.509: in all places where an ECDSA signature is verified. + +### TLS: ECDHE computation based on PSA + +Scope: Client-side, for ECDHE-RSA and ECDHE-ECDSA key exchanges, the +computation of the ECDHE key exchange is done by PSA. + +Limitations: client-side only, ECDHE-PSK not covered + +Benefits: use of PSA Crypto drivers. + +### TLS: handshake hashes and PRF computed with PSA + +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. + +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 +============================== (To be written.)