Struct rand::prng::chacha::ChaChaRng

pub struct ChaChaRng(_);

A cryptographically secure random number generator that uses the ChaCha algorithm.

ChaCha is a stream cipher designed by Daniel J. Bernstein ¹, that we use as an RNG. It is an improved variant of the Salsa20 cipher family, which was selected as one of the "stream ciphers suitable for widespread adoption" by eSTREAM ².

ChaCha uses add-rotate-xor (ARX) operations as its basis. These are safe against timing attacks, although that is mostly a concern for ciphers and not for RNGs. Also it is very suitable for SIMD implementation. Here we do not provide a SIMD implementation yet, except for what is provided by auto-vectorisation.

With the ChaCha algorithm it is possible to choose the number of rounds the core algorithm should run. The number of rounds is a tradeoff between performance and security, where 8 rounds is the minimum potentially secure configuration, and 20 rounds is widely used as a conservative choice. We use 20 rounds in this implementation, but hope to allow type-level configuration in the future.

We use a 64-bit counter and 64-bit stream identifier as in Benstein's implementation ¹ except that we use a stream identifier in place of a nonce. A 64-bit counter over 64-byte (16 word) blocks allows 1 ZiB of output before cycling, and the stream identifier allows 2⁶⁴ unique streams of output per seed. Both counter and stream are initialized to zero but may be set via set_word_pos and set_stream.

The word layout is:

constant constant constant constant
seed     seed     seed     seed
seed     seed     seed     seed
counter  counter  nonce    nonce

This implementation uses an output buffer of sixteen u32 words, and uses BlockRng to implement the RngCore methods.

---

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

2. eSTREAM: the ECRYPT Stream Cipher Project ↩

Methods

impl ChaChaRng

pub fn new_unseeded() -> ChaChaRng

Deprecated since 0.5.0

: use the FromEntropy or SeedableRng trait

Create an ChaCha random number generator using the default fixed key of 8 zero words.

Examples

use rand::{RngCore, ChaChaRng};

let mut ra = ChaChaRng::new_unseeded();
println!("{:?}", ra.next_u32());
println!("{:?}", ra.next_u32());

Since this equivalent to a RNG with a fixed seed, repeated executions of an unseeded RNG will produce the same result. This code sample will consistently produce:

• 2917185654
• 2419978656

pub fn set_stream(&mut self, stream: u64)

Set the stream number.

This is initialized to zero; 2⁶⁴ unique streams of output are available per seed/key.

Note that in order to reproduce ChaCha output with a specific 64-bit nonce, one can convert that nonce to a u64 in little-endian fashion and pass to this function. In theory a 96-bit nonce can be used by passing the last 64-bits to this function and using the first 32-bits as the most significant half of the 64-bit counter (which may be set indirectly via set_word_pos), but this is not directly supported.

Trait Implementations

impl From<ChaChaCore> for ChaChaRng

fn from(core: ChaChaCore) -> Self

Performs the conversion.

impl Clone for ChaChaRng

fn clone(&self) -> ChaChaRng

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ChaChaRng

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl SeedableRng for ChaChaRng

type Seed = <ChaChaCore as SeedableRng>::Seed

Seed type, which is restricted to types mutably-dereferencable as u8 arrays (we recommend [u8; N] for some N).

fn from_seed(seed: Self::Seed) -> Self

Create a new PRNG using the given seed.

fn from_rng<R: RngCore>(rng: R) -> Result<Self, Error>

Create a new PRNG seeded from another Rng.

fn seed_from_u64(state: u64) -> Self

Create a new PRNG using a u64 seed.

impl RngCore for ChaChaRng

fn next_u32(&mut self) -> u32

Return the next random u32.

fn next_u64(&mut self) -> u64

Return the next random u64.

fn fill_bytes(&mut self, dest: &mut [u8])

Fill dest with random data.

fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), Error>

Fill dest entirely with random data.

impl CryptoRng for ChaChaRng