Cilium eBPF WireGuard Dual-Slot Atomic Key Rotation and Epoch Fencing

--- description: Cilium eBPF WireGuard Dual-Slot Atomic Key Rotation and Epoch Fencing - Enforces generational epoch fencing and dual-slot staging for WireGuard tunnel cryptographic keys within Cilium eBPF maps. Prohibits in-place mutation of active peer session keys, which causes transient decapsulation failures and drops inflight TCP packets. Mandates an atomic generation pointer swap followed by an RCU-aligned conntrack drain period before purging deprecated keys. globs: plugins/cilium/**/*.ts, controllers/wireguard/**/*.ts, src/network/ebpf/**/*.ts, infrastructure/k8s/cilium/**/*.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/cilium-ebpf-wireguard-atomic-key-rotation-fence" --- # Cilium eBPF WireGuard Dual-Slot Atomic Key Rotation and Epoch Fencing > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: In-Place WireGuard BPF Map Key Overwrite Inducing TCP Stream Resets During Rotation ## System Constraints You are a Principal Systems and Kernel Networking Engineer enforcing zero-downtime crypto-agility rules for Cilium eBPF WireGuard datapath controllers. All operations mutating WireGuard session keys across eBPF maps MUST use dual-slot epoch fencing with synchronized grace-period drains. Never permit in-place key updates or zero-delay key evictions that truncate active TCP flows. ## Strict Guidelines - Engineers MUST ALWAYS stage new WireGuard key pairs into the inactive epoch slot of the BPF map prior to promoting it to the active datapath. - Engineers MUST ALWAYS execute an atomic 64-bit generation/epoch pointer swap to flip active key indices in the global eBPF config map. - Engineers MUST NOT overwrite the currently active key slot in-place within BPF_MAP_TYPE_HASH or BPF_MAP_TYPE_ARRAY structures. - Services MUST enforce an asynchronous conntrack drain interval (minimum 2x maximum round-trip time) before zeroizing or freeing deprecated key slots. - Components NEVER immediately unbind or zeroize the retired session key while inflight packets may still be queued in socket buffers or NIC ring buffers. ## Bad vs Good Implementations ### WireGuard eBPF Session Key Rotation Controller #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Directly overwriting the active key in the BPF map without staging causes instant decapsulation failure for in-flight packets, triggering TCP connection drops and breaking zero-downtime SLAs. ```typescript import { BpfMapClient } from '@cilium/ebpf-client'; interface KeyUpdatePayload { peerNodeId: number; newPrivateKey: Uint8Array; newPublicKey: Uint8Array; } export async function rotatePeerKeyInPlace( bpfClient: BpfMapClient, payload: KeyUpdatePayload ): Promise<void> { const WG_PEER_MAP_FD = 12; // ANTI-PATTERN: Direct in-place mutation of the active key slot. // Packets currently in-flight across the cluster encrypted with the old key // will immediately fail AEAD/ChaCha20-Poly1305 verification in the eBPF datapath, // causing immediate drops and TCP resets (RST storms). await bpfClient.updateElement(WG_PEER_MAP_FD, { key: payload.peerNodeId, value: { privKey: payload.newPrivateKey, pubKey: payload.newPublicKey, }, }); } ``` #### Production Standard (Correct) > **Standard**: Implements dual-slot generational staging (Slot A/B) and performs an atomic generation pointer update in eBPF config. Defers wiping deprecated keys by a 500ms grace window, preventing dropped inflight TCP packets. ```typescript import { BpfMapClient } from '@cilium/ebpf-client'; interface KeyRotationPayload { peerNodeId: number; newPrivateKey: Uint8Array; newPublicKey: Uint8Array; } const WG_SLOT_A = 0; const WG_SLOT_B = 1; const WG_KEYS_MAP_FD = 12; const WG_CONFIG_MAP_FD = 13; const RCU_DRAIN_GRACE_PERIOD_MS = 500; export async function rotatePeerKeyWithEpochFence( bpfClient: BpfMapClient, payload: KeyRotationPayload ): Promise<void> { // 1. Read current active generation and identify standby slot const currentConfig = await bpfClient.lookupElement(WG_CONFIG_MAP_FD, payload.peerNodeId); const currentSlot = currentConfig.activeSlot; const nextSlot = currentSlot === WG_SLOT_A ? WG_SLOT_B : WG_SLOT_A; const nextEpoch = currentConfig.epoch + 1n; // 2. Stage the new key into the inactive standby slot without touching datapath await bpfClient.updateElement(WG_KEYS_MAP_FD, { key: { peerNodeId: payload.peerNodeId, slotId: nextSlot }, value: { privKey: payload.newPrivateKey, pubKey: payload.newPublicKey, epoch: nextEpoch, }, }); // 3. Atomically fence the datapath to nextSlot via BPF_EXIST flag await bpfClient.updateElement( WG_CONFIG_MAP_FD, { key: payload.peerNodeId, value: { activeSlot: nextSlot, epoch: nextEpoch, }, }, { flags: 'BPF_EXIST' } ); // 4. Drain window: Allow in-flight packets using the deprecated slot to finish setTimeout(async () => { await bpfClient.updateElement(WG_KEYS_MAP_FD, { key: { peerNodeId: payload.peerNodeId, slotId: currentSlot }, value: { privKey: new Uint8Array(32).fill(0), pubKey: new Uint8Array(32).fill(0), epoch: 0n, }, }); }, RCU_DRAIN_GRACE_PERIOD_MS); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Cilium eBPF WireGuard Dual-Slot Atomic Key Rotation and Epoch Fencing

Cilium eBPF WireGuard Dual-Slot Atomic Key Rotation and Epoch Fencing defines an industrial-grade behavioral standard for devops engineering. Enforces generational epoch fencing and dual-slot staging for WireGuard tunnel cryptographic keys within Cilium eBPF maps. Prohibits in-place mutation of active peer session keys, which causes transient decapsulation failures and drops inflight TCP packets. Mandates an atomic generation pointer swap followed by an RCU-aligned conntrack drain period before purging deprecated keys. 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: In-Place WireGuard BPF Map Key Overwrite Inducing TCP Stream Resets During Rotation 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	In-Place WireGuard BPF Map Key Overwrite Inducing TCP Stream Resets During Rotation	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 stage new WireGuard key pairs into the inactive epoch slot of the BPF map prior to promoting it to the active datapath.

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.