Update psa-migration/strategy.md

- Update for the new hashes strategy, in part by adding references to
md-cipher-dispatch.md
- General update about the status of things since the last update

Signed-off-by: Manuel Pégourié-Gonnard <manuel.pegourie-gonnard@arm.com>

docs/architecture/psa-migration/strategy.md

@@ -18,13 +18,17 @@ needs to be changed to use new APIs. For a more detailed account of what's
 implemented, see `docs/use-psa-crypto.md`, where new APIs are about (G2), and
 internal changes implement (G1).
 
+As of early 2023, work towards G5 is in progress: Mbed TLS 3.3 and 3.4 saw
+some improvements in this area, and more will be coming in future releases.
+
 Generally speaking, the numbering above doesn't mean that each goal requires
 the preceding ones to be completed.
 
+
 Compile-time options
 ====================
 
-We currently have two compile-time options that are relevant to the migration:
+We currently have a few compile-time options that are relevant to the migration:
 
 - `MBEDTLS_PSA_CRYPTO_C` - enabled by default, controls the presence of the PSA
   Crypto APIs.
@@ -36,7 +40,9 @@ We currently have two compile-time options that are relevant to the migration:
 
 The reasons why `MBEDTLS_USE_PSA_CRYPTO` is optional and disabled by default
 are:
-- it's incompatible with `MBEDTLS_ECP_RESTARTABLE`;
+- it's not fully compatible with `MBEDTLS_ECP_RESTARTABLE`: you can enable
+  both, but then you won't get the full effect of RESTARTBLE (see the
+documentation of this option in `mbedtls_config.h`);
 - to avoid a hard/default dependency of TLS, X.509 and PK on
   `MBEDTLS_PSA_CRYPTO_C`, for backward compatibility reasons:
   - When `MBEDTLS_PSA_CRYPTO_C` is enabled and used, applications need to call
@@ -71,10 +77,10 @@ Crypto does not support restartable operations, there's a clear conflict: the
 TLS and X.509 layers can't both use only PSA APIs and get restartable
 behaviour.
 
-Supporting this in PSA is on our roadmap and currently planned for end of
+Support for restartable (aka interruptible) ECDSA sign/verify operation was
-2022, see <https://github.com/orgs/Mbed-TLS/projects/1#column-18883250>.
+added to PSA in Mbed TLS 3.4, but support for ECDH is not present yet.
 
-It will then require follow-up work to make use of the new PSA API in
+It will then require follow-up work to make use of the new PSA APIs in
 PK/X.509/TLS in all places where we currently allow restartable operations.
 
 ### Backward compatibility issues with making `MBEDTLS_USE_PSA_CRYPTO` always on
@@ -137,8 +143,11 @@ crypto API.
 - Downside: tricky to implement if the PSA implementation is currently done on
   top of that layer (dependency loop).
 
-This strategy is currently (early 2022) used for all operations in the PK
+This strategy is currently (early 2023) used for all operations in the PK
-layer.
+layer; the MD layer uses a variant where it dispatches to PSA if a driver is
+available and the driver subsystem has been initialized, regardless of whether
+`USE_PSA_CRYPTO` is enabled; see `md-cipher-dispatch.md` in the same directory
+for details.
 
 This strategy is not very well suited to the Cipher layer, as the PSA
 implementation is currently done on top of that layer.
@@ -161,8 +170,9 @@ Replace calls for each operation
   code size.
 - Downside: TLS/X.509 code has to be done for each operation.
 
-This strategy is currently (early 2022) used for the MD layer and the Cipher
+This strategy is currently (early 2023) used for the MD layer and the Cipher
-layer.
+layer in X.509 and TLS. Crypto modules however always call to MD which may
+then dispatch to PSA, see `md-cipher-dispatch.md`.
 
 Opt-in use of PSA from the abstraction layer
 --------------------------------------------
@@ -210,7 +220,10 @@ Strategies currently (early 2022) used with each abstraction layer:
 - PK (for G1): silently call PSA
 - PK (for G2): opt-in use of PSA (new key type)
 - Cipher (G1): replace calls at each call site
-- MD (G1): replace calls at each call site
+- MD (G1, X.509 and TLS): replace calls at each call site (depending on
+  `USE_PSA_CRYPTO`)
+- MD (G5): silently call PSA when a driver is available, see
+  `md-cipher-dispatch.md`.
 
 
 Supporting builds with drivers without the software implementation
