Crate getrandom

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 and Node.js	`wasm32‑*‑unknown`	`Crypto.getRandomValues` if available, then `crypto.randomFillSync` if on Node.js, 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.

+

To enable the js Cargo feature, add the following to the dependencies +section in your Cargo.toml file:

+

[dependencies]
+getrandom = { version = "0.2", features = ["js"] }
+

+

This can be done even if getrandom is not a direct dependency. Cargo +allows crates to enable features for indirect dependencies.

+

This feature should only be enabled for binary, test, or benchmark crates. +Library crates should generally not enable this feature, leaving such a +decision to users of their library. Also, libraries should not introduce +their own js features just to enable getrandom’s js feature.

+

This feature has no effect on targets other than wasm32-unknown-unknown.

+

Node.js ES module support

+

Node.js supports both CommonJS modules and ES modules. Due to +limitations in wasm-bindgen’s module support, we cannot directly +support ES Modules running on Node.js. However, on Node v15 and later, the +module author can add a simple shim to support the Web Cryptography API:

+

import { webcrypto } from 'node:crypto'
+globalThis.crypto = webcrypto
+

+

This crate will then use the provided webcrypto implementation.

+

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.

+

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.

+

On OpenBSD, this kind of entropy accounting isn’t available, and on +NetBSD, blocking on it is discouraged. On these platforms, nonblocking +interfaces are used, even when reliable entropy may not be available. +On the platforms where it is used, the reliability of entropy accounting +itself isn’t free from controversy. This library provides randomness +sourced according to the platform’s best practices, but each platform has +its own limits on the grade of randomness it can promise in environments +with few sources of entropy.

+

Error handling

+

We always choose failure over returning known 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.