Merge pull request #8240 from mpg/doc-driver-only-hashes
Document driver only hashes (overdue)
diff --git a/ChangeLog.d/driver-only-hashes.txt b/ChangeLog.d/driver-only-hashes.txt
index 4967bb1..cd1e030 100644
--- a/ChangeLog.d/driver-only-hashes.txt
+++ b/ChangeLog.d/driver-only-hashes.txt
@@ -7,4 +7,5 @@
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.
diff --git a/docs/driver-only-builds.md b/docs/driver-only-builds.md
index 4e2d68f..3b61329 100644
--- a/docs/driver-only-builds.md
+++ b/docs/driver-only-builds.md
@@ -3,7 +3,7 @@
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 @@
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)
---------------------------------
diff --git a/tests/include/test/drivers/crypto_config_test_driver_extension.h b/tests/include/test/drivers/crypto_config_test_driver_extension.h
index 138327a..ef8c88a 100644
--- a/tests/include/test/drivers/crypto_config_test_driver_extension.h
+++ b/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
diff --git a/tests/scripts/all.sh b/tests/scripts/all.sh
index 2208783..c85d486 100755
--- a/tests/scripts/all.sh
+++ b/tests/scripts/all.sh
@@ -2321,7 +2321,8 @@
# -----
# 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 @@
# -----
# 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 @@
# -----
# 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.
- loc_extra_list="ALG_SHA_1 ALG_SHA_224 ALG_SHA_256 ALG_SHA_384 ALG_SHA_512"
+ # 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 \
+ 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 @@
# -----
# 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.
- loc_extra_list="ALG_SHA_1 ALG_SHA_224 ALG_SHA_256 ALG_SHA_384 ALG_SHA_512"
+ # 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 \
+ 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 @@
# -----
# 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 @@
# -----
# 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_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 @@
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 @@
# 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 @@
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 @@
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
# ---------
diff --git a/tests/suites/test_suite_md.psa.data b/tests/suites/test_suite_md.psa.data
index cd24add..3ae787c 100644
--- a/tests/suites/test_suite_md.psa.data
+++ b/tests/suites/test_suite_md.psa.data
@@ -87,49 +87,49 @@
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