Document driver-only hashes

Signed-off-by: Manuel Pégourié-Gonnard <manuel.pegourie-gonnard@arm.com>

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.

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