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//! The standard RNG
10
11use rand_core::{CryptoRng, RngCore, SeedableRng};
12
13#[cfg(any(test, feature = "os_rng"))]
14pub(crate) use rand_chacha::ChaCha12Core as Core;
15
16use rand_chacha::ChaCha12Rng as Rng;
17
18/// A strong, fast (amortized), non-portable RNG
19///
20/// This is the "standard" RNG, a generator with the following properties:
21///
22/// - Non-[portable]: any future library version may replace the algorithm
23/// and results may be platform-dependent.
24/// (For a portable version, use the [rand_chacha] crate directly.)
25/// - [CSPRNG]: statistically good quality of randomness and [unpredictable]
26/// - Fast ([amortized](https://en.wikipedia.org/wiki/Amortized_analysis)):
27/// the RNG is fast for bulk generation, but the cost of method calls is not
28/// consistent due to usage of an output buffer.
29///
30/// The current algorithm used is the ChaCha block cipher with 12 rounds. Please
31/// see this relevant [rand issue] for the discussion. This may change as new
32/// evidence of cipher security and performance becomes available.
33///
34/// ## Seeding (construction)
35///
36/// This generator implements the [`SeedableRng`] trait. Any method may be used,
37/// but note that `seed_from_u64` is not suitable for usage where security is
38/// important. Also note that, even with a fixed seed, output is not [portable].
39///
40/// Using a fresh seed **direct from the OS** is the most secure option:
41/// ```
42/// # use rand::{SeedableRng, rngs::StdRng};
43/// let rng = StdRng::from_os_rng();
44/// # let _: StdRng = rng;
45/// ```
46///
47/// Seeding via [`rand::rng()`](crate::rng()) may be faster:
48/// ```
49/// # use rand::{SeedableRng, rngs::StdRng};
50/// let rng = StdRng::from_rng(&mut rand::rng());
51/// # let _: StdRng = rng;
52/// ```
53///
54/// Any [`SeedableRng`] method may be used, but note that `seed_from_u64` is not
55/// suitable where security is required. See also [Seeding RNGs] in the book.
56///
57/// ## Generation
58///
59/// The generators implements [`RngCore`] and thus also [`Rng`][crate::Rng].
60/// See also the [Random Values] chapter in the book.
61///
62/// [portable]: https://rust-random.github.io/book/crate-reprod.html
63/// [Seeding RNGs]: https://rust-random.github.io/book/guide-seeding.html
64/// [unpredictable]: https://rust-random.github.io/book/guide-rngs.html#security
65/// [Random Values]: https://rust-random.github.io/book/guide-values.html
66/// [CSPRNG]: https://rust-random.github.io/book/guide-gen.html#cryptographically-secure-pseudo-random-number-generator
67/// [rand_chacha]: https://crates.io/crates/rand_chacha
68/// [rand issue]: https://github.com/rust-random/rand/issues/932
69#[derive(Clone, Debug, PartialEq, Eq)]
70pub struct StdRng(Rng);
71
72impl RngCore for StdRng {
73 #[inline(always)]
74 fn next_u32(&mut self) -> u32 {
75 self.0.next_u32()
76 }
77
78 #[inline(always)]
79 fn next_u64(&mut self) -> u64 {
80 self.0.next_u64()
81 }
82
83 #[inline(always)]
84 fn fill_bytes(&mut self, dst: &mut [u8]) {
85 self.0.fill_bytes(dst)
86 }
87}
88
89impl SeedableRng for StdRng {
90 // Fix to 256 bits. Changing this is a breaking change!
91 type Seed = [u8; 32];
92
93 #[inline(always)]
94 fn from_seed(seed: Self::Seed) -> Self {
95 StdRng(Rng::from_seed(seed))
96 }
97}
98
99impl CryptoRng for StdRng {}
100
101#[cfg(test)]
102mod test {
103 use crate::rngs::StdRng;
104 use crate::{RngCore, SeedableRng};
105
106 #[test]
107 fn test_stdrng_construction() {
108 // Test value-stability of StdRng. This is expected to break any time
109 // the algorithm is changed.
110 #[rustfmt::skip]
111 let seed = [1,0,0,0, 23,0,0,0, 200,1,0,0, 210,30,0,0,
112 0,0,0,0, 0,0,0,0, 0,0,0,0, 0,0,0,0];
113
114 let target = [10719222850664546238, 14064965282130556830];
115
116 let mut rng0 = StdRng::from_seed(seed);
117 let x0 = rng0.next_u64();
118
119 let mut rng1 = StdRng::from_rng(&mut rng0);
120 let x1 = rng1.next_u64();
121
122 assert_eq!([x0, x1], target);
123 }
124}
125