RNG related functions. More...
Modules | |
RNG Configuration configuration | |
Meta RNG backend. | |
Includes all backends definitions. | |
Types shared between all @ref nrf_crypto_rng backends. | |
Types shared between all RNG related functions backends. | |
Typedefs | |
typedef nrf_crypto_backend_rng_context_t | nrf_crypto_rng_context_t |
Context type for RNG. More... | |
typedef nrf_crypto_backend_rng_temp_buffer_t | nrf_crypto_rng_temp_buffer_t |
Temporary work buffer type for RNG. More... | |
Functions | |
ret_code_t | nrf_crypto_rng_init (nrf_crypto_rng_context_t *p_context, nrf_crypto_rng_temp_buffer_t *p_temp_buffer) |
Initialize the random number generator. More... | |
ret_code_t | nrf_crypto_rng_uninit (void) |
Uninitialize the random number generator. More... | |
ret_code_t | nrf_crypto_rng_vector_generate (uint8_t *const p_target, size_t size) |
Generate random data of given size. More... | |
ret_code_t | nrf_crypto_rng_vector_generate_in_range (uint8_t *const p_target, uint8_t const *const p_min, uint8_t const *const p_max, size_t size) |
Generate a vector of constrained random data of given size, between the specified min and max values. More... | |
ret_code_t | nrf_crypto_rng_reseed (nrf_crypto_rng_temp_buffer_t *p_temp_buffer, uint8_t *p_input_data, size_t size) |
This function is used for reseeding the RNG with additional entropy. More... | |
RNG related functions.
There are two available RNG backends:
The CC310 backend meets the standards NIST 800-90B3 and AIS-31 (Class “P2 High”), and should be preferred in most cases on devices that includes the CC310 core. Devices that do not include CC310 should normally use the nRF HW RNG with mbed TLS CTR-DRBG. The mbed TLS CTR-DRBG code is standardized by NIST (SP 800-90A Rev. 1).
Context type for RNG.
Temporary work buffer type for RNG.
Only needed during initializing. Can be freed when nrf_crypto_rng_init has returned. Not needed if NRF_CRYPTO_RNG_STATIC_MEMORY_BUFFERS_ENABLED is enabled in SDK configuration header file.
ret_code_t nrf_crypto_rng_init | ( | nrf_crypto_rng_context_t * | p_context, |
nrf_crypto_rng_temp_buffer_t * | p_temp_buffer | ||
) |
Initialize the random number generator.
This function has no effect when NRF_CRYPTO_RNG_AUTO_INIT_ENABLED is enabled.
[in] | p_context | Pointer to context memory. The context will be managed internally, and the pointer is not used for subsequent calls to the nrf_crypto_rng API. The context memory is needed until nrf_crypto_rng_uninit is called, so it should normally not be on the stack. Use NULL if NRF_CRYPTO_RNG_STATIC_MEMORY_BUFFERS_ENABLED is enabled in SDK configuration header file (recommended for most applications). |
[in,out] | p_temp_buffer | Temporary buffer needed during initialization of the backend. It is not used after the return of this function, and can be freed at that point. Buffer is allocated internally if the pointer is NULL, using the allocated defined by NRF_CRYPTO_ALLOCATOR in sdk_config.h . Use NULL if NRF_CRYPTO_RNG_STATIC_MEMORY_BUFFERS_ENABLED is enabled in SDK configuration header file (recommended for most applications). |
NRF_SUCCESS | If random number generator was initialized successfully. |
NRF_ERROR_CRYPTO_NOT_INITIALIZED | nrf_crypto_init was not called prior to this function. |
NRF_ERROR_CRYPTO_CONTEXT_NULL | p_context was NULL. |
NRF_ERROR_CRYPTO_INTERNAL | If an internal error occurred in the nrf_crypto backend. |
NRF_ERROR_CRYPTO_ALLOC_FAILED | Unable to allocate memory for the context or work buffer. |
NRF_ERROR_CRYPTO_STACK_OVERFLOW | Stack overflow detected. Typically caused by allocating an instance of nrf_crypto_rng_temp_buffer_t on the stack when using CC310 backend. |
NRF_ERROR_CRYPTO_BUSY | RNG is busy. Rerun at a later time. |
ret_code_t nrf_crypto_rng_reseed | ( | nrf_crypto_rng_temp_buffer_t * | p_temp_buffer, |
uint8_t * | p_input_data, | ||
size_t | size | ||
) |
This function is used for reseeding the RNG with additional entropy.
The backends will reseed automatically when required. This function can be used to reseed at specific times and to provide additional data that is used to add personalized randomness.
[in,out] | p_temp_buffer | Temporary buffer needed during reseeding. It is not used after the return of this function, and can be freed at that point. Buffer is allocated internally if the pointer is NULL, using the allocated defined by NRF_CRYPTO_ALLOCATOR in sdk_config.h . Use NULL if NRF_CRYPTO_RNG_STATIC_MEMORY_BUFFERS_ENABLED is enabled in SDK configuration header file (recommended for most applications). |
[in] | p_input_data | Optional input data used to increase the entropy. |
[in] | size | Length of input data. Must be 0, 4, 8 or 12 for CC310. |
NRF_SUCCESS | Data was generated successfully. |
NRF_ERROR_CRYPTO_NOT_INITIALIZED | nrf_crypto_init was not called prior to this function. |
NRF_ERROR_CRYPTO_CONTEXT_NOT_INITIALIZED | nrf_crypto_rng_init was not called prior to this function and NRF_CRYPTO_RNG_AUTO_INIT_ENABLED is disabled. |
NRF_ERROR_CRYPTO_INPUT_NULL | p_temp_buffer was NULL or p_input_data was NULL and size > 0 . |
NRF_ERROR_CRYPTO_INPUT_LENGTH | Invalid input data size. |
NRF_ERROR_CRYPTO_FEATURE_UNAVAILABLE | Reseeding not supported by backend. |
NRF_ERROR_CRYPTO_INTERNAL | If an internal error occurred in the backend. |
NRF_ERROR_CRYPTO_STACK_OVERFLOW | Stack overflow detected. Typically caused by allocating an instance of nrf_crypto_rng_temp_buffer_t on the stack when using CC310 backend. |
NRF_ERROR_CRYPTO_BUSY | RNG is busy. Rerun at a later time. |
ret_code_t nrf_crypto_rng_uninit | ( | void | ) |
Uninitialize the random number generator.
NRF_SUCCESS | If RNG was uninitialized successfully. |
NRF_ERROR_CRYPTO_CONTEXT_NOT_INITIALIZED | RNG has not been initialized. |
NRF_ERROR_CRYPTO_INTERNAL | If an internal error occurred in the nrf_crypto backend. |
NRF_ERROR_CRYPTO_BUSY | RNG is busy. Rerun at a later time. |
ret_code_t nrf_crypto_rng_vector_generate | ( | uint8_t *const | p_target, |
size_t | size | ||
) |
Generate random data of given size.
nrf_crypto_rng_init must be called prior to this function unless NRF_CRYPTO_RNG_AUTO_INIT_ENABLED is enabled in SDK configuration header file.
[in,out] | p_target | Buffer to hold the random generated data. This buffer must be at least as large as the size parameter. |
[in] | size | Length (in bytes) to generate random data for. |
NRF_SUCCESS | Data was generated successfully. |
NRF_ERROR_CRYPTO_NOT_INITIALIZED | nrf_crypto_init was not called prior to this function. |
NRF_ERROR_CRYPTO_CONTEXT_NOT_INITIALIZED | nrf_crypto_rng_init was not called prior to this function and NRF_CRYPTO_RNG_AUTO_INIT_ENABLED is disabled. |
NRF_ERROR_CRYPTO_OUTPUT_NULL | p_target was NULL. |
NRF_ERROR_CRYPTO_OUTPUT_LENGTH | Size was 0 or larger than the backend supports. |
NRF_ERROR_CRYPTO_INTERNAL | If an internal error occurred in the backend. |
NRF_ERROR_CRYPTO_STACK_OVERFLOW | Stack overflow detected in nrf_crypto_rng_init when using auto initialization. Typically caused by allocating an instance of nrf_crypto_rng_temp_buffer_t on the stack when using CC310 backend. |
NRF_ERROR_CRYPTO_BUSY | RNG is busy. Rerun at a later time. |
ret_code_t nrf_crypto_rng_vector_generate_in_range | ( | uint8_t *const | p_target, |
uint8_t const *const | p_min, | ||
uint8_t const *const | p_max, | ||
size_t | size | ||
) |
Generate a vector of constrained random data of given size, between the specified min and max values.
nrf_crypto_rng_init must be called prior to this function unless NRF_CRYPTO_RNG_AUTO_INIT_ENABLED is enabled in SDK configuration header file.
All vectors are in big-endian format, with the most significant byte as the first element / lowest address.
[in,out] | p_target | Buffer to hold the random generated data. This buffer must be at least as large as the size parameter. |
[in] | p_min | Byte array defining the lower limit of the random vector. |
[in] | p_max | Byte array defining the upper limit of the random vector. |
[in] | size | Length (in bytes) to generate random data for. Note that all three buffers (p_target, p_min and p_max) must be of this size. |
NRF_SUCCESS | Data was generated successfully. |
NRF_ERROR_CRYPTO_NOT_INITIALIZED | nrf_crypto_init was not called prior to this function. |
NRF_ERROR_CRYPTO_CONTEXT_NOT_INITIALIZED | nrf_crypto_rng_init was not called prior to this function and NRF_CRYPTO_RNG_AUTO_INIT_ENABLED is disabled. |
NRF_ERROR_CRYPTO_OUTPUT_NULL | p_target was NULL. |
NRF_ERROR_CRYPTO_INPUT_NULL | p_min or p_max was NULL. |
NRF_ERROR_CRYPTO_OUTPUT_LENGTH | Size was 0 or larger than the backend supports. |
NRF_ERROR_CRYPTO_INTERNAL | If an internal error occurred in the backend. |
NRF_ERROR_CRYPTO_STACK_OVERFLOW | Stack overflow detected in nrf_crypto_rng_init when using auto initialization. Typically caused by allocating an instance of nrf_crypto_rng_temp_buffer_t on the stack when using CC310 backend. |
NRF_ERROR_CRYPTO_BUSY | RNG is busy. Rerun at a later time. |