@@ -219,10 +232,6 @@ Supporting builds with drivers without the software implementation
 This section presents a plan towards G5: save code size by compiling out our
 software implementation when a driver is available.
 
-Additionally, we want to save code size by compiling out the
-abstractions layers that we are not using when `MBEDTLS_USE_PSA_CRYPTO` is
-enabled (see previous section): MD and Cipher.
-
 Let's expand a bit on the definition of the goal: in such a configuration
 (driver used, software implementation and abstraction layer compiled out),
 we want:
@@ -238,9 +247,10 @@ at feature parity with software-based builds.
 We can roughly divide the work needed to get there in the following steps:
 
 0. Have a working driver interface for the algorithms we want to replace.
-1. Have users of these algorithms call to PSA, not the legacy API, for all
+1. Have users of these algorithms call to PSA or an abstraction layer than can
-   operations. (This is G1, and for PK, X.509 and TLS this is controlled by
+   dispatch to PSA, but not the low-level legacy API, for all operations.
-   `MBEDTLS_USE_PSA_CRYPTO`.) This needs to be done in the library and tests.
+(This is G1, and for PK, X.509 and TLS this is controlled by
+`MBEDTLS_USE_PSA_CRYPTO`.) This needs to be done in the library and tests.
 2. Have users of these algorithms not depend on the legacy API for information
    management (getting a size for a given algorithm, etc.)
 3. Adapt compile-time guards used to query availability of a given algorithm;
@@ -262,50 +272,32 @@ not possible to achieve good test coverage at the end of step 1 or step 2, it
 is preferable to group with the next step(s) in the same PR until good test
 coverage can be reached.
 
-**Status as of Mbed TLS 3.2:**
+**Status as of end of March 2023 (shortly after 3.4):**
 
 - Step 0 is achieved for most algorithms, with only a few gaps remaining.
 - Step 1 is achieved for most of PK, X.509, and TLS when
   `MBEDTLS_USE_PSA_CRYPTO` is enabled with only a few gaps remaining (see
   docs/use-psa-crypto.md).
-- Step 1 is not achieved for a lot of the crypto library including the PSA
+- Step 1 is achieved for the crypto library regarding hashes: everything uses
-  core. For example, `entropy.c` calls the legacy API
+  MD (not low-level hash APIs), which then dispatches to PSA if applicable.
-  `mbedtls_sha256` (or `mbedtls_sha512` optionally); `hmac_drbg.c` calls the
+- Step 1 is not achieved for all of the crypto library when it come to
-  legacy API `mbedtls_md` and `ctr_drbg.c` calls the legacy API `mbedtls_aes`;
+  ciphers. For example,`ctr_drbg.c` calls the legacy API `mbedtls_aes`.
-  the PSA core depends on the entropy module and at least one of the DRBG
-  modules (unless `MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG` is used). Further, several
-  crypto modules have similar issues, for example RSA PKCS#1 v2.1 calls
-  `mbedtls_md` directly.
 - Step 2 is achieved for most of X.509 and TLS (same gaps as step 1) when
-  `MBEDTLS_USE_PSA_CRYPTO` is enabled - this was tasks like #5795, #5796,
+  `MBEDTLS_USE_PSA_CRYPTO` is enabled.
-  #5797. It is being done in PK and RSA PKCS#1 v1.5 by PR #6065.
+- Step 3 is done for hashes and top-level ECC modules (ECDSA, ECDH, ECJPAKE).
-- Step 3 was mostly not started at all before 3.2; it is being done for PK by
-  PR #6065.
 
 **Strategy for step 1:**
 
 Regarding PK, X.509, and TLS, this is mostly achieved with only a few gaps.
 (The strategy was outlined in the previous section.)
 
