# Aura Protocol

The Aura protocol provides a mutually-authenticated, post-quantum-secure tunnel between a
client and a server. It is implemented in the `aura-proto` crate on top of `aura-crypto`
(hybrid KEM, HKDF, AEAD) and `aura-pki` (mutual X.509 verification).

This document is for an engineer auditing or reimplementing the protocol. Everything below
reflects the **actual implementation**, not an idealized spec. Where the original spec was
ambiguous (notably the handshake message order), the implementation pins an exact choice and
that pinned choice is what is documented here.

## Layering

```
+-------------------------------------------------------------+
|  Application IP packets (TUN)                               |
+-------------------------------------------------------------+
|  Aura inner session: Frame -> AEAD-sealed Data record       |  <- real security boundary
|  Aura inner handshake: hybrid KEM + mutual X.509            |
+-------------------------------------------------------------+
|  Outer QUIC/TLS (quinn + rustls) — MIMICRY ONLY             |  <- NOT a security boundary
|  ALPN h3 / h3-29, Chrome-like transport params,            |
|  client accepts ANY server cert                            |
+-------------------------------------------------------------+
|  UDP                                                         |
+-------------------------------------------------------------+
```

The two layers have very different jobs:

- **Outer QUIC/TLS** is camouflage. It is configured to look like ordinary browser HTTP/3
  traffic. It performs **no** meaningful authentication — see [Mimicry layer](#mimicry-layer).
- **Inner Aura handshake/session** is the real security boundary: hybrid post-quantum key
  agreement plus mutual certificate verification against the Aura CA, then an AEAD-protected
  record stream with replay protection.

The inner protocol is transport-agnostic: `client_handshake` / `server_handshake` are generic
over a separate `tokio::io::AsyncRead` reader and `AsyncWrite` writer, so the same code drives
an in-memory duplex pipe (tests) and quinn's split `RecvStream` / `SendStream` (the QUIC
transport) identically.

---

## Wire format

Every Aura protocol message is a **5-byte header** followed by a payload
(`crates/aura-proto/src/frame.rs`):

```
byte 0      : msg_type (u8)
bytes 1..4  : length   (u24, big-endian) = payload length in bytes
byte 4      : version  = 0x01
bytes 5..   : payload  (length bytes)
```

- `length` is a 24-bit big-endian integer, so the maximum payload is `0x00FF_FFFF`
  (16 MiB − 1). An oversize payload is rejected with `FrameTooLarge`.
- `version` is `0x01`. A header whose byte 4 is not `0x01` is rejected with `BadVersion`.

### Message types

| Byte   | `MsgType`     | Direction | Encrypted | Role                                       |
|--------|---------------|-----------|-----------|--------------------------------------------|
| `0x01` | `ClientHello` | C→S       | no        | Handshake 1: hybrid public key + nonce     |
| `0x02` | `ServerHello` | S→C       | no        | Handshake 2: hybrid ciphertext + nonce     |
| `0x03` | `ClientAuth`  | C→S       | yes       | Handshake 4: client cert + signature       |
| `0x04` | `ServerAuth`  | S→C       | yes       | Handshake 3: server cert + signature       |
| `0x05` | `Finished`    | both      | yes       | Handshake 5/6: HMAC over the transcript    |
| `0x06` | `Data`        | both      | yes       | Application record (AEAD-sealed `Frame`)    |
| `0xFF` | `Alert`       | both      | no        | Fatal alert; payload byte 0 is the code    |

> Note: the numeric byte values do **not** follow the send order. `ServerAuth` (`0x04`) is
> sent *before* `ClientAuth` (`0x03`). The send order is fixed by the state machine
> (below), not by the type byte.

### Application frames

Once the session is established, the application payload carried inside each encrypted `Data`
record is a `Frame` (`crates/aura-proto/src/frame.rs`). All multi-byte integers are
big-endian:

| Frame   | Tag    | Encoding                                             |
|---------|--------|-----------------------------------------------------|
| `Data`  | `0x01` | `0x01 \|\| stream_id(u32) \|\| payload`             |
| `Ping`  | `0x02` | `0x02 \|\| seq(u32)`                                 |
| `Pong`  | `0x03` | `0x03 \|\| seq(u32)`                                 |
| `Close` | `0x04` | `0x04 \|\| code(u8) \|\| reason_len(u32) \|\| reason_utf8` |

