ESP-IDF: Enable by default and use getrandom

After reviewing the updated ESP-IDF random documentation:
  - https://docs.espressif.com/projects/esp-idf/en/stable/esp32/api-reference/system/random.html
  - https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf#rng

I think we should enable this backend by default, and use their
`getrandom` bindings. Given that ESP-IDF provides such bindings, its
clear they intend for cryptographic libraries to use them. Furthurmore,
it seems like the only time the Hardware RNG would lack sufficient
entropy is during early boot, so I added a section to our "Early boot"
documentation noting this issue.

Also note that Rust's standard library unconditonally supports ESP-IDF
for both hash seed generation and generating cryptographic random bytes,
see https://github.com/rust-lang/rust/blob/62bf38fa600f4beb878d61c537837729d4ee689e/library/std/src/sys/random/espidf.rs#L7

Using the `getrandom` binding ensures that if ESP-IDF ever improves
their implementation, we will immediately be able to take advantage of
it.

Signed-off-by: Joe Richey <[email protected]>

Author: josephlr

.github/workflows/build.yml

@@ -86,6 +86,7 @@ jobs:
           armv6k-nintendo-3ds,
           armv7-sony-vita-newlibeabihf,
           i686-unknown-hurd-gnu,
+          riscv32imc-esp-espidf,
           x86_64-unknown-hermit,
           x86_64-wrs-vxworks,
           x86_64-unknown-dragonfly,
@@ -207,19 +208,6 @@ jobs:
           RUSTFLAGS: -Dwarnings --cfg getrandom_backend="rndr"
         run: cargo build --target=aarch64-unknown-linux-gnu --features std
 
-  esp-idf:
-    name: ESP-IDF
-    runs-on: ubuntu-24.04
-    steps:
-      - uses: actions/checkout@v4
-      - uses: dtolnay/rust-toolchain@nightly # Required to build libcore
-        with:
-          components: rust-src
-      - uses: Swatinem/rust-cache@v2
-      - env:
-          RUSTFLAGS: -Dwarnings --cfg getrandom_backend="esp_idf"
-        run: cargo build -Z build-std=core --target=riscv32imc-esp-espidf
-
   no-atomics:
     name: No Atomics
     runs-on: ubuntu-24.04

Cargo.toml

@@ -31,7 +31,7 @@ libc = { version = "0.2.154", default-features = false }
 libc = { version = "0.2.154", default-features = false }
 
 # getrandom
-[target.'cfg(any(target_os = "dragonfly", target_os = "freebsd", target_os = "hurd", target_os = "illumos", all(target_os = "horizon", target_arch = "arm")))'.dependencies]
+[target.'cfg(any(target_os = "dragonfly", target_os = "freebsd", target_os = "hurd", target_os = "illumos", target_os = "espidf", all(target_os = "horizon", target_arch = "arm")))'.dependencies]
 libc = { version = "0.2.154", default-features = false }
 
 # netbsd
