Struct rand::rngs::OsRng

pub struct OsRng(_);

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 usually does not block. On some systems, and notably virtual machines, it may block very early in the init process, when the OS CSPRNG has not yet been seeded.

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

• Linux, Android: reads from the getrandom(2) system call if available, otherwise from /dev/urandom.
• macOS, iOS: calls SecRandomCopyBytes.
• Windows: calls RtlGenRandom.
• WASM (with stdweb feature): calls window.crypto.getRandomValues in browsers, and in Node.js require("crypto").randomBytes.
• Emscripten: reads from emulated /dev/urandom, which maps to the same interfaces as stdweb, but falls back to the insecure Math.random() if unavailable.
• OpenBSD: calls getentropy(2).
• FreeBSD: uses the kern.arandom sysctl(2) mib.
• Fuchsia: calls cprng_draw.
• Redox: reads from rand: device.
• CloudABI: calls random_get.
• Other Unix-like systems: reads directly from /dev/urandom.

Notes on Unix /dev/urandom

Many Unix systems provide /dev/random as well as /dev/urandom. On all modern systems these two interfaces offer identical quality, with the difference that on some systems /dev/random may block. This is a dated design, and /dev/urandom is preferred by cryptography experts. See Myths about urandom.

On some systems reading from /dev/urandom “may return data prior to the entropy pool being initialized”. I.e., early in the boot process, and especially on virtual machines, /dev/urandom may return data that is less random. As a countermeasure we try to do a single read from /dev/random in non-blocking mode. If the OS RNG is not yet properly seeded, we will get an error. Because we keep one file descriptor to /dev/urandom open when succesful, this is only a small one-time cost.

Panics

OsRng is extremely unlikely to fail if OsRng::new() was 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.