Module rngs 

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

• SysRng 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 SysRng. Because this is local, it is typically much faster than SysRng. 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 [ChaCha12Rng], 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
• [ChaCha8Rng], [ChaCha12Rng] and [ChaCha20Rng] are generators over the ChaCha stream cipher designed by Daniel J. Bernstein¹.

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_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 TryRng. Most implement Rng (i.e. TryRng<Error = Infallible>) and thus also implement 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.

---

1. D. J. Bernstein, ChaCha, a variant of Salsa20 ↩

Structs

SmallRng

A small-state, fast, non-crypto, non-portable PRNG

SysError

A small and no_std compatible error type

SysRng

A TryRng interface over the system’s preferred random number source

Xoshiro128PlusPlus

A xoshiro128++ random number generator.

Xoshiro256PlusPlus

A xoshiro256++ random number generator.