A random number generator that can be explicitly seeded.
This trait encapsulates the low-level functionality common to all
pseudo-random number generators (PRNGs, or algorithmic generators).
The FromEntropy
trait from the rand
crate is automatically
implemented for every type implementing SeedableRng
, providing
a convenient from_entropy()
constructor.
Seed type, which is restricted to types mutably-dereferencable as u8
arrays (we recommend [u8; N]
for some N
).
It is recommended to seed PRNGs with a seed of at least circa 100 bits,
which means an array of [u8; 12]
or greater to avoid picking RNGs with
partially overlapping periods.
For cryptographic RNG's a seed of 256 bits is recommended, [u8; 32]
.
Note that the required traits core::default::Default
and
core::convert::AsMut<u8>
are not implemented for large arrays
[u8; N]
with N
> 32. To be able to implement the traits required by
SeedableRng
for RNGs with such large seeds, the newtype pattern can be
used:
use rand_core::SeedableRng;
const N: usize = 64;
pub struct MyRngSeed(pub [u8; N]);
pub struct MyRng(MyRngSeed);
impl Default for MyRngSeed {
fn default() -> MyRngSeed {
MyRngSeed([0; N])
}
}
impl AsMut<[u8]> for MyRngSeed {
fn as_mut(&mut self) -> &mut [u8] {
&mut self.0
}
}
impl SeedableRng for MyRng {
type Seed = MyRngSeed;
fn from_seed(seed: MyRngSeed) -> MyRng {
MyRng(seed)
}
}
Loading content...
Create a new PRNG using the given seed.
PRNG implementations are allowed to assume that bits in the seed are
well distributed. That means usually that the number of one and zero
bits are about equal, and values like 0, 1 and (size - 1) are unlikely.
PRNG implementations are recommended to be reproducible. A PRNG seeded
using this function with a fixed seed should produce the same sequence
of output in the future and on different architectures (with for example
different endianness).
It is however not required that this function yield the same state as a
reference implementation of the PRNG given equivalent seed; if necessary
another constructor replicating behaviour from a reference
implementation can be added.
PRNG implementations should make sure from_seed
never panics. In the
case that some special values (like an all zero seed) are not viable
seeds it is preferable to map these to alternative constant value(s),
for example 0xBAD5EEDu32
or 0x0DDB1A5E5BAD5EEDu64
("odd biases? bad
seed"). This is assuming only a small number of values must be rejected.
Loading content...
Create a new PRNG using a u64
seed.
This is a convenience-wrapper around from_seed
to allow construction
of any SeedableRng
from a simple u64
value. It is designed such that
low Hamming Weight numbers like 0 and 1 can be used and should still
result in good, independent seeds to the PRNG which is returned.
This is not suitable for cryptography, as should be clear given that
the input size is only 64 bits.
Implementations for PRNGs may provide their own implementations of
this function, but the default implementation should be good enough for
all purposes. Changing the implementation of this function should be
considered a value-breaking change.
Create a new PRNG seeded from another Rng
.
This is the recommended way to initialize PRNGs with fresh entropy. The
FromEntropy
trait from the rand
crate provides a convenient
from_entropy
method based on from_rng
.
Usage of this method is not recommended when reproducibility is required
since implementing PRNGs are not required to fix Endianness and are
allowed to modify implementations in new releases.
It is important to use a good source of randomness to initialize the
PRNG. Cryptographic PRNG may be rendered insecure when seeded from a
non-cryptographic PRNG or with insufficient entropy.
Many non-cryptographic PRNGs will show statistical bias in their first
results if their seed numbers are small or if there is a simple pattern
between them.
Prefer to seed from a strong external entropy source like OsRng
from
the rand_os
crate or from a cryptographic PRNG; if creating a new
generator for cryptographic uses you must seed from a strong source.
Seeding a small PRNG from another small PRNG is possible, but
something to be careful with. An extreme example of how this can go
wrong is seeding an Xorshift RNG from another Xorshift RNG, which
will effectively clone the generator. In general seeding from a
generator which is hard to predict is probably okay.
PRNG implementations are allowed to assume that a good RNG is provided
for seeding, and that it is cryptographically secure when appropriate.
Loading content...
Loading content...
Create an HC-128 random number generator with a seed. The seed has to be
256 bits in length, matching the 128 bit key
followed by 128 bit iv
when HC-128 where to be used as a stream cipher.
Create an ISAAC random number generator using an u64
as seed.
If seed == 0
this will produce the same stream of random numbers as
the reference implementation when used unseeded.
Create an ISAAC random number generator using an u64
as seed.
If seed == 0
this will produce the same stream of random numbers as
the reference implementation when used unseeded.
Create an ISAAC random number generator using an u64
as seed.
If seed == 0
this will produce the same stream of random numbers as
the reference implementation when used unseeded.
Loading content...