---

## Handshake

### Pinned message order

The original spec diagram was ambiguous about the order of the encrypted auth/Finished
messages. The implementation pins this exact order, and both peers follow it lock-step
(`crates/aura-proto/src/handshake.rs`):

```
1. C -> S  ClientHello (plaintext):  x25519_pub[32] || mlkem_ek[1184] || client_nonce[32]
2. S -> C  ServerHello (plaintext):  x25519_ephemeral[32] || mlkem_ct[1088] || server_nonce[32]
   -- both sides derive the hybrid shared secret and the two directional SessionKeys --
3. S -> C  ServerAuth (encrypted under s2c):  u16(cert_der_len) || server_leaf_cert_der || sig(transcript)
4. C -> S  ClientAuth (encrypted under c2s):  u16(cert_der_len) || client_leaf_cert_der || sig(transcript)
5. C -> S  Finished   (encrypted under c2s):  HMAC-SHA256(key_c2s, transcript)
6. S -> C  Finished   (encrypted under s2c):  HMAC-SHA256(key_s2c, transcript)
   -- encrypted Data channel is now open in both directions --
```

```mermaid
sequenceDiagram
    participant C as Client
    participant S as Server
    Note over C,S: plaintext
    C->>S: 1. ClientHello (x25519_pub, mlkem_ek, client_nonce)
    S->>C: 2. ServerHello (x25519_eph, mlkem_ct, server_nonce)
    Note over C,S: both derive shared secret + SessionKeys<br/>transcript = SHA-256(CH_frame || SH_frame)
    Note over C,S: encrypted (AEAD under directional keys)
    S->>C: 3. ServerAuth (server cert + sig over transcript)
    C->>S: 4. ClientAuth (client cert + sig over transcript)
    C->>S: 5. Finished (HMAC_c2s over transcript)
    S->>C: 6. Finished (HMAC_s2c over transcript)
    Note over C,S: session established; Data records flow both ways
```

### Hello payloads (exact sizes)

| Field             | ClientHello | ServerHello | Bytes |
|-------------------|:-----------:|:-----------:|------:|
| X25519 pub / eph  | ✔           | ✔           | 32    |
| ML-KEM-768 ek     | ✔           |             | 1184  |
| ML-KEM-768 ct     |             | ✔           | 1088  |
| nonce             | ✔           | ✔           | 32    |
| **Total payload** | **1248**    | **1152**    |       |

Hellos are sent in plaintext and validated for exact length on receipt; a wrong length is
rejected with `MalformedHandshake`.

### Transcript hash

```
transcript = SHA-256( ClientHello_frame_bytes || ServerHello_frame_bytes )
```

The hash covers the **full serialized frames** (5-byte header + payload) of ClientHello and
ServerHello, exactly as transmitted on the wire. This binds the negotiated key material and
the protocol version into both the signatures and the Finished MACs.

### Authentication (ServerAuth / ClientAuth)

Each Auth payload is:

```
u16_be(cert_der_len) || leaf_cert_der || signature
```

- `leaf_cert_der` is the sender's **leaf certificate** in DER (sent inline; no chain — the
  CA is the trust anchor on the receiving side).
- `signature` is an **ECDSA P-256 / SHA-256** signature, ASN.1 DER encoded
  (`ECDSA_P256_SHA256_ASN1`), computed over the 32-byte `transcript` (via `ring`).

Verification (`crates/aura-proto/src/handshake.rs`):

1. The receiver builds an `AuraCertVerifier` from its configured CA PEM and verifies the
   peer's leaf against the CA (chain + key-usage + validity; see `pki.md`).
   - The **client** additionally requires the server leaf to be valid for the expected
     `server_name` (DNS SAN match).
   - The **server** captures the verified **client id** (leaf Common Name) and stores it as
     the session's `peer_id`.
2. The receiver extracts the leaf's EC public-key point and verifies `signature` over
   `transcript`. A failure is `Signature(...)`.

Possession of the certificate's private key is therefore proven by the signature over the
transcript; the certificate identity is proven by the CA chain check.

### Finished

Each side sends, then verifies, a Finished MAC bound to the transcript and the direction key:

