esp_random: Add some documentation about using before RF subsystem is on

diff --git a/components/esp32/hw_random.c b/components/esp32/hw_random.c
index 3e5cb81a0a0251ca7d5c93f640860208fe393fb0..4f63ecd989921f3fe7153a6daa72644ad0081d2d 100644 (file)
--- a/components/esp32/hw_random.c
+++ b/components/esp32/hw_random.c
@@ -24,11 +24,11 @@
 uint32_t IRAM_ATTR esp_random(void)
 {
     /* The PRNG which implements WDEV_RANDOM register gets 2 bits
-     * of extra entropy from a hardware randomness source every APB clock cycle.
-     * To make sure entropy is not drained faster than it is added,
-     * this function needs to wait for at least 16 APB clock cycles after reading
-     * previous word. This implementation may actually wait a bit longer
-     * due to extra time spent in arithmetic and branch statements.
+     * of extra entropy from a hardware randomness source every APB clock cycle
+     * (provided WiFi or BT are enabled). To make sure entropy is not drained
+     * faster than it is added, this function needs to wait for at least 16 APB
+     * clock cycles after reading previous word. This implementation may actually
+     * wait a bit longer due to extra time spent in arithmetic and branch statements.
      *
      * As a (probably unncessary) precaution to avoid returning the
      * RNG state as-is, the result is XORed with additional

diff --git a/components/esp32/include/esp_system.h b/components/esp32/include/esp_system.h
index 63592081f1b2eabfe84c5694717dec7bff806d45..cd830cf161d16d3decba78e9846b6e3dd254f58d 100644 (file)
--- a/components/esp32/include/esp_system.h
+++ b/components/esp32/include/esp_system.h
@@ -98,7 +98,15 @@ uint32_t system_get_free_heap_size(void)  __attribute__ ((deprecated));
 /**
  * @brief  Get one random 32-bit word from hardware RNG
  *
- * @return random value between 0 and UINT32_MAX
+ * The hardware RNG is fully functional whenever an RF subsystem is running (ie Bluetooth or WiFi is enabled). For secure
+ * random values, call this function after WiFi or Bluetooth are started.
+ *
+ * When the app is running without an RF subsystem enabled, it should be considered a PRNG. To help improve this
+ * situation, the RNG is pre-seeded with entropy while the IDF bootloader is running. However no new entropy is
+ * available during the window of time between when the bootloader exits and an RF subsystem starts. It may be possible
+ * to discern a non-random pattern in a very large amount of output captured during this window of time.
+ *
+ * @return Random value between 0 and UINT32_MAX
  */
 uint32_t esp_random(void);