logo
Expand description

Interface to the random number generator of the operating system.

Platform sources

OSinterface
Linux, Androidgetrandom system call if available, otherwise /dev/urandom after successfully polling /dev/random
WindowsRtlGenRandom
macOSgetentropy() if available, otherwise /dev/random (identical to /dev/urandom)
iOSSecRandomCopyBytes
FreeBSDgetrandom() if available, otherwise kern.arandom
OpenBSDgetentropy
NetBSDkern.arandom
Dragonfly BSD/dev/random
Solaris, illumosgetrandom system call if available, otherwise /dev/random
Fuchsia OScprng_draw
Redoxrand:
CloudABIcloudabi_sys_random_get
Haiku/dev/random (identical to /dev/urandom)
L4RE, SGX, UEFIRDRAND
HermitRDRAND as sys_rand is currently broken.
VxWorksrandABytes after checking entropy pool initialization with randSecure
Web browsersCrypto.getRandomValues (see Support for WebAssembly and asm.js)
Node.jscrypto.randomBytes (see Support for WebAssembly and asm.js)
WASI__wasi_random_get

Getrandom doesn’t have a blanket implementation for all Unix-like operating systems that reads from /dev/urandom. This ensures all supported operating systems are using the recommended interface and respect maximum buffer sizes.

Unsupported targets

By default, compiling getrandom for an unsupported target will result in a compilation error. If you want to build an application which uses getrandom for such target, you can either:

  • Use [replace] or [patch] section in your Cargo.toml to switch to a custom implementation with a support of your target.
  • Enable the dummy feature to have getrandom use an implementation that always fails at run-time on unsupported targets.

Support for WebAssembly and asm.js

Getrandom supports all of Rust’s current wasm32 targets, and it works with both Node.js and web browsers. The three Emscripten targets asmjs-unknown-emscripten, wasm32-unknown-emscripten, and wasm32-experimental-emscripten use Emscripten’s /dev/random emulation. The WASI target wasm32-wasi uses the __wasi_random_get function defined by the WASI standard.

Getrandom also supports wasm32-unknown-unknown by directly calling JavaScript methods. Rust currently has two ways to do this: bindgen and stdweb. Getrandom supports using either one by enabling the wasm-bindgen or stdweb crate features. Note that if both features are enabled, wasm-bindgen will be used. If neither feature is enabled, calls to getrandom will always fail at runtime.

Early boot

It is possible that early in the boot process the OS hasn’t had enough time yet to collect entropy to securely seed its RNG, especially on virtual machines.

Some operating systems always block the thread until the RNG is securely seeded. This can take anywhere from a few seconds to more than a minute. Others make a best effort to use a seed from before the shutdown and don’t document much.

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) and on NetBSD reading from /dev/urandom never blocks, even when the OS hasn’t collected enough entropy yet. To avoid returning low-entropy bytes, we first read from /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.

On unsupported platforms, getrandom always fails. See the Error type for more information on what data is returned on failure.

Structs

A small and no_std compatible error type.

Functions

Fill dest with random bytes from the system’s preferred random number source.