1Random Number Generation
2========================
3
4{IDF_TARGET_RF_NAME: default="Wi-Fi or Bluetooth", esp32s2="Wi-Fi"}
5{IDF_TARGET_RF_IS: default="are", esp32s2="is"}
6{IDF_TARGET_BOOTLOADER_RANDOM_INCOMPATIBLE: default="", esp32="I2S, "}
7
8{IDF_TARGET_NAME} contains a hardware random number generator, values from it can be obtained using the APIs :cpp:func:`esp_random` and :cpp:func:`esp_fill_random`.
9
10The hardware RNG produces true random numbers under any of the following conditions:
11
12- RF subsystem is enabled (i.e. {IDF_TARGET_RF_NAME} {IDF_TARGET_RF_IS} enabled).
13- An internal entropy source has been enabled by calling :cpp:func:`bootloader_random_enable` and not yet disabled by calling :cpp:func:`bootloader_random_disable`.
14- While the ESP-IDF :ref:`second-stage-bootloader` is running. This is because the default ESP-IDF bootloader implementation calls :cpp:func:`bootloader_random_enable` when the bootloader starts, and :cpp:func:`bootloader_random_disable` before executing the app.
15
16When 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 <{IDF_TARGET_TRM_EN_URL}#rng>`__] chapter for more details.
17
18If none of the above conditions are true, the output of the RNG should be considered pseudo-random only.
19
20Startup
21-------
22
23During 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.
24
25To re-enable the entropy source temporarily during app startup, or for an application that does not use {IDF_TARGET_RF_NAME}, call the function :cpp:func:`bootloader_random_enable` to re-enable the internal entropy source. The function :cpp:func:`bootloader_random_disable` must be called to disable the entropy source again before using ADC, {IDF_TARGET_BOOTLOADER_RANDOM_INCOMPATIBLE}{IDF_TARGET_RF_NAME}.
26
27.. note::
28
29   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.
30
31.. note::
32
33   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.
34
35.. only:: not esp32
36
37    Secondary Entropy
38    -----------------
39
40    {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.
41
42API Reference
43-------------
44
45.. include-build-file:: inc/esp_random.inc
46.. include-build-file:: inc/bootloader_random.inc
47
48getrandom
49---------
50
51A compatible version of the Linux ``getrandom()`` function is also provided for ease of porting:
52
53.. code-block:: c
54
55   #include <sys/random.h>
56
57   ssize_t getrandom(void *buf, size_t buflen, unsigned int flags);
58
59This function is implemented by calling :cpp:func:`esp_fill_random` internally.
60
61The ``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.
62
63Return value is -1 (with ``errno`` set to ``EFAULT``) if the ``buf`` argument is NULL, and equal to ``buflen`` otherwise.
64
65.. _Dieharder: https://webhome.phy.duke.edu/~rgb/General/dieharder.php
66
67