# getrandom - Rust
Interface to the operating system’s random number generator.
Keywords: rust, rustlang, rust-lang, getrandom

# Crate getrandom

source · [−]
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`
Nintendo 3DS | `armv6k-nintendo-3ds` | `getrandom`

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

Error

A small and `no_std` compatible error type

## Functions

getrandom

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