Wireguard

---
name: wireguard
description: "Expert coverage of WireGuard VPN: Noise protocol framework, Cryptokey Routing, wg-quick configuration, AllowedIPs routing, PSK post-quantum protection, kernel vs userspace implementations, deployment patterns (hub-spoke, site-to-site, mesh), Tailscale/Headscale/Netmaker orchestration, and container networking. Use for \"WireGuard\", \"wg-quick\", \"AllowedIPs\", \"Cryptokey Routing\", \"wg genkey\", \"Tailscale\", \"Headscale\", \"Netmaker\", \"wireguard-go\", \"PersistentKeepalive\". Do NOT use for cross-vendor comparison, platform selection, or category-wide architecture -- use the `vpn` skill."
license: MIT
---

# WireGuard

This skill covers WireGuard VPN. Areas of expertise include:

- Noise Protocol Framework (Noise_IKpsk2_25519_ChaChaPoly_BLAKE2s)
- Cryptokey Routing (public key -> AllowedIPs mapping)
- Fixed cryptography (Curve25519, ChaCha20-Poly1305, BLAKE2s, HKDF)
- wg-quick configuration and systemd integration
- AllowedIPs routing logic (outbound: routing table; inbound: source filter)
- PSK for post-quantum protection
- Kernel module (Linux 5.6+) vs userspace implementations (wireguard-go, BoringTun)
- Deployment patterns: point-to-point, hub-spoke, site-to-site, mesh
- Management platforms: Tailscale, Headscale, Netmaker, Firezone, NetBird
- Container networking (Calico, Flannel WireGuard backends)
- MTU calculation and optimization

## How to Approach Tasks

1. **Classify**: Configuration, troubleshooting, architecture, or management platform selection
2. **Identify deployment pattern**: Point-to-point, hub-spoke, site-to-site, or mesh
3. **Load context** from `references/architecture.md` for protocol and crypto details
4. **Analyze** with WireGuard-specific understanding (stateless design, no negotiation)
5. **Recommend** with concrete config examples and operational guidance

## Core Concepts

### Cryptokey Routing
WireGuard's routing table maps public keys to allowed IP ranges. No cipher negotiation -- algorithms are fixed and hardcoded, eliminating downgrade attacks.

```
Interface: wg0 (private key: <interface_privkey>)
  Peer: <pubkey_A> -> AllowedIPs: 10.0.0.2/32
  Peer: <pubkey_B> -> AllowedIPs: 10.0.0.3/32, 192.168.10.0/24
```

### AllowedIPs Dual Purpose
1. **Outbound**: Routing table -- determines which peer to encrypt for
2. **Inbound**: Source IP filter -- only accept packets from peer if source IP matches AllowedIPs

```
AllowedIPs = 0.0.0.0/0        # Full tunnel (all traffic via VPN)
AllowedIPs = 10.0.0.0/8       # Split tunnel (only RFC 1918)
AllowedIPs = 10.0.0.2/32      # Minimal (peer's VPN IP only)
```

### Fixed Cryptography
No negotiation. All primitives are hardcoded:
- **Key exchange**: Curve25519 (X25519 ECDH)
- **Encryption**: ChaCha20-Poly1305 (AEAD)
- **Hashing**: BLAKE2s
- **KDF**: HKDF
- **Session key rotation**: Every 180 seconds automatically (forward secrecy)

## Configuration

### Key Generation
```bash
wg genkey > private.key
wg pubkey < private.key > public.key
wg genpsk > preshared.key              # PSK for post-quantum protection
```

### Server Configuration (`/etc/wireguard/wg0.conf`)
```ini
[Interface]
Address = 10.0.0.1/24
ListenPort = 51820
PrivateKey = <server_private>
MTU = 1420

PostUp = iptables -A FORWARD -i %i -j ACCEPT; iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE
PostDown = iptables -D FORWARD -i %i -j ACCEPT; iptables -t nat -D POSTROUTING -o eth0 -j MASQUERADE

[Peer]
PublicKey = <client_public>
PresharedKey = <psk>
AllowedIPs = 10.0.0.2/32
```

### Client Configuration
```ini
[Interface]
Address = 10.0.0.2/32
PrivateKey = <client_private>
DNS = 10.0.0.1, 8.8.8.8
MTU = 1420

[Peer]
PublicKey = <server_public>
PresharedKey = <psk>
Endpoint = vpn.example.com:51820
AllowedIPs = 0.0.0.0/0, ::/0          # Full tunnel
PersistentKeepalive = 25               # Required behind NAT
```

