1// Copyright 2018 Developers of the Rand project.
2//
3// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
4// https://www.apache.org/licenses/LICENSE-2.0> or the MIT license
5// <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your
6// option. This file may not be copied, modified, or distributed
7// except according to those terms.
8
9//! Random number generators and adapters
10//!
11//! This crate provides a small selection of non-[portable] generators.
12//! See also [Types of generators] and [Our RNGs] in the book.
13//!
14//! ## Generators
15//!
16//! This crate provides a small selection of non-[portable] random number generators:
17//!
18//! - [`OsRng`] is a stateless interface over the operating system's random number
19//! source. This is typically secure with some form of periodic re-seeding.
20//! - [`ThreadRng`], provided by [`crate::rng()`], is a handle to a
21//! thread-local generator with periodic seeding from [`OsRng`]. Because this
22//! is local, it is typically much faster than [`OsRng`]. It should be
23//! secure, but see documentation on [`ThreadRng`].
24//! - [`StdRng`] is a CSPRNG chosen for good performance and trust of security
25//! (based on reviews, maturity and usage). The current algorithm is ChaCha12,
26//! which is well established and rigorously analysed.
27//! [`StdRng`] is the deterministic generator used by [`ThreadRng`] but
28//! without the periodic reseeding or thread-local management.
29//! - [`SmallRng`] is a relatively simple, insecure generator designed to be
30//! fast, use little memory, and pass various statistical tests of
31//! randomness quality.
32//!
33//! The algorithms selected for [`StdRng`] and [`SmallRng`] may change in any
34//! release and may be platform-dependent, therefore they are not
35//! [reproducible][portable].
36//!
37//! ### Additional generators
38//!
39//! - The [`rdrand`] crate provides an interface to the RDRAND and RDSEED
40//! instructions available in modern Intel and AMD CPUs.
41//! - The [`rand_jitter`] crate provides a user-space implementation of
42//! entropy harvesting from CPU timer jitter, but is very slow and has
43//! [security issues](https://github.com/rust-random/rand/issues/699).
44//! - The [`rand_chacha`] crate provides [portable] implementations of
45//! generators derived from the [ChaCha] family of stream ciphers
46//! - The [`rand_pcg`] crate provides [portable] implementations of a subset
47//! of the [PCG] family of small, insecure generators
48//! - The [`rand_xoshiro`] crate provides [portable] implementations of the
49//! [xoshiro] family of small, insecure generators
50//!
51//! For more, search [crates with the `rng` tag].
52//!
53//! ## Traits and functionality
54//!
55//! All generators implement [`RngCore`] and thus also [`Rng`][crate::Rng].
56//! See also the [Random Values] chapter in the book.
57//!
58//! Secure RNGs may additionally implement the [`CryptoRng`] trait.
59//!
60//! Use the [`rand_core`] crate when implementing your own RNGs.
61//!
62//! [portable]: https://rust-random.github.io/book/crate-reprod.html
63//! [Types of generators]: https://rust-random.github.io/book/guide-gen.html
64//! [Our RNGs]: https://rust-random.github.io/book/guide-rngs.html
65//! [Random Values]: https://rust-random.github.io/book/guide-values.html
66//! [`Rng`]: crate::Rng
67//! [`RngCore`]: crate::RngCore
68//! [`CryptoRng`]: crate::CryptoRng
69//! [`SeedableRng`]: crate::SeedableRng
70//! [`rdrand`]: https://crates.io/crates/rdrand
71//! [`rand_jitter`]: https://crates.io/crates/rand_jitter
72//! [`rand_chacha`]: https://crates.io/crates/rand_chacha
73//! [`rand_pcg`]: https://crates.io/crates/rand_pcg
74//! [`rand_xoshiro`]: https://crates.io/crates/rand_xoshiro
75//! [crates with the `rng` tag]: https://crates.io/keywords/rng
76//! [chacha]: https://cr.yp.to/chacha.html
77//! [PCG]: https://www.pcg-random.org/
78//! [xoshiro]: https://prng.di.unimi.it/
79
80mod reseeding;
81pub use reseeding::ReseedingRng;
82
83pub mod mock; // Public so we don't export `StepRng` directly, making it a bit
84 // more clear it is intended for testing.
85
86#[cfg(feature = "small_rng")]
87mod small;
88#[cfg(all(
89 feature = "small_rng",
90 any(target_pointer_width = "32", target_pointer_width = "16")
91))]
92mod xoshiro128plusplus;
93#[cfg(all(feature = "small_rng", target_pointer_width = "64"))]
94mod xoshiro256plusplus;
95
96#[cfg(feature = "std_rng")]
97mod std;
98#[cfg(feature = "thread_rng")]
99pub(crate) mod thread;
100
101#[cfg(feature = "small_rng")]
102pub use self::small::SmallRng;
103#[cfg(feature = "std_rng")]
104pub use self::std::StdRng;
105#[cfg(feature = "thread_rng")]
106pub use self::thread::ThreadRng;
107
108#[cfg(feature = "os_rng")]
109pub use rand_core::OsRng;
110