System Documentation
Architecture, cryptographic primitives, dual-combiner key exchange specifications, and REST API endpoints.
1. Architecture & Threat Model
Standard classical PKI based on RSA and Diffie-Hellman is vulnerable to Shor's Algorithm on quantum computers. Adversaries use "Store Now, Decrypt Later" (SNDL) tactics to harvest encrypted traffic today.
Our channel implements an Adaptive Hybrid Classical–Post-Quantum Protocol complying with NIST FIPS 203 (ML-KEM) and IETF standards. It binds classical asymmetric cryptography with lattice-based post-quantum cryptography to guarantee IND-CCA2 confidentiality.
Setup & Identity
Client fetches Server RSA-2048 / X25519 public keys and ML-KEM-768 public encapsulation key.
Hybrid Key Exchange
Dual encapsulation computes K_classical and K_pq, feeding HKDF-SHA256 combiner to derive K_session.
Authenticated AEAD
All payloads are encrypted with AES-256-GCM using 96-bit nonce vectors and user context AAD binding.
Threat Fallback
When quantum threats are detected, the system isolates classical RSA and enforces pure ML-KEM-768.
2. Supported Cipher Suites & Wire Profiles
The engine supports 7 standardized cryptographic suites allowing real-time comparative performance analysis:
| Cipher Suite Identifier | Classical Primitive | Post-Quantum Primitive | Security Level | Wire Overhead |
|---|---|---|---|---|
HYBRID_RSA_KYBER768 |
RSA-2048 (PKCS#1 v1.5) | NIST ML-KEM-768 | NIST Cat. 3 / 112-bit | 3,324 Bytes |
HYBRID_X25519_KYBER768 |
X25519 (ECDH) | NIST ML-KEM-768 (X-Wing) | NIST Cat. 3 / 128-bit | 2,592 Bytes |
PQ_KYBER768 |
None (Isolation Mode) | NIST ML-KEM-768 | NIST Level 3 (AES-192) | 2,528 Bytes |
PQ_KYBER1024 |
None (Isolation Mode) | NIST ML-KEM-1024 | NIST Level 5 (AES-256) | 3,392 Bytes |
PQ_KYBER512 |
None (Isolation Mode) | NIST ML-KEM-512 | NIST Level 1 (AES-128) | 1,824 Bytes |
CLASSICAL_X25519 |
X25519 (ECDH) | None (Baseline) | 128-bit Classical | 320 Bytes |
CLASSICAL_RSA2048 |
RSA-2048 | None (Legacy Baseline) | 112-bit Classical | 1,052 Bytes |
Dual-PRG Key Derivation Formula
K_session = HKDF-Expand(HKDF-Extract(salt = 0^256, IKM = K_classical || K_pq), info = "Q-GEM-HYBRID-v2-AES-GCM", L = 32)
3. Symmetric AEAD & Context Binding
Data confidentiality and integrity are provided by AES-256-GCM authenticated encryption:
AEAD Parameters
- Cipher: AES-256 in Galois/Counter Mode
- Nonce Vector: 96-bit CSPRNG (
os.urandom(12)) - Auth Tag: 128-bit MAC integrity tag
Associated Data (AAD)
- Context:
user:{username} - Replay Protection: Session-isolated ciphertexts
- Tamper Resistance: Immediate MAC failure
4. REST API Specifications
All endpoints require valid Django Session Authentication and CSRF verification.
| Endpoint | Method | Parameters | Description |
|---|---|---|---|
/api/public_keys/ |
GET | None | Returns identity RSA-2048, X25519, and ML-KEM-768 public keys. |
/api/client_public_key/ |
GET | None | Retrieves or generates client-side identity keypairs. |
/api/key_exchange/ |
POST | client_rsa_public_key_pem, cipher_suite |
Executes selected handshake and derives session master secret. |
/api/encrypt_message/ |
POST | plaintext |
Encrypts payload with AES-256-GCM and session context AAD binding. |
/api/decrypt_message/ |
POST | nonce, ciphertext, tag |
Verifies 128-bit authentication tag and decrypts payload. |
/api/benchmark/ |
POST | client_rsa_public_key_pem |
Benchmarks all 7 cipher suites and returns latency metrics. |
/api/fallback_control/ |
POST | enable (boolean) |
Toggles quantum threat simulation and activates ML-KEM isolation. |
/api/log_stream/ |
GET | None | Real-time Server-Sent Events (SSE) stream for cryptographic logs. |
5. Research & Standards Compliance
- NIST FIPS 203 (ML-KEM): Module-Lattice-Based Key-Encapsulation Mechanism standard (August 2024).
- IETF RFC 9496 / X-Wing: Standard hybrid key encapsulation combining X25519 ECDH and ML-KEM-768.
- NSA CNSA 2.0: Migration framework to lattice-based post-quantum cryptography.
- NIST SP 800-56C Rev. 2: Recommendation for Key-Derivation Methods in Key-Establishment Schemes.