# [−][src]Crate rand_os

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 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.

# Usage example

    use rand_os::OsRng;
    use rand_os::rand_core::RngCore;

    let mut os_rng = OsRng::new().unwrap();
    let mut key = [0u8; 16];
    os_rng.fill_bytes(&mut key);
    let random_u64 = os_rng.next_u64();

# 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.

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.

## 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 and error handling

We cannot guarantee that `OsRng` will fail, but if it does, it will likely be either when `OsRng::new()` is first called or when data is first read. If you wish to catch errors early, then test reading of at least one byte from `OsRng` via `try_fill_bytes`. If this succeeds, it is extremely unlikely that any further errors will occur.

Only `try_fill_bytes` is able to report the cause of an error; the other [`RngCore`] methods may (depending on the error kind) retry several times, but must eventually panic if the error persists.

## Re-exports

`pub extern crate rand_core;`

## Structs

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

# Help

## Keyboard Shortcuts

`?`
  Show this help dialog
`S`
  Focus the search field
`↑`
  Move up in search results
`↓`
  Move down in search results
`↹`
  Switch tab
`⏎`
  Go to active search result
`+`
  Expand all sections
`-`
  Collapse all sections

## Search Tricks

Prefix searches with a type followed by a colon (e.g., `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g., `vec -> usize` or `* -> vec`)

Search multiple things at once by splitting your query with comma (e.g., `str,u8` or `String,struct:Vec,test`)