Struct rand::rngs::OsRng
[−]
[src]
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): callswindow.crypto.getRandomValues
in browsers, and in Node.jsrequire("crypto").randomBytes
. - Emscripten: reads from emulated
/dev/urandom
, which maps to the same interfaces asstdweb
, but falls back to the insecureMath.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
[src]
Trait Implementations
impl Clone for OsRng
[src]
fn clone(&self) -> OsRng
[src]
Returns a copy of the value. Read more
fn clone_from(&mut self, source: &Self)
1.0.0[src]
Performs copy-assignment from source
. Read more
impl Debug for OsRng
[src]
fn fmt(&self, f: &mut Formatter) -> Result
[src]
Formats the value using the given formatter. Read more
impl CryptoRng for OsRng
[src]
impl RngCore for OsRng
[src]
fn next_u32(&mut self) -> u32
[src]
Return the next random u32
. Read more
fn next_u64(&mut self) -> u64
[src]
Return the next random u64
. Read more
fn fill_bytes(&mut self, dest: &mut [u8])
[src]
Fill dest
with random data. Read more
fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), Error>
[src]
Fill dest
entirely with random data. Read more