| 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 |
} |