Struct ChaCha12Rng

pub struct ChaCha12Rng { /* private fields */ }

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

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

  2. eSTREAM: the ECRYPT Stream Cipher Project ↩

Implementations

impl ChaCha12Rng

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.

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.

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.

fn get_stream(&self) -> u64

Get the stream number.

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

Get the seed.

Trait Implementations

impl Clone for ChaCha12Rng

fn clone(&self) -> ChaCha12Rng

impl Debug for ChaCha12Rng

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

impl Eq for ChaCha12Rng

impl From<ChaCha12Core> for ChaCha12Rng

fn from(core: ChaCha12Core) -> Self

impl PartialEq for ChaCha12Rng

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

impl SeedableRng for ChaCha12Rng

type Seed = [u8; 32];
fn from_seed(seed: Self::Seed) -> Self

impl Serialize for ChaCha12Rng

fn serialize<S>(&self, s: S) -> Result<S::Ok, S::Error>
where
    S: Serializer,

impl TryCryptoRng for ChaCha12Rng

impl TryRng for ChaCha12Rng

type Error = never;
fn try_next_u32(&mut self) -> Result<u32, Infallible>
fn try_next_u64(&mut self) -> Result<u64, Infallible>
fn try_fill_bytes(&mut self, bytes: &mut [u8]) -> Result<(), Infallible>

impl<'de> Deserialize<'de> for ChaCha12Rng

fn deserialize<D>(d: D) -> Result<Self, D::Error>
where
    D: Deserializer<'de>,

Auto Trait Implementations

impl Freeze for ChaCha12Rng

impl RefUnwindSafe for ChaCha12Rng

impl Send for ChaCha12Rng

impl Sync for ChaCha12Rng

impl Unpin for ChaCha12Rng

impl UnsafeUnpin for ChaCha12Rng

impl UnwindSafe for ChaCha12Rng

Blanket Implementations

impl<R> CryptoRng for ChaCha12Rng where R: TryCryptoRng<Error = never> + ?Sized,

impl<R> Rng for ChaCha12Rng where R: TryRng<Error = never> + ?Sized,

fn next_u32(&mut self) -> u32
fn next_u64(&mut self) -> u64
fn fill_bytes(&mut self, dst: &mut [u8])

impl<R> RngCore for ChaCha12Rng where R: Rng,

impl<R> TryRngCore for ChaCha12Rng where R: TryRng,

type Error = <R as TryRng>::Error;

impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for ChaCha12Rng where ST: ?Sized, DT: ?Sized,

impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for ChaCha12Rng where ST: ?Sized, DT: ?Sized,

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

fn type_id(&self) -> TypeId

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

fn borrow(&self) -> &T

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

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

impl<T> CloneToUninit for ChaCha12Rng where T: Clone,

unsafe fn clone_to_uninit(&self, dest: *mut u8)

impl<T> DeserializeOwned for ChaCha12Rng where T: for<'de> Deserialize<'de>,

impl<T> From<T> for ChaCha12Rng

fn from(t: T) -> T

Returns the argument unchanged.

impl<T> Read<Exclusive, BecauseExclusive> for ChaCha12Rng where T: ?Sized,

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

type Owned = T;
fn to_owned(&self) -> T
fn clone_into(&self, target: &mut T)

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

fn into(self) -> U

Calls U::from(self).

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

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

type Error = never;
fn try_from(value: U) -> Result<T, never>

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

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

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

fn vzip(self) -> V