Skip to content

Latest commit

 

History

History
66 lines (38 loc) · 4.29 KB

random.rst

File metadata and controls

66 lines (38 loc) · 4.29 KB
Raw

Random Number Generation

{IDF_TARGET_RF_NAME: default="Wi-Fi or Bluetooth", esp32s2="Wi-Fi"} {IDF_TARGET_RF_IS: default="are", esp32s2="is"} {IDF_TARGET_BOOTLOADER_RANDOM_INCOMPATIBLE: default="", esp32="I2S, "}

{IDF_TARGET_NAME} contains a hardware random number generator, values from it can be obtained using the APIs :cppesp_random and :cppesp_fill_random.

The hardware RNG produces true random numbers under any of the following conditions:

  • RF subsystem is enabled (i.e. {IDF_TARGET_RF_NAME} {IDF_TARGET_RF_IS} enabled).
  • An internal entropy source has been enabled by calling :cppbootloader_random_enable and not yet disabled by calling :cppbootloader_random_disable.
  • While the ESP-IDF second-stage-bootloader is running. This is because the default ESP-IDF bootloader implementation calls :cppbootloader_random_enable when the bootloader starts, and :cppbootloader_random_disable before executing the app.

When any of these conditions are true, samples of physical noise are continuously mixed into the internal hardware RNG state to provide entropy. Consult the {IDF_TARGET_NAME} Technical Reference Manual > Random Number Generator (RNG) [PDF] chapter for more details.

If none of the above conditions are true, the output of the RNG should be considered pseudo-random only.

Startup

During startup, ESP-IDF bootloader temporarily enables a non-RF entropy source (internal reference voltage noise) that provides entropy for any first boot key generation. However, after the app starts executing then normally only pseudo-random numbers are available until {IDF_TARGET_RF_NAME} {IDF_TARGET_RF_IS} initialized.

To re-enable the entropy source temporarily during app startup, or for an application that does not use {IDF_TARGET_RF_NAME}, call the function :cppbootloader_random_enable to re-enable the internal entropy source. The function :cppbootloader_random_disable must be called to disable the entropy source again before using ADC, {IDF_TARGET_BOOTLOADER_RANDOM_INCOMPATIBLE}{IDF_TARGET_RF_NAME}.

Note

The entropy source enabled during the boot process by the ESP-IDF Second Stage Bootloader will seed the internal RNG state with some entropy. However, the internal hardware RNG state is not large enough to provide a continuous stream of true random numbers. This is why a continuous entropy source must be enabled whenever true random numbers are required.

Note

If an application requires a source of true random numbers but it is not possible to permanently enable a hardware entropy source, consider using a strong software DRBG implementation such as the mbedTLS CTR-DRBG or HMAC-DRBG, with an initial seed of entropy from hardware RNG true random numbers.

not esp32

Secondary Entropy

{IDF_TARGET_NAME} RNG contains a secondary entropy source, based on sampling an asynchronous 8MHz internal oscillator (see the Technical Reference Manual for details). This entropy source is always enabled in ESP-IDF and continuously mixed into the RNG state by hardware. In testing, this secondary entropy source was sufficient to pass the Dieharder random number test suite without the main entropy source enabled (test input was created by concatenating short samples from a continuously resetting {IDF_TARGET_NAME}). However, it is currently only guaranteed that true random numbers will be produced when the main entropy source is also enabled as described above.

API Reference

inc/esp_random.inc

inc/bootloader_random.inc

getrandom

A compatible version of the Linux getrandom() function is also provided for ease of porting:

#include <sys/random.h>

ssize_t getrandom(void *buf, size_t buflen, unsigned int flags);

This function is implemented by calling :cppesp_fill_random internally.

The flags argument is ignored, this function is always non-blocking but the strength of any random numbers is dependent on the same conditions described above.

Return value is -1 (with errno set to EFAULT) if the buf argument is NULL, and equal to buflen otherwise.