pub struct ReseedingRng<R, Rsdr>(_)
where
R: BlockRngCore + SeedableRng,
Rsdr: RngCore;
Expand description
A wrapper around any PRNG that implements BlockRngCore
, that adds the
ability to reseed it.
ReseedingRng
reseeds the underlying PRNG in the following cases:
- On a manual call to
reseed()
. - After
clone()
, the clone will be reseeded on first use. - When a process is forked on UNIX, the RNGs in both the parent and child
processes will be reseeded just before the next call to
BlockRngCore::generate
, i.e. “soon”. For ChaCha and Hc128 this is a maximum of fifteenu32
values before reseeding. - After the PRNG has generated a configurable number of random bytes.
When should reseeding after a fixed number of generated bytes be used?
Reseeding after a fixed number of generated bytes is never strictly necessary. Cryptographic PRNGs don’t have a limited number of bytes they can output, or at least not a limit reachable in any practical way. There is no such thing as ‘running out of entropy’.
Occasionally reseeding can be seen as some form of ‘security in depth’. Even if in the future a cryptographic weakness is found in the CSPRNG being used, or a flaw in the implementation, occasionally reseeding should make exploiting it much more difficult or even impossible.
Use ReseedingRng::new
with a threshold
of 0
to disable reseeding
after a fixed number of generated bytes.
Limitations
It is recommended that a ReseedingRng
(including ThreadRng
) not be used
from a fork handler.
Use OsRng
or getrandom
, or defer your use of the RNG until later.
Error handling
Although unlikely, reseeding the wrapped PRNG can fail. ReseedingRng
will
never panic but try to handle the error intelligently through some
combination of retrying and delaying reseeding until later.
If handling the source error fails ReseedingRng
will continue generating
data from the wrapped PRNG without reseeding.
Manually calling reseed()
will not have this retry or delay logic, but
reports the error.
Example
use rand::prelude::*;
use rand_chacha::ChaCha20Core; // Internal part of ChaChaRng that
// implements BlockRngCore
use rand::rngs::OsRng;
use rand::rngs::adapter::ReseedingRng;
let prng = ChaCha20Core::from_entropy();
let mut reseeding_rng = ReseedingRng::new(prng, 0, OsRng);
println!("{}", reseeding_rng.gen::<u64>());
let mut cloned_rng = reseeding_rng.clone();
assert!(reseeding_rng.gen::<u64>() != cloned_rng.gen::<u64>());
Implementations
sourceimpl<R, Rsdr> ReseedingRng<R, Rsdr> where
R: BlockRngCore + SeedableRng,
Rsdr: RngCore,
impl<R, Rsdr> ReseedingRng<R, Rsdr> where
R: BlockRngCore + SeedableRng,
Rsdr: RngCore,
sourcepub fn new(rng: R, threshold: u64, reseeder: Rsdr) -> ReseedingRng<R, Rsdr>
pub fn new(rng: R, threshold: u64, reseeder: Rsdr) -> ReseedingRng<R, Rsdr>
Create a new ReseedingRng
from an existing PRNG, combined with a RNG
to use as reseeder.
threshold
sets the number of generated bytes after which to reseed the
PRNG. Set it to zero to never reseed based on the number of generated
values.
Trait Implementations
sourceimpl<R, Rsdr> Clone for ReseedingRng<R, Rsdr> where
R: BlockRngCore + SeedableRng + Clone,
Rsdr: RngCore + Clone,
impl<R, Rsdr> Clone for ReseedingRng<R, Rsdr> where
R: BlockRngCore + SeedableRng + Clone,
Rsdr: RngCore + Clone,
sourcefn clone(&self) -> ReseedingRng<R, Rsdr>
fn clone(&self) -> ReseedingRng<R, Rsdr>
Returns a copy of the value. Read more
1.0.0 · sourcefn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
Performs copy-assignment from source
. Read more
sourceimpl<R, Rsdr> Debug for ReseedingRng<R, Rsdr> where
R: Debug + BlockRngCore + SeedableRng,
Rsdr: Debug + RngCore,
impl<R, Rsdr> Debug for ReseedingRng<R, Rsdr> where
R: Debug + BlockRngCore + SeedableRng,
Rsdr: Debug + RngCore,
sourceimpl<R, Rsdr> RngCore for ReseedingRng<R, Rsdr> where
Rsdr: RngCore,
R: BlockRngCore<Item = u32> + SeedableRng,
<R as BlockRngCore>::Results: AsRef<[u32]>,
<R as BlockRngCore>::Results: AsMut<[u32]>,
impl<R, Rsdr> RngCore for ReseedingRng<R, Rsdr> where
Rsdr: RngCore,
R: BlockRngCore<Item = u32> + SeedableRng,
<R as BlockRngCore>::Results: AsRef<[u32]>,
<R as BlockRngCore>::Results: AsMut<[u32]>,
impl<R, Rsdr> CryptoRng for ReseedingRng<R, Rsdr> where
R: BlockRngCore + SeedableRng + CryptoRng,
Rsdr: RngCore + CryptoRng,
Auto Trait Implementations
impl<R, Rsdr> RefUnwindSafe for ReseedingRng<R, Rsdr> where
R: RefUnwindSafe,
Rsdr: RefUnwindSafe,
<R as BlockRngCore>::Results: RefUnwindSafe,
impl<R, Rsdr> Send for ReseedingRng<R, Rsdr> where
R: Send,
Rsdr: Send,
<R as BlockRngCore>::Results: Send,
impl<R, Rsdr> Sync for ReseedingRng<R, Rsdr> where
R: Sync,
Rsdr: Sync,
<R as BlockRngCore>::Results: Sync,
impl<R, Rsdr> Unpin for ReseedingRng<R, Rsdr> where
R: Unpin,
Rsdr: Unpin,
<R as BlockRngCore>::Results: Unpin,
impl<R, Rsdr> UnwindSafe for ReseedingRng<R, Rsdr> where
R: UnwindSafe,
Rsdr: UnwindSafe,
<R as BlockRngCore>::Results: UnwindSafe,
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
sourceimpl<R> Rng for R where
R: RngCore + ?Sized,
impl<R> Rng for R where
R: RngCore + ?Sized,
sourcefn gen<T>(&mut self) -> T where
Standard: Distribution<T>,
fn gen<T>(&mut self) -> T where
Standard: Distribution<T>,
sourcefn gen_range<T, R>(&mut self, range: R) -> T where
T: SampleUniform,
R: SampleRange<T>,
fn gen_range<T, R>(&mut self, range: R) -> T where
T: SampleUniform,
R: SampleRange<T>,
Generate a random value in the given range. Read more
sourcefn sample<T, D>(&mut self, distr: D) -> T where
D: Distribution<T>,
fn sample<T, D>(&mut self, distr: D) -> T where
D: Distribution<T>,
Sample a new value, using the given distribution. Read more
sourcefn sample_iter<T, D>(self, distr: D) -> DistIter<D, Self, T>ⓘNotable traits for DistIter<D, R, T>impl<D, R, T> Iterator for DistIter<D, R, T> where
D: Distribution<T>,
R: Rng, type Item = T;
where
D: Distribution<T>,
fn sample_iter<T, D>(self, distr: D) -> DistIter<D, Self, T>ⓘNotable traits for DistIter<D, R, T>impl<D, R, T> Iterator for DistIter<D, R, T> where
D: Distribution<T>,
R: Rng, type Item = T;
where
D: Distribution<T>,
D: Distribution<T>,
R: Rng, type Item = T;
Create an iterator that generates values using the given distribution. Read more
sourcefn gen_bool(&mut self, p: f64) -> bool
fn gen_bool(&mut self, p: f64) -> bool
Return a bool with a probability p
of being true. Read more
sourcefn gen_ratio(&mut self, numerator: u32, denominator: u32) -> bool
fn gen_ratio(&mut self, numerator: u32, denominator: u32) -> bool
Return a bool with a probability of numerator/denominator
of being
true. I.e. gen_ratio(2, 3)
has chance of 2 in 3, or about 67%, of
returning true. If numerator == denominator
, then the returned value
is guaranteed to be true
. If numerator == 0
, then the returned
value is guaranteed to be false
. Read more
sourceimpl<T> ToOwned for T where
T: Clone,
impl<T> ToOwned for T where
T: Clone,
type Owned = T
type Owned = T
The resulting type after obtaining ownership.
sourcefn clone_into(&self, target: &mut T)
fn clone_into(&self, target: &mut T)
toowned_clone_into
)Uses borrowed data to replace owned data, usually by cloning. Read more