Encryption

Active contributors: brb, MrFreezeex, julianwiedmann, jrfastab

Purpose

Cilium can transparently encrypt all node-to-node pod traffic. Two backends ship today:

• WireGuard — the recommended default. Each node runs a WireGuard interface managed by Cilium; the kernel handles encryption.
• IPSec — historical option. Encrypts using xfrm with keys distributed through Kubernetes Secrets.

Encryption applies to traffic between Cilium-managed nodes; endpoints inside the same node are not encrypted (no need — they share a kernel).

WireGuard

pkg/wireguard/
├── agent/                   # cell that programs the WG interface
├── types/                   # shared types
└── ...
bpf/bpf_wireguard.c          # tail call helpers for WG offload

Mechanics:

1. The agent generates (or reads) a WireGuard private key and stores the public key in CiliumNode.spec.encryption.publicKey.
2. Every agent watches CiliumNode resources, learns the public keys of all peer nodes, and programs WireGuard peers via netlink.
3. The dataplane redirects pod-to-pod traffic into the cilium_wg0 interface for nodes that should be encrypted; the kernel encrypts and decapsulates transparently.
4. bpf_wireguard.c provides BPF helpers for re-injecting decrypted traffic back into the per-pod path with the correct identity.

User configuration:

encryption:
  enabled: true
  type: wireguard
  nodeEncryption: false # node-to-node; or true for full encryption

IPSec

pkg/datapath/linux/ipsec/ configures Linux xfrm policies and SAs. Keys are loaded from a Kubernetes Secret (cilium-ipsec-keys), keyed by SPI, and rotated by recreating the Secret. The dataplane uses the same encapsulation paths but routes packets through xfrm before transmission.

IPSec is typically harder to operate than WireGuard (key rotation, MTU, NAT-traversal nuances). New deployments are encouraged to use WireGuard.

Integration points

• CiliumNode CRD: carries the per-node WireGuard public key.
• MTU: pkg/mtu/ accounts for encryption overhead (~80 bytes for WireGuard, varies for IPSec).
• Cluster Mesh: node-to-node encryption applies across cluster boundaries — peer nodes from other clusters need their public keys exported.
• Health: the cilium-health connectivity probe runs over the encrypted path so a broken key shows up immediately.

Limitations and corner cases

• Host networking traffic is encrypted only with nodeEncryption: true.
• Hubble flow events are still emitted on the source node; downstream packet captures see only encrypted bytes.
• IPSec and WireGuard are mutually exclusive; switching is not seamless.
• Some advanced features (BPF host firewall, certain XDP modes) require careful interaction with encryption hooks.

Key source files

File	Purpose
pkg/wireguard/agent/agent.go	WireGuard cell.
pkg/datapath/linux/ipsec/ipsec.go	IPSec config.
bpf/bpf_wireguard.c	WG-related BPF code.
pkg/mtu/mtu.go	MTU calculation.
cilium-cli/encrypt/	cilium encrypt status CLI.