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 //! ## Background: Random number generators (RNGs) 12 //! 13 //! Computers cannot produce random numbers from nowhere. We classify 14 //! random number generators as follows: 15 //! 16 //! - "True" random number generators (TRNGs) use hard-to-predict data sources 17 //! (e.g. the high-resolution parts of event timings and sensor jitter) to 18 //! harvest random bit-sequences, apply algorithms to remove bias and 19 //! estimate available entropy, then combine these bits into a byte-sequence 20 //! or an entropy pool. This job is usually done by the operating system or 21 //! a hardware generator (HRNG). 22 //! - "Pseudo"-random number generators (PRNGs) use algorithms to transform a 23 //! seed into a sequence of pseudo-random numbers. These generators can be 24 //! fast and produce well-distributed unpredictable random numbers (or not). 25 //! They are usually deterministic: given algorithm and seed, the output 26 //! sequence can be reproduced. They have finite period and eventually loop; 27 //! with many algorithms this period is fixed and can be proven sufficiently 28 //! long, while others are chaotic and the period depends on the seed. 29 //! - "Cryptographically secure" pseudo-random number generators (CSPRNGs) 30 //! are the sub-set of PRNGs which are secure. Security of the generator 31 //! relies both on hiding the internal state and using a strong algorithm. 32 //! 33 //! ## Traits and functionality 34 //! 35 //! All RNGs implement the [`RngCore`] trait, as a consequence of which the 36 //! [`Rng`] extension trait is automatically implemented. Secure RNGs may 37 //! additionally implement the [`CryptoRng`] trait. 38 //! 39 //! All PRNGs require a seed to produce their random number sequence. The 40 //! [`SeedableRng`] trait provides three ways of constructing PRNGs: 41 //! 42 //! - `from_seed` accepts a type specific to the PRNG 43 //! - `from_rng` allows a PRNG to be seeded from any other RNG 44 //! - `seed_from_u64` allows any PRNG to be seeded from a `u64` insecurely 45 //! - `from_entropy` securely seeds a PRNG from fresh entropy 46 //! 47 //! Use the [`rand_core`] crate when implementing your own RNGs. 48 //! 49 //! ## Our generators 50 //! 51 //! This crate provides several random number generators: 52 //! 53 //! - [`OsRng`] is an interface to the operating system's random number 54 //! source. Typically the operating system uses a CSPRNG with entropy 55 //! provided by a TRNG and some type of on-going re-seeding. 56 //! - [`ThreadRng`], provided by the [`thread_rng`] function, is a handle to a 57 //! thread-local CSPRNG with periodic seeding from [`OsRng`]. Because this 58 //! is local, it is typically much faster than [`OsRng`]. It should be 59 //! secure, though the paranoid may prefer [`OsRng`]. 60 //! - [`StdRng`] is a CSPRNG chosen for good performance and trust of security 61 //! (based on reviews, maturity and usage). The current algorithm is ChaCha12, 62 //! which is well established and rigorously analysed. 63 //! [`StdRng`] provides the algorithm used by [`ThreadRng`] but without 64 //! periodic reseeding. 65 //! - [`SmallRng`] is an **insecure** PRNG designed to be fast, simple, require 66 //! little memory, and have good output quality. 67 //! 68 //! The algorithms selected for [`StdRng`] and [`SmallRng`] may change in any 69 //! release and may be platform-dependent, therefore they should be considered 70 //! **not reproducible**. 71 //! 72 //! ## Additional generators 73 //! 74 //! **TRNGs**: The [`rdrand`] crate provides an interface to the RDRAND and 75 //! RDSEED instructions available in modern Intel and AMD CPUs. 76 //! The [`rand_jitter`] crate provides a user-space implementation of 77 //! entropy harvesting from CPU timer jitter, but is very slow and has 78 //! [security issues](https://github.com/rust-random/rand/issues/699). 79 //! 80 //! **PRNGs**: Several companion crates are available, providing individual or 81 //! families of PRNG algorithms. These provide the implementations behind 82 //! [`StdRng`] and [`SmallRng`] but can also be used directly, indeed *should* 83 //! be used directly when **reproducibility** matters. 84 //! Some suggestions are: [`rand_chacha`], [`rand_pcg`], [`rand_xoshiro`]. 85 //! A full list can be found by searching for crates with the [`rng` tag]. 86 //! 87 //! [`Rng`]: crate::Rng 88 //! [`RngCore`]: crate::RngCore 89 //! [`CryptoRng`]: crate::CryptoRng 90 //! [`SeedableRng`]: crate::SeedableRng 91 //! [`thread_rng`]: crate::thread_rng 92 //! [`rdrand`]: https://crates.io/crates/rdrand 93 //! [`rand_jitter`]: https://crates.io/crates/rand_jitter 94 //! [`rand_chacha`]: https://crates.io/crates/rand_chacha 95 //! [`rand_pcg`]: https://crates.io/crates/rand_pcg 96 //! [`rand_xoshiro`]: https://crates.io/crates/rand_xoshiro 97 //! [`rng` tag]: https://crates.io/keywords/rng 98 99 #[cfg_attr(doc_cfg, doc(cfg(feature = "std")))] 100 #[cfg(feature = "std")] pub mod adapter; 101 102 pub 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(all(feature = "small_rng", target_pointer_width = "64"))] 106 mod xoshiro256plusplus; 107 #[cfg(all(feature = "small_rng", not(target_pointer_width = "64")))] 108 mod xoshiro128plusplus; 109 #[cfg(feature = "small_rng")] mod small; 110 111 #[cfg(feature = "std_rng")] mod std; 112 #[cfg(all(feature = "std", feature = "std_rng"))] pub(crate) mod thread; 113 114 #[cfg(feature = "small_rng")] pub use self::small::SmallRng; 115 #[cfg(feature = "std_rng")] pub use self::std::StdRng; 116 #[cfg(all(feature = "std", feature = "std_rng"))] pub use self::thread::ThreadRng; 117 118 #[cfg_attr(doc_cfg, doc(cfg(feature = "getrandom")))] 119 #[cfg(feature = "getrandom")] pub use rand_core::OsRng; 120