| 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 |
|
| 80 |
mod reseeding; |
| 81 |
pub use reseeding::ReseedingRng; |
| 82 |
|
| 83 |
#[deprecated(since = "0.9.2")] |
| 84 |
pub mod mock; // Public so we don't export `StepRng` directly, making it a bit |
| 85 |
// more clear it is intended for testing. |
| 86 |
|
| 87 |
#[cfg(feature = "small_rng")] |
| 88 |
mod small; |
| 89 |
#[cfg(all( |
| 90 |
feature = "small_rng", |
| 91 |
any(target_pointer_width = "32", target_pointer_width = "16") |
| 92 |
))] |
| 93 |
mod xoshiro128plusplus; |
| 94 |
#[cfg(all(feature = "small_rng", target_pointer_width = "64"))] |
| 95 |
mod xoshiro256plusplus; |
| 96 |
|
| 97 |
#[cfg(feature = "std_rng")] |
| 98 |
mod std; |
| 99 |
#[cfg(feature = "thread_rng")] |
| 100 |
pub(crate) mod thread; |
| 101 |
|
| 102 |
#[cfg(feature = "small_rng")] |
| 103 |
pub use self::small::SmallRng; |
| 104 |
#[cfg(feature = "std_rng")] |
| 105 |
pub use self::std::StdRng; |
| 106 |
#[cfg(feature = "thread_rng")] |
| 107 |
pub use self::thread::ThreadRng; |
| 108 |
|
| 109 |
#[cfg(feature = "os_rng")] |
| 110 |
pub use rand_core::OsRng; |