Expand description
Random number generators and adapters
Background: Random number generators (RNGs)
Computers cannot produce random numbers from nowhere. We classify random number generators as follows:
- “True” random number generators (TRNGs) use hard-to-predict data sources (e.g. the high-resolution parts of event timings and sensor jitter) to harvest random bit-sequences, apply algorithms to remove bias and estimate available entropy, then combine these bits into a byte-sequence or an entropy pool. This job is usually done by the operating system or a hardware generator (HRNG).
- “Pseudo”-random number generators (PRNGs) use algorithms to transform a seed into a sequence of pseudo-random numbers. These generators can be fast and produce well-distributed unpredictable random numbers (or not). They are usually deterministic: given algorithm and seed, the output sequence can be reproduced. They have finite period and eventually loop; with many algorithms this period is fixed and can be proven sufficiently long, while others are chaotic and the period depends on the seed.
- “Cryptographically secure” pseudo-random number generators (CSPRNGs) are the sub-set of PRNGs which are secure. Security of the generator relies both on hiding the internal state and using a strong algorithm.
Traits and functionality
All RNGs implement the RngCore
trait, as a consequence of which the
Rng
extension trait is automatically implemented. Secure RNGs may
additionally implement the CryptoRng
trait.
All PRNGs require a seed to produce their random number sequence. The
SeedableRng
trait provides three ways of constructing PRNGs:
from_seed
accepts a type specific to the PRNGfrom_rng
allows a PRNG to be seeded from any other RNGseed_from_u64
allows any PRNG to be seeded from au64
insecurelyfrom_entropy
securely seeds a PRNG from fresh entropy
Use the rand_core
crate when implementing your own RNGs.
Our generators
This crate provides several random number generators:
OsRng
is an interface to the operating system’s random number source. Typically the operating system uses a CSPRNG with entropy provided by a TRNG and some type of on-going re-seeding.ThreadRng
, provided by thethread_rng
function, is a handle to a thread-local CSPRNG with periodic seeding fromOsRng
. Because this is local, it is typically much faster thanOsRng
. It should be secure, though the paranoid may preferOsRng
.StdRng
is a CSPRNG chosen for good performance and trust of security (based on reviews, maturity and usage). The current algorithm is ChaCha12, which is well established and rigorously analysed.StdRng
provides the algorithm used byThreadRng
but without periodic reseeding.SmallRng
is an insecure PRNG designed to be fast, simple, require little memory, and have good output quality.
The algorithms selected for StdRng
and SmallRng
may change in any
release and may be platform-dependent, therefore they should be considered
not reproducible.
Additional generators
TRNGs: The rdrand
crate provides an interface to the RDRAND and
RDSEED instructions available in modern Intel and AMD CPUs.
The rand_jitter
crate provides a user-space implementation of
entropy harvesting from CPU timer jitter, but is very slow and has
security issues.
PRNGs: Several companion crates are available, providing individual or
families of PRNG algorithms. These provide the implementations behind
StdRng
and SmallRng
but can also be used directly, indeed should
be used directly when reproducibility matters.
Some suggestions are: rand_chacha
, rand_pcg
, rand_xoshiro
.
A full list can be found by searching for crates with the rng
tag.
Modules
- adapter
std
Wrappers / adapters forming RNGs - Mock random number generator
Structs
- OsRng
getrandom
A random number generator that retrieves randomness from the operating system. - SmallRng
small_rng
A small-state, fast non-crypto PRNG - StdRng
std_rng
The standard RNG. The PRNG algorithm inStdRng
is chosen to be efficient on the current platform, to be statistically strong and unpredictable (meaning a cryptographically secure PRNG). - ThreadRng
std
andstd_rng
A reference to the thread-local generator