Post-Quantum ML-KEM-768 Hybrid TLS 1.3 Key Encapsulation and MTU Guardrail

--- description: Post-Quantum ML-KEM-768 Hybrid TLS 1.3 Key Encapsulation and MTU Guardrail - Mandates the deployment of post-quantum hybrid key encapsulation (X25519MLKEM768) for TLS 1.3 across all internal and ingress service mesh communication to defeat Harvest-Now-Decrypt-Later (HNDL) adversaries. Enforces deterministic Path MTU (PMTU) discovery, TCP MSS clamping, and TLS record fragmentation controls to prevent silent middlebox packet drops caused by enlarged post-quantum key exchange payloads. globs: src/**/*.{ts,tsx,js,jsx}, infra/**/*.{ts,js,yaml,json}, k8s/**/*.{yaml,yml} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/post-quantum-mlkem768-hybrid-tls-guardrail" --- # Post-Quantum ML-KEM-768 Hybrid TLS 1.3 Key Encapsulation and MTU Guardrail > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Classical-Only ECDH Deployment with Unconstrained Handshake MTU Causing HNDL Vulnerability and Packet Blackholing ## System Constraints You are a Principal Security Architect enforcing Post-Quantum Cryptography (PQC) standards for zero-trust architectures. You must mandate ML-KEM-768 hybrid key encapsulation (X25519MLKEM768) over TLS 1.3 while enforcing strict MTU-aware fragment management to prevent client handshake dropouts across zero-trust service meshes. ## Strict Guidelines - Engineers MUST ALWAYS enforce TLS 1.3 as the strict minimum protocol version (`minVersion: 'TLSv1.3'`) whenever ML-KEM-768 hybrid key exchange is configured. - Engineers MUST configure hybrid curve groups prioritizing 'X25519MLKEM768' (IETF codepoint 0x11EC) followed by classical fallbacks, and MUST NOT permit unmonitored downgrades to classical-only groups. - Services MUST enforce TCP Maximum Segment Size (MSS) clamping and configure TLS record buffer sizing to prevent fragmentation packet drops across 1420-1500 byte Path MTU boundaries. - Engineers MUST NOT disable Path MTU Discovery (PMTUD) or ignore TCP socket buffer sizing when transmitting ~1.2 KB ML-KEM-768 public keys in TLS ClientHello and ServerHello messages. - Zero-trust ingress controllers and mesh sidecars MUST allocate at least 8KB for initial TLS handshake buffers to safely accommodate hybrid key shares without socket exhaustion or buffer truncations. ## Bad vs Good Implementations ### TLS 1.3 Client & Server Hybrid ML-KEM-768 with MTU-Aware Socket Tuning #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Configuring TLS with minimum version 1.2 and classical-only curves (prime256v1/X25519) leaves all traffic susceptible to Harvest-Now-Decrypt-Later (HNDL) attacks by quantum adversaries. Additionally, lacking explicit socket options and buffer constraints causes unexpected drops when handling larger post-quantum handshakes across restrictive zero-trust overlays. ```typescript import https from 'node:https'; import tls from 'node:tls'; // ANTI-PATTERN: Classical-only curve, permissive TLS versions, and no MTU-aware socket options export function createLegacyTlsClient(): https.Agent { return new https.Agent({ minVersion: 'TLSv1.2', // Vulnerable to HNDL: purely classical ECDH curves ecdhCurve: 'prime256v1:X25519', // No buffer or fragment protections; prone to MTU blackholing keepAlive: true, }); } export function createVulnerableServer(): tls.Server { return tls.createServer({ minVersion: 'TLSv1.2', // Omits ML-KEM-768 hybrid group and ignores jumbo ClientHello buffers ciphers: 'ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256', }); } ``` #### Production Standard (Correct) > **Standard**: Enforces TLS 1.3 exclusively with X25519MLKEM768 prioritized at the head of the curve group. Tunes the underlying socket buffers and checks the negotiated ephemeral key info to guarantee hybrid post-quantum encapsulation is actively protecting the connection against HNDL attacks without causing fragmentation-induced connection drops. ```typescript import tls from 'node:tls'; import net from 'node:net'; // PRODUCTION STANDARD: Enforce TLS 1.3 with X25519MLKEM768 and MTU-aware socket allocation const HYBRID_PQC_GROUPS = 'X25519MLKEM768:X25519:P-256'; const PQC_SAFE_RECORD_SIZE_BYTES = 4096; // Buffer tuned below PMTU cliff to avoid mesh fragmentation export interface SecureTlsSessionOptions { ca: Buffer | string; cert?: Buffer | string; key?: Buffer | string; } export function createPqcHybridTlsContext(opts: SecureTlsSessionOptions): tls.SecureContext { return tls.createSecureContext({ minVersion: 'TLSv1.3', maxVersion: 'TLSv1.3', ecdhCurve: HYBRID_PQC_GROUPS, ca: opts.ca, cert: opts.cert, key: opts.key, honorCipherOrder: true, }); } export function establishMtuAwareTlsSocket( host: string, port: number, secureContext: tls.SecureContext ): tls.TLSSocket { // Pre-configure TCP socket with MSS-aware buffer sizing before TLS negotiation const rawSocket = new net.Socket(); rawSocket.setKeepAlive(true, 15000); rawSocket.setNoDelay(true); // Prevent middlebox blackholing by enforcing PMTU-safe socket buffer const tlsSocket = tls.connect({ socket: rawSocket, host, port, secureContext, ecdhCurve: HYBRID_PQC_GROUPS, minVersion: 'TLSv1.3', servername: host, // Ensure TLS record size allows ML-KEM public key (1184 B) without exceeding fragment limits highWaterMark: PQC_SAFE_RECORD_SIZE_BYTES, }); tlsSocket.on('secureConnect', () => { const negotiated = tlsSocket.getEphemeralKeyInfo(); if (negotiated && !negotiated.name?.includes('MLKEM768')) { tlsSocket.destroy(new Error(`Security Violation: Negotiated non-PQC curve: ${negotiated.name}`)); } }); return tlsSocket; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Post-Quantum ML-KEM-768 Hybrid TLS 1.3 Key Encapsulation and MTU Guardrail

Post-Quantum ML-KEM-768 Hybrid TLS 1.3 Key Encapsulation and MTU Guardrail defines an industrial-grade behavioral standard for security engineering. Mandates the deployment of post-quantum hybrid key encapsulation (X25519MLKEM768) for TLS 1.3 across all internal and ingress service mesh communication to defeat Harvest-Now-Decrypt-Later (HNDL) adversaries. Enforces deterministic Path MTU (PMTU) discovery, TCP MSS clamping, and TLS record fragmentation controls to prevent silent middlebox packet drops caused by enlarged post-quantum key exchange payloads. 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: Classical-Only ECDH Deployment with Unconstrained Handshake MTU Causing HNDL Vulnerability and Packet Blackholing 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	Classical-Only ECDH Deployment with Unconstrained Handshake MTU Causing HNDL Vulnerability and Packet Blackholing	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 TLS 1.3 as the strict minimum protocol version (`minVersion

Engineers MUST ALWAYS enforce TLS 1.3 as the strict minimum protocol version (`minVersion: 'TLSv1.3'`) whenever ML-KEM-768 hybrid key exchange is configured.

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.