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(())
}

Raw AEAD API

seal and open expose the XChaCha20-Poly1305 primitive without ENA1 framing, key identifiers, or packet parsing. Callers pass a 32-byte key, a 24-byte nonce, plaintext, and any required associated data, and the returned ciphertext contains the Poly1305 tag. Callers are responsible for nonce uniqueness and any framing or header metadata, while AeadBox::seal/AeadBox::open reuse the same key storage for convenience.

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

cargo test

Changelog

0.1.1: add raw seal/open API so higher-level crates can reuse the XChaCha20-Poly1305 primitive while keeping framing and nonce transport orthogonal to encryption.

enigma-aead 0.1.1