Update strategy document to reflect new macros

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

docs/architecture/psa-migration/strategy.md

@@ -327,30 +327,33 @@ will check for `PSA_WANT_ALG_SHA_256`, while legacy-based code that wants to
 use SHA-256 will check for `MBEDTLS_SHA256_C` if using the `mbedtls_sha256`
 API, or for `MBEDTLS_MD_C && MBEDTLS_SHA256_C` if using the `mbedtls_md` API.
 
-It is suggested to introduce a new set of macros, `MBEDTLS_USE_PSA_WANT_xxx`,
+Code that obeys `MBEDTLS_USE_PSA_CRYPTO` will want to use one of the two
-for use in the parts of the code that use either API depending of whether
+dependencies above depending on whether `MBEDTLS_USE_PSA_CRYPTO` is defined:
-`MBEDTLS_USE_PSA_CRYPTO` is enabled (that is, PK, X.509 and TLS 1.2). This is
+if it is, the code want the algorithm available in PSA, otherwise, it wants it
-done for hash algorithms, as an example, by PR 6065. These macros can be used
+available via the legacy API(s) is it using (MD and/or low-level).
-in library code (most useful when algorithm availability is checked far from the
-code that will be using it, such as in TLS negotiation) as well as test
-dependencies.
 
-It should also be noted that there is a fourth case: utility functions /
+The strategy for steps 1 and 2 above will introduce new situations: code that
-information tables that are not tied to a particular crypto API, and may be
+currently compute hashes using MD (resp. a low-level hash module) will gain
-used by functions that are either purely PSA-based, purely legacy-based, or
+the ability to "fall back" to using PSA if the legacy dependency isn't
-hybrid governed by `MBEDTLS_USE_PSA_CRYPTO` should use `MBEDTLS_xxx ||
+available. Data related to a certain hash (OID, sizes, translations) should
-PSA_WANT_xxx` - for example, `oid_md_alg` from `oid.c`, used by both X.509 and
+only be included in the build if it is possible to use that hash in some way.
-RSA. A new family of macros `MBEDTLS_OR_PSA_WANT_xxx` is defined for this.
 
-To sum up, there are 4 categories:
+In order to cater to these new needs, new families of macros are introduced in
+`library/legacy_or_psa.h`, see its documentation for details.
 
-- legacy-based code depends on `MBEDTLS_xxx`;
+It should be noted that there are currently:
-- PSA-based code depends on `PSA_WANT_xxx`;
+- too many different ways of computing a hash (low-level, MD, PSA);
-- hybrid code governed by `MBEDTLS_USE_PSA_CRYPTO` can use
+- too many different ways to configure the library that influence which of
-  `MBEDTLS_USE_PSA_WANT_xxx` to express dependencies in common parts;
+  these ways is available and will be used (`MBEDTLS_USE_PSA_CRYPTO`,
-- data and crypto-agnostic helpers that can be used by code from at least two
+`MBEDTLS_PSA_CRYPTO_CONFIG`, `mbedtls_config.h` + `psa/crypto_config.h`).
-  of the above categories should depend on `MBEDTLS_OR_PSA_WANT_xxx`.
 
+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 everthing is
+based on PSA Crypto. In the meantime, long and explicit names where chosen for
+the new macros in the hope of avoiding confusion.
+
+Executing step 3 will mostly consist of using the right dependency macros in
+the right places (once the previous steps are done).
 
 Migrating away from the legacy API
 ==================================