# [−][src]Struct rand_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. 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. 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 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 `set_word_pos` and `set_stream`.

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.

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

2. eSTREAM: the ECRYPT Stream Cipher Project ↩

## Methods

### `impl ChaChaRng`[src]

#### `pub fn get_word_pos(&self) -> u128`[src]

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.

Note: this function is currently only available with Rust 1.26 or later.

#### `pub fn set_word_pos(&mut self, word_offset: u128)`[src]

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.

Note: this function is currently only available with Rust 1.26 or later.

#### `pub fn set_stream(&mut self, stream: u64)`[src]

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.

## Trait Implementations

### `impl From<ChaChaCore> for ChaChaRng`[src]

#### `fn from(core: ChaChaCore) -> Self`[src]

Performs the conversion.

### `impl Debug for ChaChaRng`[src]

#### `fn fmt(&self, f: &mut Formatter) -> Result`[src]

Formats the value using the given formatter. Read more

### `impl Clone for ChaChaRng`[src]

#### `fn clone(&self) -> ChaChaRng`[src]

Returns a copy of the value. Read more

#### `fn clone_from(&mut self, source: &Self)`1.0.0[src]

Performs copy-assignment from `source`. Read more

### `impl SeedableRng for ChaChaRng`[src]

#### `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`). Read more

#### `fn from_seed(seed: Self::Seed) -> Self`[src]

Create a new PRNG using the given seed. Read more

#### `fn from_rng<R: RngCore>(rng: R) -> Result<Self, Error>`[src]

Create a new PRNG seeded from another `Rng`. Read more

#### `fn seed_from_u64(state: u64) -> Self`[src]

Create a new PRNG using a `u64` seed. Read more

### `impl RngCore for ChaChaRng`[src]

#### `fn next_u32(&mut self) -> u32`[src]

Return the next random `u32`. Read more

#### `fn next_u64(&mut self) -> u64`[src]

Return the next random `u64`. Read more

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

Fill `dest` with random data. Read more

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

Fill `dest` entirely with random data. Read more

### `impl CryptoRng for ChaChaRng`[src]

## Auto Trait Implementations

### `impl Unpin for ChaChaRng`

### `impl Send for ChaChaRng`

### `impl Sync for ChaChaRng`

### `impl UnwindSafe for ChaChaRng`

### `impl RefUnwindSafe for ChaChaRng`

## Blanket Implementations

### `impl<T> From<T> for T`[src]

#### `fn from(t: T) -> T`[src]

Performs the conversion.

### `impl<T, U> TryFrom<U> for T where
U: Into<T>,` [src]

#### `type Error = Infallible`

The type returned in the event of a conversion error.

#### `fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>`[src]

Performs the conversion.

### `impl<T, U> Into<U> for T where
U: From<T>,` [src]

#### `fn into(self) -> U`[src]

Performs the conversion.

### `impl<T, U> TryInto<U> for T where
U: TryFrom<T>,` [src]

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

The type returned in the event of a conversion error.

#### `fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>`[src]

Performs the conversion.

### `impl<T> Borrow<T> for T where
T: ?Sized,` [src]

#### `fn borrow(&self) -> &T`[src]

Immutably borrows from an owned value. Read more

### `impl<T> BorrowMut<T> for T where
T: ?Sized,` [src]

#### `fn borrow_mut(&mut self) -> &mut T`[src]

Mutably borrows from an owned value. Read more

### `impl<T> Any for T where
T: 'static + ?Sized,` [src]

#### `fn type_id(&self) -> TypeId`[src]

Gets the `TypeId` of `self`. Read more

### `impl<T> ToOwned for T where
T: Clone,` [src]

#### `type Owned = T`

The resulting type after obtaining ownership.

#### `fn to_owned(&self) -> T`[src]

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

#### `fn clone_into(&self, target: &mut T)`[src]

🔬 This is a nightly-only experimental API. (`toowned_clone_into`)

recently added

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

# Help

## Keyboard Shortcuts

`?`
  Show this help dialog
`S`
  Focus the search field
`↑`
  Move up in search results
`↓`
  Move down in search results
`↹`
  Switch tab
`⏎`
  Go to active search result
`+`
  Expand all sections
`-`
  Collapse all sections

## Search Tricks

Prefix searches with a type followed by a colon (e.g., `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g., `vec -> usize` or `* -> vec`)

Search multiple things at once by splitting your query with comma (e.g., `str,u8` or `String,struct:Vec,test`)