Merge pull request #8240 from mpg/doc-driver-only-hashes

Document driver only hashes (overdue)

ChangeLog.d/driver-only-hashes.txt

@@ -7,4 +7,5 @@ Features
      provided - these limitations are lifted in this version. A new set of
      feature macros, MBEDTLS_MD_CAN_xxx, has been introduced that can be used
      to check for availability of hash algorithms, regardless of whether
-     they're provided by a built-in implementation, a driver or both.
+     they're provided by a built-in implementation, a driver or both. See
+     docs/driver-only-builds.md.

docs/driver-only-builds.md

@@ -3,7 +3,7 @@ cryptographic mechanisms are provided only by PSA drivers (that is, no
 built-in implementation of those algorithms), from a user's perspective.
 
 This is useful to save code size for people who are using either a hardware
-accelerator, or an alternative software implementation that's more
+accelerator, or an alternative software implementation that is more
 aggressively optimized for code size than the default one in Mbed TLS.
 
 General considerations
@@ -71,7 +71,31 @@ you're interested in driver-only support for RSA, please let us know.
 Hashes
 ------
 
-TODO
+It is possible to have all hash operations provided only by a driver.
+
+More precisely:
+- you can enable `PSA_WANT_ALG_SHA_256` without `MBEDTLS_SHA256_C`, provided
+  you have `MBEDTLS_PSA_ACCEL_ALG_SHA_256` enabled;
+- and similarly for all supported hash algorithms: `MD5`, `RIPEMD160`,
+  `SHA_1`, `SHA_224`, `SHA_256`, `SHA_384`, `SHA_512`, `SHA3_224`, `SHA3_256`,
+`SHA3_384`, `SHA3_512`.
+
+In such a build, all crypto operations (via the PSA Crypto API, or non-PSA
+APIs), as well as X.509 and TLS, will work as usual, except that direct calls
+to low-level hash APIs (`mbedtls_sha256()` etc.) are not possible for the
+modules that are disabled.
+
+You need to call `psa_crypto_init()` before any crypto operation that uses
+a hash algorithm that is provided only by a driver, as mentioned in [General
+considerations](#general-considerations) above.
+
+If you want to check at compile-time whether a certain hash algorithm is
+available in the present build of Mbed TLS, regardless of whether it's
+provided by a driver or built-in, you should use the following macros:
+- for code that uses only the PSA Crypto API: `PSA_WANT_ALG_xxx` from
+  `psa/crypto.h`;
+- for code that uses non-PSA crypto APIs: `MBEDTLS_MD_CAN_xxx` from
+  `mbedtls/md.h`.
 
 Elliptic-curve cryptography (ECC)
 ---------------------------------

tests/include/test/drivers/crypto_config_test_driver_extension.h

@@ -152,6 +152,38 @@
 #endif
 #endif
 
+#if defined(PSA_WANT_ALG_SHA3_224)
+#if defined(MBEDTLS_PSA_ACCEL_ALG_SHA3_224)
+#undef MBEDTLS_PSA_ACCEL_ALG_SHA3_224
+#else
+#define MBEDTLS_PSA_ACCEL_ALG_SHA3_224 1
+#endif
+#endif
+
+#if defined(PSA_WANT_ALG_SHA3_256)
+#if defined(MBEDTLS_PSA_ACCEL_ALG_SHA3_256)
+#undef MBEDTLS_PSA_ACCEL_ALG_SHA3_256
+#else
+#define MBEDTLS_PSA_ACCEL_ALG_SHA3_256 1
+#endif
+#endif
+
+#if defined(PSA_WANT_ALG_SHA3_384)
+#if defined(MBEDTLS_PSA_ACCEL_ALG_SHA3_384)
+#undef MBEDTLS_PSA_ACCEL_ALG_SHA3_384
+#else
+#define MBEDTLS_PSA_ACCEL_ALG_SHA3_384 1
+#endif
+#endif
+
+#if defined(PSA_WANT_ALG_SHA3_512)
+#if defined(MBEDTLS_PSA_ACCEL_ALG_SHA3_512)
+#undef MBEDTLS_PSA_ACCEL_ALG_SHA3_512
+#else
+#define MBEDTLS_PSA_ACCEL_ALG_SHA3_512 1
+#endif
+#endif
+
 #if defined(PSA_WANT_ALG_XTS)
 #if defined(MBEDTLS_PSA_ACCEL_ALG_XTS)
 #undef MBEDTLS_PSA_ACCEL_ALG_XTS

tests/scripts/all.sh

@@ -2321,7 +2321,8 @@ component_test_psa_crypto_config_accel_ecdsa () {
     # -----
 
     # These hashes are needed for some ECDSA signature tests.
-    loc_extra_list="ALG_SHA_224 ALG_SHA_256 ALG_SHA_384 ALG_SHA_512"
+    loc_extra_list="ALG_SHA_224 ALG_SHA_256 ALG_SHA_384 ALG_SHA_512 \
+                    ALG_SHA3_224 ALG_SHA3_256 ALG_SHA3_384 ALG_SHA3_512"
 
     helper_libtestdriver1_make_drivers "$loc_accel_list" "$loc_extra_list"
 
@@ -2527,7 +2528,8 @@ component_test_psa_crypto_config_accel_ecc_ecp_light_only () {
     # -----
 
     # These hashes are needed for some ECDSA signature tests.
-    loc_extra_list="ALG_SHA_1 ALG_SHA_224 ALG_SHA_256 ALG_SHA_384 ALG_SHA_512"
+    loc_extra_list="ALG_SHA_1 ALG_SHA_224 ALG_SHA_256 ALG_SHA_384 ALG_SHA_512 \
+                    ALG_SHA3_224 ALG_SHA3_256 ALG_SHA3_384 ALG_SHA3_512"
     helper_libtestdriver1_make_drivers "$loc_accel_list" "$loc_extra_list"
 
     helper_libtestdriver1_make_main "$loc_accel_list"
@@ -2629,8 +2631,9 @@ component_test_psa_crypto_config_accel_ecc_no_ecp_at_all () {
     # -----
 
     # Things we wanted supported in libtestdriver1, but not accelerated in the main library:
-    # SHA-1 and all SHA-2 variants, as they are used by ECDSA deterministic.
+    # SHA-1 and all SHA-2/3 variants, as they are used by ECDSA deterministic.
-    loc_extra_list="ALG_SHA_1 ALG_SHA_224 ALG_SHA_256 ALG_SHA_384 ALG_SHA_512"
+    loc_extra_list="ALG_SHA_1 ALG_SHA_224 ALG_SHA_256 ALG_SHA_384 ALG_SHA_512 \
+                    ALG_SHA3_224 ALG_SHA3_256 ALG_SHA3_384 ALG_SHA3_512"
 
     helper_libtestdriver1_make_drivers "$loc_accel_list" "$loc_extra_list"
 
@@ -2806,8 +2809,9 @@ common_test_psa_crypto_config_accel_ecc_ffdh_no_bignum () {
     # -----
 
     # Things we wanted supported in libtestdriver1, but not accelerated in the main library:
-    # SHA-1 and all SHA-2 variants, as they are used by ECDSA deterministic.
+    # SHA-1 and all SHA-2/3 variants, as they are used by ECDSA deterministic.
-    loc_extra_list="ALG_SHA_1 ALG_SHA_224 ALG_SHA_256 ALG_SHA_384 ALG_SHA_512"
+    loc_extra_list="ALG_SHA_1 ALG_SHA_224 ALG_SHA_256 ALG_SHA_384 ALG_SHA_512 \
+                    ALG_SHA3_224 ALG_SHA3_256 ALG_SHA3_384 ALG_SHA3_512"
 
     helper_libtestdriver1_make_drivers "$loc_accel_list" "$loc_extra_list"
 
@@ -3052,7 +3056,8 @@ psa_crypto_config_accel_all_curves_except_one () {
     # -----
 
     # These hashes are needed for some ECDSA signature tests.
-    loc_extra_list="ALG_SHA_224 ALG_SHA_256 ALG_SHA_384 ALG_SHA_512"
+    loc_extra_list="ALG_SHA_224 ALG_SHA_256 ALG_SHA_384 ALG_SHA_512 \
+                    ALG_SHA3_224 ALG_SHA3_256 ALG_SHA3_384 ALG_SHA3_512"
     helper_libtestdriver1_make_drivers "$loc_accel_list" "$loc_extra_list"
 
     # (See above regarding loc_curve_list.)
@@ -3219,7 +3224,8 @@ component_test_psa_crypto_config_accel_rsa_signature () {
     # -----
 
     # These hashes are needed for some RSA-PSS signature tests.
-    loc_extra_list="ALG_SHA_1 ALG_SHA_224 ALG_SHA_256 ALG_SHA_384 ALG_SHA_512"
+    loc_extra_list="ALG_SHA_1 ALG_SHA_224 ALG_SHA_256 ALG_SHA_384 ALG_SHA_512 \
+                    ALG_SHA3_224 ALG_SHA3_256 ALG_SHA3_384 ALG_SHA3_512"
     helper_libtestdriver1_make_drivers "$loc_accel_list" "$loc_extra_list"
 
     helper_libtestdriver1_make_main "$loc_accel_list"
@@ -3290,7 +3296,9 @@ component_test_new_psa_want_key_pair_symbol() {
 component_test_psa_crypto_config_accel_hash () {
     msg "test: MBEDTLS_PSA_CRYPTO_CONFIG with accelerated hash"
 
-    loc_accel_list="ALG_MD5 ALG_RIPEMD160 ALG_SHA_1 ALG_SHA_224 ALG_SHA_256 ALG_SHA_384 ALG_SHA_512"
+    loc_accel_list="ALG_MD5 ALG_RIPEMD160 ALG_SHA_1 \
+                    ALG_SHA_224 ALG_SHA_256 ALG_SHA_384 ALG_SHA_512 \
+                    ALG_SHA3_224 ALG_SHA3_256 ALG_SHA3_384 ALG_SHA3_512"
 
     # Configure
     # ---------
@@ -3306,6 +3314,7 @@ component_test_psa_crypto_config_accel_hash () {
     scripts/config.py unset MBEDTLS_SHA256_C
     scripts/config.py unset MBEDTLS_SHA384_C
     scripts/config.py unset MBEDTLS_SHA512_C
+    scripts/config.py unset MBEDTLS_SHA3_C
 
     # Build
     # -----
@@ -3334,7 +3343,9 @@ component_test_psa_crypto_config_accel_hash_keep_builtins () {
     # This component ensures that all the test cases for
     # md_psa_dynamic_dispatch with legacy+driver in test_suite_md are run.
 
-    loc_accel_list="ALG_MD5 ALG_RIPEMD160 ALG_SHA_1 ALG_SHA_224 ALG_SHA_256 ALG_SHA_384 ALG_SHA_512"
+    loc_accel_list="ALG_MD5 ALG_RIPEMD160 ALG_SHA_1 \
+                    ALG_SHA_224 ALG_SHA_256 ALG_SHA_384 ALG_SHA_512 \
+                    ALG_SHA3_224 ALG_SHA3_256 ALG_SHA3_384 ALG_SHA3_512"
 
     # Start from default config (no TLS 1.3, no USE_PSA)
     helper_libtestdriver1_adjust_config "default"
@@ -3363,6 +3374,7 @@ config_psa_crypto_hash_use_psa () {
         scripts/config.py unset MBEDTLS_SHA384_C
         scripts/config.py unset MBEDTLS_SHA512_C
         scripts/config.py unset MBEDTLS_SHA512_USE_A64_CRYPTO_IF_PRESENT
+        scripts/config.py unset MBEDTLS_SHA3_C
     fi
 }
 
@@ -3372,7 +3384,9 @@ config_psa_crypto_hash_use_psa () {
 component_test_psa_crypto_config_accel_hash_use_psa () {
     msg "test: full with accelerated hashes"
 
-    loc_accel_list="ALG_MD5 ALG_RIPEMD160 ALG_SHA_1 ALG_SHA_224 ALG_SHA_256 ALG_SHA_384 ALG_SHA_512"
+    loc_accel_list="ALG_MD5 ALG_RIPEMD160 ALG_SHA_1 \
+                    ALG_SHA_224 ALG_SHA_256 ALG_SHA_384 ALG_SHA_512 \
+                    ALG_SHA3_224 ALG_SHA3_256 ALG_SHA3_384 ALG_SHA3_512"
 
     # Configure
     # ---------

tests/suites/test_suite_md.psa.data

@@ -87,49 +87,49 @@ depends_on:MBEDTLS_SHA512_C:MBEDTLS_MD_SHA512_VIA_PSA
 md_psa_dynamic_dispatch:MBEDTLS_MD_SHA512:0:MBEDTLS_MD_ENGINE_PSA
 
 PSA dispatch SHA3-224 legacy only
-depends_on:MBEDTLS_SHA3_224_C:!MBEDTLS_MD_SHA3_224_VIA_PSA
+depends_on:MBEDTLS_SHA3_C:!MBEDTLS_MD_SHA3_224_VIA_PSA
 md_psa_dynamic_dispatch:MBEDTLS_MD_SHA3_224:0:MBEDTLS_MD_ENGINE_LEGACY
 
 PSA dispatch SHA3-224 driver only
-depends_on:!MBEDTLS_SHA3_224_C:MBEDTLS_MD_SHA3_224_VIA_PSA
+depends_on:!MBEDTLS_SHA3_C:MBEDTLS_MD_SHA3_224_VIA_PSA
 md_psa_dynamic_dispatch:MBEDTLS_MD_SHA3_224:MBEDTLS_ERR_MD_BAD_INPUT_DATA:MBEDTLS_MD_ENGINE_PSA
 
 PSA dispatch SHA3-224 legacy+driver
-depends_on:MBEDTLS_SHA3_224_C:MBEDTLS_MD_SHA3_224_VIA_PSA
+depends_on:MBEDTLS_SHA3_C:MBEDTLS_MD_SHA3_224_VIA_PSA
 md_psa_dynamic_dispatch:MBEDTLS_MD_SHA3_224:0:MBEDTLS_MD_ENGINE_PSA
 
 PSA dispatch SHA3-256 legacy only
-depends_on:MBEDTLS_SHA3_256_C:!MBEDTLS_MD_SHA3_256_VIA_PSA
+depends_on:MBEDTLS_SHA3_C:!MBEDTLS_MD_SHA3_256_VIA_PSA
 md_psa_dynamic_dispatch:MBEDTLS_MD_SHA3_256:0:MBEDTLS_MD_ENGINE_LEGACY
 
 PSA dispatch SHA3-256 driver only
-depends_on:!MBEDTLS_SHA3_256_C:MBEDTLS_MD_SHA3_256_VIA_PSA
+depends_on:!MBEDTLS_SHA3_C:MBEDTLS_MD_SHA3_256_VIA_PSA
 md_psa_dynamic_dispatch:MBEDTLS_MD_SHA3_256:MBEDTLS_ERR_MD_BAD_INPUT_DATA:MBEDTLS_MD_ENGINE_PSA
 
 PSA dispatch SHA3-256 legacy+driver
-depends_on:MBEDTLS_SHA3_256_C:MBEDTLS_MD_SHA3_256_VIA_PSA
+depends_on:MBEDTLS_SHA3_C:MBEDTLS_MD_SHA3_256_VIA_PSA
 md_psa_dynamic_dispatch:MBEDTLS_MD_SHA3_256:0:MBEDTLS_MD_ENGINE_PSA
 
 PSA dispatch SHA3-384 legacy only
-depends_on:MBEDTLS_SHA3_384_C:!MBEDTLS_MD_SHA3_384_VIA_PSA
+depends_on:MBEDTLS_SHA3_C:!MBEDTLS_MD_SHA3_384_VIA_PSA
 md_psa_dynamic_dispatch:MBEDTLS_MD_SHA3_384:0:MBEDTLS_MD_ENGINE_LEGACY
 
 PSA dispatch SHA3-384 driver only
-depends_on:!MBEDTLS_SHA3_384_C:MBEDTLS_MD_SHA3_384_VIA_PSA
+depends_on:!MBEDTLS_SHA3_C:MBEDTLS_MD_SHA3_384_VIA_PSA
 md_psa_dynamic_dispatch:MBEDTLS_MD_SHA3_384:MBEDTLS_ERR_MD_BAD_INPUT_DATA:MBEDTLS_MD_ENGINE_PSA
 
 PSA dispatch SHA3-384 legacy+driver
-depends_on:MBEDTLS_SHA3_384_C:MBEDTLS_MD_SHA3_384_VIA_PSA
+depends_on:MBEDTLS_SHA3_C:MBEDTLS_MD_SHA3_384_VIA_PSA
 md_psa_dynamic_dispatch:MBEDTLS_MD_SHA3_384:0:MBEDTLS_MD_ENGINE_PSA
 
 PSA dispatch SHA3-512 legacy only
-depends_on:MBEDTLS_SHA3_512_C:!MBEDTLS_MD_SHA3_512_VIA_PSA
+depends_on:MBEDTLS_SHA3_C:!MBEDTLS_MD_SHA3_512_VIA_PSA
 md_psa_dynamic_dispatch:MBEDTLS_MD_SHA3_512:0:MBEDTLS_MD_ENGINE_LEGACY
 
 PSA dispatch SHA3-512 driver only
-depends_on:!MBEDTLS_SHA3_512_C:MBEDTLS_MD_SHA3_512_VIA_PSA
+depends_on:!MBEDTLS_SHA3_C:MBEDTLS_MD_SHA3_512_VIA_PSA
 md_psa_dynamic_dispatch:MBEDTLS_MD_SHA3_512:MBEDTLS_ERR_MD_BAD_INPUT_DATA:MBEDTLS_MD_ENGINE_PSA
 
 PSA dispatch SHA3-512 legacy+driver
-depends_on:MBEDTLS_SHA3_512_C:MBEDTLS_MD_SHA3_512_VIA_PSA
+depends_on:MBEDTLS_SHA3_C:MBEDTLS_MD_SHA3_512_VIA_PSA
 md_psa_dynamic_dispatch:MBEDTLS_MD_SHA3_512:0:MBEDTLS_MD_ENGINE_PSA