From 1f61b7b8ea4a699e70979d754868d6fa0ba528e5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Manuel=20P=C3=A9gouri=C3=A9-Gonnard?= Date: Fri, 22 Sep 2023 10:15:22 +0200 Subject: [PATCH] Document driver-only hashes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Manuel Pégourié-Gonnard --- ChangeLog.d/driver-only-hashes.txt | 3 ++- docs/driver-only-builds.md | 26 +++++++++++++++++++++++++- 2 files changed, 27 insertions(+), 2 deletions(-) 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..a20b24a26 100644 --- a/docs/driver-only-builds.md +++ b/docs/driver-only-builds.md @@ -71,7 +71,31 @@ you're interested in driver-only support for RSA, please let us know. Hashes ------ -TODO +If 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'll need to call `psa_crypto_init()` before any crypto operation that uses +a hash algorithm that's 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 may also use non-PSA crypto APIs: `MBEDTLS_MD_CAN_xxx` from + `mbedtls/md.h`. Elliptic-curve cryptography (ECC) ---------------------------------