[][src]Crate getrandom

Interface to the random number generator of the operating system.

Platform sources

OS interface
Linux, Android getrandom system call if available, otherwise /dev/urandom after reading from /dev/random once
Windows RtlGenRandom
macOS, iOS SecRandomCopyBytes
FreeBSD kern.arandom
OpenBSD, Bitrig getentropy
NetBSD /dev/urandom after reading from /dev/random once
Dragonfly BSD /dev/random
Solaris, illumos getrandom system call if available, otherwise /dev/random
Fuchsia OS cprng_draw
Redox rand:
CloudABI random_get
Haiku /dev/random (identical to /dev/urandom)
Web browsers Crypto.getRandomValues (see Support for WebAssembly and ams.js)
Node.js crypto.randomBytes (see Support for WebAssembly and ams.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.

Support for WebAssembly and ams.js

The three Emscripten targets asmjs-unknown-emscripten, wasm32-unknown-emscripten and wasm32-experimental-emscripten use Emscripten's emulation of /dev/random on web browsers and Node.js.

The bare WASM target wasm32-unknown-unknown tries to call the javascript methods directly, using either stdweb or wasm-bindgen depending on what features are activated for this crate. Note that if both features are enabled wasm-bindgen will be used. If neither feature is enabled, getrandom will always fail.

The WASI target wasm32-wasi uses the __wasi_random_get function defined by the WASI standard.

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 genrandom 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 with Error::UNAVAILABLE.

Error codes

The crate uses the following custom error codes:

  • 0x57f4c500 (dec: 1475659008) - an unknown error. Constant: Error::UNKNOWN
  • 0x57f4c501 (dec: 1475659009) - no generator is available. Constant: Error::UNAVAILABLE
  • 0x57f4c580 (dec: 1475659136) - self.crypto is undefined, wasm-bindgen specific error.
  • 0x57f4c581 (dec: 1475659137) - crypto.getRandomValues is undefined, wasm-bindgen specific error.

These codes are provided for reference only and should not be matched upon (but you can match on Error constants). The codes may change in future and such change will not be considered a breaking one.

Other error codes will originate from an underlying system. In case if such error is encountered, please consult with your system documentation.



The error type.



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