use-psa-crypto.md (7316B)
1 This document describes the compile-time configuration option 2 `MBEDTLS_USE_PSA_CRYPTO` from a user's perspective. 3 4 This option: 5 - makes the X.509 and TLS libraries use PSA for cryptographic operations as 6 much as possible, see "Internal changes" below; 7 - enables new APIs for using keys handled by PSA Crypto, such as 8 `mbedtls_pk_setup_opaque()` and `mbedtls_ssl_conf_psk_opaque()`, see 9 "New APIs / API extensions" below. 10 11 General considerations 12 ---------------------- 13 14 **Application code:** when this option is enabled, you need to call 15 `psa_crypto_init()` before calling any function from the SSL/TLS, X.509 or PK 16 modules, except for the various mbedtls_xxx_init() functions which can be called 17 at any time. 18 19 **Why enable this option:** to fully take advantage of PSA drivers in PK, 20 X.509 and TLS. For example, enabling this option is what allows use of drivers 21 for ECDSA, ECDH and EC J-PAKE in those modules. However, note that even with 22 this option disabled, some code in PK, X.509, TLS or the crypto library might 23 still use PSA drivers, if it can determine it's safe to do so; currently 24 that's the case for hashes. 25 26 **Relationship with other options:** This option depends on 27 `MBEDTLS_PSA_CRYPTO_C`. These two options differ in the following way: 28 - `MBEDTLS_PSA_CRYPTO_C` enables the implementation of the PSA Crypto API. 29 When it is enabled, `psa_xxx()` APIs are available and you must call 30 `psa_crypto_init()` before you call any other `psa_xxx()` function. Other 31 modules in the library (non-PSA crypto APIs, X.509, TLS) may or may not use 32 PSA Crypto but you're not required to call `psa_crypto_init()` before calling 33 non-PSA functions, unless explicitly documented (TLS 1.3). 34 - `MBEDTLS_USE_PSA_CRYPTO` means that X.509 and TLS will use PSA Crypto as 35 much as possible (that is, everywhere except for features that are not 36 supported by PSA Crypto, see "Internal Changes" below for a complete list of 37 exceptions). When it is enabled, you need to call `psa_crypto_init()` before 38 calling any function from PK, X.509 or TLS; however it doesn't change anything 39 for the rest of the library. 40 41 **Scope:** `MBEDTLS_USE_PSA_CRYPTO` has no effect on modules other than PK, 42 X.509 and TLS. It also has no effect on most of the TLS 1.3 code, which always 43 uses PSA crypto. The parts of the TLS 1.3 code that will use PSA Crypto or not 44 depending on this option being set or not are: 45 - record protection; 46 - running handshake hash; 47 - asymmetric signature verification & generation; 48 - X.509 certificate chain verification. 49 You need to enable `MBEDTLS_USE_PSA_CRYPTO` if you want TLS 1.3 to use PSA 50 everywhere. 51 52 **Historical note:** This option was introduced at a time when PSA Crypto was 53 still beta and not ready for production, so we made its use in X.509 and TLS 54 opt-in: by default, these modules would keep using the stable, 55 production-ready legacy (pre-PSA) crypto APIs. So, the scope of was X.509 and 56 TLS, as well as some of PK for technical reasons. Nowadays PSA Crypto is no 57 longer beta, and production quality, so there's no longer any reason to make 58 its use in other modules opt-in. However, PSA Crypto functions require that 59 `psa_crypto_init()` has been called before their use, and for backwards 60 compatibility reasons we can't impose this requirement on non-PSA functions 61 that didn't have such a requirement before. So, nowadays the main meaning of 62 `MBEDTLS_USE_PSA_CRYPTO` is that the user promises to call `psa_crypto_init()` 63 before calling any PK, X.509 or TLS functions. For the same compatibility 64 reasons, we can't extend its scope. However, new modules in the library, such 65 as TLS 1.3, can be introduced with a requirement to call `psa_crypto_init()`. 66 67 New APIs / API extensions 68 ------------------------- 69 70 ### PSA-held (opaque) keys in the PK layer 71 72 **New API function:** `mbedtls_pk_setup_opaque()` - can be used to 73 wrap a PSA key pair into a PK context. The key can be used for private-key 74 operations and its public part can be exported. 75 76 **Benefits:** isolation of long-term secrets, use of PSA Crypto drivers. 77 78 **Limitations:** please refer to the documentation of `mbedtls_pk_setup_opaque()` 79 for a full list of supported operations and limitations. 80 81 **Use in X.509 and TLS:** opt-in. The application needs to construct the PK context 82 using the new API in order to get the benefits; it can then pass the 83 resulting context to the following existing APIs: 84 85 - `mbedtls_ssl_conf_own_cert()` or `mbedtls_ssl_set_hs_own_cert()` to use the 86 key together with a certificate for certificate-based key exchanges; 87 - `mbedtls_x509write_csr_set_key()` to generate a CSR (certificate signature 88 request); 89 - `mbedtls_x509write_crt_set_issuer_key()` to generate a certificate. 90 91 ### PSA-held (opaque) keys for TLS pre-shared keys (PSK) 92 93 **New API functions:** `mbedtls_ssl_conf_psk_opaque()` and 94 `mbedtls_ssl_set_hs_psk_opaque()`. Call one of these from an application to 95 register a PSA key for use with a PSK key exchange. 96 97 **Benefits:** isolation of long-term secrets. 98 99 **Limitations:** none. 100 101 **Use in TLS:** opt-in. The application needs to register the key using one of 102 the new APIs to get the benefits. 103 104 ### PSA-held (opaque) keys for TLS 1.2 EC J-PAKE key exchange 105 106 **New API function:** `mbedtls_ssl_set_hs_ecjpake_password_opaque()`. 107 Call this function from an application to register a PSA key for use with the 108 TLS 1.2 EC J-PAKE key exchange. 109 110 **Benefits:** isolation of long-term secrets. 111 112 **Limitations:** none. 113 114 **Use in TLS:** opt-in. The application needs to register the key using one of 115 the new APIs to get the benefits. 116 117 ### PSA-based operations in the Cipher layer 118 119 There is a new API function `mbedtls_cipher_setup_psa()` to set up a context 120 that will call PSA to store the key and perform the operations. 121 122 This function only worked for a small number of ciphers. It is now deprecated 123 and it is recommended to use `psa_cipher_xxx()` or `psa_aead_xxx()` functions 124 directly instead. 125 126 **Warning:** This function will be removed in a future version of Mbed TLS. If 127 you are using it and would like us to keep it, please let us know about your 128 use case. 129 130 Internal changes 131 ---------------- 132 133 All of these internal changes are active as soon as `MBEDTLS_USE_PSA_CRYPTO` 134 is enabled, no change required on the application side. 135 136 ### TLS: most crypto operations based on PSA 137 138 Current exceptions: 139 140 - Finite-field (non-EC) Diffie-Hellman (used in key exchanges: DHE-RSA, 141 DHE-PSK). 142 - Restartable operations when `MBEDTLS_ECP_RESTARTABLE` is also enabled (see 143 the documentation of that option). 144 145 Other than the above exceptions, all crypto operations are based on PSA when 146 `MBEDTLS_USE_PSA_CRYPTO` is enabled. 147 148 ### X.509: most crypto operations based on PSA 149 150 Current exceptions: 151 152 - Restartable operations when `MBEDTLS_ECP_RESTARTABLE` is also enabled (see 153 the documentation of that option). 154 155 Other than the above exception, all crypto operations are based on PSA when 156 `MBEDTLS_USE_PSA_CRYPTO` is enabled. 157 158 ### PK layer: most crypto operations based on PSA 159 160 Current exceptions: 161 162 - Verification of RSA-PSS signatures with an MGF hash that's different from 163 the message hash. 164 - Restartable operations when `MBEDTLS_ECP_RESTARTABLE` is also enabled (see 165 the documentation of that option). 166 167 Other than the above exceptions, all crypto operations are based on PSA when 168 `MBEDTLS_USE_PSA_CRYPTO` is enabled. 169