Debian Codegraph @

.cargo/vendor/rand/src/rngs/std.rs

raw
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
11 use rand_core::{CryptoRng, RngCore, SeedableRng};
12
13 #[cfg(any(test, feature = "os_rng"))]
14 pub(crate) use rand_chacha::ChaCha12Core as Core;
15
16 use 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)]
70 pub struct StdRng(Rng);
71
72 impl 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
89 impl 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
99 impl CryptoRng for StdRng {}
100
101 #[cfg(test)]
102 mod 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 }