Lines Matching +full:all +full:- +full:apis
3 built-in implementation of those algorithms), from a user's perspective.
10 ----------------------
14 guide](psa-driver-example-and-guide.md) for information on writing a
18 the following compile-time configuration options enabled:
20 - `MBEDTLS_PSA_CRYPTO_C` (enabled by default) - this enables PSA Crypto.
21 - `MBEDTLS_USE_PSA_CRYPTO` (disabled by default) - this makes PK, X.509 and
24 [the dedicated document](use-psa-crypto.md) for details.)
25 - `MBEDTLS_PSA_CRYPTO_CONFIG` (disabled by default) - this enables
29 TLS](proposed/psa-conditional-inclusion-c.md) for details.
33 - Define the corresponding `PSA_WANT` macro in `psa/crypto_config.h` - this
35 - Define the corresponding `MBEDTLS_PSA_ACCEL` in your build. This could be
38 - Undefine / comment out the corresponding `MBEDTLS_xxx_C` macro in
39 `mbedtls/mbedtls_config.h`. This ensures the built-in implementation is not
42 For example, if you want SHA-256 to be provided only by a driver, you'll want
46 In addition to these compile-time considerations, at runtime you'll need to
48 driver-only mechanisms. Note that this is already a requirement for any use of
54 ------------------
58 - hashes: SHA-3, SHA-2, SHA-1, MD5, etc.
59 - elliptic-curve cryptography (ECC): ECDH, ECDSA, EC J-PAKE, ECC key types.
60 - finite-field Diffie-Hellman: FFDH algorithm, DH key types.
61 - RSA: PKCS#1 v1.5 and v2.1 signature and encryption algorithms, RSA key types
63 - AEADs:
64 - GCM and CCM with AES, ARIA and Camellia key types
65 - ChachaPoly with ChaCha20 Key type
66 - Unauthenticated ciphers:
67 - key types: AES, ARIA, Camellia, DES
68 - modes: ECB, CBC, CTR, CFB, OFB, XTS
70 For each family listed above, all the mentioned alorithms/key types are also
71 all the mechanisms that exist in PSA API.
75 work in the same way as if the mechanisms where built-in, except as documented
76 in the "Limitations" sub-sections of the sections dedicated to each family
80 ------
82 It is possible to have all hash operations provided only by a driver.
86 - you can enable `PSA_WANT_ALG_SHA_256` without `MBEDTLS_SHA256_C`, provided
88 - and similarly for all supported hash algorithms: `MD5`, `RIPEMD160`,
92 In such a build, all crypto operations (via the PSA Crypto API, or non-PSA
93 APIs), as well as X.509 and TLS, will work as usual, except that direct calls
94 to low-level hash APIs (`mbedtls_sha256()` etc.) are not possible for the
99 considerations](#general-considerations) above.
101 If you want to check at compile-time whether a certain hash algorithm is
103 provided by a driver or built-in, you should use the following macros:
105 - for code that uses only the PSA Crypto API: `PSA_WANT_ALG_xxx` from
107 - for code that uses non-PSA crypto APIs: `MBEDTLS_MD_CAN_xxx` from
114 - HMAC algorithm and key type, i.e. `[PSA_WANT|MBEDTLS_PSA_ACCEL]_ALG_HMAC` and
116 - Required hash algorithm(s) as explained in [Hashes](#hashes) section.
121 - As mentioned in [Hashes](#hashes) direct calls to legacy lo-level hash APIs
124 - Legacy HMAC support (`mbedtls_md_hmac_xxx()`) won't be possible.
125 - `MBEDTLS_PKCS[5|7]_C`, `MBEDTLS_HMAC_DRBG_C` and `MBEDTLS_HKDF_C` since they
127 - disabling HMAC_DRBG_C cause deterministic ECDSA (i.e.
131 Elliptic-curve cryptography (ECC)
132 ---------------------------------
136 - the ECDH, ECDSA and EC J-PAKE algorithms;
137 - key import, export, and random generation.
141 - you have driver support for ECC public and using private keys (that is,
144 - you have driver support for all ECC curves that are enabled (that is, for
150 - enable `PSA_WANT_ALG_ECDH` without `MBEDTLS_ECDH_C`, provided
152 - enable `PSA_WANT_ALG_ECDSA` without `MBEDTLS_ECDSA_C`, provided
154 - enable `PSA_WANT_ALG_JPAKE` without `MBEDTLS_ECJPAKE_C`, provided
159 - none of `MBEDTLS_ECDH_C`, `MBEDTLS_ECDSA_C`, `MBEDTLS_ECJPAKE_C` are enabled
161 - you have driver support for all enabled ECC key pair operations - that is,
167 still be included in the build, see limitations sub-section below.
171 - `MBEDTLS_ECP_C` is fully removed (see limitation sub-section below),
172 - and support for RSA key types and algorithms is either fully disabled or
174 - and support for DH key types and the FFDH algorithm is either disabled or
179 In such builds, all crypto operations via the PSA Crypto API will work as
183 - direct calls to APIs from the disabled modules are not possible;
184 - PK, X.509 and TLS will not support restartable ECC operations (see
185 limitation sub-section below).
187 If you want to check at compile-time whether a certain curve is available in
189 driver or built-in, you should use the following macros:
191 - for code that uses only the PSA Crypto API: `PSA_WANT_ECC_xxx` from
193 - for code that may also use non-PSA crypto APIs: `MBEDTLS_ECP_HAVE_xxx` from
197 Note that for externally-provided drivers, the integrator is responsible for
199 for the p256-m driver that's provided with the library, those macros are
204 A limited subset of `ecp.c` will still be automatically re-enabled if any of
207 - `MBEDTLS_PK_PARSE_EC_COMPRESSED` - support for parsing ECC keys where the
209 - `MBEDTLS_PK_PARSE_EC_EXTENDED` - support for parsing ECC keys where the
211 - `PSA_WANT_KEY_TYPE_ECC_KEY_PAIR_DERIVE` - support for deterministic
233 documentation](use-psa-crypto.md).
238 ### Limitations regarding "mixed" builds (driver and built-in)
240 In order for a build to be driver-only (no built-in implementation), all the
248 algorithms. In this case, the built-in implementation of the accelerated
249 algorithms will be disabled, provided all the requested curves and key types
262 Finite-field Diffie-Hellman
263 ---------------------------
265 Support is pretty similar to the "Elliptic-curve cryptography (ECC)" section
270 - `[PSA_WANT|MBEDTLS_PSA_ACCEL]_KEY_TYPE_DH_PUBLIC_KEY`;
271 - `[PSA_WANT|MBEDTLS_PSA_ACCEL]_KEY_TYPE_DH_KEY_PAIR_BASIC`;
272 - `[PSA_WANT|MBEDTLS_PSA_ACCEL]_KEY_TYPE_DH_KEY_PAIR_IMPORT`;
273 - `[PSA_WANT|MBEDTLS_PSA_ACCEL]_KEY_TYPE_DH_KEY_PAIR_EXPORT`;
274 - `[PSA_WANT|MBEDTLS_PSA_ACCEL]_KEY_TYPE_DH_KEY_PAIR_GENERATE`;
281 ---
283 It is possible for all RSA operations to be provided only by a driver.
287 - all the RSA algorithms that are enabled (`PSA_WANT_ALG_RSA_*`) are also
289 - and all the RSA key types that are enabled (`PSA_WANT_KEY_TYPE_RSA_*`) are
297 Unlike other mechanisms, for now in configurations with driver-only RSA, only
299 driver-only RSA even if `MBEDTLS_USE_PSA_CRYPTO` is enabled.
302 interested in wider driver-only support for RSA, please let us know.
305 ----------------------------------
307 It is possible to have all ciphers and AEAD operations provided only by a
311 - Enable desired PSA key type(s):
312 - `PSA_WANT_KEY_TYPE_AES`,
313 - `PSA_WANT_KEY_TYPE_ARIA`,
314 - `PSA_WANT_KEY_TYPE_CAMELLIA`,
315 - `PSA_WANT_KEY_TYPE_CHACHA20`,
316 - `PSA_WANT_KEY_TYPE_DES`.
317 - Enable desired PSA algorithm(s):
318 - Unauthenticated ciphers modes:
319 - `PSA_WANT_ALG_CBC_NO_PADDING`,
320 - `PSA_WANT_ALG_CBC_PKCS7`,
321 - `PSA_WANT_ALG_CCM_STAR_NO_TAG`,
322 - `PSA_WANT_ALG_CFB`,
323 - `PSA_WANT_ALG_CTR`,
324 - `PSA_WANT_ALG_ECB_NO_PADDING`,
325 - `PSA_WANT_ALG_OFB`,
326 - `PSA_WANT_ALG_STREAM_CIPHER`.
327 - AEADs:
328 - `PSA_WANT_ALG_CCM`,
329 - `PSA_WANT_ALG_GCM`,
330 - `PSA_WANT_ALG_CHACHA20_POLY1305`.
331 - Enable `MBEDTLS_PSA_ACCEL_[KEY_TYPE_xxx|ALG_yyy]` symbol(s) which correspond
333 - Disable builtin support of key types:
334 - `MBEDTLS_AES_C`,
335 - `MBEDTLS_ARIA_C`,
336 - `MBEDTLS_CAMELLIA_C`,
337 - `MBEDTLS_DES_C`,
338 - `MBEDTLS_CHACHA20_C`.
340 - `MBEDTLS_CBC_C`,
341 - `MBEDTLS_CFB_C`,
342 - `MBEDTLS_CTR_C`,
343 - `MBEDTLS_OFB_C`,
344 - `MBEDTLS_XTS_C`,
345 - `MBEDTLS_CCM_C`,
346 - `MBEDTLS_GCM_C`,
347 - `MBEDTLS_CHACHAPOLY_C`,
348 - `MBEDTLS_NULL_CIPHER`.
350 Once a key type and related algorithm are accelerated, all the PSA Crypto APIs
352 some non-PSA APIs will be absent or have reduced functionality, see
357 - If an algorithm other than CCM and GCM (see
358 ["Partial acceleration for CCM/GCM"](#partial-acceleration-for-ccmgcm) below)
359 is enabled but not accelerated, then all key types that can be used with it
360 will need to be built-in.
361 - If a key type is enabled but not accelerated, then all algorithms that can be
362 used with it will need to be built-in.
365 need to be disabled, or have reduced features when the built-in implementations
368 - `MBEDTLS_NIST_KW_C` needs built-in AES: it must be disabled when
370 - `MBEDTLS_CMAC_C` needs built-in AES/DES: it must be disabled when
374 CMAC and all compatible key types, then `PSA_WANT_ALG_CMAC` can be enabled
375 without `MBEDTLS_CMAC_C` and CMAC will be usable with `psa_max_xxx` APIs.)
376 - `MBEDTLS_CIPHER_C`: the `mbedtls_cipher_xxx()` APIs will only work with
377 ciphers that are built-in - that is, both the underlying cipher
380 - `MBEDTLS_PKCS5_C`: encryption/decryption (PBES2, PBE) will only work with
381 ciphers that are built-in.
382 - PEM decryption will only work with ciphers that are built-in.
383 - PK parse will only be able to parse encrypted keys using built-in ciphers.
386 restrictions, see [Disabling `MBEDTLS_CIPHER_C`](#disabling-mbedtls_cipher_c).
388 ### Legacy <-> PSA matching
393 - ECB mode is always enabled in the legacy configuration for each key type that
396 - In the legacy API, `MBEDTLS_CHACHA20_C` enables the ChaCha20 stream cipher, and
397 enabling `MBEDTLS_CHACHAPOLY_C` also enables the ChaCha20-Poly1305 AEAD. In the
400 - The legacy symbol `MBEDTLS_CCM_C` adds support for both cipher and AEAD,
416 - Use CCM and GCM via the PSA Crypto APIs.
417 - Use CCM and GCM via legacy functions `mbedtls_[ccm|gcm]_xxx()` (but not the
419 - Disable legacy key types (`MBEDTLS_[AES|ARIA|CAMELLIA]_C`) if there is no
425 ### CTR-DRBG
427 The legacy CTR-DRBG module (enabled by `MBEDTLS_CTR_DRBG_C`) can also benefit
430 - The legacy AES module (`MBEDTLS_AES_C`) is not enabled and
431 - AES is supported on the PSA side together with ECB mode, i.e.
436 It is possible to save code size by disabling MBEDTLS_CIPHER_C when all of the
439 - The application is not using the `mbedtls_cipher_` API.
440 - In PSA, all unauthenticated (that is, non-AEAD) ciphers are either disabled or
441 fully accelerated (that is, all compatible key types are accelerated too).
442 - Either TLS is disabled, or `MBEDTLS_USE_PSA_CRYPTO` is enabled.
443 - `MBEDTLS_NIST_KW` is disabled.
444 - `MBEDTLS_CMAC_C` is disabled. (Note: support for CMAC in PSA can be provided by
449 - Encryption/decryption functions from the PKCS5 and PKCS12 module will not be
451 - Parsing of PKCS5- or PKCS12-encrypted keys in PK parse will fail.
454 MBEDTLS_CIPHER_C even when using the built-in implementations.
456 If you also have some ciphers fully accelerated and the built-ins removed, see
457 [Restrictions](#restrictions) for restrictions related to removing the built-ins.