RNG related functions

Context type for RNG.

Note

The actual type depend on the backend in use.

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 .

Note

The actual type depend on the backend in use.

Initialize the random number generator.

This function has no effect when NRF_CRYPTO_RNG_AUTO_INIT_ENABLED is enabled.

Warning

The p_temp_buffer is 6112 bytes when using the CC310 backend. Ensure that stack size is sufficient if allocated on stack. Applications that use nRF HW RNG as backend or are not RAM constrained can use internal static allocation of context and temporary buffers ( NRF_CRYPTO_RNG_STATIC_MEMORY_BUFFERS_ENABLED ).

Note

The context object can be reused without the need for a full reinitialization of the backend in case of for example wakeup from system OFF, provided that the context is located in a memory block that is retained. This only apply to the CC310 backend, and when the context is allocated manually (NRF_CRYPTO_RNG_STATIC_MEMORY_BUFFERS_ENABLED disabled).

Parameters

[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).

Return values

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.

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.

Note

Reseeding is not supported if using the nRF HW RNG backend without mbed TLS CTR-DRBG (NRF_CRYPTO_BACKEND_NRF_HW_RNG_MBEDTLS_CTR_DRBG_ENABLED disabled in sdk_config.h).

Warning

The p_temp_buffer is 6112 bytes when the CC310 backend is used. Ensure that stack size is sufficient if allocated on stack.

Parameters

[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.

Return values

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.

Uninitialize the random number generator.

Return values

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.

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 .

Parameters

[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.

Return values

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.

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.

Note

This function may execute for a long time if the window between p_min and p_max is small.

Parameters

[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.

Return values

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.