pub struct ChaCha20Rng { /* private fields */ }
Expand description

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

ChaCha is a stream cipher designed by Daniel J. Bernstein1, 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 eSTREAM2.

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. We provide a SIMD implementation to support high throughput on a variety of common hardware platforms.

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 a 64-bit counter and 64-bit stream identifier as in Bernstein’s implementation1 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 264 unique streams of output per seed. Both counter and stream are initialized to zero but may be set via the set_word_pos and set_stream methods.

The word layout is:

constant  constant  constant  constant
seed      seed      seed      seed
seed      seed      seed      seed
counter   counter   stream_id stream_id

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

Implementations§

source§

impl ChaCha20Rng

source

pub fn get_word_pos(&self) -> u128

Get the offset from the start of the stream, in 32-bit words.

Since the generated blocks are 16 words (24) long and the counter is 64-bits, the offset is a 68-bit number. Sub-word offsets are not supported, hence the result can simply be multiplied by 4 to get a byte-offset.

source

pub fn set_word_pos(&mut self, word_offset: u128)

Set the offset from the start of the stream, in 32-bit words.

As with get_word_pos, we use a 68-bit number. Since the generator simply cycles at the end of its period (1 ZiB), we ignore the upper 60 bits.

source

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

Set the stream number.

This is initialized to zero; 264 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.

source

pub fn get_stream(&self) -> u64

Get the stream number.

source

pub fn get_seed(&self) -> [u8; 32]

Get the seed.

Trait Implementations§

source§

impl Clone for ChaCha20Rng

source§

fn clone(&self) -> ChaCha20Rng

Returns a copy of the value. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more
source§

impl Debug for ChaCha20Rng

source§

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

Formats the value using the given formatter. Read more
source§

impl From<ChaCha20Core> for ChaCha20Rng

source§

fn from(core: ChaCha20Core) -> Self

Converts to this type from the input type.
source§

impl PartialEq for ChaCha20Rng

source§

fn eq(&self, rhs: &ChaCha20Rng) -> bool

This method tests for self and other values to be equal, and is used by ==.
1.0.0 · source§

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
source§

impl RngCore for ChaCha20Rng

source§

fn next_u32(&mut self) -> u32

Return the next random u32. Read more
source§

fn next_u64(&mut self) -> u64

Return the next random u64. Read more
source§

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

Fill dest with random data. Read more
source§

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

Fill dest entirely with random data. Read more
source§

impl SeedableRng for ChaCha20Rng

§

type Seed = [u8; 32]

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

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

Create a new PRNG using the given seed. Read more
source§

fn seed_from_u64(state: u64) -> Self

Create a new PRNG using a u64 seed. Read more
source§

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

Create a new PRNG seeded from another Rng. Read more
source§

fn from_entropy() -> Self

Creates a new instance of the RNG seeded via getrandom. Read more
source§

impl CryptoRng for ChaCha20Rng

source§

impl Eq for ChaCha20Rng

Auto Trait Implementations§

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> CryptoRngCore for T
where T: CryptoRng + RngCore,

source§

fn as_rngcore(&mut self) -> &mut dyn RngCore

Upcast to an RngCore trait object.
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> ToOwned for T
where T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
source§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

source§

fn vzip(self) -> V