diff --git a/docs/use-psa-crypto.md b/docs/use-psa-crypto.md new file mode 100644 index 000000000..6ec2dcaa1 --- /dev/null +++ b/docs/use-psa-crypto.md @@ -0,0 +1,204 @@ +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 +=============== + +General limitations +------------------- + +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 + +There is a new API function `mbedtls_pk_setup_opaque()` that can be used to +wrap a PSA keypair 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. + +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 +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 (note: while +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 are two other functions 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 pre-shared keys (PSK) + +There are two new 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. + +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`. + +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 + +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). + +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. + +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 +============================== + +This is only a high-level overview, grouped by theme + +TLS: 1.3 experimental support +----------------------------- + +No part of the experimental support for TLS 1.3 is covered at the moment. + +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 diff --git a/include/mbedtls/config.h b/include/mbedtls/config.h index 2c7bed206..3c9967ec4 100644 --- a/include/mbedtls/config.h +++ b/include/mbedtls/config.h @@ -2119,15 +2119,13 @@ * will still continue to work as usual, so enabling this option should not * break backwards compatibility. * - * \warning The PSA Crypto API is in beta stage. While you're welcome to - * experiment using it, incompatible API changes are still possible, and some - * parts may not have reached the same quality as the rest of Mbed TLS yet. + * \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 This option enables new Mbed TLS APIs that are dependent on the - * PSA Crypto API, so can't come with the same stability guarantees as the - * rest of the Mbed TLS APIs. You're welcome to experiment with them, but for - * now, access to these APIs is opt-in (via enabling the present option), in - * order to clearly differentiate them from the stable Mbed TLS APIs. + * \warning This option enables new Mbed TLS APIs which are currently + * considered experimental and may change in incompatible ways at any time. + * That is, the APIs enabled by this option are not covered by the usual + * promises of API stability. * * Requires: MBEDTLS_PSA_CRYPTO_C. * @@ -3199,10 +3197,6 @@ * * Enable the Platform Security Architecture cryptography API. * - * \warning The PSA Crypto API is still beta status. While you're welcome to - * experiment using it, incompatible API changes are still possible, and some - * parts may not have reached the same quality as the rest of Mbed TLS yet. - * * Module: library/psa_crypto.c * * Requires: either MBEDTLS_CTR_DRBG_C and MBEDTLS_ENTROPY_C,