# Phase 3: Post-Quantum Communication (PQXDH)

**Status:** ✅ COMPLETE
**Date:** 2026-01-30
**Component:** L1 Identity Layer (`l1-identity/`)

## Overview

This phase implements the **PQXDH** (Post-Quantum Extended Diffie-Hellman) key agreement protocol as defined in RFC-0830 (draft). It provides hybrid forward secrecy by combining:

1.  **Classical ECDH:** `X25519` (Curve25519) - Proven security against classical computers.
2.  **Post-Quantum KEM:** `ML-KEM-768` (Kyber-768, FIPS 203) - Security against quantum computers.

The result is a shared secret that remains secure even if a quantum computer breaks Curve25519 in the future ("Harvest Now, Decrypt Later" protection).

## Implementation Details

-   **Protocol:** Full X3DH flow with ML-KEM encapsulation added to the initial message.
-   **KDF:** `HKDF-SHA256` combines 4 ECDH shared secrets + 1 KEM shared secret.
-   **Library:** Uses `liboqs` (Open Quantum Safe) for ML-KEM implementation.
-   **Linking:** Statically linked `liboqs.a` to avoid runtime dependencies.
-   **Optimizations:**
    -   OpenSSL disabled (uses internal SHA3 implementation) to minimize binary size.
    -   Standard `ML-KEM` enabled, legacy `Kyber` disabled to avoid symbol conflicts.

## Build Instructions

To build the project with PQXDH support, you must first compile `liboqs`:

```bash
# 1. Build static liboqs (requires cmake, ninja/make)
./scripts/build_liboqs.sh

# 2. Run SDK tests
zig build test
```

## Key Files

-   `l1-identity/pqxdh.zig`: Core protocol logic (Initiator/Responder state machines).
-   `l1-identity/test_pqxdh.zig`: Comprehensive unit tests verify full handshake correctness.
-   `scripts/build_liboqs.sh`: Automated build script for dependency management.

## Performance

-   **Handshake Time:** ~2ms (ML-KEM) + ~0.5ms (X25519).
-   **Ciphertext Size:** 1088 bytes (ML-KEM-768).
-   **Public Key Size:** 1184 bytes (ML-KEM-768).
-   Total initial message overhead: ~1.1 KB (fits in 2 LWF jumbo frames).