Module aead 

Available on crate features aead-chacha20 or aead-aes-gcm only.

Authenticated encryption with associated data (AEAD).

This module exposes the high-level Crypt handle and the Algorithm enum. The default algorithm is ChaCha20-Poly1305 (RFC 8439): it is fast in software, post-quantum-safe at 256-bit symmetric strength, and the recommended choice when hardware AES acceleration is not available.

0.3.0 adds AES-256-GCM (NIST SP 800-38D) as a peer. Both algorithms share the same Crypt::encrypt / Crypt::decrypt surface, the same 32-byte key length, the same 12-byte nonce length, and the same 16-byte tag length — the only thing that changes is the underlying primitive (and the hardware-acceleration profile: AES-NI on x86, ARMv8 crypto extensions on AArch64).

Wire format

The ciphertext returned by Crypt::encrypt / Crypt::encrypt_with_aad is the concatenation nonce || ciphertext || tag, where:

• nonce is a 12-byte CSPRNG-generated value (mod-rand Tier 3, backed by the OS — getrandom on Linux, getentropy on macOS, BCryptGenRandom on Windows).
• ciphertext is the encryption of the plaintext under the supplied key and generated nonce.
• tag is the 16-byte authentication tag (Poly1305 for ChaCha20-Poly1305, GHASH for AES-256-GCM), covering both the ciphertext and any associated data passed to the AAD variants.

Crypt::decrypt / Crypt::decrypt_with_aad split this layout, verify the tag in constant time (provided by upstream RustCrypto), and return the decrypted plaintext.

Algorithm choice

Pick ChaCha20-Poly1305 unless you have a reason not to. It is fast in software, has no timing-side-channel risk on platforms without constant-time hardware AES, and is the post-quantum-safe default at the 256-bit symmetric strength the crate ships.

Pick AES-256-GCM when:

• You’re on a server-class x86 CPU with AES-NI + CLMUL (every Intel / AMD chip since ~2010), or an ARMv8 CPU with the crypto extensions (modern Apple Silicon, AWS Graviton, recent mobile SoCs). The aes-gcm crate detects these at runtime and dispatches to the hardware-accelerated path automatically — typically a 2–5× throughput win over the software path.
• You have an interop requirement (TLS records, JWE A256GCM, anything spec’d to AES-GCM).

Nonce policy

Nonces are generated fresh for every call. The 96-bit nonce space has a birthday bound of ~2^48 — well beyond any realistic message volume for a single key. Callers that need a specific nonce (interop with another implementation, deterministic test vectors) are out of scope for the 0.2.0 API; that surface will arrive in a later milestone with explicit “I understand the risk” naming.

Example

use crypt_io::Crypt;

let key = [0x42u8; 32];
let plaintext = b"attack at dawn";

let crypt = Crypt::new();
let ciphertext = crypt.encrypt(&key, plaintext).expect("encrypt");
let recovered = crypt.decrypt(&key, &ciphertext).expect("decrypt");

assert_eq!(&*recovered, plaintext);

Structs

Crypt

High-level encryption handle.

Enums

Algorithm

Supported AEAD algorithms.

Constants

AES_GCM_NONCE_LEN

Length of an AES-256-GCM nonce, in bytes. Equal to 12 (96 bits — the length NIST SP 800-38D specifies as the GCM default).

AES_GCM_TAG_LEN

Length of an AES-256-GCM authentication tag, in bytes. Equal to 16.

CHACHA20_NONCE_LEN

Length of a ChaCha20-Poly1305 nonce, in bytes. Equal to 12.

CHACHA20_TAG_LEN

Length of a ChaCha20-Poly1305 authentication tag, in bytes. Equal to 16.

KEY_LEN

Length of a symmetric key for any algorithm shipped in this version, in bytes. Equal to 32 (256-bit keys).