Module rand::rngs

source · [−]

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.

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