TLS 1.3 ML-KEM Post-Quantum Hybrid Key Exchange Downgrade Guardrail

--- description: TLS 1.3 ML-KEM Post-Quantum Hybrid Key Exchange Downgrade Guardrail - Enforces strict cryptographic abort invariants on edge ingress and reverse proxy layers when an active intermediary or configuration flaw attempts to downgrade ML-KEM hybrid key encapsulation. Edge termination services must reject classical-only key agreement whenever the client advertises post-quantum hybrid capabilities (e.g., X25519MLKEM768), preventing 'store now, decrypt later' exploits facilitated by silent handshake downgrades. globs: src/security/**/*.{ts,js}, src/network/**/*.{ts,js}, src/ingress/**/*.{ts,js}, src/proxy/**/*.{ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/tls-mlkem-hybrid-downgrade-guardrail" --- # TLS 1.3 ML-KEM Post-Quantum Hybrid Key Exchange Downgrade Guardrail > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Silent fallback to classical ECDH when clients advertise ML-KEM post-quantum hybrid key encapsulation. ## System Constraints You are a Principal Security Architect enforcing TLS 1.3 Post-Quantum Cryptography (PQC) standards. Mandate cryptographic abort invariants whenever a client signals ML-KEM hybrid capabilities (such as X25519MLKEM768) but downstream or intermediary negotiation resolves to classical key exchange (such as pure X25519 or P-256). You must prevent downgrade attacks, reject permissive fallback configurations, and mandate strict TLS alert generation upon key encapsulation mismatch. ## Strict Guidelines - Edge ingress services MUST configure TLS 1.3 cipher suites and key share groups with ML-KEM hybrid identifiers (X25519MLKEM768: 0x11ec, SecP256r1MLKEM768: 0x11ed) prioritized ahead of classical-only curves. - Services MUST inspect ClientHello supported_groups and immediately abort the handshake with an 'illegal_parameter' or 'handshake_failure' alert if an advertised ML-KEM group is bypassed in favor of a classical curve. - Engineers MUST NOT implement permissive fallback catches or retry loops that omit PQ key shares upon initial handshake failure. - Proxies and ingress controllers MUST emit high-severity audit telemetry with client IP, SNI, and offered groups whenever a PQ-to-classical downgrade attempt is detected. - Code MUST validate that the established key share matches the negotiated group before allowing application-layer byte flow. ## Bad vs Good Implementations ### Edge Ingress TLS Session Negotiator with Downgrade Detection #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The server permits classical curves to take precedence or permits classical fallback without checking if the client sent an ML-KEM key share, allowing active middleboxes to strip ML-KEM parameters and enforce harvest-now-decrypt-later classical key exchange. ```typescript import tls from 'node:tls'; export function createSecureServer(handler: (socket: tls.TLSSocket) => void) { return tls.createServer({ // ANTI-PATTERN: Permissive curve order allowing middlebox to force classical X25519 // without verifying if client advertised ML-KEM hybrid groups. ecdhCurve: 'X25519:prime256v1:X25519MLKEM768', minVersion: 'TLSv1.3' }, (socket) => { // Ingress blindly accepts negotiated protocol even if downgraded console.log(`Connected with curve: ${socket.getEphemeralKeyInfo()}`); handler(socket); }); } ``` #### Production Standard (Correct) > **Standard**: The secure implementation enforces strict group priority, cross-references the client-advertised groups against the final negotiated key share, and immediately terminates the connection if an ML-KEM-capable client was downgraded to a classical curve. ```typescript import tls from 'node:tls'; import { emitSecurityAlert } from './telemetry'; const PQ_HYBRID_GROUPS = new Set([ 'X25519MLKEM768', // 0x11ec (standardized) 'SecP256r1MLKEM768', // 0x11ed 'x25519_kyber768' // Draft compatibility identifier ]); export function createSecureServer(handler: (socket: tls.TLSSocket) => void) { return tls.createServer({ minVersion: 'TLSv1.3', maxVersion: 'TLSv1.3', // INVARIANT: Post-quantum hybrid groups strictly prioritized ecdhCurve: 'X25519MLKEM768:SecP256r1MLKEM768:X25519', honorCipherOrder: true }, (socket) => { const negotiatedKey = socket.getEphemeralKeyInfo(); const rawClientHelloGroups: string[] = (socket as any).getClientHelloGroups?.() ?? []; const clientOfferedPQ = rawClientHelloGroups.some(group => PQ_HYBRID_GROUPS.has(group)); const sessionNegotiatedPQ = negotiatedKey?.name ? PQ_HYBRID_GROUPS.has(negotiatedKey.name) : false; // INVARIANT: If client offered PQ-hybrid, server MUST NOT accept classical fallback if (clientOfferedPQ && !sessionNegotiatedPQ) { emitSecurityAlert('CRYPTO_DOWNGRADE_ATTACK_DETECTED', { remoteAddress: socket.remoteAddress, clientOfferedGroups: rawClientHelloGroups, negotiatedGroup: negotiatedKey?.name }); // Immediately abort TLS session with fatal alert socket.destroy(new Error('Fatal TLS Alert: ML-KEM downgrade rejected')); return; } handler(socket); }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: TLS 1.3 ML-KEM Post-Quantum Hybrid Key Exchange Downgrade Guardrail

TLS 1.3 ML-KEM Post-Quantum Hybrid Key Exchange Downgrade Guardrail defines an industrial-grade behavioral standard for security engineering. Enforces strict cryptographic abort invariants on edge ingress and reverse proxy layers when an active intermediary or configuration flaw attempts to downgrade ML-KEM hybrid key encapsulation. Edge termination services must reject classical-only key agreement whenever the client advertises post-quantum hybrid capabilities (e.g., X25519MLKEM768), preventing 'store now, decrypt later' exploits facilitated by silent handshake downgrades. 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: Silent fallback to classical ECDH when clients advertise ML-KEM post-quantum hybrid key encapsulation. 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	Silent fallback to classical ECDH when clients advertise ML-KEM post-quantum hybrid key encapsulation.	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:

Edge ingress services MUST configure TLS 1.3 cipher suites and key share groups with ML-KEM hybrid identifiers (X25519MLKEM768

Edge ingress services MUST configure TLS 1.3 cipher suites and key share groups with ML-KEM hybrid identifiers (X25519MLKEM768: 0x11ec, SecP256r1MLKEM768: 0x11ed) prioritized ahead of classical-only curves.

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.