Lines Matching +full:check +full:- +full:api +full:- +full:compatibility
10 G2. Allow isolation of long-term secrets (for example, private keys).
11 G3. Allow isolation of short-term secrets (for example, TLS session keys).
12 G4. Have a clean, unified API for Crypto (retire the legacy API).
18 implemented, see `docs/use-psa-crypto.md`, where new APIs are about (G2), and
24 Compile-time options
27 We currently have two compile-time options that are relevant to the migration:
29 - `MBEDTLS_PSA_CRYPTO_C` - enabled by default, controls the presence of the PSA
31 - `MBEDTLS_USE_PSA_CRYPTO` - disabled by default (enabled in "full" config),
34 - `PSA_CRYPTO_CONFIG` - disabled by default, supports builds with drivers and
39 - it's incompatible with `MBEDTLS_ECP_RESTARTABLE`;
40 - to avoid a hard/default dependency of TLS, X.509 and PK on
41 `MBEDTLS_PSA_CRYPTO_C`, for backward compatibility reasons:
42 - When `MBEDTLS_PSA_CRYPTO_C` is enabled and used, applications need to call
45 - `MBEDTLS_PSA_CRYPTO_C` has a hard dependency on `MBEDTLS_ENTROPY_C ||
48 Also, we can't just auto-enable `MBEDTLS_ENTROPY_C` as it doesn't build
50 `MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG` as it requires a user-provided RNG
54 `MBDEDTLS_USE_PSA_CRYPTO` non-optional (always enabled), we have to maintain
61 backward compatibility issues, and in particular if the cost of implementing
75 2022, see <https://github.com/orgs/Mbed-TLS/projects/1#column-18883250>.
77 It will then require follow-up work to make use of the new PSA API in
80 ### Backward compatibility issues with making `MBEDTLS_USE_PSA_CRYPTO` always on
86 <https://github.com/ARM-software/psa-crypto-api/pull/536> for that).
89 auto-enable the latter, as it won't build or work out of the box on all
100 available in entropy-less builds. (Then code using those functions still needs
101 to have one version using it, for entropy-less builds, and one version using
104 See <https://github.com/Mbed-TLS/mbedtls/issues/5156>.
106 Taking advantage of the existing abstractions layers - or not
110 algorithm-agnostic APIs for a class of algorithms:
112 - MD for messages digests aka hashes (including HMAC)
113 - Cipher for symmetric ciphers (included AEAD)
114 - PK for asymmetric (aka public-key) cryptography (excluding key exchange)
118 These abstraction layers typically provide, in addition to the API for crypto
130 -----------------------------------------------
132 - Provide a new definition (conditionally on `USE_PSA_CRYPTO`) of wrapper
134 crypto API.
135 - Upside: changes contained to a single place, no need to change TLS or X.509
137 - Downside: tricky to implement if the PSA implementation is currently done on
154 --------------------------------
156 - For every operation that's done through this layer in TLS or X.509, just
158 - Upside: conceptually simple, and if the PSA implementation is currently done
160 - Upside: opens the door to building TLS/X.509 without that layer, saving some
162 - Downside: TLS/X.509 code has to be done for each operation.
167 Opt-in use of PSA from the abstraction layer
168 --------------------------------------------
170 - Provide a new way to set up a context that causes operations on that context
172 - Upside: changes mostly contained in one place, TLS/X.509 code only needs to
176 - Upside: avoids dependency loop when PSA implemented on top of that layer.
177 - Downside: when the context is typically set up by the application, requires
181 one-shot function `mbedtls_md()`.
189 private-key operations in the PK layer - see `mbedtls_pk_setup_opaque()`. This
190 allows use of PSA-held private ECDSA keys in TLS and X.509 with no change to
194 included) in the Cipher layer - see `mbedtls_cipher_setup_psa()`. This allowed
200 "opt-in" strategy can apply, and can complement each other, as one provides
206 -------
210 - PK (for G1): silently call PSA
211 - PK (for G2): opt-in use of PSA (new key type)
212 - Cipher (G1): replace calls at each call site
213 - MD (G1): replace calls at each call site
230 a. the library to build in a reasonably-complete configuration,
235 Criterion (c) ensures not only test coverage, but that driver-based builds are
236 at feature parity with software-based builds.
241 1. Have users of these algorithms call to PSA, not the legacy API, for all
244 2. Have users of these algorithms not depend on the legacy API for information
246 3. Adapt compile-time guards used to query availability of a given algorithm;
254 below) is the reason why criterion (a) has "a reasonably-complete
256 working on other parts such as X.509 and TLS - for example, a configuration
267 - Step 0 is achieved for most algorithms, with only a few gaps remaining.
268 - Step 1 is achieved for most of PK, X.509, and TLS when
270 docs/use-psa-crypto.md).
271 - Step 1 is not achieved for a lot of the crypto library including the PSA
272 core. For example, `entropy.c` calls the legacy API
274 legacy API `mbedtls_md` and `ctr_drbg.c` calls the legacy API `mbedtls_aes`;
279 - Step 2 is achieved for most of X.509 and TLS (same gaps as step 1) when
280 `MBEDTLS_USE_PSA_CRYPTO` is enabled - this was tasks like #5795, #5796,
282 - Step 3 was mostly not started at all before 3.2; it is being done for PK by
292 backwards compatibility issues, by using the software implementation if
293 available, and "falling back" to PSA only if it's not. The compile-time
298 break of backwards compatibility, as it was previously impossible to build in
300 application code keeps working unchanged. An work-in-progress example of
302 <https://github.com/Mbed-TLS/mbedtls/pull/6141>
312 The most satisfying situation here is when we can just use the PSA Crypto API
314 convenient, for example in parts of the code that accept old-style identifiers
315 (such as `mbedtls_md_type_t`) in their API and can't assume PSA to be
319 later when removing the legacy API including its identifiers (G4), we may
320 occasionally use ad-hoc internal functions, such as the ones introduced by PR
329 There are currently two (complementary) ways for crypto-using code to check if a
331 `PSA_WANT_xxx` macros. For example, PSA-based code that want to use SHA-256
332 will check for `PSA_WANT_ALG_SHA_256`, while legacy-based code that wants to
333 use SHA-256 will check for `MBEDTLS_SHA256_C` if using the `mbedtls_sha256`
334 API, or for `MBEDTLS_MD_C && MBEDTLS_SHA256_C` if using the `mbedtls_md` API.
339 available via the legacy API(s) is it using (MD and/or low-level).
342 currently compute hashes using MD (resp. a low-level hash module) will gain
351 - too many different ways of computing a hash (low-level, MD, PSA);
352 - too many different ways to configure the library that influence which of
362 - code that always uses PSA Crypto (for example, code specific to TLS 1.3)
364 - code that always uses the legacy API (for example, crypto modules that have
366 - code that may use one of the two APIs, either based on
376 Since supporting driver-only builds is not about adding features, but about
379 that build and run tests in newly-supported configurations. For example, if
389 - the sets of tests skipped in the default config and the full config must be
391 - the set of tests skipped in the driver-only build is the same as in an
392 equivalent software-based configuration, or the difference is small enough,
396 driver-only build. In other cases, analysis of the outcome files is needed,
397 see the example script `outcome-analysis.sh` in the same directory.
400 Migrating away from the legacy API
407 ---------------------------------------------------
417 ### Zero-cost compatibility layer?
419 The most favourable case is if we can have a zero-cost abstraction (no
424 same context type for hashes and HMACs, while the PSA API (rightfully) has
426 type for unauthenticated and AEAD ciphers, which again the PSA API
429 It is unclear how much value, if any, a zero-cost compatibility layer that's
431 only AEAD) or differs significantly from the existing API (for example,
434 ### Low-cost compatibility layers?
436 Another possibility is to keep most or all of the existing API for the PK, MD
443 pointers, just call the corresponding PSA API).
445 Since this would still represent a non-zero cost, not only in terms of code
447 be a temporary solution: for example keep the compatibility layers in 4.0 (and
451 existing API unchanged. Their might be conflicts between this goal and that of
462 parsing on-demand" (#2478), and then the public key data would be held as
469 Crypto API.
475 those would be in the MD, Cipher and PK compatibility layers mentioned above,
481 Generally speaking, we would retire all of the low-level, non-generic modules,
482 such as AES, SHA-256, RSA, DHM, ECDH, ECP, bignum, etc, without providing
483 compatibility APIs for them. People would be encouraged to switch to the PSA
484 API. (The compatibility implementation of the existing PK, MD, Cipher APIs
486 the low-level, alg-specific ones.)
497 Since some users would probably still be using the compatibility PK layer, it
504 the underlying crypto implementation and use TLS-specific identifiers instead
506 `mbedtls_ssl_conf_groups()` API, see #4859).
509 -------
512 the low-level crypto APIs and making PK, MD and Cipher optional compatibility
515 API for tests, or manually migrate tests to the PSA Crypto API. Perhaps a