enigma-aead 0.1.1

AEAD + framing + nonce transport layer for Enigma secure messaging
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54

# 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
```rust
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.