.. _random_api: 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 :c:func:`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 :c:func:`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 (:c:func:`sys_rand_get`, :c:func:`sys_rand8_get`, :c:func:`sys_rand16_get`, :c:func:`sys_rand32_get`, :c:func:`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: - :c:func:`sys_rand_get` - Fill a buffer with random bytes - :c:func:`sys_rand8_get` - Get a random 8-bit value - :c:func:`sys_rand16_get` - Get a random 16-bit value - :c:func:`sys_rand32_get` - Get a random 32-bit value - :c:func:`sys_rand64_get` - Get a random 64-bit value Example usage: .. code-block:: c #include 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 :c:func:`sys_csrand_get`: .. code-block:: c #include 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:: :c:func:`sys_csrand_get` returns 0 on success, or ``-EIO`` if the entropy source fails. Always check the return value when generating cryptographic material. .. _random_kconfig: Kconfig Options *************** All configuration options can be found in :zephyr_file:`subsys/random/Kconfig`. General Options =============== :kconfig:option:`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 :kconfig:option:`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. :kconfig:option:`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. :kconfig:option:`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 :kconfig:option:`CONFIG_TEST_RANDOM_GENERATOR` to be enabled. Cryptographically Secure Random Generator Selection =================================================== The :kconfig:option:`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: .. code-block:: kconfig choice CSPRNG_GENERATOR_CHOICE default PSA_CSPRNG_GENERATOR endchoice Available generators: :kconfig:option:`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. :kconfig:option:`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. :kconfig:option:`CONFIG_TEST_CSPRNG_GENERATOR` Routes calls to :c:func:`sys_csrand_get` through :c:func:`sys_rand_get`. This allows testing libraries that require CSPRNG on platforms without hardware entropy support. Requires :kconfig:option:`CONFIG_TEST_RANDOM_GENERATOR` to be enabled. .. warning:: This option provides **no cryptographic security**. Use only for testing. CTR-DRBG Personalization ------------------------ :kconfig:option:`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: .. code-block:: devicetree / { 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 ************* .. doxygengroup:: random_api