Expand description
Interface to the operating system’s random number generator.
Supported targets
| Target | Target Triple | Implementation |
|---|---|---|
| Linux, Android | *‑linux‑* | getrandom system call if available, otherwise /dev/urandom after successfully polling /dev/random |
| Windows | *‑windows‑* | BCryptGenRandom |
| macOS | *‑apple‑darwin | getentropy if available, otherwise /dev/random (identical to /dev/urandom) |
| iOS | *‑apple‑ios | SecRandomCopyBytes |
| FreeBSD | *‑freebsd | getrandom if available, otherwise kern.arandom |
| OpenBSD | *‑openbsd | getentropy |
| NetBSD | *‑netbsd | kern.arandom |
| Dragonfly BSD | *‑dragonfly | getrandom if available, otherwise /dev/random |
| Solaris, illumos | *‑solaris, *‑illumos | getrandom if available, otherwise /dev/random |
| Fuchsia OS | *‑fuchsia | cprng_draw |
| Redox | *‑redox | /dev/urandom |
| Haiku | *‑haiku | /dev/random (identical to /dev/urandom) |
| Hermit | x86_64-*-hermit | RDRAND |
| SGX | x86_64‑*‑sgx | RDRAND |
| VxWorks | *‑wrs‑vxworks‑* | randABytes after checking entropy pool initialization with randSecure |
| ESP-IDF | *‑espidf | esp_fill_random |
| Emscripten | *‑emscripten | /dev/random (identical to /dev/urandom) |
| WASI | wasm32‑wasi | random_get |
| Web Browser | wasm32‑*‑unknown | Crypto.getRandomValues, see WebAssembly support |
| Node.js | wasm32‑*‑unknown | crypto.randomBytes, see WebAssembly support |
| SOLID | *-kmc-solid_* | SOLID_RNG_SampleRandomBytes |
There is no blanket implementation on unix targets that reads from
/dev/urandom. This ensures all supported targets are using the recommended
interface and respect maximum buffer sizes.
Pull Requests that add support for new targets to getrandom are always welcome.
Unsupported targets
By default, getrandom will not compile on unsupported targets, but certain
features allow a user to select a “fallback” implementation if no supported
implementation exists.
All of the below mechanisms only affect unsupported targets. Supported targets will always use their supported implementations. This prevents a crate from overriding a secure source of randomness (either accidentally or intentionally).
RDRAND on x86
If the rdrand Cargo feature is enabled, getrandom will fallback to using
the RDRAND instruction to get randomness on no_std x86/x86_64
targets. This feature has no effect on other CPU architectures.
WebAssembly support
This crate fully supports the
wasm32-wasi and
wasm32-unknown-emscripten
targets. However, the wasm32-unknown-unknown target (i.e. the target used
by wasm-pack) is not automatically
supported since, from the target name alone, we cannot deduce which
JavaScript interface is in use (or if JavaScript is available at all).
Instead, if the js Cargo feature is enabled, this crate will assume
that you are building for an environment containing JavaScript, and will
call the appropriate methods. Both web browser (main window and Web Workers)
and Node.js environments are supported, invoking the methods
described above using the
wasm-bindgen toolchain.
This feature has no effect on targets other than wasm32-unknown-unknown.
Custom implementations
The [register_custom_getrandom!] macro allows a user to mark their own
function as the backing implementation for getrandom. See the macro’s
documentation for more information about writing and registering your own
custom implementations.
Note that registering a custom implementation only has an effect on targets
that would otherwise not compile. Any supported targets (including those
using rdrand and js Cargo features) continue using their normal
implementations even if a function is registered.
Indirect Dependencies
If getrandom is not a direct dependency of your crate, you can still
enable any of the above fallback behaviors by enabling the relevant
feature in your root crate’s Cargo.toml:
[dependencies]
getrandom = { version = "0.2", features = ["js"] }Early boot
Sometimes, early in the boot process, the OS has not collected enough entropy to securely seed its RNG. This is especially common on virtual machines, where standard “random” events are hard to come by.
Some operating system interfaces always block until the RNG is securely seeded. This can take anywhere from a few seconds to more than a minute. A few (Linux, NetBSD and Solaris) offer a choice between blocking and getting an error; in these cases, we always choose to block.
On Linux (when the getrandom system call is not available), reading from
/dev/urandom never blocks, even when the OS hasn’t collected enough
entropy yet. To avoid returning low-entropy bytes, we first poll
/dev/random and only switch to /dev/urandom once this has succeeded.
Error handling
We always choose failure over returning insecure “random” bytes. In general,
on supported platforms, failure is highly unlikely, though not impossible.
If an error does occur, then it is likely that it will occur on every call to
getrandom, hence after the first successful call one can be reasonably
confident that no errors will occur.
Structs
A small and no_std compatible error type
Functions
Fill dest with random bytes from the system’s preferred random number
source.