getrandom

getrandom is a minimal-dependency Rust crate that provides a single, uniform interface for filling a buffer with random bytes sourced from the underlying operating system’s secure random number generator. It abstracts the differences between platform-specific APIs - getrandom(2)//dev/urandom on Linux, BCryptGenRandom on Windows, getentropy on macOS/BSD, and WASI/wasm-bindgen paths for WebAssembly - behind one getrandom::fill() call. Maintained by the Rand Project, it’s a foundational dependency underpinning much of the Rust cryptography and randomness ecosystem, including the rand crate itself.

What You Get

• A single fill() function (plus a fallible try_fill() variant) that populates a byte slice with cryptographically secure random data from the OS
• Platform backend implementations for Linux, Windows, macOS, the BSDs, WASI, and wasm32 targets (via an opt-in wasm_js feature) unified behind one public API
• no_std compatibility, making it usable in embedded and other environments without the Rust standard library
• An optional sys_rng feature exposing a SysRng type compatible with the rand_core traits for integration with the broader rand ecosystem
• An Error type with no_std-friendly error codes plus an optional std-feature conversion to std::io::Error

Common Use Cases

• Generating cryptographic key material, nonces, or salts that need to come directly from the OS’s secure randomness source rather than a userspace PRNG
• Seeding a higher-level PRNG (such as those in the rand crate) with OS entropy at program startup
• Sourcing random bytes in no_std or embedded Rust environments where the standard library isn’t available
• Getting random bytes in a WebAssembly target, using the wasm_js feature to call into the browser’s crypto.getRandomValues under the hood

Under The Hood

Architecture The crate’s public surface lives almost entirely in the 159-line src/lib.rs, which declares the fill/try_fill functions and re-exports the Error type from src/error.rs; the actual platform dispatch happens in src/backends.rs, which uses cfg-if-driven conditional compilation to select the correct backend module (Linux’s getrandom(2) syscall, Windows’ BCryptGenRandom, macOS/BSD getentropy, WASI, or the optional wasm-bindgen path) at compile time rather than runtime, so there is zero dispatch overhead per call. src/sys_rng.rs layers an optional rand_core-compatible SysRng type on top of the same backend calls for crates that want to plug directly into the rand ecosystem’s trait hierarchy. build.rs handles target-specific build-time configuration (detecting libc features, WASM target variants) needed to pick the right backend at compile time. Tech Stack Pure Rust, edition 2024, with cfg-if as effectively the only unconditional dependency; wasm-bindgen/js-sys and rand_core are opt-in via Cargo features (wasm_js, sys_rng) rather than defaults, keeping the dependency footprint minimal for the common non-WASM case. The crate is no_std-compatible by default, with std gated behind an explicit feature flag. Code Quality The tests/ directory is small (2 files) since most of the real testing burden is platform-matrix CI rather than unit tests of pure logic — there’s little application logic to unit test beyond backend dispatch — supplemented by a separate custom_impl_test and nopanic_check crate in the repo root that verify the custom-backend override mechanism and confirm the fast path is panic-free. Given the crate’s small, security-sensitive surface, the low line count itself is a quality signal: less code means less to audit. API Design The API is deliberately reduced to essentially one call (getrandom::fill(&mut buf)), which is about as low-friction as a public API can get; the tradeoff is that feature flags (std, wasm_js, sys_rng) and backend-override mechanisms via getrandom_backend cfg require reading the docs for anything beyond the default case, which is appropriate for a foundational crate whose users are mostly other libraries rather than end applications.