```
Finished_c2s = HMAC-SHA256(key_c2s, transcript)   // client sends (msg 5), server verifies
Finished_s2c = HMAC-SHA256(key_s2c, transcript)   // server sends (msg 6), client verifies
```

Verification is constant-time (`Hmac::verify_slice`); a mismatch is `FinishedMismatch`. The
Finished exchange confirms both sides derived identical keys and agree on the full transcript.

### Encrypted handshake messages and counter continuity

Messages 3–6 are AEAD-sealed under the **same** two directional `AeadSession`s that protect
application Data; their nonce counters are continuous across the handshake/data boundary.

- The AAD for each encrypted handshake message is its 5-byte frame header (binding type +
  length), matching the Data-record convention.
- Each direction seals **exactly two** encrypted handshake messages before Data begins:
  - c2s seals `ClientAuth` (counter 0) and `Finished` (counter 1)
  - s2c seals `ServerAuth` (counter 0) and `Finished` (counter 1)
- Therefore both directions reach AEAD counter **2** at the end of the handshake, and the
  first application Data record stamps `seq == 2` (`POST_HANDSHAKE_COUNTER`). This seeds the
  replay window (below).

---

## Hybrid KEM

The key exchange is a hybrid of classical X25519 ECDH and post-quantum ML-KEM-768
(`crates/aura-crypto/src/kem/`). An attacker must break **both** primitives to recover the
session key.

> **ML-KEM-768 (FIPS 203)**, via the RustCrypto `ml-kem` crate (v0.3) — this is the
> standardized FIPS 203 scheme, **not** round-3 Kyber.

### Roles

- The **client** owns the long-term `HybridPrivateKey` and publishes its `HybridPublicKey`
  in ClientHello.
- The **server** calls `encapsulate()` against that public key: it generates an **ephemeral**
  X25519 keypair and an ML-KEM encapsulation, returns the `HybridCiphertext` in ServerHello,
  and derives the shared secret.
- The **client** recovers the same secret via `decapsulate()`.

So X25519 is **ephemeral–static** (server ephemeral against client static public), while
ML-KEM is a standard KEM against the client's encapsulation key.

### Sizes

| Quantity                          | Bytes | Constant            |
|-----------------------------------|------:|---------------------|
| X25519 public / ephemeral / secret| 32    | `X25519_LEN`        |
| ML-KEM-768 encapsulation key (ek) | 1184  | `EK_LEN`            |
| ML-KEM-768 ciphertext (ct)        | 1088  | `CT_LEN`            |
| ML-KEM-768 shared secret          | 32    | `SS_LEN`            |
| ML-KEM-768 decapsulation key (dk) | 2400  | `DK_LEN`            |

> **Implementation detail — dk encoding.** The decapsulation (secret) key is stored in the
> FIPS 203 **expanded 2400-byte** form (`ExpandedKeyEncoding`), not the 64-byte seed that
> `ml-kem` 0.3 prefers. This is the encoding the project's ACVP / FIPS-203 known-answer test
> vectors operate on, so it is used for interop/KAT compatibility. The dk never travels on the
> wire — only `ek` (1184 B) and `ct` (1088 B) do.

### Combined shared secret

```
shared = x25519_ss (32 B) || mlkem_ss (32 B)   // 64 bytes total
```

ML-KEM decapsulation is infallible on a correctly sized ciphertext: a tampered ciphertext
yields a pseudo-random secret (implicit rejection) rather than an error, which surfaces later
as an AEAD/Finished failure.

---

## Key derivation (HKDF)

Directional session keys are derived with **HKDF-SHA256** (RFC 5869)
(`crates/aura-crypto/src/kdf.rs`):

```
salt = client_nonce || server_nonce                 (64 bytes)
IKM  = x25519_ss || mlkem_ss                          (64 bytes)
info = "aura-v1-session"
OKM  = HKDF-Expand(HKDF-Extract(salt, IKM), info, 64) (64 bytes)

key_client_to_server = OKM[0..32]
key_server_to_client = OKM[32..64]
```

The derivation is fully deterministic in its inputs. The `info` string provides domain
separation. Intermediate secret material (`salt`, `IKM`, `OKM`) is zeroized after use, and
`SessionKeys` zeroizes its keys on drop.

---

## AEAD

The record cipher is **ChaCha20-Poly1305** (`crates/aura-crypto/src/aead.rs`). An
`AeadSession` holds a 256-bit key and a 64-bit message counter; each direction has its own
session.

