Random Number Generation

The random API subsystem provides random number generation APIs in both cryptographically and non-cryptographically secure instances. Which random API to use is based on the cryptographic requirements of the random number. The non-cryptographic APIs will return random values much faster if non-cryptographic values are needed.

The cryptographically secure random functions shall be compliant to the FIPS 140-2 [NIST02] recommended algorithms. Hardware based random-number generators (RNG) can be used on platforms with appropriate hardware support. Platforms without hardware RNG support shall use the CTR-DRBG algorithm. The algorithm can be provided by TinyCrypt or mbedTLS depending on your application performance and resource requirements.

Note

The CTR-DRBG generator needs an entropy source to establish and maintain the cryptographic security of the PRNG.

Kconfig Options

These options can be found in the following path subsys/random/Kconfig.

CONFIG_TEST_RANDOM_GENERATOR: For testing, this option allows a non-random number generator to be used and permits random number APIs to return values that are not truly random.

The random number generator choice group allows selection of the RNG source function for the system via the RNG_GENERATOR_CHOICE choice group. An override of the default value can be specified in the SOC or board .defconfig file by using:

choice RNG_GENERATOR_CHOICE
        default XOSHIRO_RANDOM_GENERATOR
endchoice

The random number generators available include:

CONFIG_TIMER_RANDOM_GENERATOR: enables number generator based on system timer clock. This number generator is not random and used for testing only.
CONFIG_ENTROPY_DEVICE_RANDOM_GENERATOR: enables a random number generator that uses the enabled hardware entropy gathering driver to generate random numbers.
CONFIG_XOSHIRO_RANDOM_GENERATOR: enables the Xoshiro128++ pseudo-random number generator, that uses the entropy driver as a seed source.

The CSPRNG_GENERATOR_CHOICE choice group provides selection of the cryptographically secure random number generator source function. An override of the default value can be specified in the SOC or board .defconfig file by using:

choice CSPRNG_GENERATOR_CHOICE
        default CTR_DRBG_CSPRNG_GENERATOR
endchoice

The cryptographically secure random number generators available include:

CONFIG_HARDWARE_DEVICE_CS_GENERATOR: enables a cryptographically secure random number generator using the hardware random generator driver
CONFIG_CTR_DRBG_CSPRNG_GENERATOR: enables the CTR-DRBG pseudo-random number generator. The CTR-DRBG is a FIPS140-2 recommended cryptographically secure random number generator.

Personalization data can be provided in addition to the entropy source to make the initialization of the CTR-DRBG as unique as possible.

CONFIG_CS_CTR_DRBG_PERSONALIZATION: CTR-DRBG Initialization Personalization string

API Reference

Related code samples

AWS IoT Core MQTT: Connect to AWS IoT Core and publish messages using MQTT.
Microsoft Azure IoT Hub MQTT: Connect to Azure IoT Hub and publish messages using MQTT.

group random_api

Random Function APIs.

Since: 1.0
Version: 1.0.0

Functions

void sys_rand_get(void *dst, size_t len)

Fill the destination buffer with random data values that should pass general randomness tests.

Note

The random values returned are not considered cryptographically secure random number values.

Parameters:

dst – [out] destination buffer to fill with random data.
len – size of the destination buffer.

int sys_csrand_get(void *dst, size_t len)

Fill the destination buffer with cryptographically secure random data values.

Note

If the random values requested do not need to be cryptographically secure then use sys_rand_get() instead.

Parameters:

dst – [out] destination buffer to fill.
len – size of the destination buffer.

Returns:

0 if success, -EIO if entropy reseed error

static inline uint8_t sys_rand8_get(void)

Return a 8-bit random value that should pass general randomness tests.

Note

The random value returned is not a cryptographically secure random number value.

Returns:: 8-bit random value.

static inline uint16_t sys_rand16_get(void)

Return a 16-bit random value that should pass general randomness tests.

Note

The random value returned is not a cryptographically secure random number value.

Returns:: 16-bit random value.

static inline uint32_t sys_rand32_get(void)

Return a 32-bit random value that should pass general randomness tests.

Note

The random value returned is not a cryptographically secure random number value.

Returns:: 32-bit random value.

static inline uint64_t sys_rand64_get(void)

Return a 64-bit random value that should pass general randomness tests.

Note

The random value returned is not a cryptographically secure random number value.

Returns:: 64-bit random value.