# [−] [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 | `getentropy()` if available, otherwise `/dev/random` (identical to `/dev/urandom`)
iOS | `SecRandomCopyBytes`
FreeBSD | `getrandom()` if available, otherwise `kern.arandom`
OpenBSD | `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 | `cloudabi_sys_random_get`
Haiku | `/dev/random` (identical to `/dev/urandom`)
L4RE, SGX, UEFI | RDRAND
Hermit | RDRAND as `sys_rand` is currently broken.
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. See the [`Error`] type for more information on what data is returned on failure.

## Structs

Error | A small and `no_std` compatible error type.

## Functions

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

# Help

## Keyboard Shortcuts

`?`
  Show this help dialog
`S`
  Focus the search field
`↑`
  Move up in search results
`↓`
  Move down in search results
`↹`
  Switch tab
`⏎`
  Go to active search result
`+`
  Expand all sections
`-`
  Collapse all sections

## Search Tricks

Prefix searches with a type followed by a colon (e.g., `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g., `vec -> usize` or `* -> vec`)

Search multiple things at once by splitting your query with comma (e.g., `str,u8` or `String,struct:Vec,test`)