Crate chacha20 

RustCrypto: ChaCha20

Pure Rust implementation of the ChaCha20 Stream Cipher.

About

ChaCha20 is a stream cipher which is designed to support high-performance software implementations.

It improves upon the previous Salsa20 stream cipher with increased per-round diffusion at no cost to performance.

This crate also contains an implementation of XChaCha20: a variant of ChaCha20 with an extended 192-bit (24-byte) nonce, gated under the chacha20 Cargo feature (on-by-default).

Implementations

This crate contains the following implementations of ChaCha20, all of which work on stable Rust with the following RUSTFLAGS:

• x86 / x86_64
  • avx2: (~1.4cpb) -Ctarget-cpu=haswell -Ctarget-feature=+avx2
  • sse2: (~1.6cpb) -Ctarget-feature=+sse2 (on by default on x86 CPUs)
  • avx512: -Ctarget-feature=+avx512f,+avx512vl --cfg chacha20_avx512 requires Rust 1.89+
• aarch64
  • neon (~2-3x faster than soft) requires the neon feature enabled
• Portable
  • soft: (~5 cpb on x86/x86_64)

NOTE: cpb = cycles per byte (smaller is better)

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, i.e. 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.

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.

Usage

Cipher functionality is accessed using traits from re-exported [cipher] crate, or as a set of random number generator types ending in *Rng which implement traits from the rand_core crate.

This crate contains the following variants of the ChaCha20 core algorithm:

• [ChaCha20]: standard IETF variant with 96-bit nonce
• [ChaCha8] / [ChaCha12]: reduced round variants of ChaCha20
• [XChaCha20]: 192-bit extended nonce variant
• [XChaCha8] / [XChaCha12]: reduced round variants of XChaCha20
• [ChaCha20Legacy]: “djb” variant with 64-bit nonce. WARNING: This implementation internally uses 32-bit counter, while the original implementation uses 64-bit counter. In other words, it does not allow encryption of more than 256 GiB of data.

Example

use chacha20::ChaCha20;
// Import relevant traits
use chacha20::cipher::{KeyIvInit, StreamCipher, StreamCipherSeek};
use hex_literal::hex;

let key = [0x42; 32];
let nonce = [0x24; 12];
let plaintext = hex!("00010203 04050607 08090A0B 0C0D0E0F");
let ciphertext = hex!("e405626e 4f1236b3 670ee428 332ea20e");

// 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.clone();

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

let ciphertext = buffer.clone();

// 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.

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

# In .cargo/config.toml
[build]
rustflags = ['--cfg', 'chacha20_backend="avx2"']

AVX-512 support

To use the MSRV 1.89 AVX-512 support, you must enable it using: --cfg chacha20_avx512.

Re-exports

pub use rand_core;

Modules

variants

ChaCha variant-specific configurations.

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

Traits

Rounds

Marker type for a number of ChaCha rounds to perform.

Type Aliases

Seed

Seed value used to initialize ChaCha-based RNGs.

SerializedRngState

Serialized RNG state.