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