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

Detailed Description

RNG related functions.

There are two available RNG backends:

ARM CryptoCell CC310 (default for devices with CC310).
nRF HW RNG peripheral.
- CTR-DRBG mode - nRF HW RNG used for seeding mbed TLS CTR-DRBG (default for devices without CC310).
- Raw mode - all data is generated by the nRF HW RNG.

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

Typedef Documentation

typedef nrf_crypto_backend_rng_context_t nrf_crypto_rng_context_t

Context type for RNG.

Note: The actual type depend on the backend in use.

typedef nrf_crypto_backend_rng_temp_buffer_t nrf_crypto_rng_temp_buffer_t

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.

Function Documentation

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.

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.

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.

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.

ret_code_t nrf_crypto_rng_uninit ( void )

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.

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.

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.

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.

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.

Modules

Typedefs

Functions

Detailed Description

Typedef Documentation

Function Documentation