rand

Module rngs

Source
Expand description

Random number generators and adapters

§Generators

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

§Non-deterministic 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.
§Standard generators

These use selected best-in-class algorithms. They are deterministic but not portable: the algorithms may be changed in any release and may be platform-dependent.

  • 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 current algorithm is one of the Xoshiro generators below, depending on the target’s pointer size.
§Named portable generators

These are similar to the standard generators, but with the additional guarantees of reproducibility:

  • Xoshiro256PlusPlus is a very fast 64-bit insecure generator using 256 bits of state with good performance in statistical tests of quality
  • Xoshiro128PlusPlus is a very fast 32-bit insecure generator using 128 bits of state with good performance in statistical tests of quality

§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§

mockDeprecated
Mock random number generator

Structs§

OsRng
An interface over the operating-system’s random data source
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
Xoshiro128PlusPlus
A xoshiro128++ random number generator.
Xoshiro256PlusPlus
A xoshiro256++ random number generator.