yuzu-emu/mbedtls
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

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

Browse source 
Document driver only hashes (overdue)
This commit is contained in:
Dave Rodgman 2023-09-24 13:41:45 +01:00 committed by GitHub
commit f6f76c5a25
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
5 changed files with 97 additions and 26 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3
ChangeLog.d/driver-only-hashes.txt
View file

@ -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.

28
docs/driver-only-builds.md
View file

@ -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)
---------------------------------

32
tests/include/test/drivers/crypto_config_test_driver_extension.h
View file

@ -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

36
tests/scripts/all.sh
View file

@ -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
# ---------

24
tests/suites/test_suite_md.psa.data
View file

@ -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