[−][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 successfully polling /dev/random |
| 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 successfully polling /dev/random |
| 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.
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 yourCargo.tomlto switch to a custom implementation with a support of your target. - Enable the
dummyfeature to have getrandom use an implementation that always fails at run-time on unsupported targets.
Support for WebAssembly and asm.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,
compiling getrandom will result in a compilation error. It can be avoided
by enabling the dummy feature, which will make getrandom to use an
always failing implementation.
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 |
Functions
| getrandom | Fill |