WireGuard

What It Is

WireGuard is a modern VPN protocol and implementation built into the Linux kernel (since 5.6). It creates encrypted tunnels between machines using public-key cryptography. The entire codebase is ~4,000 lines of kernel code -- deliberately minimal to be auditable.

WireGuard's core insight: your public key is your identity. No certificates, no usernames, no complex PKI. You generate a keypair, share the public key with peers, and WireGuard handles encryption, authentication, and key rotation.

Why It Matters

VPNs have traditionally been complex (OpenVPN config files, IPSec phase negotiations, certificate management). WireGuard reduces this to: a keypair, a list of peers (by public key), and an endpoint (IP:port). That's it.

For cluster networking, WireGuard provides:

Encryption: All traffic between nodes is encrypted
Authentication: Each packet is authenticated (peers verified by public key)
Performance: Kernel-native, near wire speed
Simplicity: Easy to configure, easy to debug

How It Works

Cryptokey Routing

WireGuard's routing model is unique: each peer is associated with a set of allowed IPs. When a packet is sent to a destination IP, WireGuard looks up which peer "owns" that IP and encrypts the packet for that peer's public key.

# Node A's WireGuard config
[Interface]
PrivateKey = <node A private key>
Address = fd00::1/128

[Peer]
PublicKey = <node B public key>
AllowedIPs = fd00::2/128
Endpoint = 203.0.113.50:51820

[Peer]
PublicKey = <node C public key>
AllowedIPs = fd00::3/128
Endpoint = 198.51.100.10:51820

When Node A sends a packet to fd00::2, WireGuard encrypts it with Node B's public key and sends it to Node B's endpoint. This mapping (IP -> public key -> endpoint) is called cryptokey routing.

The Protocol

WireGuard uses:

Noise Protocol Framework (Noise_IKpsk2) for key exchange
ChaCha20-Poly1305 for symmetric encryption
BLAKE2s for hashing
Curve25519 for key agreement

All fixed choices -- no cipher negotiation, no version downgrade attacks. WireGuard either uses these exact algorithms or doesn't connect.

Key Rotation

WireGuard automatically performs a key handshake every 2 minutes (or on first packet after silence). Session keys are ephemeral -- compromising one session key doesn't reveal past or future traffic (perfect forward secrecy).

NAT Traversal

WireGuard uses UDP, which works through most NATs. The PersistentKeepalive option sends a keepalive packet every N seconds to keep NAT mappings alive. For nodes behind restrictive NATs (symmetric NAT), a relay or STUN-like mechanism is needed (WireGuard itself doesn't provide this).

Roaming

If a peer's physical IP changes (laptop moves from Wi-Fi to cellular), WireGuard automatically updates the endpoint when it receives an authenticated packet from the new address. No reconfiguration needed.

How FortrOS Uses It

Overlay network: All inter-node communication travels over WireGuard tunnels. The overlay uses IPv6 ULA (fd00::/8) addressing with a per-org random /48 prefix.

Identity: The WireGuard public key IS the node's overlay identity. The overlay address is derived from the key hash. The keypair is generated during enrollment and stored on /persist.

Mesh management: The maintainer adds/removes WireGuard peers based on org CRDT membership state. When a new node joins (via gossip), existing nodes add it as a WireGuard peer. When a node is revoked, its peer entry is removed.

Persistent keepalive: All peers use PersistentKeepalive = 25 to maintain NAT mappings. This is especially important for nodes behind home routers.

conn_auth on top: WireGuard encrypts the transport. FortrOS adds a raw-Ed25519 challenge-response handshake (the conn_auth module in fortros-net) on top for service-level authentication. WireGuard proves "this packet came from a WireGuard peer." conn_auth proves "this connection is from a pubkey that's in the org's CRDT member list right now."

Constrained Environments

WireGuard is UDP-only with a recognizable handshake pattern. This works on most networks but fails in specific constrained environments:

Environment	Problem	Mitigation
Symmetric NAT	WireGuard UDP can't punch through (both sides behind strict NAT, no predictable port mapping)	Route through a lighthouse with a public IP. The lighthouse relays traffic between the two NATted nodes.
UDP-blocking firewall	Corporate or hotel firewalls that only allow TCP 80/443	TCP wrapping: tunnel WireGuard UDP inside a TCP connection (wstunnel, udp2raw). Adds overhead but gets through.
Deep packet inspection (DPI)	Firewalls that detect VPN protocols by their handshake pattern and block them	Obfuscation: wrap WireGuard in a protocol that looks like HTTPS (shadowsocks, obfs4). The DPI sees normal-looking HTTPS, not a VPN handshake.
VPN-blocking countries	State-level censorship (China's GFW, Russia, Iran) that actively detects and blocks VPN traffic	Domain fronting via CDNs, or Tor as a transport layer. These are harder to block because blocking them means blocking major cloud providers or Tor's entire network.
HTTPS-only networks	Airport Wi-Fi, captive portals that only pass HTTP/HTTPS after authentication	WebSocket tunnel (wstunnel over WSS on port 443). Looks like a normal HTTPS connection to the captive portal.

FortrOS handles these through its lighthouse infrastructure:

Default: Direct WireGuard UDP between peers. Works on most networks.
NAT fallback: Traffic routes through lighthouses (public IP, always reachable). The mesh topology scoring from 07 Overlay Networking naturally routes through lighthouses when direct connections fail.
TCP/obfuscation: For nodes in heavily restricted environments, the maintainer can configure a transport wrapper (WireGuard UDP inside a TCP or HTTPS tunnel to a lighthouse). This is per-node configuration based on what the network allows.
Tor: As a last-resort transport for nodes in hostile network environments. High latency but gets through nearly any censorship system. Pluggable transports (obfs4, snowflake) provide censorship circumvention without full Tor overhead.

The principle: WireGuard handles the crypto and identity. The transport underneath WireGuard adapts to whatever the network allows. On an open network, it's raw UDP. On a restricted network, it's UDP-inside-TCP or UDP-inside-HTTPS. The WireGuard layer doesn't know or care -- it sees the same peer-to-peer encrypted tunnel regardless.

Alternatives

OpenVPN: Mature, widely deployed, runs in userspace. Supports TCP (works through HTTP proxies) and complex PKI. Much larger codebase (~100,000 lines) and slower (userspace processing). Better for environments that require TCP tunneling.

IPSec: The traditional standard for site-to-site VPNs. Kernel-native (like WireGuard) but enormously complex (~400,000 lines). Supports many cipher suites (more attack surface). Used in enterprise network equipment.

Tailscale/Headscale: Built on WireGuard but adds a coordination layer for automatic mesh configuration, NAT traversal (DERP relay servers), and MagicDNS. Tailscale is a managed service; Headscale is the self-hosted alternative. FortrOS handles coordination itself via gossip rather than depending on an external service.

Nebula: Overlay network by Slack with certificate-based identity and lighthouse-based peer discovery. Runs in userspace. More infrastructure to self-host than raw WireGuard.