1This document describes the compile-time configuration option
2`MBEDTLS_USE_PSA_CRYPTO` from a user's perspective, more specifically its
3current effects as well as the parts that aren't covered yet.
4
5Current effects
6===============
7
8General limitations
9-------------------
10
11Compile-time: enabling `MBEDTLS_USE_PSA_CRYPTO` requires
12`MBEDTLS_ECP_RESTARTABLE` and
13`MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER` to be disabled.
14
15Effect: `MBEDTLS_USE_PSA_CRYPTO` currently has no effect on TLS 1.3 (which is
16itself experimental and only partially supported so far): TLS 1.3 always uses
17the legacy APIs even when this option is set.
18
19Stability: any API that's only available when `MBEDTLS_USE_PSA_CRYPTO` is
20defined is considered experimental and may change in incompatible ways at any
21time. Said otherwise, these APIs are explicitly excluded from the usual API
22stability promises.
23
24New APIs / API extensions
25-------------------------
26
27Some of these APIs are meant for the application to use in place of
28pre-existing APIs, in order to get access to the benefits; in the sub-sections
29below these are indicated by "Use in (X.509 and) TLS: opt-in", meaning that
30this requires changes to the application code for the (X.509 and) TLS layers
31to pick up the improvements.
32
33Some of these APIs are mostly meant for internal use by the TLS (and X.509)
34layers; they are indicated below by "Use in (X.509 and) TLS: automatic",
35meaning that no changes to the application code are required for the TLS (and
36X.509) layers to pick up the improvements.
37
38### PSA-held (opaque) keys in the PK layer
39
40There is a new API function `mbedtls_pk_setup_opaque()` that can be used to
41wrap a PSA keypair into a PK context. The key can be used for private-key
42operations and its public part can be exported.
43
44Benefits: isolation of long-term secrets, use of PSA Crypto drivers.
45
46Limitations: only for private keys, only ECC. (That is, only ECDSA signature
47generation. Note: currently this will use randomized ECDSA while Mbed TLS uses
48deterministic ECDSA by default.) The following operations are not supported
49with a context set this way, while they would be available with a normal
50`ECKEY` context: `mbedtls_pk_verify()`, `mbedtls_pk_check_pair()`,
51`mbedtls_pk_debug()`.
52
53Use in X.509 and TLS: opt-in. The application needs to construct the PK context
54using the new API in order to get the benefits; it can then pass the
55resulting context to the following existing APIs:
56
57- `mbedtls_ssl_conf_own_cert()` or `mbedtls_ssl_set_hs_own_cert()` to use the
58  key together with a certificate for ECDSA-based key exchanges (note: while
59this is supported on both sides, it's currently only tested client-side);
60- `mbedtls_x509write_csr_set_key()` to generate a CSR (certificate signature
61  request).
62
63In the TLS and X.509 API, there are two other functions which accept a key or
64keypair as a PK context: `mbedtls_x509write_crt_set_subject_key()` and
65`mbedtls_x509write_crt_set_issuer_key()`. Use of opaque contexts here probably
66works but is so far untested.
67
68### PSA-held (opaque) keys for TLS pre-shared keys (PSK)
69
70There are two new API functions `mbedtls_ssl_conf_psk_opaque()` and
71`mbedtls_ssl_set_hs_psk_opaque()`. Call one of these from an application to
72register a PSA key for use with a PSK key exchange.
73
74Benefits: isolation of long-term secrets.
75
76Limitations: the key can only be used with "pure"
77PSK key exchanges (ciphersuites starting with `TLS_PSK_WITH_`), to the
78exclusion of RSA-PSK, DHE-PSK and ECDHE-PSK key exchanges. It is the responsibility of
79the user to make sure that when provisioning an opaque pre-shared key, the
80only PSK ciphersuites that can be negotiated are "pure" PSK; other XXX-PSK key
81exchanges will result in a handshake failure with the handshake function
82returning `MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE`.
83
84Use in TLS: opt-in. The application needs to register the key using the new
85APIs to get the benefits.
86
87### PSA-based operations in the Cipher layer
88
89There is a new API function `mbedtls_cipher_setup_psa()` to set up a context
90that will call PSA to store the key and perform the operations.
91
92Benefits: use of PSA Crypto drivers; partial isolation of short-term secrets
93(still generated outside of PSA, but then held by PSA).
94
95Limitations: the key is still passed in the clear by the application. The
96multi-part APIs are not supported, only the one-shot APIs. The only modes
97supported are ECB, CBC without padding, GCM and CCM (this excludes stream
98ciphers and ChachaPoly); the only cipher supported is AES (this excludes Aria,
99Camellia, and ChachaPoly). (Note: ECB is currently not tested.) (Note: it is
100possible to perform multiple one-shot operations with the same context;
101however this is not unit-tested, only tested via usage in TLS.)
102
103Use in TLS: automatic. Used when the cipher and mode is supported (with
104gracious fallback to the legacy API otherwise) in all places where a cipher is
105used. There are two such places: in `ssl_tls.c` for record protection, and in
106`ssl_ticket.c` for protecting tickets we issue.
107
108Internal changes
109----------------
110
111All of these internal changes are active as soon as `MBEDTLS_USE_PSA_CRYPTO`
112is enabled, no change required on the application side.
113
114### TLS: cipher operations based on PSA
115
116See "PSA-based operations in the Cipher layer" above.
117
118### PK layer: ECDSA verification based on PSA
119
120Scope: `mbedtls_pk_verify()` will call to PSA for ECDSA signature
121verification.
122
123Benefits: use of PSA Crypto drivers.
124
125Use in TLS and X.509: in all places where an ECDSA signature is verified.
126
127### TLS: ECDHE computation based on PSA
128
129Scope: Client-side, for ECDHE-RSA and ECDHE-ECDSA key exchanges, the
130computation of the ECDHE key exchange is done by PSA.
131
132Limitations: client-side only, ECDHE-PSK not covered
133
134Benefits: use of PSA Crypto drivers.
135
136### TLS: handshake hashes and PRF computed with PSA
137
138Scope: with TLS 1.2, the following are computed with PSA:
139- the running handshake hashes;
140- the hash of the ServerKeyExchange part that is signed;
141- the `verify_data` part of the Finished message;
142- the TLS PRF.
143
144Benefits: use of PSA Crypto drivers.
145
146### X.509: some hashes computed with PSA
147
148Scope: the following hashes are computed with PSA:
149- when verifying a certificate chain, hash of the child for verifying the
150  parent's signature;
151- when writing a CSR, hash of the request for self-signing the request.
152
153Benefits: use of PSA Crypto drivers.
154
155Parts that are not covered yet
156==============================
157
158This is only a high-level overview, grouped by theme
159
160TLS: 1.3 experimental support
161-----------------------------
162
163No part of the experimental support for TLS 1.3 is covered at the moment.
164
165TLS: key exchanges / asymmetric crypto
166--------------------------------------
167
168The following key exchanges are not covered at all:
169
170- RSA
171- DHE-RSA
172- DHE-PSK
173- RSA-PSK
174- ECDHE-PSK
175- ECDH-RSA
176- ECDH-ECDSA
177- ECJPAKE
178
179The following key exchanges are only partially covered:
180
181- ECDHE-RSA: RSA operations are not covered and, server-side, the ECDHE
182  operation isn't either
183- ECDHE-ECDSA: server-side, the ECDHE operation isn't covered. (ECDSA
184  signature generation is only covered if using `mbedtls_pk_setup_opaque()`.)
185
186PSK if covered when the application uses `mbedtls_ssl_conf_psk_opaque()` or
187`mbedtls_ssl_set_hs_psk_opaque()`.
188
189TLS: symmetric crypto
190---------------------
191
192- some ciphers not supported via PSA yet: ARIA, Camellia, ChachaPoly (silent
193  fallback to the legacy APIs)
194- the HMAC part of the CBC and NULL ciphersuites
195- the HMAC computation in `ssl_cookie.c`
196
197X.509
198-----
199
200- most hash operations are still done via the legacy API, except the few that
201  are documented above as using PSA
202- RSA PKCS#1 v1.5 signature generation (from PSA-held keys)
203- RSA PKCS#1 v1.5 signature verification
204- RSA-PSS signature verification
205