rand/rngs/
reseeding.rs

1// Copyright 2018 Developers of the Rand project.
2// Copyright 2013 The Rust Project Developers.
3//
4// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
5// https://www.apache.org/licenses/LICENSE-2.0> or the MIT license
6// <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your
7// option. This file may not be copied, modified, or distributed
8// except according to those terms.
9
10//! A wrapper around another PRNG that reseeds it after it
11//! generates a certain number of random bytes.
12
13use core::mem::size_of_val;
14
15use rand_core::block::{BlockRng, BlockRngCore, CryptoBlockRng};
16use rand_core::{CryptoRng, RngCore, SeedableRng, TryCryptoRng, TryRngCore};
17
18/// A wrapper around any PRNG that implements [`BlockRngCore`], that adds the
19/// ability to reseed it.
20///
21/// `ReseedingRng` reseeds the underlying PRNG in the following cases:
22///
23/// - On a manual call to [`reseed()`].
24/// - After `clone()`, the clone will be reseeded on first use.
25/// - After the PRNG has generated a configurable number of random bytes.
26///
27/// # When should reseeding after a fixed number of generated bytes be used?
28///
29/// Reseeding after a fixed number of generated bytes is never strictly
30/// *necessary*. Cryptographic PRNGs don't have a limited number of bytes they
31/// can output, or at least not a limit reachable in any practical way. There is
32/// no such thing as 'running out of entropy'.
33///
34/// Occasionally reseeding can be seen as some form of 'security in depth'. Even
35/// if in the future a cryptographic weakness is found in the CSPRNG being used,
36/// or a flaw in the implementation, occasionally reseeding should make
37/// exploiting it much more difficult or even impossible.
38///
39/// Use [`ReseedingRng::new`] with a `threshold` of `0` to disable reseeding
40/// after a fixed number of generated bytes.
41///
42/// # Error handling
43///
44/// Although unlikely, reseeding the wrapped PRNG can fail. `ReseedingRng` will
45/// never panic but try to handle the error intelligently through some
46/// combination of retrying and delaying reseeding until later.
47/// If handling the source error fails `ReseedingRng` will continue generating
48/// data from the wrapped PRNG without reseeding.
49///
50/// Manually calling [`reseed()`] will not have this retry or delay logic, but
51/// reports the error.
52///
53/// # Example
54///
55/// ```
56/// use rand::prelude::*;
57/// use rand_chacha::ChaCha20Core; // Internal part of ChaChaRng that
58///                              // implements BlockRngCore
59/// use rand::rngs::OsRng;
60/// use rand::rngs::ReseedingRng;
61///
62/// let mut reseeding_rng = ReseedingRng::<ChaCha20Core, _>::new(0, OsRng).unwrap();
63///
64/// println!("{}", reseeding_rng.random::<u64>());
65///
66/// let mut cloned_rng = reseeding_rng.clone();
67/// assert!(reseeding_rng.random::<u64>() != cloned_rng.random::<u64>());
68/// ```
69///
70/// [`BlockRngCore`]: rand_core::block::BlockRngCore
71/// [`ReseedingRng::new`]: ReseedingRng::new
72/// [`reseed()`]: ReseedingRng::reseed
73#[derive(Debug)]
74pub struct ReseedingRng<R, Rsdr>(BlockRng<ReseedingCore<R, Rsdr>>)
75where
76    R: BlockRngCore + SeedableRng,
77    Rsdr: TryRngCore;
78
79impl<R, Rsdr> ReseedingRng<R, Rsdr>
80where
81    R: BlockRngCore + SeedableRng,
82    Rsdr: TryRngCore,
83{
84    /// Create a new `ReseedingRng` from an existing PRNG, combined with a RNG
85    /// to use as reseeder.
86    ///
87    /// `threshold` sets the number of generated bytes after which to reseed the
88    /// PRNG. Set it to zero to never reseed based on the number of generated
89    /// values.
90    pub fn new(threshold: u64, reseeder: Rsdr) -> Result<Self, Rsdr::Error> {
91        Ok(ReseedingRng(BlockRng::new(ReseedingCore::new(
92            threshold, reseeder,
93        )?)))
94    }
95
96    /// Immediately reseed the generator
97    ///
98    /// This discards any remaining random data in the cache.
99    pub fn reseed(&mut self) -> Result<(), Rsdr::Error> {
100        self.0.reset();
101        self.0.core.reseed()
102    }
103}
104
105// TODO: this should be implemented for any type where the inner type
106// implements RngCore, but we can't specify that because ReseedingCore is private
107impl<R, Rsdr> RngCore for ReseedingRng<R, Rsdr>
108where
109    R: BlockRngCore<Item = u32> + SeedableRng,
110    Rsdr: TryRngCore,
111{
112    #[inline(always)]
113    fn next_u32(&mut self) -> u32 {
114        self.0.next_u32()
115    }
116
117    #[inline(always)]
118    fn next_u64(&mut self) -> u64 {
119        self.0.next_u64()
120    }
121
122    fn fill_bytes(&mut self, dest: &mut [u8]) {
123        self.0.fill_bytes(dest)
124    }
125}
126
127impl<R, Rsdr> Clone for ReseedingRng<R, Rsdr>
128where
129    R: BlockRngCore + SeedableRng + Clone,
130    Rsdr: TryRngCore + Clone,
131{
132    fn clone(&self) -> ReseedingRng<R, Rsdr> {
133        // Recreating `BlockRng` seems easier than cloning it and resetting
134        // the index.
135        ReseedingRng(BlockRng::new(self.0.core.clone()))
136    }
137}
138
139impl<R, Rsdr> CryptoRng for ReseedingRng<R, Rsdr>
140where
141    R: BlockRngCore<Item = u32> + SeedableRng + CryptoBlockRng,
142    Rsdr: TryCryptoRng,
143{
144}
145
146#[derive(Debug)]
147struct ReseedingCore<R, Rsdr> {
148    inner: R,
149    reseeder: Rsdr,
150    threshold: i64,
151    bytes_until_reseed: i64,
152}
153
154impl<R, Rsdr> BlockRngCore for ReseedingCore<R, Rsdr>
155where
156    R: BlockRngCore + SeedableRng,
157    Rsdr: TryRngCore,
158{
159    type Item = <R as BlockRngCore>::Item;
160    type Results = <R as BlockRngCore>::Results;
161
162    fn generate(&mut self, results: &mut Self::Results) {
163        if self.bytes_until_reseed <= 0 {
164            // We get better performance by not calling only `reseed` here
165            // and continuing with the rest of the function, but by directly
166            // returning from a non-inlined function.
167            return self.reseed_and_generate(results);
168        }
169        let num_bytes = size_of_val(results.as_ref());
170        self.bytes_until_reseed -= num_bytes as i64;
171        self.inner.generate(results);
172    }
173}
174
175impl<R, Rsdr> ReseedingCore<R, Rsdr>
176where
177    R: BlockRngCore + SeedableRng,
178    Rsdr: TryRngCore,
179{
180    /// Create a new `ReseedingCore`.
181    ///
182    /// `threshold` is the maximum number of bytes produced by
183    /// [`BlockRngCore::generate`] before attempting reseeding.
184    fn new(threshold: u64, mut reseeder: Rsdr) -> Result<Self, Rsdr::Error> {
185        // Because generating more values than `i64::MAX` takes centuries on
186        // current hardware, we just clamp to that value.
187        // Also we set a threshold of 0, which indicates no limit, to that
188        // value.
189        let threshold = if threshold == 0 {
190            i64::MAX
191        } else if threshold <= i64::MAX as u64 {
192            threshold as i64
193        } else {
194            i64::MAX
195        };
196
197        let inner = R::try_from_rng(&mut reseeder)?;
198
199        Ok(ReseedingCore {
200            inner,
201            reseeder,
202            threshold,
203            bytes_until_reseed: threshold,
204        })
205    }
206
207    /// Reseed the internal PRNG.
208    fn reseed(&mut self) -> Result<(), Rsdr::Error> {
209        R::try_from_rng(&mut self.reseeder).map(|result| {
210            self.bytes_until_reseed = self.threshold;
211            self.inner = result
212        })
213    }
214
215    #[inline(never)]
216    fn reseed_and_generate(&mut self, results: &mut <Self as BlockRngCore>::Results) {
217        let num_bytes = size_of_val(results.as_ref());
218
219        if let Err(e) = self.reseed() {
220            panic!("Reseeding RNG failed: {e}");
221        }
222
223        self.bytes_until_reseed = self.threshold - num_bytes as i64;
224        self.inner.generate(results);
225    }
226}
227
228impl<R, Rsdr> Clone for ReseedingCore<R, Rsdr>
229where
230    R: BlockRngCore + SeedableRng + Clone,
231    Rsdr: TryRngCore + Clone,
232{
233    fn clone(&self) -> ReseedingCore<R, Rsdr> {
234        ReseedingCore {
235            inner: self.inner.clone(),
236            reseeder: self.reseeder.clone(),
237            threshold: self.threshold,
238            bytes_until_reseed: 0, // reseed clone on first use
239        }
240    }
241}
242
243impl<R, Rsdr> CryptoBlockRng for ReseedingCore<R, Rsdr>
244where
245    R: BlockRngCore<Item = u32> + SeedableRng + CryptoBlockRng,
246    Rsdr: TryCryptoRng,
247{
248}
249
250#[cfg(feature = "std_rng")]
251#[cfg(test)]
252mod test {
253    use crate::rngs::std::Core;
254    use crate::test::const_rng;
255    use crate::Rng;
256
257    use super::ReseedingRng;
258
259    #[test]
260    fn test_reseeding() {
261        let zero = const_rng(0);
262        let thresh = 1; // reseed every time the buffer is exhausted
263        let mut reseeding = ReseedingRng::<Core, _>::new(thresh, zero).unwrap();
264
265        // RNG buffer size is [u32; 64]
266        // Debug is only implemented up to length 32 so use two arrays
267        let mut buf = ([0u32; 32], [0u32; 32]);
268        reseeding.fill(&mut buf.0);
269        reseeding.fill(&mut buf.1);
270        let seq = buf;
271        for _ in 0..10 {
272            reseeding.fill(&mut buf.0);
273            reseeding.fill(&mut buf.1);
274            assert_eq!(buf, seq);
275        }
276    }
277
278    #[test]
279    #[allow(clippy::redundant_clone)]
280    fn test_clone_reseeding() {
281        let zero = const_rng(0);
282        let mut rng1 = ReseedingRng::<Core, _>::new(32 * 4, zero).unwrap();
283
284        let first: u32 = rng1.random();
285        for _ in 0..10 {
286            let _ = rng1.random::<u32>();
287        }
288
289        let mut rng2 = rng1.clone();
290        assert_eq!(first, rng2.random::<u32>());
291    }
292}
rand/rngs/reseeding.rs

rand/rngs/
reseeding.rs
