WireGuard® Key Rotation Procedure Checklist

Overview

This is a practical checklist for safely rotating WireGuard® cryptographic keys (private/public keypairs) to maintain security — e.g., as part of routine maintenance, compliance, suspected compromise, or offboarding. Verify all commands in your environment before production use.

For Defguard-specific procedures, see docs.defguard.net.

Important notes:

• Always test commands in your specific environment first.
• For Defguard-managed setups, use the web UI where possible (simpler and centralized) — see docs.defguard.net for exact steps.

Core principle:

Rotate keys without causing prolonged outages, and always have a rollback path.

---

Pre-Rotation Checklist

• Identify rotation scope: Single device, user offboarding, or full rotation
• Verify backup access: Confirm out-of-band access to all endpoints (console, IPMI, local admin)
• Document current state: Export current peer configurations
• Schedule maintenance window: Notify affected users if production environment
• Prepare rollback: Keep old private keys accessible for 24-48 hours post-rotation

---

Key Generation (Per Device)

# Generate new keypair
wg genkey | tee privatekey | wg pubkey > publickey

# Verify key format (base64, 44 characters)
cat publickey | wc -c  # Expected: 45 (44 + newline)

# Set restrictive permissions
chmod 600 privatekey

Security Notes:

• Generate keys on the device that will use them (never transfer private keys over the network).
• Never reuse the same keypair on multiple devices.
• Never commit private keys to git, backups, or any version control.

---

Server-Side Update (Updating the Gateway)

Important: Due to WireGuard®‘s Cryptokey Routing, avoid configuring the same AllowedIPs for multiple peers simultaneously. Order is critical to avoid breaking connectivity:

1. Generate new keys on client first
2. Update client configuration with new private key
3. Restart client to establish connection with new public key
4. Add new peer on server:

wg set wg0 peer <NEW_PUBLIC_KEY> allowed-ips <CLIENT_IP>/32

5. Verify new connection (wait for handshake):

# Check for recent handshake (should be < 2 minutes)
wg show wg0 latest-handshakes

6. Once confirmed working, remove the old peer:

wg set wg0 peer <OLD_PUBLIC_KEY> remove

Note on old session persistence: WireGuard® has no instant “kill switch” for existing sessions. Remember the following after removing a peer:

• Existing sessions continue until the next rekey attempt fails or the session expires.
• Rekey is attempted ~every 2 minutes (REKEY_AFTER_TIME ≈ 120 seconds) if traffic is flowing.
• Sessions are hard-rejected after ~3 minutes of no activity (REJECT_AFTER_TIME ≈ 180 seconds).
• Maximum persistence of an old session is typically 3–5 minutes, depending on traffic, keepalive settings (default 10s), and whether the peer is actively sending/receiving data. In practice, most old tunnels become unusable within 180–300 seconds after removal.

Key reminder: Thanks to WireGuard®’s “Cryptokey Routing,” never have two peers with overlapping AllowedIPs at the same time — it causes unpredictable routing.

---

Client-Side Update

1. Update configuration file:

[Interface]
PrivateKey = <NEW_PRIVATE_KEY>
# Keep all other settings unchanged

2. Restart WireGuard® interface:

Linux:bash wg-quick down wg0 && wg-quick up wg0

macOS/Windows (Defguard client): Use the Defguard desktop app to refresh/pull new config

3. Verify connectivity:

# Check handshake timestamp
wg show wg0 latest-handshakes

# Test connectivity
ping -c 3 <GATEWAY_IP>

---

Defguard-Managed Rotation

When using Defguard, key rotation is simplified through the web interface:

• Log into Defguard admin panel → Device management section.
• Regenerate keys or enrollment tokens for the target device(s).
• Clients automatically receive and apply the new configuration (via Defguard sync).
• Monitor device status in the UI for successful reconnection/handshake.

Benefit: Centralized, no manual copy-paste of keys, automatic across multiple locations.

Verify in docs.defguard.net: Current procedures for device key management and rotation

---

Post-Rotation Verification

• Handshake confirmed: wg show shows recent handshake (within last 3–5 minutes)
• Traffic flowing: Ping test to internal resources succeeds
• Audit log updated: Rotation event logged (Defguard: check audit trail)
• Old keys destroyed: Securely delete old private key files
• Documentation updated: Record rotation date and reason

---

Rollback Procedure

If rotation fails:

1. Client side: Restore previous private key in config
2. Server side: Re-add old public key as peer

# Server-side rollback
wg set wg0 peer <OLD_PUBLIC_KEY> allowed-ips <CLIENT_IP>/32

3. Restart interfaces: Both client and server
4. Investigate: Check logs for handshake failures

# Check for errors
dmesg | grep wireguard
journalctl -u wg-quick@wg0 --since "10 minutes ago"

---

Rotation Schedule Recommendations

Scenario	Frequency	Trigger
Normal operations	3–12 months or per policy	Scheduled / Compliance-driven
Suspected compromise	Immediate	Incident response
Employee offboarding	Immediate	HR event
Device loss/theft	Immediate	User report
Compliance requirement	Per policy	Audit cycle

---

Common Failure Modes

Symptom	Likely Cause	Resolution
No handshake after rotation	Wrong public key on server	Verify key matches
Handshake but no traffic	AllowedIPs mismatch	Check IP assignments
Intermittent connectivity	MTU issues (unrelated to rotation)	Check MTU settings
“Invalid key” error	Key format corruption	Regenerate keypair

---

Audit Trail Requirements

For compliance, log the following:

• Timestamp of rotation
• Device/user identifier
• Operator who performed rotation
• Reason for rotation (scheduled, incident, offboarding)
• Verification method used

Defguard users: Audit trail is automatic. Export via Settings → Audit Logs.

Core takeaway:

WireGuard® key rotation is straightforward but requires careful sequencing:

generate → update client → add new peer on server → verify → remove old peer.

Defguard dramatically simplifies this with centralized UI-based rotation and automatic client sync. Always prepare rollback, verify at every step, and document for compliance. Test in non-production first, and never expose private keys.