aead

aead defines a common trait interface for Authenticated Encryption with Associated Data (AEAD) ciphers in Rust, the algorithm family behind AES-GCM, ChaCha20Poly1305, and similar constructions that guarantee both confidentiality and integrity. Rather than shipping a specific cipher implementation, it establishes the AeadCore, Aead, and AeadInOut traits that concrete crates like aes-gcm and chacha20poly1305 implement, so application code can be written generically against any AEAD algorithm.

The crate is part of the RustCrypto project’s traits workspace, which also houses cipher, digest, crypto-common, and related trait crates that form the foundation of the RustCrypto ecosystem. It is no_std by default, uses hybrid-array-backed fixed-size nonce and tag types for compile-time sizing, and supports optional integrations with bytes, arrayvec, and rand_core behind feature flags.

What You Get

• AeadCore trait - Declares nonce size, tag size, and tag position for a given AEAD algorithm at the type level.
• Aead and AeadInOut traits - High-level encrypt/decrypt methods returning Vec<u8>, plus in-place/inout variants for buffer-constrained code.
• Generic Nonce/Tag types - Fixed-size Array<u8, N> aliases sized per-algorithm via associated types, catching size mismatches at compile time.
• dev module test harness - pass_test/fail_test helpers plus a blobby-based test-vector format for validating new AEAD implementations.
• no_std support with optional alloc/bytes/arrayvec backends - Runs on embedded targets by default, with feature flags to opt into heap-allocated or bytes-backed buffers.

Common Use Cases

• Writing a cipher-agnostic encryption layer - A library author implements AeadInOut for AES-GCM and ChaCha20Poly1305 backends and exposes a single generic API to callers.
• Building a new AEAD cipher crate - A cryptography engineer implements AeadCore/AeadInOut for a novel construction and gets Aead’s allocating encrypt/decrypt methods for free via the blanket impl.
• Embedded/no_std encrypted storage - A firmware developer encrypts data in-place on a fixed buffer using encrypt_in_place/decrypt_in_place without pulling in alloc.
• Validating AEAD implementations against test vectors - A maintainer wires up the dev module’s blobby-based vectors to catch regressions in encrypt/decrypt round-trips.

Under The Hood

Architecture The crate is a pure trait-definition layer with no concrete cipher implementations. Execution starts at the public API surface in src/lib.rs: AeadCore establishes associated types (NonceSize, TagSize, TagPosition) at compile time via the hybrid-array-based ArraySize bound; AeadInOut extends it with encrypt_inout_detached/decrypt_inout_detached as the primitive operations that concrete ciphers implement; Aead (gated behind the alloc feature) and the higher-level encrypt_in_place/decrypt_in_place default methods on AeadInOut are blanket-implemented on top of that single primitive, so any downstream crate needs to implement only the detached in/out methods to get the full ergonomic API for free. A deprecated AeadInPlace trait (also blanket-implemented) exists purely to forward calls for backward compatibility. The dev module is a separate test-harness layer, gated behind the dev feature, that depends on the public traits to run pass/fail test vectors - no core logic lives there. Because the crate defines no runtime state, changing a core abstraction would primarily affect the downstream RustCrypto cipher crates (aes-gcm, chacha20poly1305, and others) that implement it, since correctness lives entirely at the trait/type level.

Tech Stack Rust, edition 2024, MSRV 1.85. The core dependency is crypto-common (aliased as common), the sibling RustCrypto trait crate providing Key, KeyInit, KeySizeUser, and the hybrid-array-based Array/ArraySize/typenum machinery used for compile-time-sized nonces and tags; inout supplies the InOutBuf abstraction for in-place buffer operations. Optional dependencies are feature-gated: arrayvec for fixed-capacity no-alloc buffers, blobby for binary test-vector decoding under the dev feature, and bytes for BytesMut buffer support. The crate is no_std by default with an opt-in alloc feature for Vec-returning APIs, and forbids unsafe code entirely. Build tooling is plain cargo with workspace-level lints inherited from the parent RustCrypto/traits workspace; docs.rs metadata builds with all features enabled. There is no web framework, database, or deployment target - this is a library-only crate consumed via crates.io.

Code Quality Tests live in a dummy-cipher integration test that implements a minimal XOR-based, non-cryptographic cipher purely to exercise the trait plumbing - encrypt/decrypt round-trips, in-place vs allocating APIs, and prefix vs postfix tag positions - against blobby-encoded test vectors, rather than testing real cryptography, which is delegated to implementing crates such as aes-gcm. Error handling is deliberately minimal and typed: a single opaque Error unit struct implements the standard Error trait and Display, explicitly documented as opaque to avoid side-channel leakage such as padding-oracle-style attacks rather than swallowing errors carelessly. Naming is consistent with RustCrypto conventions across the workspace. Type safety is strong - nonce and tag sizes are enforced at compile time via associated ArraySize types rather than runtime length checks. Unsafe code is forbidden crate-wide, and workspace-inherited lints plus scoped clippy allow-lists indicate an actively linted codebase; CI runs at the workspace level.

API Design The crate’s central ergonomic idea is decoupling the primitive a cipher implementer must write (encrypt_inout_detached/decrypt_inout_detached, taking an InOutBuf and returning a detached Tag) from the convenience APIs consumers get for free via blanket impls (allocating encrypt/decrypt returning Vec<u8>, and in-place variants operating on any Buffer) - so a new cipher crate implements one trait once and automatically gains three API surfaces with correct prefix/postfix tag handling already solved generically. The opaque Error type is a deliberate security-by-API-design choice that structurally prevents callers from branching on failure reason and leaking timing information. Compile-time nonce/tag sizing via associated types catches size mismatches before runtime rather than via length-check panics. None of this is novel research - it mirrors the standard RustCrypto trait-crate pattern shared across sibling crates in the same workspace - but as a low-boilerplate design for implementing and consuming AEAD ciphers in Rust, it is well executed.