Module rngs

Random number generators and adapters

This crate provides a small selection of non-portable generators. See also Types of generators and Our RNGs in the book.

Generators

This crate provides a small selection of non-portable random number generators:

• OsRng is a stateless interface over the operating system’s random number source. This is typically secure with some form of periodic re-seeding.
• ThreadRng, provided by crate::rng(), is a handle to a thread-local generator with periodic seeding from OsRng. Because this is local, it is typically much faster than OsRng. It should be secure, but see documentation on ThreadRng.
• 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 is the deterministic generator used by ThreadRng but without the periodic reseeding or thread-local management.
• SmallRng is a relatively simple, insecure generator designed to be fast, use little memory, and pass various statistical tests of randomness quality.

The algorithms selected for StdRng and SmallRng may change in any release and may be platform-dependent, therefore they are not reproducible.

Additional generators

• 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.
• The rand_chacha crate provides portable implementations of generators derived from the ChaCha family of stream ciphers
• The rand_pcg crate provides portable implementations of a subset of the PCG family of small, insecure generators
• The rand_xoshiro crate provides portable implementations of the xoshiro family of small, insecure generators

For more, search crates with the rng tag.

Traits and functionality

All generators implement RngCore and thus also Rng. See also the Random Values chapter in the book.

Secure RNGs may additionally implement the CryptoRng trait.

Use the rand_core crate when implementing your own RNGs.

Modules

• mock
  Mock random number generator

Structs

• OsRng
  A random number generator that retrieves randomness from the operating system.
• ReseedingRng
  A wrapper around any PRNG that implements BlockRngCore, that adds the ability to reseed it.
• SmallRng
  A small-state, fast, non-crypto, non-portable PRNG
• StdRng
  A strong, fast (amortized), non-portable RNG
• ThreadRng
  A reference to the thread-local generator