Lines Matching +full:for +full:- +full:in
3 built-in implementation of those algorithms), from a user's perspective.
5 This is useful to save code size for people who are using either a hardware
7 aggressively optimized for code size than the default one in Mbed TLS.
10 ----------------------
14 guide](psa-driver-example-and-guide.md) for information on writing a
17 In order to have some mechanism provided only by a driver, you'll want
18 the 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
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
27 mechanism through the PSA API in Mbed
28 TLS](proposed/psa-conditional-inclusion-c.md) for details.
30 In 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
35 informs 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
38 included in the build.
40 For example, if you want SHA-256 to be provided only by a driver, you'll want
44 In addition to these compile-time considerations, at runtime you'll need to
46 driver-only mechanisms. Note that this is already a requirement for any use of
47 the 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
52 ------------------
54 For 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.
61 work in the same way as if the mechanisms where built-in, except as documented
62 in the "Limitations" sub-sections of the sections dedicated to each family
65 In the near future (end of 2023), we are planning to also add support for
68 Currently (mid-2023) we don't have plans to extend this to RSA. If
69 you're interested in driver-only support for RSA, please let us know.
72 ------
77 - you can enable `PSA_WANT_ALG_SHA_256` without `MBEDTLS_SHA256_C`, provided
79 - and similarly for all supported hash algorithms: `MD5`, `RIPEMD160`,
83 In such a build, all crypto operations (via the PSA Crypto API, or non-PSA
85 to low-level hash APIs (`mbedtls_sha256()` etc.) are not possible for the
89 a hash algorithm that is provided only by a driver, as mentioned in [General
90 considerations](#general-considerations) above.
92 If you want to check at compile-time whether a certain hash algorithm is
93 available in the present build of Mbed TLS, regardless of whether it's
94 provided 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
97 - for code that uses non-PSA crypto APIs: `MBEDTLS_MD_CAN_xxx` from
100 Elliptic-curve cryptography (ECC)
101 ---------------------------------
104 - the ECDH, ECDSA and EC J-PAKE algorithms;
105 - key import, export, and random generation.
108 - you have driver support for ECC public and using private keys (that is,
111 - you have driver support for all ECC curves that are enabled (that is, for
116 - enable `PSA_WANT_ALG_ECDH` without `MBEDTLS_ECDH_C`, provided
118 - enable `PSA_WANT_ALG_ECDSA` without `MBEDTLS_ECDSA_C`, provided
120 - enable `PSA_WANT_ALG_JPAKE` without `MBEDTLS_ECJPAKE_C`, provided
123 In addition, if:
124 - none of `MBEDTLS_ECDH_C`, `MBEDTLS_ECDSA_C`, `MBEDTLS_ECJPAKE_C` are enabled
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
132 still be included in the build, see limitations sub-section below.
134 In 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
142 In such builds, all crypto operations via the PSA Crypto API will work as
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).
149 If you want to check at compile-time whether a certain curve is available in
151 driver or built-in, you should use the following macros:
152 - for code that uses only the PSA Crypto API: `PSA_WANT_ECC_xxx` from
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
158 Note that for externally-provided drivers, the integrator is responsible for
160 for the p256-m driver that's provided with the library, those macros are
165 A limited subset of `ecp.c` will still be automatically re-enabled if any of
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
171 - `PSA_WANT_KEY_TYPE_ECC_KEY_PAIR_DERIVE` - support for deterministic
175 automatically be included in the build in order to support it. Therefore
176 you can still disable `MBEDTLS_ECP_C` in `mbedtls_config.h` and this will
177 result in some code size savings, but not as much as when none of the
180 We do have plans to support each of these with `ecp.c` fully removed in the
182 let us know, so we can take it into consideration in our planning.
186 At the moment, there is no driver support for interruptible operations
188 consequence these are not supported in builds without `MBEDTLS_ECDSA_C`.
190 Similarly, there is no PSA support for interruptible ECDH operations so these
192 restartable operations with `MBEDTLS_USE_PSA_CRYPTO` in [its
193 documentation](use-psa-crypto.md).
195 Again, we have plans to support this in the future but not with an established
198 ### Limitations regarding "mixed" builds (driver and built-in)
200 In order for a build to be driver-only (no built-in implementation), all the
205 want to have more enabled in you build?
207 It is possible to have acceleration for only a subset of the requested
208 algorithms. In this case, the built-in implementation of the accelerated
212 There is very limited support for having acceleration for only a subset of the
218 There is limited support for having acceleration for only a subset of the
219 requested curves. In such builds, only the PSA API is currently tested and
220 working; there are known issues in PK, and X.509 and TLS are untested.
222 Finite-field Diffie-Hellman
223 ---------------------------
225 Support is pretty similar to the "Elliptic-curve cryptography (ECC)" section
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`;
236 The same holds for the associated algorithm:
241 Support for deterministic derivation of a DH keypair