diff --git a/ChangeLog.d/driver-only-hashes.txt b/ChangeLog.d/driver-only-hashes.txt index 4967bb187e..cd1e030d17 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 4e2d68f363..a20b24a264 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) ---------------------------------