enigma-aead

enigma-aead provides a reusable AEAD + framing + nonce transport layer for Enigma components. It combines deterministic packet framing with XChaCha20-Poly1305 to ensure every encrypted message is self-describing and ready for any transport.

Purpose

Bind ciphertext, header, and caller-supplied associated data into one authenticated packet
Provide safe nonce generation and a canonical binary format with strict bounds checking
Offer a minimal API that accepts 32-byte symmetric keys from higher layers like identity or ratchet components

Non-goals

Key agreement, storage, or ratcheting state machines
Replay protection or transport-level sequencing
Streaming encryption of unbounded payloads

Quickstart

use enigma_aead::AeadBox;

fn demo() -> Result<(), Box<dyn std::error::Error>> {
    let key = [0u8; 32];
    let boxy = AeadBox::new(key);
    let packet = boxy.encrypt(b"hello", b"chat")?;
    let plaintext = boxy.decrypt(&packet, b"chat")?;
    assert_eq!(plaintext, b"hello");
    Ok(())
}

Packet format summary

Magic: ENA1
Version: 0x01
Algorithm: 0x01 for XChaCha20-Poly1305
Flags: currently 0x00
Reserved: 0x00
Key identifier: 8 bytes (all zeros if unused)
Nonce: 24 bytes
Ciphertext + Poly1305 tag: remainder of the packet (at least 16 bytes)
Minimum size: 56 bytes (40-byte header + 16-byte tag)
Maximum size: 16 MiB

See docs/format.md for the full binary layout.

Testing