This document describes the compile-time configuration option MBEDTLS_USE_PSA_CRYPTO
from a user's perspective.
Compile-time: enabling MBEDTLS_USE_PSA_CRYPTO
requires MBEDTLS_ECP_RESTARTABLE
and MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER
to be disabled.
Scope: MBEDTLS_USE_PSA_CRYPTO
has no effect on the parts of the code that are specific to TLS 1.3; those parts always use PSA Crypto. The parts of the TLS 1.3 code that are common with TLS 1.2, however, follow this option (this is currently just the record protection code).
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: 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 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 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).mbedtls_x509write_crt_set_issuer_key()
to generate a certificate.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: 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.
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.
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.
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.
All of these internal changes are active as soon as MBEDTLS_USE_PSA_CRYPTO
is enabled, no change required on the application side.
Current exceptions:
MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED
)Other than the above exceptions, all crypto operations are based on PSA when MBEDTLS_USE_PSA_CRYPTO
is enabled.
Current exception:
Other than the above exceptions, all crypto operations are based on PSA when MBEDTLS_USE_PSA_CRYPTO
is enabled.
Current exception:
Other than the above exceptions, all crypto operations are based on PSA when MBEDTLS_USE_PSA_CRYPTO
is enabled.