Crate chacha20

The ChaCha20 stream cipher (RFC 8439)

ChaCha20 is a lightweight stream cipher which is amenable to fast, constant-time implementations in software. It improves upon the previous Salsa20 stream cipher, providing increased per-round diffusion with no cost to performance.

Cipher functionality is accessed using traits from re-exported cipher crate.

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

• ChaCha20: standard IETF variant with 96-bit nonce
• [ChaCha20Legacy]: (gated under the legacy feature) “djb” variant with 64-bit nonce
• ChaCha8 / ChaCha12: reduced round variants of ChaCha20
• XChaCha20: 192-bit extended nonce variant
• XChaCha8 / XChaCha12: reduced round variants of XChaCha20

⚠️ Security Warning: Hazmat!

This crate does not ensure ciphertexts are authentic, which can lead to serious vulnerabilities if used incorrectly!

If in doubt, use the chacha20poly1305 crate instead, which provides an authenticated mode on top of ChaCha20.

USE AT YOUR OWN RISK!

Diagram

This diagram illustrates the ChaCha quarter round function. Each round consists of four quarter-rounds:

Legend:

• ⊞ add
• ‹‹‹ rotate
• ⊕ xor

Usage

use chacha20::{ChaCha20, Key, Nonce};
use chacha20::cipher::{NewCipher, StreamCipher, StreamCipherSeek};

let mut data = [1, 2, 3, 4, 5, 6, 7];

let key = Key::from_slice(b"an example very very secret key.");
let nonce = Nonce::from_slice(b"secret nonce");

// create cipher instance
let mut cipher = ChaCha20::new(&key, &nonce);

// apply keystream (encrypt)
cipher.apply_keystream(&mut data);
assert_eq!(data, [73, 98, 234, 202, 73, 143, 0]);

// seek to the keystream beginning and apply it again to the `data` (decrypt)
cipher.seek(0);
cipher.apply_keystream(&mut data);
assert_eq!(data, [1, 2, 3, 4, 5, 6, 7]);

Re-exports

• pub use cipher;

Structs

• ChaCha
  ChaCha family stream cipher, generic around a number of rounds.
• XChaCha
  XChaCha family stream cipher, generic around a number of rounds.

Constants

• BLOCK_SIZE
  Size of a ChaCha20 block in bytes
• KEY_SIZE
  Size of a ChaCha20 key in bytes

Type Definitions

• 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
  ChaCha20 key type (256-bits/32-bytes)
• Nonce
  Nonce type (96-bits/12-bytes)
• 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
  XChaCha20 is a ChaCha20 variant with an extended 192-bit (24-byte) nonce.
• XNonce
  EXtended ChaCha20 nonce (192-bits/24-bytes)