1This document explains how to create builds of Mbed TLS where some 2cryptographic mechanisms are provided only by PSA drivers (that is, no 3built-in implementation of those algorithms), from a user's perspective. 4 5This is useful to save code size for people who are using either a hardware 6accelerator, or an alternative software implementation that is more 7aggressively optimized for code size than the default one in Mbed TLS. 8 9General considerations 10---------------------- 11 12This document assumes that you already have a working driver. 13Otherwise, please see the [PSA driver example and 14guide](psa-driver-example-and-guide.md) for information on writing a 15driver. 16 17In order to have some mechanism provided only by a driver, you'll want 18the following compile-time configuration options enabled: 19- `MBEDTLS_PSA_CRYPTO_C` (enabled by default) - this enables PSA Crypto. 20- `MBEDTLS_USE_PSA_CRYPTO` (disabled by default) - this makes PK, X.509 and 21 TLS use PSA Crypto. You need to enable this if you're using PK, X.509 or TLS 22and want them to have access to the algorithms provided by your driver. (See 23[the dedicated document](use-psa-crypto.md) for details.) 24- `MBEDTLS_PSA_CRYPTO_CONFIG` (disabled by default) - this enables 25 configuration of cryptographic algorithms using `PSA_WANT` macros in 26`include/psa/crypto_config.h`. See [Conditional inclusion of cryptographic 27mechanism through the PSA API in Mbed 28TLS](proposed/psa-conditional-inclusion-c.md) for details. 29 30In addition, for each mechanism you want provided only by your driver: 31- Define the corresponding `PSA_WANT` macro in `psa/crypto_config.h` - this 32 means the algorithm will be available in the PSA Crypto API. 33- Define the corresponding `MBEDTLS_PSA_ACCEL` in your build. This could be 34 defined in `psa/crypto_config.h` or your compiler's command line. This 35informs the PSA code that an accelerator is available for this mechanism. 36- Undefine / comment out the corresponding `MBEDTLS_xxx_C` macro in 37 `mbedtls/mbedtls_config.h`. This ensures the built-in implementation is not 38included in the build. 39 40For example, if you want SHA-256 to be provided only by a driver, you'll want 41`PSA_WANT_ALG_SHA_256` and `MBEDTLS_PSA_ACCEL_SHA_256` defined, and 42`MBEDTLS_SHA256_C` undefined. 43 44In addition to these compile-time considerations, at runtime you'll need to 45make sure you call `psa_crypto_init()` before any function that uses the 46driver-only mechanisms. Note that this is already a requirement for any use of 47the PSA Crypto API, as well as for use of the PK, X.509 and TLS modules when 48`MBEDTLS_USE_PSA_CRYPTO` is enabled, so in most cases your application will 49already be doing this. 50 51Mechanisms covered 52------------------ 53 54For now, only the following (families of) mechanisms are supported: 55- hashes: SHA-3, SHA-2, SHA-1, MD5, etc. 56- elliptic-curve cryptography (ECC): ECDH, ECDSA, EC J-PAKE, ECC key types. 57- finite-field Diffie-Hellman: FFDH algorithm, DH key types. 58 59Supported means that when those are provided only by drivers, everything 60(including PK, X.509 and TLS if `MBEDTLS_USE_PSA_CRYPTO` is enabled) should 61work in the same way as if the mechanisms where built-in, except as documented 62in the "Limitations" sub-sections of the sections dedicated to each family 63below. 64 65In the near future (end of 2023), we are planning to also add support for 66ciphers (AES) and AEADs (GCM, CCM, ChachaPoly). 67 68Currently (mid-2023) we don't have plans to extend this to RSA. If 69you're interested in driver-only support for RSA, please let us know. 70 71Hashes 72------ 73 74It is possible to have all hash operations provided only by a driver. 75 76More precisely: 77- you can enable `PSA_WANT_ALG_SHA_256` without `MBEDTLS_SHA256_C`, provided 78 you have `MBEDTLS_PSA_ACCEL_ALG_SHA_256` enabled; 79- and similarly for all supported hash algorithms: `MD5`, `RIPEMD160`, 80 `SHA_1`, `SHA_224`, `SHA_256`, `SHA_384`, `SHA_512`, `SHA3_224`, `SHA3_256`, 81`SHA3_384`, `SHA3_512`. 82 83In such a build, all crypto operations (via the PSA Crypto API, or non-PSA 84APIs), as well as X.509 and TLS, will work as usual, except that direct calls 85to low-level hash APIs (`mbedtls_sha256()` etc.) are not possible for the 86modules that are disabled. 87 88You need to call `psa_crypto_init()` before any crypto operation that uses 89a hash algorithm that is provided only by a driver, as mentioned in [General 90considerations](#general-considerations) above. 91 92If you want to check at compile-time whether a certain hash algorithm is 93available in the present build of Mbed TLS, regardless of whether it's 94provided by a driver or built-in, you should use the following macros: 95- for code that uses only the PSA Crypto API: `PSA_WANT_ALG_xxx` from 96 `psa/crypto.h`; 97- for code that uses non-PSA crypto APIs: `MBEDTLS_MD_CAN_xxx` from 98 `mbedtls/md.h`. 99 100Elliptic-curve cryptography (ECC) 101--------------------------------- 102 103It is possible to have most ECC operations provided only by a driver: 104- the ECDH, ECDSA and EC J-PAKE algorithms; 105- key import, export, and random generation. 106 107More precisely, if: 108- you have driver support for ECC public and using private keys (that is, 109`MBEDTLS_PSA_ACCEL_KEY_TYPE_ECC_PUBLIC_KEY` and 110`MBEDTLS_PSA_ACCEL_KEY_TYPE_ECC_KEY_PAIR_BASIC` are enabled), and 111- you have driver support for all ECC curves that are enabled (that is, for 112 each `PSA_WANT_ECC_xxx` macro enabled, the corresponding 113`MBEDTLS_PSA_ACCEL_ECC_xxx` macros is enabled as well); 114 115then you can: 116- enable `PSA_WANT_ALG_ECDH` without `MBEDTLS_ECDH_C`, provided 117 `MBEDTLS_PSA_ACCEL_ALG_ECDH` is enabled 118- enable `PSA_WANT_ALG_ECDSA` without `MBEDTLS_ECDSA_C`, provided 119 `MBEDTLS_PSA_ACCEL_ALG_ECDSA` is enabled; 120- enable `PSA_WANT_ALG_JPAKE` without `MBEDTLS_ECJPAKE_C`, provided 121 `MBEDTLS_PSA_ACCEL_ALG_JPAKE` is enabled. 122 123In addition, if: 124- none of `MBEDTLS_ECDH_C`, `MBEDTLS_ECDSA_C`, `MBEDTLS_ECJPAKE_C` are enabled 125 (see conditions above), and 126- you have driver support for all enabled ECC key pair operations - that is, 127 for each `PSA_WANT_KEY_TYPE_ECC_KEY_PAIR_xxx` macro enabled, the 128corresponding `MBEDTLS_PSA_ACCEL_KEY_TYPE_ECC_KEY_PAIR_xxx` macros is also 129enabled, 130 131then you can also disable `MBEDTLS_ECP_C`. However, a small subset of it might 132still be included in the build, see limitations sub-section below. 133 134In addition, if: 135- `MBEDTLS_ECP_C` is fully removed (see limitation sub-section below), and 136- support for RSA key types and algorithms is fully disabled, and 137- support for DH key types and the FFDH algorithm is either disabled, or 138 fully provided by a driver, 139 140then you can also disable `MBEDTLS_BIGNUM_C`. 141 142In such builds, all crypto operations via the PSA Crypto API will work as 143usual, as well as the PK, X.509 and TLS modules if `MBEDTLS_USE_PSA_CRYPTO` is 144enabled, with the following exceptions: 145- direct calls to APIs from the disabled modules are not possible; 146- PK, X.509 and TLS will not support restartable ECC operations (see 147 limitation sub-section below). 148 149If you want to check at compile-time whether a certain curve is available in 150the present build of Mbed TLS, regardless of whether ECC is provided by a 151driver or built-in, you should use the following macros: 152- for code that uses only the PSA Crypto API: `PSA_WANT_ECC_xxx` from 153 `psa/crypto.h`; 154- for code that may also use non-PSA crypto APIs: `MBEDTLS_ECP_HAVE_xxx` from 155 `mbedtls/build_info.h` where xxx can take the same values as for 156`MBEDTLS_ECP_DP_xxx` macros. 157 158Note that for externally-provided drivers, the integrator is responsible for 159ensuring the appropriate `MBEDTLS_PSA_ACCEL_xxx` macros are defined. However, 160for the p256-m driver that's provided with the library, those macros are 161automatically defined when enabling `MBEDTLS_PSA_P256M_DRIVER_ENABLED`. 162 163### Limitations regarding fully removing `ecp.c` 164 165A limited subset of `ecp.c` will still be automatically re-enabled if any of 166the following is enabled: 167- `MBEDTLS_PK_PARSE_EC_COMPRESSED` - support for parsing ECC keys where the 168 public part is in compressed format; 169- `MBEDTLS_PK_PARSE_EC_EXTENDED` - support for parsing ECC keys where the 170 curve is identified not by name, but by explicit parameters; 171- `PSA_WANT_KEY_TYPE_ECC_KEY_PAIR_DERIVE` - support for deterministic 172 derivation of an ECC keypair with `psa_key_derivation_output_key()`. 173 174Note: when any of the above options is enabled, a subset of `ecp.c` will 175automatically be included in the build in order to support it. Therefore 176you can still disable `MBEDTLS_ECP_C` in `mbedtls_config.h` and this will 177result in some code size savings, but not as much as when none of the 178above features are enabled. 179 180We do have plans to support each of these with `ecp.c` fully removed in the 181future, however there is no established timeline. If you're interested, please 182let us know, so we can take it into consideration in our planning. 183 184### Limitations regarding restartable / interruptible ECC operations 185 186At the moment, there is no driver support for interruptible operations 187(see `psa_sign_hash_start()` + `psa_sign_hash_complete()` etc.) so as a 188consequence these are not supported in builds without `MBEDTLS_ECDSA_C`. 189 190Similarly, there is no PSA support for interruptible ECDH operations so these 191are not supported without `ECDH_C`. See also limitations regarding 192restartable operations with `MBEDTLS_USE_PSA_CRYPTO` in [its 193documentation](use-psa-crypto.md). 194 195Again, we have plans to support this in the future but not with an established 196timeline, please let us know if you're interested. 197 198### Limitations regarding "mixed" builds (driver and built-in) 199 200In order for a build to be driver-only (no built-in implementation), all the 201requested algorithms, key types (key operations) and curves must be 202accelerated (plus a few other restrictions, see "Limitations regarding fully 203removing `ecp.c`" above). However, what if you have an accelerator that only 204supports some algorithms, some key types (key operations), or some curves, but 205want to have more enabled in you build? 206 207It is possible to have acceleration for only a subset of the requested 208algorithms. In this case, the built-in implementation of the accelerated 209algorithms will be disabled, provided all the requested curves and key types 210that can be used with this algorithm are also declared as accelerated. 211 212There is very limited support for having acceleration for only a subset of the 213requested key type operations. The only configuration that's tested is that of 214a driver accelerating `PUBLIC_KEY`, `KEY_PAIR_BASIC`, `KEY_PAIR_IMPORT`, 215`KEY_PAIR_EXPORT` but not `KEY_PAIR_GENERATE`. (Note: currently the driver 216interface does not support `KEY_PAIR_DERIVE`.) 217 218There is limited support for having acceleration for only a subset of the 219requested curves. In such builds, only the PSA API is currently tested and 220working; there are known issues in PK, and X.509 and TLS are untested. 221 222Finite-field Diffie-Hellman 223--------------------------- 224 225Support is pretty similar to the "Elliptic-curve cryptography (ECC)" section 226above. 227Key management and usage can be enabled by means of the usual `PSA_WANT` + 228`MBEDTLS_PSA_ACCEL` pairs: 229 230- `[PSA_WANT|MBEDTLS_PSA_ACCEL]_KEY_TYPE_DH_PUBLIC_KEY`; 231- `[PSA_WANT|MBEDTLS_PSA_ACCEL]_KEY_TYPE_DH_KEY_PAIR_BASIC`; 232- `[PSA_WANT|MBEDTLS_PSA_ACCEL]_KEY_TYPE_DH_KEY_PAIR_IMPORT`; 233- `[PSA_WANT|MBEDTLS_PSA_ACCEL]_KEY_TYPE_DH_KEY_PAIR_EXPORT`; 234- `[PSA_WANT|MBEDTLS_PSA_ACCEL]_KEY_TYPE_DH_KEY_PAIR_GENERATE`; 235 236The same holds for the associated algorithm: 237`[PSA_WANT|MBEDTLS_PSA_ACCEL]_ALG_FFDH` allow builds accelerating FFDH and 238removing builtin support (i.e. `MBEDTLS_DHM_C`). 239 240### Limitations 241Support for deterministic derivation of a DH keypair 242(i.e. `PSA_WANT_KEY_TYPE_RSA_KEY_PAIR_DERIVE`) is not supported. 243
