logo
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 fifteen u32 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

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.

Reseed the internal PRNG.

Trait Implementations

Returns a copy of the value. Read more

Performs copy-assignment from source. Read more

Formats the value using the given formatter. Read more

Return the next random u32. Read more

Return the next random u64. Read more

Fill dest with random data. Read more

Fill dest entirely with random data. Read more

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Return a random value supporting the Standard distribution. Read more

Generate a random value in the given range. Read more

Sample a new value, using the given distribution. Read more

Create an iterator that generates values using the given distribution. Read more

Fill any type implementing Fill with random data Read more

Fill any type implementing Fill with random data Read more

Return a bool with a probability p of being true. Read more

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

The resulting type after obtaining ownership.

Creates owned data from borrowed data, usually by cloning. Read more

🔬 This is a nightly-only experimental API. (toowned_clone_into)

Uses borrowed data to replace owned data, usually by cloning. Read more

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.