Crate smallrand

This crate provides a lightweight alternative to rand, using the “xoshiro256++” (https://prng.di.unimi.it) and “ChaCha12” algorithms (https://cr.yp.to/chacha.html), which are also the ones used by rand for its SmallRng and StdRng, respectively.

The crate is intended to be easy to audit. Its only dependency is getrandom, and that is only used on non-Linux/Unix platforms. It can also be built as no-std, in which case getrandom is not used at all (but you´ll then have to provide the seed yourself).

Basic usage:

#[cfg(feature = "std")]
{
use smallrand::StdRng;
let mut rng = StdRng::new();
let coin_flip : bool = rng.random();
let some_int = rng.random::<u32>();
let uniformly_distributed : u32 = rng.range(0..=42);
let a_float : f64 = rng.range(0.0..42.0);
}

smallrand can also be used as “no-std”, in which case you can use it like this:

use smallrand::{StdRng, SplitMix};
const SEED : u64 = 42;
let mut rng = StdRng::from_entropy(&mut SplitMix::new(SEED));
let some_int = rng.random::<u32>();

The use of the SplitMix may seem cumbersome, but this is done for two reasons:

• Requiring that the StdRng is initialized from something that implements EntropySource (like SplitMix) provides an interface independent of the actual algorithm used (different algorithms need different amount of entropy when initializing).
• Xoshiro256++ must be initialized with four u64 values. Having that as the interface could tempt users to provide only one actual value and use zero for the other three. This could cause the algorithm to produce very bad output. The use of SplitMix generates values that makes most algorithms perform better in this case.

It is fairly easy to write your own implementation of EntropySource for your platform.

Structs

ChaCha12

This is a random generator based on the ChaCha crypto algorithm with 12 rounds.

DevUrandom

This is an entropy source that generates seeds by reading from /dev/urandom

HashMapEntropy

This is an entropy source that generates seeds using std::collections::hash_map::RandomState. This is likely to equivalent to ´getrandom´ on most platforms.

SecureEntropy

This is an EntropySource (entropy source for seeds) which uses a DefaultEntropy as its source of data, but performs security tests on the data to check that the entropy source is not broken.

SmallRng

This is a numerically good PRNG if you need something small and fast but not cryptographically secure. The PRNG currently used is Xoshiro256pp.

SplitMix

This implementation of EntropySource generates an arbitrary length output from a u64 seed using the SplitMix algorithm from https://prng.di.unimi.it/splitmix64.c

StdRng

This is the default random generator. It has more state than SmallRng and is slower, but it has much better security properties. The PRNG algorithm currently used is ChaCha12, which is based on the chacha crypto algorithm with 12 rounds.

Xoshiro256pp

An xoshiro256++ 1.0 (see https://prng.di.unimi.it) random generator. This is an efficient PRNG with good random properties, but not cryptographically secure: An attacker will be able to calculate the internal state by observing a number of samples, and thus predict future output.

Traits

EntropySource

This is a trait for entropy sources, used to produce seeds for RNGs.

Rng

This is the trait that all PRNGs must implement. It declares two functions that PRNGs must implement (to generate u32 and u64 random values), and based on these provides implementations of all the other functions supported by the crate.

Type Aliases

DefaultEntropy

This is an alias that maps to DevUrandom or GetRandom, depending on the platform