Random generator

Functions
psa_status_t	psa_random_reseed (const uint8_t *perso, size_t perso_size)
psa_status_t	psa_random_deplete (void)
psa_status_t	psa_random_set_prediction_resistance (unsigned enabled)

Detailed Description

Function Documentation

psa_random_deplete()

psa_status_t psa_random_deplete

(

void

)

Force a reseed of the PSA random generator the next time it is used.

The entropy source(s) are the ones configured at compile time.

The random generator is always seeded automatically before use, and it is reseeded as needed based on the configured policy, so most applications do not need to call this function.

This function has a similar purpose as psa_random_reseed(), but the reseed will happen the next time the random generator is used. The advantage of this function is that it does not fail unless the system is in an unintended state, so it can be used in contexts where propagating errors is difficult.

Note

This function has no effect when #MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG is enabled.

If prediction resistance is enabled (either explicitly, or because the reseed interval is set to 1), calling this function is unnecessary since the random generator will always reseed anyway.

Return values

PSA_SUCCESS	The reseed succeeded.
PSA_ERROR_BAD_STATE	The PSA random generator is not active.
PSA_ERROR_NOT_SUPPORTED	PSA uses an external random generator because the compilation option #MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG is enabled. This configuration does not support explicit reseeding.

psa_random_reseed()

psa_status_t psa_random_reseed	(	const uint8_t *	perso,
		size_t	perso_size )

Force an immediate reseed of the PSA random generator.

The entropy source(s) are the ones configured at compile time.

The random generator is always seeded automatically before use, and it is reseeded as needed based on the configured policy, so most applications do not need to call this function.

The main reason to call this function is in scenarios where the process state is cloned (i.e. duplicated) while the random generator is active. In such scenarios, you must call this function in every clone of the original process before performing any cryptographic operation that uses randomness. (Note that any operation that uses a private or secret key may use randomness internally even if the result is not randomized, but hashing and signature verification are ok.) For example:

• If the process is part of a live virtual machine that is cloned, call this function after cloning so that the new instance has a distinct random generator state.
• If the process is part of a hibernated image that may be resumed multiple times, call this function after resuming so that each resumed instance has a distinct random generator state.
• If the process is cloned through the fork() system call, the child process should call this function before using the random generator.

An additional consideration applies in configurations where there is no actual entropy source, only a nonvolatile seed (i.e. #MBEDTLS_ENTROPY_NV_SEED is enabled, #MBEDTLS_NO_PLATFORM_ENTROPY is enabled and #MBEDTLS_ENTROPY_HARDWARE_ALT is disabled). In such configurations, simply calling psa_random_reseed() in multiple cloned processes would result in the same random generator state in all the clones. To avoid this, in such configurations, you must pass a unique perso string in every clone.

Note

This function has no effect when the compilation option #MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG is enabled.

In client-server builds, this function may not be available from clients, since the decision to reseed is generally based on the server state.

If the entropy source fails, the random generator remains usable: subsequent calls to generate random data will succeed until the random generator itself decides to reseed. If you want to force a reseed, either treat the failure as a fatal error, or call psa_random_deplete() instead of this function (or in addition).

Parameters

[in]	perso	A personalization string, i.e. a byte string to inject into the random generator state in addition to entropy obtained from the normal source(s). In most cases, it is fine for perso to be empty. The main use case for a personalization string is when the random generator state is cloned, as described above, and there is no actual entropy source.
	perso_size	Length of perso in bytes.

Return values

PSA_SUCCESS	The reseed succeeded.
PSA_ERROR_BAD_STATE	The PSA random generator is not active.
PSA_ERROR_NOT_SUPPORTED	PSA uses an external random generator because the compilation option #MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG is enabled. This configuration does not support explicit reseeding.
PSA_ERROR_INSUFFICIENT_ENTROPY	The entropy source failed.

psa_random_set_prediction_resistance()

psa_status_t psa_random_set_prediction_resistance

(

unsigned

enabled

)

Enable or disable prediction resistance in the PSA random generator.

When prediction resistance is enabled, the random generator injects extra entropy before each request regardless of its size. As a consequence, a temporary compromise of the random generator state does not, by itself, compromise future steps. Furthermore, duplicating the random generator state (because the running application instance is cloned) is safe since it will not lead to identical random generator outputs in the clones.

When prediction resistance is disabled, the random generator injects extra entropy periodically only as determined by MBEDTLS_CTR_DRBG_RESEED_INTERVAL if MBEDTLS_CTR_DRBG_C is enabled, or MBEDTLS_HMAC_DRBG_RESEED_INTERVAL otherwise.

Prediction resistance is disabled by default, although setting MBEDTLS_CTR_DRBG_RESEED_INTERVAL or MBEDTLS_HMAC_DRBG_RESEED_INTERVAL to 1 satisfies the prediction resistance property even when the option is disabled.

Note

This function has no effect when #MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG is enabled.

Prediction resistance cannot be enabled when the only entropy source is a nonvolatile seed, since prediction resistance is effectively impossible to achieve without actual entropy.

Parameters

enabled

1 to enable prediction resistance. 0 to disable prediction resistance.

Return values

PSA_SUCCESS	The PSA random generator is active, and prediction resistance has been changed to the desired option.
PSA_ERROR_BAD_STATE	The PSA random generator is not active.
PSA_ERROR_INVALID_ARGUMENT	enabled is not valid.
PSA_ERROR_NOT_SUPPORTED	PSA uses an external random generator because the compilation option #MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG is enabled. Or, the random generator only has a nonvolatile seed but no entropy source, and prediction resistance has been requested.