From d3a6cbb6bb17502d40c0a30d8c8f00edce2df673 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Thu, 26 Jun 2025 13:39:37 +0200 Subject: [PATCH] Subsection for the removal of explicit RNG contexts Signed-off-by: Gilles Peskine --- docs/4.0-migration-guide/psa-only.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/4.0-migration-guide/psa-only.md b/docs/4.0-migration-guide/psa-only.md index 68b7f1bc5e..e4f293dda8 100644 --- a/docs/4.0-migration-guide/psa-only.md +++ b/docs/4.0-migration-guide/psa-only.md @@ -10,6 +10,14 @@ The X.509, PKCS7 and SSL always use PSA for cryptography, with a few exceptions A few functions take different parameters to migrate them to the PSA API. See “[Function prototype changes](#function-prototype-changes)”. +### No random generator instantiation + +Formerly, applications using TLS, asymmetric cryptography operations involving a private key, or other features needing random numbers, needed to provide a random generator, generally by instantiating an entropy context (`mbedtls_entropy_context`) and a DRBG context (`mbedtls_ctr_drbg_context` or `mbedtls_hmac_drbg_context`). This is no longer necessary, or possible. All features that require a random generator (RNG) now use the one provided by the PSA subsystem. + +Instead, applications that use random generators or keys (even public keys) need to call `psa_crypto_init()` before any cryptographic operation or key management operation. + +See also [function prototype changes](#function-prototype-changes), many of which are related to the move from RNG callbacks to a global RNG. + ### Impact on the library configuration Mbed TLS follows the configuration of TF-PSA-Crypto with respect to cryptographic mechanisms. They are now based on `PSA_WANT_xxx` macros instead of legacy configuration macros such as `MBEDTLS_RSA_C`, `MBEDTLS_PKCS1_V15`, etc. The configuration of X.509 and TLS is not directly affected by the configuration. However, applications and middleware that rely on these configuration symbols to know which cryptographic mechanisms to support will need to migrate to `PSA_WANT_xxx` macros. For more information, consult the PSA transition guide in TF-PSA-Crypto.