Struct rand::rngs::OsRng

[+] Show declaration

pub struct OsRng(_);

[−] Expand description

A random number generator that retrieves randomness straight from the operating system.

This is the preferred external source of entropy for most applications. Commonly it is used to initialize a user-space RNG, which can then be used to generate random values with much less overhead than OsRng.

You may prefer to use EntropyRng instead of OsRng. It is unlikely, but not entirely theoretical, for OsRng to fail. In such cases EntropyRng falls back on a good alternative entropy source.

OsRng::new() is guaranteed to be very cheap (after the first successful call), and will never consume more than one file handle per process.

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)
Web browsers	Crypto.getRandomValues (see Support for WebAssembly and ams.js)
Node.js	crypto.randomBytes (see Support for WebAssembly and ams.js)

Rand 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. Unfortunately it falls back to the insecure Math.random() if a browser doesn't support Crypto.getRandomValues.

The bare Wasm target wasm32-unknown-unknown tries to call the javascript methods directly, using stdweb in combination with cargo-web. wasm-bindgen is not yet supported.

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. With try_fill_bytes we choose to get the error (ErrorKind::NotReady), while the other methods use a blocking interface.

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. As a countermeasure we try to do a single read from /dev/random until we know the OS RNG is initialized (and store this in a global static).

Panics

OsRng is extremely unlikely to fail if OsRng::new(), and one read from it, where succesfull. But in case it does fail, only try_fill_bytes is able to report the cause. Depending on the error the other RngCore methods will retry several times, and panic in case the error remains.

Methods

impl OsRng

[−]

pub fn new() -> Result<OsRng, Error>

[−]

Create a new OsRng.

Trait Implementations

impl Clone for OsRng

[+]

fn clone(&self) -> OsRng

[−]

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

[−]

Performs copy-assignment from source.

impl Debug for OsRng

[+]

fn fmt(&self, f: &mut Formatter) -> Result

[−]

Formats the value using the given formatter.

impl CryptoRng for OsRng

impl RngCore for OsRng

[+]

fn next_u32(&mut self) -> u32

[−]

Return the next random u32.

fn next_u64(&mut self) -> u64

[−]

Return the next random u64.

fn fill_bytes(&mut self, dest: &mut [u8])

[−]

Fill dest with random data.

fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), Error>

[−]

Fill dest entirely with random data.