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 [1], 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 [2].

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. By default ChaChaRng is created as ChaCha20, which means 20 rounds. The number of rounds is a tradeoff between performance and security, 8 rounds are considered the minimum to be secure. A different number of rounds can be set using set_rounds.

We deviate slightly from the ChaCha specification regarding the nonce, which is used to extend the counter to 128 bits. This is provably as strong as the original cipher, though, since any distinguishing attack on our variant also works against ChaCha with a chosen-nonce. See the XSalsa20 [3] security proof for a more involved example of this.

The modified word layout is:

constant constant constant constant
key      key      key      key
key      key      key      key
counter  counter  counter  counter

[1]: D. J. Bernstein, ChaCha, a variant of Salsa20

[2]: eSTREAM: the ECRYPT Stream Cipher Project

[3]: Daniel J. Bernstein. Extending the Salsa20 nonce.

Methods

impl ChaChaRng

pub fn new_unseeded() -> ChaChaRng

Deprecated since 0.5.0

: use the NewRng 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_counter(&mut self, counter_low: u64, counter_high: u64)

Sets the internal 128-bit ChaCha counter to a user-provided value. This permits jumping arbitrarily ahead (or backwards) in the pseudorandom stream.

The 128 bits used for the counter overlap with the nonce and smaller counter of ChaCha when used as a stream cipher. It is in theory possible to use set_counter to obtain the conventional ChaCha pseudorandom stream associated with a particular nonce. This is not a supported use of the RNG, because a nonce set that way is not treated as a constant value but still as part of the counter, besides endian issues.

Examples

use rand::{RngCore, ChaChaRng};

let mut rng1 = ChaChaRng::new_unseeded(); // Use `ChaChaRng::new()` or
                                          // `ChaChaRng::from_rng()`
                                          // outside of testing.
let mut rng2 = rng1.clone();

// Skip to round 20. Because every round generates 16 `u32` values, this
// actually means skipping 320 values.
for _ in 0..(20*16) { rng1.next_u32(); }
rng2.set_counter(20, 0);
assert_eq!(rng1.next_u32(), rng2.next_u32());

pub fn set_rounds(&mut self, rounds: usize)

Sets the number of rounds to run the ChaCha core algorithm per block to generate.

By default this is set to 20. Other recommended values are 12 and 8, which trade security for performance. rounds only supports values that are multiples of 4 and less than or equal to 20.

Examples

use rand::{RngCore, ChaChaRng};

let mut rng = ChaChaRng::new_unseeded(); // Use `ChaChaRng::new()` or
                                          // `ChaChaRng::from_rng()`
                                          // outside of testing.
rng.set_rounds(8);

assert_eq!(rng.next_u32(), 0x2fef003e);

Trait Implementations

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, __arg_0: &mut Formatter) -> Result

Formats the value using the given formatter.

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

impl CryptoRng for ChaChaRng