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.
D. J. Bernstein, ChaCha, a variant of Salsa20 ↩
Implementations§
Source§impl ChaCha20Rng
impl ChaCha20Rng
Sourcepub fn get_word_pos(&self) -> u128
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.
Sourcepub fn set_word_pos(&mut self, word_offset: u128)
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.
Sourcepub fn set_stream(&mut self, stream: u64)
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.
Sourcepub fn get_stream(&self) -> u64
pub fn get_stream(&self) -> u64
Get the stream number.
Trait Implementations§
Source§impl Clone for ChaCha20Rng
impl Clone for ChaCha20Rng
Source§fn clone(&self) -> ChaCha20Rng
fn clone(&self) -> ChaCha20Rng
1.0.0 · Source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source
. Read moreSource§impl Debug for ChaCha20Rng
impl Debug for ChaCha20Rng
Source§impl From<ChaCha20Core> for ChaCha20Rng
impl From<ChaCha20Core> for ChaCha20Rng
Source§fn from(core: ChaCha20Core) -> Self
fn from(core: ChaCha20Core) -> Self
Source§impl PartialEq for ChaCha20Rng
impl PartialEq for ChaCha20Rng
Source§impl RngCore for ChaCha20Rng
impl RngCore for ChaCha20Rng
Source§fn fill_bytes(&mut self, bytes: &mut [u8])
fn fill_bytes(&mut self, bytes: &mut [u8])
dest
with random data. Read moreSource§impl SeedableRng for ChaCha20Rng
impl SeedableRng for ChaCha20Rng
Source§type Seed = [u8; 32]
type Seed = [u8; 32]
u8
arrays (we recommend [u8; N]
for some N
). Read moreSource§fn seed_from_u64(state: u64) -> Self
fn seed_from_u64(state: u64) -> Self
u64
seed. Read moreSource§fn from_rng<R>(rng: R) -> Result<Self, Error>where
R: RngCore,
fn from_rng<R>(rng: R) -> Result<Self, Error>where
R: RngCore,
Rng
. Read moreSource§fn from_entropy() -> Self
fn from_entropy() -> Self
impl CryptoRng for ChaCha20Rng
impl Eq for ChaCha20Rng
Auto Trait Implementations§
impl Freeze for ChaCha20Rng
impl RefUnwindSafe for ChaCha20Rng
impl Send for ChaCha20Rng
impl Sync for ChaCha20Rng
impl Unpin for ChaCha20Rng
impl UnwindSafe for ChaCha20Rng
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
Source§impl<T> CryptoRngCore for T
impl<T> CryptoRngCore for T
Source§fn as_rngcore(&mut self) -> &mut dyn RngCore
fn as_rngcore(&mut self) -> &mut dyn RngCore
RngCore
trait object.Layout§
Note: Most layout information is completely unstable and may even differ between compilations. The only exception is types with certain repr(...)
attributes. Please see the Rust Reference's “Type Layout” chapter for details on type layout guarantees.
Size: 320 bytes