Crate getrandom

source ·
Expand description

Interface to the operating system’s random number generator.

Supported targets

TargetTarget TripleImplementation
Linux, Android*‑linux‑*getrandom system call if available, otherwise /dev/urandom after successfully polling /dev/random
Windows*‑windows‑*BCryptGenRandom
macOS*‑apple‑darwingetentropy() if available, otherwise /dev/random (identical to /dev/urandom)
iOS*‑apple‑iosSecRandomCopyBytes
FreeBSD*‑freebsdgetrandom() if available, otherwise kern.arandom
OpenBSD*‑openbsdgetentropy
NetBSD*‑netbsdkern.arandom
Dragonfly BSD*‑dragonfly/dev/random
Solaris, illumos*‑solaris, *‑illumosgetrandom() if available, otherwise /dev/random
Fuchsia OS*‑fuchsiacprng_draw
Redox*‑redoxrand:
Haiku*‑haiku/dev/random (identical to /dev/urandom)
SGXx86_64‑*‑sgxRDRAND
VxWorks*‑wrs‑vxworks‑*randABytes after checking entropy pool initialization with randSecure
Emscripten*‑emscripten/dev/random (identical to /dev/urandom)
WASIwasm32‑wasi__wasi_random_get
Web Browserwasm32‑*‑unknownCrypto.getRandomValues(), see WebAssembly support
Node.jswasm32‑*‑unknowncrypto.randomBytes, see WebAssembly support

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 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.