-Regarding libmbedcrypto, outside of the RNG subsystem, for modules that
+Regarding libmbedcrypto:
-currently depend on other legacy crypto modules, this can be achieved without
+- for hashes and ciphers, see `md-cipher-dispatch.md` in the same directory;
-backwards compatibility issues, by using the software implementation if
+- for ECC, we have no internal uses of the top-level algorithms (ECDSA, ECDH,
-available, and "falling back" to PSA only if it's not. The compile-time
+  ECJPAKE), however they all depend on `ECP_C` which in turn depends on
-dependency changes from the current one (say, `MD_C` or `AES_C`) to "the
+`BIGNUM_C`. So, direct calls from TLS, X.509 and PK to ECP and Bignum will
-previous dependency OR PSA Crypto with needed algorithms". When building
+need to be replaced; see <https://github.com/Mbed-TLS/mbedtls/issues/6839> and
-without software implementation, users need to call `psa_crypto_init()` before
+liked issues for a summary of intermediate steps and open points.
-calling any function from these modules. This condition does not constitute a
-break of backwards compatibility, as it was previously impossible to build in
-those configurations, and in configurations were the build was possible,
-application code keeps working unchanged. An work-in-progress example of
-applying this strategy, for RSA PKCS#1 v2.1, is here:
-<https://github.com/Mbed-TLS/mbedtls/pull/6141>
-
-There is a problem with the modules used for the PSA RNG, as currently the RNG
-is initialized before drivers and the key store. This part will need further
-study, but in the meantime we can proceed with everything that's not the
-entropy module of one of the DRBG modules, and that does not depend on one of
-those modules.
 
 **Strategy for step 2:**
 
@@ -315,14 +307,11 @@ convenient, for example in parts of the code that accept old-style identifiers
 (such as `mbedtls_md_type_t`) in their API and can't assume PSA to be
 compiled in (such as `rsa.c`).
 
-It is suggested that, as a temporary solution until we clean this up
+When using an existing abstraction layer such as MD, it can provide
-later when removing the legacy API including its identifiers (G4), we may
+information management functions. In other cases, information that was in a
-occasionally use ad-hoc internal functions, such as the ones introduced by PR
+low-level module but logically belongs in a higher-level module can be moved
-6065 in `library/hash_info.[ch]`.
+to that module (for example, TLS identifiers of curves and there conversion
-
+to/from PSA or legacy identifiers belongs in TLS, not `ecp.c`).
-An alternative would be to have two different code paths depending on whether
-`MBEDTLS_PSA_CRYPTO_C` is defined or not. However this is not great for
-readability or testability.
 
 **Strategy for step 3:**
 
@@ -338,35 +327,15 @@ dependencies above depending on whether `MBEDTLS_USE_PSA_CRYPTO` is defined:
 if it is, the code want the algorithm available in PSA, otherwise, it wants it
 available via the legacy API(s) is it using (MD and/or low-level).
 
-The strategy for steps 1 and 2 above will introduce new situations: code that
+As much as possible, we're trying to create for each algorithm a single new
-currently compute hashes using MD (resp. a low-level hash module) will gain
+macro that can be used to express dependencies everywhere (except pure PSA
-the ability to "fall back" to using PSA if the legacy dependency isn't
+code that should always use `PSA_WANT`). For example, for hashes this is the
-available. Data related to a certain hash (OID, sizes, translations) should
+`MBEDTLS_MD_CAN_xxx` family. For ECC algorithms, we have similar
-only be included in the build if it is possible to use that hash in some way.
+`MBEDTLS_PK_CAN_xxx` macros.
 
-In order to cater to these new needs, new families of macros are introduced in
+Note that in order to achieve that goal, even for code that obeys
-`legacy_or_psa.h`, see its documentation for details.
+`USE_PSA_CRYPTO`, it is useful to impose that all algorithms that are
-
+available via the legacy APIs are also available via PSA.
-It should be noted that there are currently:
-- too many different ways of computing a hash (low-level, MD, PSA);
-- too many different ways to configure the library that influence which of
-  these ways is available and will be used (`MBEDTLS_USE_PSA_CRYPTO`,
-  `MBEDTLS_PSA_CRYPTO_CONFIG`, `mbedtls_config.h` + `psa/crypto_config.h`).
-
-As a result, we need more families of dependency macros than we'd like to.
-This is a temporary situation until we move to a place where everything is
-based on PSA Crypto. In the meantime, long and explicit names where chosen for
-the new macros in the hope of avoiding confusion.
-
-Note: the new macros supplement but do not replace the existing macros:
-- code that always uses PSA Crypto (for example, code specific to TLS 1.3)
-  should use `PSA_WANT_xxx`;
-- code that always uses the legacy API (for example, crypto modules that have
-  not undergone step 1 yet) should use `MBEDTLS_xxx_C`;
-- code that may use one of the two APIs, either based on
-  `MBEDTLS_USE_PSA_CRYPTO` (X.509, TLS 1.2, shared between TLS 1.2 and 1.3),
-  or based on availability (crypto modules after step 1), should use one of
-  the new macros from `legacy_or_psa.h`.
 
 Executing step 3 will mostly consist of using the right dependency macros in
 the right places (once the previous steps are done).