Module rand::rngs

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 PRNG
from_rng allows a PRNG to be seeded from any other RNG
seed_from_u64 allows any PRNG to be seeded from a u64 insecurely
from_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 the thread_rng function, is a handle to a thread-local CSPRNG with periodic seeding from OsRng. Because this is local, it is typically much faster than OsRng. It should be secure, though the paranoid may prefer OsRng.
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 by ThreadRng 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.

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

Wrappers / adapters forming RNGs

mock

Mock random number generator

Structs

OsRng

A random number generator that retrieves randomness from the operating system.

SmallRng

A small-state, fast non-crypto PRNG

StdRng

The standard RNG. The PRNG algorithm in StdRng is chosen to be efficient on the current platform, to be statistically strong and unpredictable (meaning a cryptographically secure PRNG).

ThreadRng