@@ -76,7 +76,7 @@ rustc-dep-of-std = ["dep:compiler_builtins", "dep:core"]
 [lints.rust.unexpected_cfgs]
 level = "warn"
 check-cfg = [
-  'cfg(getrandom_backend, values("custom", "rdrand", "rndr", "linux_getrandom", "wasm_js", "esp_idf"))',
+  'cfg(getrandom_backend, values("custom", "rdrand", "rndr", "linux_getrandom", "wasm_js"))',
   'cfg(getrandom_msan)',
   'cfg(getrandom_test_linux_fallback)',
   'cfg(getrandom_test_netbsd_fallback)',

README.md

@@ -65,6 +65,7 @@ fn get_random_u128() -> Result<u128, getrandom::Error> {
 | WASI 0.2           | `wasm32‑wasip2`    | [`get-random-u64`]
 | SOLID              | `*-kmc-solid_*`    | `SOLID_RNG_SampleRandomBytes`
 | Nintendo 3DS       | `*-nintendo-3ds`   | [`getrandom`][18]
+| ESP-IDF            | `*‑espidf`         | [`getrandom`][esp-idf-getrandom], see "Early Boot" section below
 | PS Vita            | `*-vita-*`         | [`getentropy`][19]
 | QNX Neutrino       | `*‑nto-qnx*`       | [`/dev/urandom`][14] (identical to `/dev/random`)
 | AIX                | `*-ibm-aix`        | [`/dev/urandom`][15]
@@ -81,7 +82,6 @@ of randomness based on their specific needs:
 | `linux_getrandom` | Linux, Android       | `*‑linux‑*`              | [`getrandom`][1] system call (without `/dev/urandom` fallback). Bumps minimum supported Linux kernel version to 3.17 and Android API level to 23 (Marshmallow).
 | `rdrand`          | x86, x86-64          | `x86_64-*`, `i686-*`     | [`RDRAND`] instruction
 | `rndr`            | AArch64              | `aarch64-*`              | [`RNDR`] register
-| `esp_idf`         | ESP-IDF              | `*‑espidf`               | [`esp_fill_random`]. WARNING: can return low-quality entropy without proper hardware configuration!
 | `wasm_js`         | Web Browser, Node.js | `wasm32‑unknown‑unknown`, `wasm32v1-none` | [`Crypto.getRandomValues`]
 | `custom`          | All targets          | `*`                      | User-provided custom implementation (see [custom backend])
 
@@ -247,6 +247,13 @@ sourced according to the platform's best practices, but each platform has
 its own limits on the grade of randomness it can promise in environments
 with few sources of entropy.
 
+On ESP-IDF, if `getrandom` is used before enabling WiFi, BT, or the voltage
+noise entropy source (SAR ADC), the Hardware RNG will only be seeded via
+RC_FAST_CLK. This can occur during early boot unless
+`bootloader_random_enable()` is called. For more information see the
+[ESP-IDF RNG Docs][esp-idf-rng] or the
+[RNG section of the ESP32 Technical Reference Manual][esp-trng-docs].
+
 ## Error handling
 
 We always prioritize failure over returning known insecure "random" bytes.
@@ -335,7 +342,9 @@ dual licensed as above, without any additional terms or conditions.
 [`RNDR`]: https://developer.arm.com/documentation/ddi0601/2024-06/AArch64-Registers/RNDR--Random-Number
 [`CCRandomGenerateBytes`]: https://opensource.apple.com/source/CommonCrypto/CommonCrypto-60074/include/CommonRandom.h.auto.html
 [`cprng_draw`]: https://fuchsia.dev/fuchsia-src/zircon/syscalls/cprng_draw
-[`esp_fill_random`]: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/system/random.html#_CPPv415esp_fill_randomPv6size_t
+[esp-idf-getrandom]: https://docs.espressif.com/projects/esp-idf/en/stable/esp32/api-reference/system/random.html#getrandom
+[esp-idf-rng]: https://docs.espressif.com/projects/esp-idf/en/stable/esp32/api-reference/system/random.html
+[esp-trng-docs]: https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf#rng
 [`random_get`]: https://github.com/WebAssembly/WASI/blob/snapshot-01/phases/snapshot/docs.md#-random_getbuf-pointeru8-buf_len-size---errno
 [`get-random-u64`]: https://github.com/WebAssembly/WASI/blob/v0.2.1/wasip2/random/random.wit#L23-L28
 [configuration flags]: #configuration-flags

src/backends.rs

@@ -22,9 +22,6 @@ cfg_if! {
     } else if #[cfg(getrandom_backend = "wasm_js")] {
         mod wasm_js;
         pub use wasm_js::*;
-    } else if #[cfg(getrandom_backend = "esp_idf")] {
-        mod esp_idf;
-        pub use esp_idf::*;
     } else if #[cfg(any(
         target_os = "haiku",
         target_os = "redox",
@@ -46,6 +43,7 @@ cfg_if! {
         target_os = "freebsd",
         target_os = "hurd",
         target_os = "illumos",
+        target_os = "espidf",
         // Check for target_arch = "arm" to only include the 3DS. Does not
         // include the Nintendo Switch (which is target_arch = "aarch64").
         all(target_os = "horizon", target_arch = "arm"),

src/backends/esp_idf.rs

@@ -9,6 +9,7 @@
 //!   - DragonFly 5.7
 //!   - Hurd Glibc 2.31
 //!   - shim-3ds since Feb 2022
+//!   - ESP-IDF since v3.2 (April 2019)
 //!
 //! For these platforms, we always use the default pool and never set the
 //! GRND_RANDOM flag to use the /dev/random pool. On Linux/Android/Hurd, using