1This document describes the compile-time configuration option 2`MBEDTLS_USE_PSA_CRYPTO` from a user's perspective. 3 4This option makes the X.509 and TLS library use PSA for cryptographic 5operations, and enables new APIs for using keys handled by PSA Crypto. 6 7General considerations 8---------------------- 9 10**Application code:** when this option is enabled, you need to call 11`psa_crypto_init()` before calling any function from the SSL/TLS, X.509 or PK 12module. 13 14**Scope:** `MBEDTLS_USE_PSA_CRYPTO` has no effect on the most of the TLS 1.3 15code, which always uses PSA crypto. The parts of the TLS 1.3 code that will 16use PSA Crypto or not depending on the value of this option are: 17- record protection; 18- running handshake hash; 19- asymmetric signature verification & generation; 20- X.509 certificate chain verification. 21You need to enable `MBEDTLS_USE_PSA_CRYPTO` if you want TLS 1.3 to use PSA 22everywhere. 23 24New APIs / API extensions 25------------------------- 26 27### PSA-held (opaque) keys in the PK layer 28 29**New API function:** `mbedtls_pk_setup_opaque()` - can be used to 30wrap a PSA key pair into a PK context. The key can be used for private-key 31operations and its public part can be exported. 32 33**Benefits:** isolation of long-term secrets, use of PSA Crypto drivers. 34 35**Limitations:** can only wrap a key pair, can only use it for private key 36operations. (That is, signature generation, and for RSA decryption too.) 37Note: for ECDSA, currently this uses randomized ECDSA while Mbed TLS uses 38deterministic ECDSA by default. The following operations are not supported 39with a context set this way, while they would be available with a normal 40context: `mbedtls_pk_check_pair()`, `mbedtls_pk_debug()`, all public key 41operations. 42 43**Use in X.509 and TLS:** opt-in. The application needs to construct the PK context 44using the new API in order to get the benefits; it can then pass the 45resulting context to the following existing APIs: 46 47- `mbedtls_ssl_conf_own_cert()` or `mbedtls_ssl_set_hs_own_cert()` to use the 48 key together with a certificate for certificate-based key exchanges; 49- `mbedtls_x509write_csr_set_key()` to generate a CSR (certificate signature 50 request); 51- `mbedtls_x509write_crt_set_issuer_key()` to generate a certificate. 52 53### PSA-held (opaque) keys for TLS pre-shared keys (PSK) 54 55**New API functions:** `mbedtls_ssl_conf_psk_opaque()` and 56`mbedtls_ssl_set_hs_psk_opaque()`. Call one of these from an application to 57register a PSA key for use with a PSK key exchange. 58 59**Benefits:** isolation of long-term secrets. 60 61**Limitations:** none. 62 63**Use in TLS:** opt-in. The application needs to register the key using one of 64the new APIs to get the benefits. 65 66### PSA-based operations in the Cipher layer 67 68There is a new API function `mbedtls_cipher_setup_psa()` to set up a context 69that will call PSA to store the key and perform the operations. 70 71This function only worked for a small number of ciphers. It is now deprecated 72and it is recommended to use `psa_cipher_xxx()` or `psa_aead_xxx()` functions 73directly instead. 74 75**Warning:** This function will be removed in a future version of Mbed TLS. If 76you are using it and would like us to keep it, please let us know about your 77use case. 78 79Internal changes 80---------------- 81 82All of these internal changes are active as soon as `MBEDTLS_USE_PSA_CRYPTO` 83is enabled, no change required on the application side. 84 85### TLS: most crypto operations based on PSA 86 87Current exceptions: 88 89- Finite-field (non-EC) Diffie-Hellman (used in key exchanges: DHE-RSA, 90 DHE-PSK). 91- Restartable operations when `MBEDTLS_ECP_RESTARTABLE` is also enabled (see 92 the documentation of that option). 93 94Other than the above exceptions, all crypto operations are based on PSA when 95`MBEDTLS_USE_PSA_CRYPTO` is enabled. 96 97### X.509: most crypto operations based on PSA 98 99Current exceptions: 100 101- Restartable operations when `MBEDTLS_ECP_RESTARTABLE` is also enabled (see 102 the documentation of that option). 103 104Other than the above exception, all crypto operations are based on PSA when 105`MBEDTLS_USE_PSA_CRYPTO` is enabled. 106 107### PK layer: most crypto operations based on PSA 108 109Current exceptions: 110 111- Verification of RSA-PSS signatures with an MGF hash that's different from 112 the message hash. 113- Restartable operations when `MBEDTLS_ECP_RESTARTABLE` is also enabled (see 114 the documentation of that option). 115 116Other than the above exceptions, all crypto operations are based on PSA when 117`MBEDTLS_USE_PSA_CRYPTO` is enabled. 118 119