Random Number Generation

Overview

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.

  • Use sys_rand_get() and related functions for non-cryptographic purposes such as randomizing delays, shuffling data, or general-purpose randomization. These functions are faster but not suitable for security applications.

  • Use sys_csrand_get() for cryptographic purposes such as generating encryption keys, nonces, initialization vectors, or any data that must be unpredictable to an attacker.

Warning

Never use the non-cryptographic random functions (sys_rand_get(), sys_rand8_get(), sys_rand16_get(), sys_rand32_get(), sys_rand64_get()) for security-sensitive operations. These functions do not provide cryptographically secure random numbers.

API Usage

Non-Cryptographic Random Numbers

The following functions provide non-cryptographically secure random numbers:

Example usage:

#include <zephyr/random/random.h>

void example_random_usage(void)
{
    uint8_t buffer[16];
    uint32_t random_value;

    /* Fill buffer with random bytes */
    sys_rand_get(buffer, sizeof(buffer));

    /* Get a single random 32-bit value */
    random_value = sys_rand32_get();
}

Cryptographically Secure Random Numbers

For cryptographic purposes, use sys_csrand_get():

#include <zephyr/random/random.h>

int generate_encryption_key(uint8_t *key, size_t key_len)
{
    int ret;

    ret = sys_csrand_get(key, key_len);
    if (ret != 0) {
        /* Handle error - entropy source may have failed */
        return ret;
    }

    return 0;
}

Note

sys_csrand_get() returns 0 on success, or -EIO if the entropy source fails. Always check the return value when generating cryptographic material.

Kconfig Options

All configuration options can be found in subsys/random/Kconfig.

General Options

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.

Warning

This option is intended only for testing on platforms that lack hardware entropy support. The random numbers generated when this option is enabled are predictable and not suitable for any security-sensitive use.

Non-Cryptographic Random Generator Selection

CONFIG_ENTROPY_DEVICE_RANDOM_GENERATOR

Uses the hardware entropy driver directly to generate random numbers. This provides high-quality random numbers but may be slower than pseudo-random alternatives. Select this option when your hardware entropy source has sufficient performance for your application’s needs.

CONFIG_XOSHIRO_RANDOM_GENERATOR

Uses the Xoshiro128++ pseudo-random number generator, seeded from the hardware entropy source. This is a fast, general-purpose PRNG with a 128-bit state that passes all standard randomness tests.

This is the recommended choice for most applications that need fast non-cryptographic random numbers.

CONFIG_TIMER_RANDOM_GENERATOR

Uses the system timer to generate pseudo-random numbers. This generator produces predictable values and is intended only for testing on platforms without hardware entropy support.

Requires CONFIG_TEST_RANDOM_GENERATOR to be enabled.

Cryptographically Secure Random Generator Selection

The CSPRNG_GENERATOR_CHOICE kconfig choice selects the source for cryptographically secure random number generation.

To override the default in a board or SoC configuration file:

choice CSPRNG_GENERATOR_CHOICE
        default PSA_CSPRNG_GENERATOR
endchoice

Available generators:

CONFIG_HARDWARE_DEVICE_CS_GENERATOR

Uses the hardware entropy driver directly as the source for cryptographically secure random numbers. Select this when your hardware random number generator is certified or validated for cryptographic use.

CONFIG_PSA_CSPRNG_GENERATOR

enables a cryptographically secure random number generator that uses the PSA Crypto API. This CSPRNG implementation leverages the underlying PSA Crypto library’s secure random number generation capabilities, which may use hardware entropy sources when available. The PSA CSPRNG provides cryptographically secure random numbers suitable for security-sensitive applications.

CONFIG_TEST_CSPRNG_GENERATOR

Routes calls to sys_csrand_get() through sys_rand_get(). This allows testing libraries that require CSPRNG on platforms without hardware entropy support.

Requires CONFIG_TEST_RANDOM_GENERATOR to be enabled.

Warning

This option provides no cryptographic security. Use only for testing.

CTR-DRBG Personalization

CONFIG_CS_CTR_DRBG_PERSONALIZATION

A personalization string used during CTR-DRBG initialization. This string is mixed with the entropy source during seeding to make the DRBG state as unique as possible.

Consider customizing this value for your application to add additional uniqueness to the DRBG initialization.

Helper Configuration Options

Devicetree Configuration

The random subsystem uses the zephyr,entropy chosen node to identify the hardware entropy device:

/ {
    chosen {
        zephyr,entropy = &rng;
    };
};

Ensure your board’s devicetree correctly specifies this chosen node if your platform has a hardware random number generator.

API Reference

Random Function APIs

Related code samples