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.
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 has no effect on TLS 1.3 for which PSA cryptography is mandatory.
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.
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.
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.
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.
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.
All of these internal changes are active as soon as MBEDTLS_USE_PSA_CRYPTO is enabled, no change required on the application side.
See “PSA-based operations in the Cipher layer” above.
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.
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.
Scope: with TLS 1.2, the following are computed with PSA:
verify_data part of the Finished message;Benefits: use of PSA Crypto drivers.
Scope: the following hashes are computed with PSA:
Benefits: use of PSA Crypto drivers.
This is only a high-level overview, grouped by theme
The following key exchanges are not covered at all:
The following key exchanges are only partially covered:
mbedtls_pk_setup_opaque().)PSK if covered when the application uses mbedtls_ssl_conf_psk_opaque() or mbedtls_ssl_set_hs_psk_opaque().
ssl_cookie.c