rand/rngs/
mod.rs

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//! ## Generators
12//!
13//! This crate provides a small selection of generators.
14//! See also [Types of generators] and [Our RNGs] in the book.
15//!
16//! ##### Non-deterministic 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//!
25//! ##### Standard generators
26//!
27//! These use selected best-in-class algorithms. They are deterministic but not
28//! portable: the algorithms may be changed in any release and may be
29//! platform-dependent.
30//!
31//! -   [`StdRng`] is a CSPRNG chosen for good performance and trust of security
32//!     (based on reviews, maturity and usage). The current algorithm is
33//!     [`ChaCha12Rng`], which is well established and rigorously analysed.
34//!     [`StdRng`] is the deterministic generator used by [`ThreadRng`] but
35//!     without the periodic reseeding or thread-local management.
36//! -   [`SmallRng`] is a relatively simple, insecure generator designed to be
37//!     fast, use little memory, and pass various statistical tests of
38//!     randomness quality. The current algorithm is one of the Xoshiro
39//!     generators below, depending on the target's pointer size.
40//!
41//! ##### Named portable generators
42//!
43//! These are similar to the [standard generators](#standard-generators), but
44//! with the additional [guarantees of reproducibility]:
45//!
46//! -   [`Xoshiro256PlusPlus`] is a very fast 64-bit insecure generator using
47//!     256 bits of state with good performance in statistical tests of quality
48//! -   [`Xoshiro128PlusPlus`] is a very fast 32-bit insecure generator using
49//!     128 bits of state with good performance in statistical tests of quality
50//! -   [`ChaCha8Rng`], [`ChaCha12Rng`] and [`ChaCha20Rng`] are generators over
51//!     the ChaCha stream cipher designed by Daniel J. Bernstein[^1].
52//!
53//! ### Additional generators
54//!
55//! -   The [`rdrand`] crate provides an interface to the RDRAND and RDSEED
56//!     instructions available in modern Intel and AMD CPUs.
57//! -   The [`rand_jitter`] crate provides a user-space implementation of
58//!     entropy harvesting from CPU timer jitter, but is very slow and has
59//!     [security issues](https://github.com/rust-random/rand/issues/699).
60//! -   The [`rand_chacha`] crate provides portable implementations of
61//!     generators derived from the [ChaCha] family of stream ciphers
62//! -   The [`rand_pcg`] crate provides portable implementations of a subset
63//!     of the [PCG] family of small, insecure generators
64//! -   The [`rand_xoshiro`] crate provides portable implementations of the
65//!     [xoshiro] family of small, insecure generators
66//!
67//! For more, search [crates with the `rng` tag].
68//!
69//! ## Traits and functionality
70//!
71//! All generators implement [`RngCore`] and thus also [`Rng`][crate::Rng].
72//! See also the [Random Values] chapter in the book.
73//!
74//! Secure RNGs may additionally implement the [`CryptoRng`] trait.
75//!
76//! Use the [`rand_core`] crate when implementing your own RNGs.
77//!
78//! [^1]: D. J. Bernstein, [*ChaCha, a variant of Salsa20*](https://cr.yp.to/chacha.html)
79//!
80//! [guarantees of reproducibility]: https://rust-random.github.io/book/crate-reprod.html
81//! [Types of generators]: https://rust-random.github.io/book/guide-gen.html
82//! [Our RNGs]: https://rust-random.github.io/book/guide-rngs.html
83//! [Random Values]: https://rust-random.github.io/book/guide-values.html
84//! [`Rng`]: crate::Rng
85//! [`RngCore`]: crate::RngCore
86//! [`CryptoRng`]: crate::CryptoRng
87//! [`SeedableRng`]: crate::SeedableRng
88//! [`rdrand`]: https://crates.io/crates/rdrand
89//! [`rand_jitter`]: https://crates.io/crates/rand_jitter
90//! [`rand_chacha`]: https://crates.io/crates/rand_chacha
91//! [`rand_pcg`]: https://crates.io/crates/rand_pcg
92//! [`rand_xoshiro`]: https://crates.io/crates/rand_xoshiro
93//! [crates with the `rng` tag]: https://crates.io/keywords/rng
94//! [chacha]: https://cr.yp.to/chacha.html
95//! [PCG]: https://www.pcg-random.org/
96//! [xoshiro]: https://prng.di.unimi.it/
97
98mod reseeding;
99pub use reseeding::ReseedingRng;
100
101#[deprecated(since = "0.9.2")]
102pub mod mock; // Public so we don't export `StepRng` directly, making it a bit
103// more clear it is intended for testing.
104
105#[cfg(feature = "small_rng")]
106mod small;
107#[cfg(feature = "small_rng")]
108mod xoshiro128plusplus;
109#[cfg(feature = "small_rng")]
110mod xoshiro256plusplus;
111
112#[cfg(feature = "std_rng")]
113mod std;
114#[cfg(feature = "thread_rng")]
115pub(crate) mod thread;
116
117#[cfg(feature = "small_rng")]
118pub use self::small::SmallRng;
119#[cfg(feature = "small_rng")]
120pub use xoshiro128plusplus::Xoshiro128PlusPlus;
121#[cfg(feature = "small_rng")]
122pub use xoshiro256plusplus::Xoshiro256PlusPlus;
123
124#[cfg(feature = "std_rng")]
125pub use self::std::StdRng;
126#[cfg(feature = "thread_rng")]
127pub use self::thread::ThreadRng;
128
129#[cfg(feature = "chacha")]
130pub use chacha20::{ChaCha8Rng, ChaCha12Rng, ChaCha20Rng};
131
132#[cfg(feature = "os_rng")]
133pub use rand_core::OsRng;
rand/rngs/mod.rs

rand/rngs/
mod.rs
