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