Crate chacha20 

RustCrypto: ChaCha20

Implementation of the ChaCha family of stream ciphers.

ChaCha improves upon the previous Salsa family of stream ciphers with increased per-round diffusion at no cost to performance.

This crate also contains an implementation of the XChaCha family of stream ciphers with an extended 192-bit (24-byte) nonce, gated under the xchacha Cargo feature, and “legacy” (a.k.a “djb”) variant with 64-bit nonce, gated under the legacy crate feature.

WARNING: This implementation internally uses 32-bit counter, while the original “legacy” variant implementation uses 64-bit counter. In other words, it does not allow encryption of more than 256 GiB of data.

Security

⚠️ Warning: Hazmat!

This crate does not ensure ciphertexts are authentic (i.e. by using a MAC to verify ciphertext integrity), which can lead to serious vulnerabilities if used incorrectly!

To avoid this, use an AEAD mode based on ChaCha20, e.g. chacha20poly1305. See the RustCrypto/AEADs repository for more information.

USE AT YOUR OWN RISK!

Notes

This crate has received one security audit by NCC Group, with no significant findings. We would like to thank MobileCoin for funding the audit.

All implementations contained in the crate (along with the underlying ChaCha20 stream cipher itself) are designed to execute in constant time.

Examples

// This example requires `cipher` crate feature
#[cfg(feature = "cipher")] {

use chacha20::ChaCha20;
use chacha20::cipher::{KeyIvInit, StreamCipher, StreamCipherSeek};
use hex_literal::hex;

let key = [0x42; 32];
let nonce = [0x24; 12];
let plaintext = hex!("000102030405060708090A0B0C0D0E0F");
let ciphertext = hex!("e405626e4f1236b3670ee428332ea20e");

// Key and IV must be references to the `Array` type.
// Here we use the `Into` trait to convert arrays into it.
let mut cipher = ChaCha20::new(&key.into(), &nonce.into());

let mut buffer = plaintext;

// apply keystream (encrypt)
cipher.apply_keystream(&mut buffer);
assert_eq!(buffer, ciphertext);

let ciphertext = buffer;

// ChaCha ciphers support seeking
cipher.seek(0u32);

// decrypt ciphertext by applying keystream again
cipher.apply_keystream(&mut buffer);
assert_eq!(buffer, plaintext);

// stream ciphers can be used with streaming messages
cipher.seek(0u32);
for chunk in buffer.chunks_mut(3) {
    cipher.apply_keystream(chunk);
}
assert_eq!(buffer, ciphertext);
}

Configuration Flags

You can modify crate using the following configuration flags:

• chacha20_backend="avx2": force AVX2 backend on x86/x86_64 targets. Requires enabled AVX2 target feature. Ignored on non-x86(_64) targets.
• chacha20_backend="avx512": force AVX-512 backend on x86/x86_64 targets. Requires enabled AVX-512 target feature (MSRV 1.89). Ignored on non-x86(_64) targets.
• chacha20_backend="soft": force software backend.
• chacha20_backend="sse2": force SSE2 backend on x86/x86_64 targets. Requires enabled SSE2 target feature. Ignored on non-x86(-64) targets.

To use the MSRV 1.89 AVX-512 support with autodetection, you must enable it using chacha20_avx512 configuration flag.

The flags can be enabled using RUSTFLAGS environmental variable (e.g. RUSTFLAGS='--cfg chacha20_backend="avx2"') or by modifying .cargo/config.toml.

License

Licensed under either of:

• Apache License, Version 2.0
• MIT license

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Re-exports

pub use cipher;

pub use rand_core;

Modules

avx2_cpuid 🔒

backends 🔒

chacha 🔒

rng 🔒

sse2_cpuid 🔒

variants

ChaCha variant-specific configurations.

xchacha 🔒

XChaCha is an extended nonce variant of ChaCha

Structs

ChaCha8Rng

A cryptographically secure random number generator that uses the ChaCha stream cipher.

ChaCha12Rng

A cryptographically secure random number generator that uses the ChaCha stream cipher.

ChaCha20Rng

A cryptographically secure random number generator that uses the ChaCha stream cipher.

ChaChaCore

The ChaCha core function.

R8

8-rounds

R12

12-rounds

R20

20-rounds

Constants

CONSTANTS 🔒

State initialization constant (“expand 32-byte k”)

STATE_WORDS 🔒

Number of 32-bit words in the ChaCha state

Traits

KeyIvInit

Types which can be initialized from a key and initialization vector (nonce).

Rounds

Marker type for a number of ChaCha rounds to perform.

Functions

hchacha

The HChaCha function: adapts the ChaCha core function in the same manner that HSalsa adapts the Salsa function.

quarter_round 🔒

The ChaCha20 quarter round function

Type Aliases

ChaCha8

ChaCha8 stream cipher (reduced-round variant of ChaCha20 with 8 rounds)

ChaCha12

ChaCha12 stream cipher (reduced-round variant of ChaCha20 with 12 rounds)

ChaCha20

ChaCha20 stream cipher (RFC 8439 version with 96-bit nonce)

Key

Key type used by all ChaCha variants.

Nonce

Nonce type used by ChaCha variants.

Seed

Seed value used to initialize ChaCha-based RNGs.

SerializedRngState

Serialized RNG state.

Tokens 🔒

XChaCha8

XChaCha8 stream cipher (reduced-round variant of XChaCha20 with 8 rounds)

XChaCha12

XChaCha12 stream cipher (reduced-round variant of XChaCha20 with 12 rounds)

XChaCha20

XChaCha is a ChaCha20 variant with an extended 192-bit (24-byte) nonce.

XNonce

Nonce type used by XChaCha variants.