diff --git a/ChangeLog.d/driver-only-hashes.txt b/ChangeLog.d/driver-only-hashes.txt index 4967bb187..cd1e030d1 100644 --- a/ChangeLog.d/driver-only-hashes.txt +++ b/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. diff --git a/docs/driver-only-builds.md b/docs/driver-only-builds.md index 4e2d68f36..3b6132903 100644 --- a/docs/driver-only-builds.md +++ b/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) --------------------------------- 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 138327ae8..ef8c88a66 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 22087831f..c85d4865e 100755 --- a/tests/scripts/all.sh +++ b/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. - 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 @@ 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. - 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 @@ 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 # --------- diff --git a/tests/suites/test_suite_md.psa.data b/tests/suites/test_suite_md.psa.data index cd24add46..3ae787cbe 100644 --- a/tests/suites/test_suite_md.psa.data +++ b/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