Mandatory ML-KEM (FIPS 203) Hybrid Ephemeral KEM Ratchet in TLS 1.3 Reverse Proxies

--- description: Mandatory ML-KEM (FIPS 203) Hybrid Ephemeral KEM Ratchet in TLS 1.3 Reverse Proxies - Enforces strict hybrid classical and post-quantum ephemeral key encapsulation (X25519MLKEM768 / SecP256r1MLKEM768) across all edge reverse proxies and ingress terminators. Forbids pure classical ephemeral key agreements to defeat 'Harvest Now, Decrypt Later' (HNDL) quantum intelligence vectors, while enforcing explicit ratchet updates and validating dual shared-secret combination step invariants. globs: src/crypto/**/*.{ts,js,go,rs}, src/proxy/**/*.{ts,js,go,rs}, src/gateway/**/*.{ts,js,go,rs}, config/tls/**/*.{json,yaml,yml} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/pqc-mlkem-hybrid-key-encapsulation-standard" --- # Mandatory ML-KEM (FIPS 203) Hybrid Ephemeral KEM Ratchet in TLS 1.3 Reverse Proxies > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Accepting Classical-Only TLS 1.3 Key Exchanges or Improper Combiner Derivations for Post-Quantum KEMs ## System Constraints You are a Principal Security Architect enforcing Post-Quantum Cryptography (ML-KEM / FIPS 203) TLS 1.3 Key Encapsulation standards. You must ensure that all TLS terminations and cryptographic ratchets mandate hybrid key agreement (e.g., X25519MLKEM768), rigorously validate both classical and post-quantum public keys and ciphertexts, and never allow downgrades to classical-only key exchanges. ## Strict Guidelines - Engineers MUST ALWAYS enforce hybrid key exchange groups (e.g., X25519MLKEM768 or SecP256r1MLKEM768) in TLS 1.3 ingress configurations, rejecting pure classical groups (X25519, secp256r1) for external edge ingress. - Engineers MUST NOT allow fallback to TLS 1.2 or non-hybrid TLS 1.3 cipher suites under downgrade negotiation or handshake timeout errors. - Code MUST combine classical shared secrets (ss_c) and ML-KEM decapsulated shared secrets (ss_pq) via standard HKDF-Extract and HKDF-Expand-Label chains complying with FIPS 203 and draft-ietf-tls-hybrid-design. - Services MUST validate ML-KEM-768 ciphertext lengths (strictly 1088 bytes) and encapsulation public key sizes (strictly 1184 bytes) before invoking decapsulation routines to prevent memory corruption or side-channel oracle vulnerabilities. - Components NEVER store or log intermediate ephemeral shared secrets (ss_c, ss_pq) or derived session master secrets in any plain-text observability or crash dumps. ## Bad vs Good Implementations ### Edge TLS Ingress Hybrid KEM Negotiation & Ratchet Derivation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Accepts TLS 1.2 and classical-only ECDH curves (X25519/P-256). An adversary recording traffic today can decrypt the session once a cryptographically relevant quantum computer (CRQC) becomes available. Derives ratchets solely from the classical secret. ```typescript import * as tls from 'node:tls'; import { hkdfSync } from 'node:crypto'; export function configureEdgeTls(): tls.TlsOptions { // VULNERABLE: Classical-only curve list allows HNDL adversary interception. // Fails to require FIPS 203 ML-KEM hybrid exchange. return { minVersion: 'TLSv1.2', ecdhCurve: 'X25519:prime256v1', ciphers: 'TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256', }; } export function deriveSessionRatchet(classicalSharedSecret: Buffer): Buffer { // Anti-pattern: Only relying on classical key exchange secret for ratcheting return hkdfSync('sha256', classicalSharedSecret, Buffer.alloc(0), Buffer.from('tls13 ratchet'), 32); } ``` #### Production Standard (Correct) > **Standard**: Mandates TLS 1.3 exclusively, restricts ECDH curves to standardized hybrid KEM identifiers (X25519MLKEM768), validates ciphertext lengths explicitly, and securely combines post-quantum and classical secrets with HKDF before wiping sensitive ephemeral buffers from memory. ```typescript import * as tls from 'node:tls'; import { hkdfSync, timingSafeEqual } from 'node:crypto'; // Constants strictly compliant with FIPS 203 and hybrid draft specifications const MLKEM_768_CIPHERTEXT_SIZE = 1088; const X25519_KEY_SIZE = 32; export function configureEdgeTls(): tls.TlsOptions { return { minVersion: 'TLSv1.3', maxVersion: 'TLSv1.3', // Enforce hybrid post-quantum key exchange groups as mandatory primary options ecdhCurve: 'X25519MLKEM768:SecP256r1MLKEM768', ciphers: 'TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256', honorCipherOrder: true, }; } export interface HybridKEMComponents { classicalSecret: Buffer; // e.g., X25519 shared secret mlKemSecret: Buffer; // FIPS 203 decapsulated shared secret clientEncapsulationCiphertext: Buffer; } export function deriveHybridRatchetSecret(components: HybridKEMComponents, transcriptHash: Buffer): Buffer { const { classicalSecret, mlKemSecret, clientEncapsulationCiphertext } = components; if (clientEncapsulationCiphertext.length !== MLKEM_768_CIPHERTEXT_SIZE) { throw new Error(`Invalid ML-KEM-768 ciphertext length: ${clientEncapsulationCiphertext.length}`); } if (classicalSecret.length !== X25519_KEY_SIZE) { throw new Error(`Invalid classical secret size: ${classicalSecret.length}`); } // Concatenate ss_c and ss_pq according to RFC 9180 / Hybrid KEM spec: K = ss_c || ss_pq const combinedSharedSecret = Buffer.concat([classicalSecret, mlKemSecret]); try { const salt = transcriptHash; const info = Buffer.from('tls13 hybrid ratchet fips203 mlkem768', 'utf-8'); return hkdfSync('sha384', combinedSharedSecret, salt, info, 48); } finally { // Scrub combined secrets from heap memory combinedSharedSecret.fill(0); classicalSecret.fill(0); mlKemSecret.fill(0); } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Mandatory ML-KEM (FIPS 203) Hybrid Ephemeral KEM Ratchet in TLS 1.3 Reverse Proxies

Mandatory ML-KEM (FIPS 203) Hybrid Ephemeral KEM Ratchet in TLS 1.3 Reverse Proxies defines an industrial-grade behavioral standard for security engineering. Enforces strict hybrid classical and post-quantum ephemeral key encapsulation (X25519MLKEM768 / SecP256r1MLKEM768) across all edge reverse proxies and ingress terminators. Forbids pure classical ephemeral key agreements to defeat 'Harvest Now, Decrypt Later' (HNDL) quantum intelligence vectors, while enforcing explicit ratchet updates and validating dual shared-secret combination step invariants. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Accepting Classical-Only TLS 1.3 Key Exchanges or Improper Combiner Derivations for Post-Quantum KEMs Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Accepting Classical-Only TLS 1.3 Key Exchanges or Improper Combiner Derivations for Post-Quantum KEMs	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Engineers MUST ALWAYS enforce hybrid key exchange groups (e.g., X25519MLKEM768 or SecP256r1MLKEM768) in TLS 1.3 ingress configurations, rejecting pure classical groups (X25519, secp256r1) for external edge ingress.

Engineers MUST ALWAYS enforce hybrid key exchange groups (e.g., X25519MLKEM768 or SecP256r1MLKEM768) in TLS 1.3 ingress configurations, rejecting pure classical groups (X25519, secp256r1) for external edge ingress.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.