[−][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 ) |
SGX | RDRAND |
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-unknown-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.
Structs
Error | The error type. |
Functions
getrandom | Fill |