Group psa_rng

group Random generator

Functions

psa_status_t mbedtls_psa_external_get_random(mbedtls_psa_external_random_context_t *context, uint8_t *output, size_t output_size, size_t *output_length)

External random generator function, implemented by the platform.

When the compile-time option MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG is enabled, this function replaces Mbed TLS’s entropy and DRBG modules for all random generation triggered via PSA crypto interfaces.

Note

This random generator must deliver random numbers with cryptographic quality and high performance. It must supply unpredictable numbers with a uniform distribution. The implementation of this function is responsible for ensuring that the random generator is seeded with sufficient entropy. If you have a hardware TRNG which is slow or delivers non-uniform output, declare it as an entropy source with mbedtls_entropy_add_source() instead of enabling this option.

Parameters:

  • context – [inout] Pointer to the random generator context. This is all-bits-zero on the first call and preserved between successive calls.

  • output – [out] Output buffer. On success, this buffer contains random data with a uniform distribution.

  • output_size – The size of the output buffer in bytes.

  • output_length – [out] On success, set this value to output_size.

Return values:

  • PSA_SUCCESS – Success. The output buffer contains output_size bytes of cryptographic-quality random data, and *output_length is set to output_size.

  • PSA_ERROR_INSUFFICIENT_ENTROPY – The random generator requires extra entropy and there is no way to obtain entropy under current environment conditions. This error should not happen under normal circumstances since this function is responsible for obtaining as much entropy as it needs. However implementations of this function may return PSA_ERROR_INSUFFICIENT_ENTROPY if there is no way to obtain entropy without blocking indefinitely.

  • PSA_ERROR_HARDWARE_FAILURE – A failure of the random generator hardware that isn’t covered by PSA_ERROR_INSUFFICIENT_ENTROPY.

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 and MBEDTLS_ENTROPY_NO_SOURCES_OK are enabled, and MBEDTLS_PSA_BUILTIN_GET_ENTROPY and MBEDTLS_PSA_DRIVER_GET_ENTROPY are 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.

Note

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

Note

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:

  • perso – [in] 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_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.

Note

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_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_PSA_RNG_RESEED_INTERVAL.

Prediction resistance is disabled by default, although setting MBEDTLS_PSA_RNG_RESEED_INTERVAL to 1 satisfies the prediction resistance property even when the specific setting for prediction resistance is disabled.

Note

This function has no effect when MBEDTLS_PSA_CRYPTO_EXTERNAL_RNG is enabled.

Note

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.