Merge pull request #6639 from mpg/doc-driver-only-limitation

Document another limitation of driver-only hashes
This commit is contained in:
Manuel Pégourié-Gonnard 2022-11-25 09:44:35 +01:00 committed by GitHub
commit 91f88db019
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 38 additions and 19 deletions

View file

@ -1,20 +1,19 @@
Features
* Some crypto modules that previously depended on MD or a low-level hash
module, either unconditionally (RSA, PK, PKCS5, PKCS12, EC J-PAKE), or
for some features (PEM for encrypted files), are now able to use PSA
Crypto instead when the legacy API is not available. This means it is
now possible to use all features from those modules in configurations
where the built-in implementations of hashes are excluded and the hashes
are only provided by PSA drivers. In these configurations, you need to
call `psa_crypto_init()` before you call any function from those
modules; this is not required in configurations where the built-in
implementation is still available. Note that some crypto modules and
features still depend on the built-in implementation of hashes:
MBEDTLS_HKDF_C (but the PSA HKDF function do not depend on it),
MBEDTLS_ENTROPY_C, MBEDTLS_HMAC_DRBG_C and MBEDTLS_ECDSA_DETERMINISTIC.
In particular, for now, compiling without built-in hashes requires use
of MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG.
* When MBEDTLS_USE_PSA_CRYPTO is enabled, X.509, TLS 1.2 and TLS 1.3 no
longer depend on MD. This means it is now possible to use them in
configurations where the built-in implementations of hashes are excluded
and the hashes are only provided by PSA drivers.
* Some modules can now use PSA drivers for hashes, including with no
built-in implementation present, but only in some configurations.
- RSA OAEP and PSS (PKCS#1 v2.1), PKCS5, PKCS12 and EC J-PAKE now use
hashes from PSA when (and only when) MBEDTLS_MD_C is disabled.
- PEM parsing of encrypted files now uses MD-5 from PSA when (and only
when) MBEDTLS_MD5_C is disabled.
See the documentation of the corresponding macros in mbedtls_config.h for
details.
Note that some modules are not able to use hashes from PSA yet, including
the entropy module. As a consequence, for now the only way to build with
all hashes only provided by drivers (no built-in hash) is to use
MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG.
* When MBEDTLS_USE_PSA_CRYPTO is enabled, X.509, TLS 1.2 and TLS 1.3 now
properly negotiate/accept hashes based on their availability in PSA.
As a consequence, they now work in configurations where the built-in
implementations of (some) hashes are excluded and those hashes are only
provided by PSA drivers. (See previous entry for limitation on RSA-PSS
though: that module only use hashes from PSA when MBEDTLS_MD_C is off).

View file

@ -1146,6 +1146,11 @@
* \warning If building without MBEDTLS_MD_C, you must call psa_crypto_init()
* before doing any PKCS#1 v2.1 operation.
*
* \warning When building with MBEDTLS_MD_C, all hashes used with this
* need to be available as built-ins (that is, for SHA-256, MBEDTLS_SHA256_C,
* etc.) as opposed to just PSA drivers. So far, PSA drivers are only used by
* this module in builds where MBEDTLS_MD_C is disabled.
*
* This enables support for RSAES-OAEP and RSASSA-PSS operations.
*/
#define MBEDTLS_PKCS1_V21
@ -2433,6 +2438,11 @@
*
* \warning If building without MBEDTLS_MD_C, you must call psa_crypto_init()
* before doing any EC J-PAKE operations.
*
* \warning When building with MBEDTLS_MD_C, all hashes used with this
* need to be available as built-ins (that is, for SHA-256, MBEDTLS_SHA256_C,
* etc.) as opposed to just PSA drivers. So far, PSA drivers are only used by
* this module in builds where MBEDTLS_MD_C is disabled.
*/
#define MBEDTLS_ECJPAKE_C
@ -2777,6 +2787,11 @@
* \warning If building without MBEDTLS_MD_C, you must call psa_crypto_init()
* before doing any PKCS5 operation.
*
* \warning When building with MBEDTLS_MD_C, all hashes used with this
* need to be available as built-ins (that is, for SHA-256, MBEDTLS_SHA256_C,
* etc.) as opposed to just PSA drivers. So far, PSA drivers are only used by
* this module in builds where MBEDTLS_MD_C is disabled.
*
* This module adds support for the PKCS#5 functions.
*/
#define MBEDTLS_PKCS5_C
@ -2796,6 +2811,11 @@
* \warning If building without MBEDTLS_MD_C, you must call psa_crypto_init()
* before doing any PKCS12 operation.
*
* \warning When building with MBEDTLS_MD_C, all hashes used with this
* need to be available as built-ins (that is, for SHA-256, MBEDTLS_SHA256_C,
* etc.) as opposed to just PSA drivers. So far, PSA drivers are only used by
* this module in builds where MBEDTLS_MD_C is disabled.
*
* This module enables PKCS#12 functions.
*/
#define MBEDTLS_PKCS12_C