Function esp_idf_svc::hal::sys::mbedtls_psa_inject_entropy

pub unsafe extern "C" fn mbedtls_psa_inject_entropy(
    seed: *const u8,
    seed_size: usize,
) -> i32

\brief Inject an initial entropy seed for the random generator into secure storage.

This function injects data to be used as a seed for the random generator used by the PSA Crypto implementation. On devices that lack a trusted entropy source (preferably a hardware random number generator), the Mbed PSA Crypto implementation uses this value to seed its random generator.

On devices without a trusted entropy source, this function must be called exactly once in the lifetime of the device. On devices with a trusted entropy source, calling this function is optional. In all cases, this function may only be called before calling any other function in the PSA Crypto API, including psa_crypto_init().

When this function returns successfully, it populates a file in persistent storage. Once the file has been created, this function can no longer succeed.

If any error occurs, this function does not change the system state. You can call this function again after correcting the reason for the error if possible.

\warning This function can fail! Callers MUST check the return status.

\warning If you use this function, you should use it as part of a factory provisioning process. The value of the injected seed is critical to the security of the device. It must be secret, unpredictable and (statistically) unique per device. You should be generate it randomly using a cryptographically secure random generator seeded from trusted entropy sources. You should transmit it securely to the device and ensure that its value is not leaked or stored anywhere beyond the needs of transmitting it from the point of generation to the call of this function, and erase all copies of the value once this function returns.

This is an Mbed TLS extension.

\note This function is only available on the following platforms:

• If the compile-time option MBEDTLS_PSA_INJECT_ENTROPY is enabled. Note that you must provide compatible implementations of mbedtls_nv_seed_read and mbedtls_nv_seed_write.
• In a client-server integration of PSA Cryptography, on the client side, if the server supports this feature. \param[in] seed Buffer containing the seed value to inject. \param[in] seed_size Size of the \p seed buffer. The size of the seed in bytes must be greater or equal to both #MBEDTLS_ENTROPY_BLOCK_SIZE and the value of \c MBEDTLS_ENTROPY_MIN_PLATFORM in library/entropy_poll.h in the Mbed TLS source code. It must be less or equal to #MBEDTLS_ENTROPY_MAX_SEED_SIZE.

\retval #PSA_SUCCESS The seed value was injected successfully. The random generator of the PSA Crypto implementation is now ready for use. You may now call psa_crypto_init() and use the PSA Crypto implementation. \retval #PSA_ERROR_INVALID_ARGUMENT \p seed_size is out of range. \retval #PSA_ERROR_STORAGE_FAILURE There was a failure reading or writing from storage. \retval #PSA_ERROR_NOT_PERMITTED The library has already been initialized. It is no longer possible to call this function.