mod.rs

// Copyright 2018 The Rust Project Developers. See the COPYRIGHT
// file at the top-level directory of this distribution and at
// https://rust-lang.org/COPYRIGHT.
//
// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
// https://www.apache.org/licenses/LICENSE-2.0> or the MIT license
// <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your
// option. This file may not be copied, modified, or distributed
// except according to those terms.

//! Random number generators and adapters for common usage:
//!
//! - [`ThreadRng`], a fast, secure, auto-seeded thread-local generator
//! - [`StdRng`] and [`SmallRng`], algorithms to cover typical usage
//! - [`EntropyRng`], [`OsRng`] and [`JitterRng`] as entropy sources
//! - [`mock::StepRng`] as a simple counter for tests
//! - [`adapter::ReadRng`] to read from a file/stream
//! - [`adapter::ReseedingRng`] to reseed a PRNG on clone / process fork etc.
//!
//! # Background — Random number generators (RNGs)
//!
//! Computers are inherently deterministic, so to get *random* numbers one
//! either has to use a hardware generator or collect bits of *entropy* from
//! various sources (e.g. event timestamps, or jitter). This is a relatively
//! slow and complicated operation.
//!
//! Generally the operating system will collect some entropy, remove bias, and
//! use that to seed its own PRNG; [`OsRng`] provides an interface to this.
//! [`JitterRng`] is an entropy collector included with Rand that measures
//! jitter in the CPU execution time, and jitter in memory access time.
//! [`EntropyRng`] is a wrapper that uses the best entropy source that is
//! available.
//!
//! ## Pseudo-random number generators
//!
//! What is commonly used instead of "true" random number renerators, are
//! *pseudo-random number generators* (PRNGs), deterministic algorithms that
//! produce an infinite stream of pseudo-random numbers from a small random
//! seed. PRNGs are faster, and have better provable properties. The numbers
//! produced can be statistically of very high quality and can be impossible to
//! predict. (They can also have obvious correlations and be trivial to predict;
//! quality varies.)
//!
//! There are two different types of PRNGs: those developed for simulations
//! and statistics, and those developed for use in cryptography; the latter are
//! called Cryptographically Secure PRNGs (CSPRNG or CPRNG). Both types can
//! have good statistical quality but the latter also have to be impossible to
//! predict, even after seeing many previous output values. Rand provides a good
//! default algorithm from each class:
//!
//! - [`SmallRng`] is a PRNG chosen for low memory usage, high performance and
//!   good statistical quality.
//!   The current algorithm (plain Xorshift) unfortunately performs
//!   poorly in statistical quality test suites (TestU01 and PractRand) and will
//!   be replaced in the next major release.
//! - [`StdRng`] is a CSPRNG chosen for good performance and trust of security
//!   (based on reviews, maturity and usage). The current algorithm is HC-128,
//!   which is one of the recommendations by ECRYPT's eSTREAM project.
//!
//! The above PRNGs do not cover all use-cases; more algorithms can be found in
//! the [`prng` module], as well as in several other crates. For example, you
//! may wish a CSPRNG with significantly lower memory usage than [`StdRng`]
//! while being less concerned about performance, in which case [`ChaChaRng`]
//! is a good choice.
//!
//! One complexity is that the internal state of a PRNG must change with every
//! generated number. For APIs this generally means a mutable reference to the
//! state of the PRNG has to be passed around.
//!
//! A solution is [`ThreadRng`]. This is a thread-local implementation of
//! [`StdRng`] with automatic seeding on first use. It is the best choice if you
//! "just" want a convenient, secure, fast random number source. Use via the
//! [`thread_rng`] function, which gets a reference to the current thread's
//! local instance.
//!
//! ## Seeding
//!
//! As mentioned above, PRNGs require a random seed in order to produce random
//! output. This is especially important for CSPRNGs, which are still
//! deterministic algorithms, thus can only be secure if their seed value is
//! also secure. To seed a PRNG, use one of:
//!
//! - [`FromEntropy::from_entropy`]; this is the most convenient way to seed
//!   with fresh, secure random data.
//! - [`SeedableRng::from_rng`]; this allows seeding from another PRNG or
//!   from an entropy source such as [`EntropyRng`].
//! - [`SeedableRng::from_seed`]; this is mostly useful if you wish to be able
//!   to reproduce the output sequence by using a fixed seed. (Don't use
//!   [`StdRng`] or [`SmallRng`] in this case since different algorithms may be
//!   used by future versions of Rand; use an algorithm from the
//!   [`prng` module].)
//!
//! ## Conclusion
//!
//! - [`thread_rng`] is what you often want to use.
//! - If you want more control, flexibility, or better performance, use
//!   [`StdRng`], [`SmallRng`] or an algorithm from the [`prng` module].
//! - Use [`FromEntropy::from_entropy`] to seed new PRNGs.
//! - If you need reproducibility, use [`SeedableRng::from_seed`] combined with
//!   a named PRNG.
//!
//! More information and notes on cryptographic security can be found
//! in the [`prng` module].
//!
//! ## Examples
//!
//! Examples of seeding PRNGs:
//!
//! ```
//! use rand::prelude::*;
//! # use rand::Error;
//!
//! // StdRng seeded securely by the OS or local entropy collector:
//! let mut rng = StdRng::from_entropy();
//! # let v: u32 = rng.gen();
//!
//! // SmallRng seeded from thread_rng:
//! # fn try_inner() -> Result<(), Error> {
//! let mut rng = SmallRng::from_rng(thread_rng())?;
//! # let v: u32 = rng.gen();
//! # Ok(())
//! # }
//! # try_inner().unwrap();
//!
//! // SmallRng seeded by a constant, for deterministic results:
//! let seed = [1,2,3,4, 5,6,7,8, 9,10,11,12, 13,14,15,16]; // byte array
//! let mut rng = SmallRng::from_seed(seed);
//! # let v: u32 = rng.gen();
//! ```
//!
//!
//! # Implementing custom RNGs
//!
//! If you want to implement custom RNG, see the [`rand_core`] crate. The RNG
//! will have to implement the [`RngCore`] trait, where the [`Rng`] trait is
//! build on top of.
//!
//! If the RNG needs seeding, also implement the [`SeedableRng`] trait.
//!
//! [`CryptoRng`] is a marker trait cryptographically secure PRNGs can
//! implement.
//!
//!
// This module:
//! [`ThreadRng`]: struct.ThreadRng.html
//! [`StdRng`]: struct.StdRng.html
//! [`SmallRng`]: struct.SmallRng.html
//! [`EntropyRng`]: struct.EntropyRng.html
//! [`OsRng`]: struct.OsRng.html
//! [`JitterRng`]: struct.JitterRng.html
// Other traits and functions:
//! [`rand_core`]: https://crates.io/crates/rand_core
//! [`prng` module]: ../prng/index.html
//! [`CryptoRng`]: ../trait.CryptoRng.html
//! [`FromEntropy`]: ../trait.FromEntropy.html
//! [`FromEntropy::from_entropy`]: ../trait.FromEntropy.html#tymethod.from_entropy
//! [`RngCore`]: ../trait.RngCore.html
//! [`Rng`]: ../trait.Rng.html
//! [`SeedableRng`]: ../trait.SeedableRng.html
//! [`SeedableRng::from_rng`]: ../trait.SeedableRng.html#tymethod.from_rng
//! [`SeedableRng::from_seed`]: ../trait.SeedableRng.html#tymethod.from_seed
//! [`thread_rng`]: ../fn.thread_rng.html
//! [`mock::StepRng`]: mock/struct.StepRng.html
//! [`adapter::ReadRng`]: adapter/struct.ReadRng.html
//! [`adapter::ReseedingRng`]: adapter/struct.ReseedingRng.html
//! [`ChaChaRng`]: ../prng/chacha/struct.ChaChaRng.html

pub mod adapter;

#[cfg(feature="std")] mod entropy;
mod jitter;
pub mod mock;   // Public so we don't export `StepRng` directly, making it a bit
                // more clear it is intended for testing.
#[cfg(feature="std")] mod os;
mod small;
mod std;
#[cfg(feature="std")] pub(crate) mod thread;


pub use self::jitter::{JitterRng, TimerError};
#[cfg(feature="std")] pub use self::entropy::EntropyRng;
#[cfg(feature="std")] pub use self::os::OsRng;

pub use self::small::SmallRng;
pub use self::std::StdRng;
#[cfg(feature="std")] pub use self::thread::ThreadRng;