### MTU Calculation
WireGuard overhead: ~60 bytes (20 IP + 8 UDP + 32 WG header + 16 Poly1305 tag)
```
Standard Ethernet: 1500 - 60 = 1420 (recommended default)
PPPoE (1492): 1492 - 60 = 1432
Safe for IPv6: 1280
```

## Operations

```bash
wg-quick up wg0                    # Bring up from /etc/wireguard/wg0.conf
wg-quick down wg0                  # Tear down
wg show                            # All interfaces: peers, endpoints, traffic
wg show wg0 transfer               # RX/TX bytes per peer
wg show wg0 latest-handshakes      # Last handshake per peer
wg set wg0 peer <pubkey> endpoint <ip>:<port>  # Update peer endpoint
wg set wg0 peer <pubkey> remove    # Remove peer
wg syncconf wg0 <(wg-quick strip wg0)  # Reload config without restart
systemctl enable wg-quick@wg0      # Enable at boot
```

## Deployment Patterns

### Hub-and-Spoke (Remote Access)
Hub has one [Peer] block per client. Hub requires `net.ipv4.ip_forward = 1`. Spoke-to-spoke traffic routes through hub.

### Site-to-Site
Both gateways have AllowedIPs including the remote LAN subnet. Both need Endpoint set. Add static routes or run OSPF/BGP over WireGuard interface.

### Mesh (via Orchestration)
Direct peer-to-peer using Tailscale, Headscale, Netmaker, or NetBird. These handle key distribution, NAT traversal, and peer discovery automatically.

## Management Platforms

| Platform | Key Feature | License |
|---|---|---|
| **Tailscale** | Managed mesh VPN; MagicDNS; ACL policies; DERP relay | Proprietary (free tier) |
| **Headscale** | Self-hosted Tailscale-compatible coordination server | Open source |
| **Netmaker** | Kernel-space WireGuard mesh; REST API; ~8 Gbps | Open source |
| **Firezone** | Web UI; SSO (OIDC/SAML); per-user policies | Open source |
| **NetBird** | Zero-config mesh; STUN/TURN NAT traversal; SSO | Open source |

## PSK for Post-Quantum Protection
```ini
PresharedKey = <wg genpsk output>
```
Adds 256-bit symmetric key into handshake derivation. Even if Curve25519 is broken by quantum computers, the attacker still needs the PSK. Recommended for sensitive deployments now as a quantum hedge.

## Common Pitfalls

1. **AllowedIPs overlap**: Two peers cannot have overlapping AllowedIPs -- WireGuard cannot route to both. Ensure each peer has unique IP ranges.
2. **Forgetting PersistentKeepalive**: Behind NAT, without keepalive, the NAT mapping expires and the peer becomes unreachable. Set to 25 seconds.
3. **Full tunnel DNS leak**: With AllowedIPs = 0.0.0.0/0, DNS must also route through VPN. Set DNS in [Interface] section.
4. **MTU issues**: Symptoms: connections stall after handshake, large transfers fail. Set MTU to 1420 (or lower for PPPoE/double-encapsulation).
5. **No built-in logging**: WireGuard is intentionally silent. Monitor at the OS level (iptables LOG, tcpdump).
6. **Key distribution at scale**: Without orchestration, manual key exchange becomes unmanageable beyond ~20 peers. Use Tailscale, Netmaker, or config management.
7. **UDP blocking**: Some networks block UDP. WireGuard has no TCP fallback. Use udp2raw or wstunnel for TCP tunneling, or Tailscale DERP relay.

## Limitations

| Limitation | Workaround |
|---|---|
| UDP only | udp2raw, wstunnel, Tailscale DERP |
| No user authentication | Firezone, wg-access-server, Tailscale (SSO layer) |
| No key distribution | Tailscale/Headscale, Netmaker, Ansible/Terraform |
| No dynamic IP support | PersistentKeepalive + `wg set` scripts; Tailscale |
| No access control | Firewall rules; per-user subnets; orchestration platforms |
| Blockable (UDP signature) | wstunnel (WebSocket), domain fronting |

## Reference Files

- `references/architecture.md` -- Noise protocol, cryptographic primitives, handshake flow, DoS protection, key timers, performance benchmarks, container deployment.