### Nonce scheme

The 96-bit (12-byte) nonce is derived from the counter:

```
nonce[0..8]  = counter as little-endian u64
nonce[8..12] = 0x00 00 00 00
```

The counter advances by one on every `seal` **and** every `open` (even on a failed `open`),
so a paired seal/open stay aligned without transmitting the nonce. The nonce is never reused
within a session (the 2^64 counter wrap is unreachable; an overflow panics rather than
reusing a nonce). The key is zeroized on drop.

---

## Data records and replay protection

After the handshake, application `Frame`s are exchanged as `Data` records
(`crates/aura-proto/src/session.rs`). Each `Data` record's **payload** is:

```
seq (u64, big-endian) || ChaCha20Poly1305_seal( frame_bytes, aad = header || seq )
```

- `seq` is the 8-byte big-endian record counter. On the happy path it equals the sealing
  AEAD's counter (and the receiver's expected AEAD counter).
- The AEAD **AAD** is the 5-byte frame `header` concatenated with the 8-byte `seq`, so the
  record is cryptographically bound to both its declared length/type and its claimed position.
- The ciphertext includes the 16-byte Poly1305 tag.

So the full record on the wire is:

```
[ header(5) ][ seq(8) ][ ciphertext + tag ]
\_____________________________________________/
   header.length = 8 + len(ciphertext+tag)
```

### Sliding replay window

The receiver runs a **64-wide sliding-window** replay check (`REPLAY_WINDOW = 64`) *before*
touching the AEAD, so a duplicate or too-old record is rejected with `Replay(seq)` without
disturbing the AEAD counter (the session stays usable). The window:

- tracks the highest accepted `seq` plus a 64-bit bitmap of accepted positions below it;
- accepts a `seq` iff it is strictly newer than everything seen, or falls within the window
  and has not been seen before;
- rejects a `seq` that equals the current highest, is already marked in the bitmap, or is
  more than `REPLAY_WINDOW` below the highest.

The window is seeded at the post-handshake counter (`start = 2`): everything strictly below
`start` is treated as already-consumed, so the first legitimate Data record (`seq == 2`) is
accepted as "newer".

### Full-duplex split

A `Session` can be `split()` into independent `SessionSender` (writer + outbound AEAD +
send counter) and `SessionReceiver` (reader + inbound AEAD + replay window) halves, which can
be driven from separate tasks for a concurrent read/write data path (e.g. the VPN tunnel).
`recv_frame` is **not** cancellation-safe and must be driven from a single owning task.

---

## Mimicry layer

The outer QUIC/TLS layer (`crates/aura-transport/`) exists purely to disguise the connection
as browser HTTP/3 traffic. It is explicitly **not** the authentication boundary.

- **ALPN** advertises `h3` and `h3-29` (`ALPN_H3`) — exactly what Chrome offers for HTTP/3 —
  so the ALPN extension is indistinguishable from a real browser's.
- **Transport params** mirror a Chromium HTTP/3 connection: ~30 s idle timeout, ~15 s
  keep-alive, 100 concurrent bidi/uni streams, ~10 MB flow-control receive windows
  (`chrome_quic_transport_config`).
- **SNI** defaults to a generic CDN-looking hostname (`cdn.example.com`) when the caller does
  not supply one; deployments pass their own camouflage hostname.
- The QUIC **client accepts any server certificate** (`AcceptAnyServerCert` — all verifier
  methods return success). This is safe *only* because the outer TLS is not authentication:
  the real mutual auth is the inner Aura handshake. The server's outer TLS likewise disables
  client auth (`with_no_client_auth`).

> Do not reuse `AcceptAnyServerCert` anywhere the TLS layer *is* the authentication boundary.

---

## Error model

The protocol layer surfaces `ProtoError` (`crates/aura-proto/src/lib.rs`), including:
`Io`, `Crypto`, `Pki`, `UnknownMsgType`, `BadVersion`, `FrameTooLarge`, `UnexpectedMsg`,
`MalformedHandshake`, `MalformedFrame`, `Signature`, `FinishedMismatch`, `Replay`, and
`Alert`. A peer may send a fatal `Alert` frame (type `0xFF`); the first payload byte is the
alert code, surfaced to the local side as `ProtoError::Alert(code)`.