Interface to the random number generator of the operating system.

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

You may prefer to useEntropyRng instead ofOsRng. It is unlikely, butnot entirely theoretical, forOsRng to fail. In such casesEntropyRngfalls back on a good alternative entropy source.

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

Usage example

userand_os::OsRng;userand_os::rand_core::RngCore;letmutos_rng=OsRng::new().unwrap();letmutkey= [0u8;16];os_rng.fill_bytes(&mutkey);letrandom_u64=os_rng.next_u64();

Platform sources

Rand doesn't have a blanket implementation for all Unix-like operatingsystems that reads from/dev/urandom. This ensures all supported operatingsystems are using the recommended interface and respect maximum buffersizes.

Support for WebAssembly and ams.js

The three Emscripten targetsasmjs-unknown-emscripten,wasm32-unknown-emscripten andwasm32-experimental-emscripten useEmscripten's emulation of/dev/random on web browsers and Node.js.

The bare WASM targetwasm32-unknown-unknown tries to call the javascriptmethods directly, using eitherstdweb orwasm-bindgen depending on whatfeatures are activated for this crate. Note that if both features areenabledwasm-bindgen will be used.

Early boot

It is possible that early in the boot process the OS hasn't had enough timeyet to collect entropy to securely seed its RNG, especially on virtualmachines.

Some operating systems always block the thread until the RNG is securelyseeded. 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'tdocument much.

A few, Linux, NetBSD and Solaris, offer a choice between blocking, andgetting an error. Withtry_fill_bytes we choose to get the error(ErrorKind::NotReady), while the other methods use a blocking interface.

On Linux (when thegenrandom system call is not available) and on NetBSDreading from/dev/urandom never blocks, even when the OS hasn't collectedenough 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 aglobal static).

Panics and error handling

We cannot guarantee thatOsRng will fail, but if it does, it will likelybe either whenOsRng::new() is first called or when data is first read.If you wish to catch errors early, then test reading of at least one bytefromOsRng viatry_fill_bytes. If this succeeds, it is extremelyunlikely that any further errors will occur.

Onlytry_fill_bytes is able to report the cause of an error; the otherRngCore methods may (depending on the error kind) retry several times,but must eventually panic if the error persists.