WireGuard

Why it exists

IPsec’s SAD/SPD and IKEv2 are a lot of moving parts for a host tunnel. WireGuard aims for a small, auditable kernel interface: one private key, a UDP port, and a list of peers. WireGuard Protocol §1 Introduction & Motivation

WireGuard is a protocol and an interface, not a managed VPN service. Key distribution, addressing, and policy remain the operator’s problem. WireGuard Protocol §1 Introduction & Motivation

One interface, one peer, one handshake

A wg0 interface holds a private key and a UDP listen port. A peer is a public key, an endpoint, and allowed IPs. The handshake is one round trip over UDP; unauthenticated packets get silence.

How it works

Cryptokey routing associates each peer’s public key with the tunnel IP prefixes that peer may source and that should be routed toward it. WireGuard Protocol §2 Cryptokey Routing

Session keys come from a one-round-trip Noise_IK handshake using Curve25519. Transport packets use ChaCha20-Poly1305 over UDP. WireGuard Protocol §Key Exchange and Data Packets

There is no cipher negotiation. One set of primitives is built in; changing them means a new protocol version — removing a large class of downgrade attacks. WireGuard Protocol §Primitives

Authenticated packets from a new source address update the peer’s endpoint (roaming). Unauthenticated packets allocate no state and receive no reply. WireGuard Protocol §DoS Mitigation

On the wire

Constructed examples, encoded from the field table below them — not captured traffic.

Configure it

When it breaks

Symptom first, because that is what you have when it happens.

1. A peer will not connect and there is nothing in the log to explain it.

   Narrow it down

   1. Check whether each side has the other’s public key exactly.
   2. Confirm the endpoint address and port on the initiating side.
   3. Check the allowed IPs on both, which is where most misconfiguration lives.

   Cause

   WireGuard does not respond to a packet it cannot authenticate. An unknown key produces silence rather than an error, which is deliberate — the interface is unresponsive to anything that cannot prove it belongs.

   Fix

   Verify the keys and the allowed IPs. The silence is the design; expecting a rejection message wastes the first hour.

   WireGuard Protocol §DoS Mitigation

2. Traffic to some destinations goes through the tunnel and others do not, with no routing configured to that effect.

   Narrow it down

   1. Read the allowed IPs for each peer.
   2. Check the routing table entries WireGuard installed from them.
   3. Look for two peers with overlapping allowed IPs.

   Cause

   Allowed IPs is two things at once: a routing table for outbound traffic and an access filter for inbound. A prefix listed against a peer routes there, and a packet arriving from that peer with a source outside the list is dropped.

   Fix

   Treat it as both. Overlapping ranges across peers make the last one configured win for routing, which is rarely what was intended.

   WireGuard Protocol §2 Cryptokey Routing

3. The tunnel works and then goes quiet after a few minutes of idleness, until traffic is sent from one particular side.

   Narrow it down

   1. Check which side is behind NAT.
   2. Look at whether persistent keepalive is configured on that side.
   3. Compare the NAT mapping timeout against the idle period.

   Cause

   WireGuard sends nothing when there is no traffic, so a NAT mapping expires and the peer behind it becomes unreachable from outside until it sends again.

   Fix

   Set persistent keepalive on the side behind NAT — twenty-five seconds is the usual value. The peer with a public address does not need it.

   WireGuard Protocol §NAT and Firewall Traversal Persistence

4. Handshake never completes through a middlebox that allows TCP VPN traffic.

   Narrow it down

   1. Confirm the UDP destination port is permitted both ways.
   2. Check whether the initiator’s source port is being rewritten unexpectedly.
   3. Capture on the responder to see whether handshake datagrams arrive at all.

   Cause

   WireGuard is UDP-only. Filters that allow TCP 443 or ESP but drop arbitrary UDP block the handshake before cryptography matters.

   Fix

   Permit the configured UDP port end to end, or move the listen port to one the path already allows — without inventing a TCP mode that does not exist.

   WireGuard Protocol §Key Exchange and Data Packets

5. A peer moved networks and never reconnects until the other side restarts.

   Narrow it down

   1. Check which side still has the old endpoint cached.
   2. Confirm whether the moved peer can initiate (it must send an authenticatable packet).
   3. Look for a sticky NAT or firewall session to the old address.

   Cause

   Endpoints update from authenticated packets. If the peer that moved cannot initiate — for example it is behind NAT without keepalive and the other side still targets the old mapping — the session stays stuck.

   Fix

   Ensure the roaming peer can initiate (keepalive if behind NAT) so the new source address is learned from authenticated traffic.

   WireGuard Protocol §2.1 Endpoints & Roaming

Design notes

Allowed IPs is both routing and inbound filtering. Overlaps across peers are configuration bugs, not load-balancing.

Silence on a wrong key is deliberate. Expecting an authentication-failure log wastes the first hour of troubleshooting.

Contrast with IPsec: no SPD in the IKE sense, no IKEv2 identities, static keys like OpenSSH authorized_keys. Mixing vocabularies is how configs get copied wrong. RFC 4301 §4Security AssociationsRFC 4301 · PROPOSED STANDARD · December 2005

Misconceptions

“WireGuard is a VPN service.”

It is a protocol and a kernel interface. Everything else — user management, address assignment, key distribution, routing policy — is the operator’s problem or a separate product’s. That minimalism is why it is small enough to audit.

“Allowed IPs is a firewall rule.”

It is a routing table and an inbound filter simultaneously. Adding a prefix to route traffic to a peer also permits that peer to source traffic from it, and the two cannot be separated. WireGuard Protocol §2 Cryptokey Routing

“WireGuard negotiates ciphers.”

It does not. One set of primitives is built in, and changing them means a new version of the protocol. Removing negotiation removes downgrade attacks and a large share of the complexity that TLS and IKE carry. WireGuard Protocol §Primitives

More walkthroughs

Terms

Allowed IPs

In WireGuard, the prefixes associated with a peer’s public key. They install outbound routes toward that peer and filter which inner source addresses are accepted from it — one setting, two jobs.

Cryptokey routing

WireGuard’s peer table: a public key maps to allowed tunnel IPs and an optional underlay endpoint. There is no separate IPsec-style SPD.

Check yourself

• A peer with a wrong public key tries to connect. What happens?

  • An authentication failure is logged
  • Nothing — the interface does not respond to what it cannot authenticate
  • The connection is refused
  • It falls back to a shared key
• What does allowed IPs control?

  • Outbound routing only
  • Both outbound routing to that peer and which source addresses are accepted from it
  • Inbound filtering only
  • The tunnel MTU
• Why does a peer behind NAT need persistent keepalive?

  • To detect failure faster
  • WireGuard sends nothing when idle, so the NAT mapping expires and the peer becomes unreachable
  • To renegotiate keys
  • To keep the route installed
• How does WireGuard negotiate its ciphers?

  • Like TLS, from a list
  • It does not — one set is built in, and changing it means a new protocol version
  • The server chooses
  • Per peer, in the config
• What does installing WireGuard give you out of the box?

  • User accounts and a portal
  • A tunnel interface and a peer table — keys, addressing, and policy are still yours
  • Automatic certificate enrolment
  • An SPD like IPsec
• What transport carries WireGuard on the underlay?

  • TCP
  • UDP
  • ESP without UDP
  • SCTP
• How does a peer’s endpoint update after it changes networks?

  • IKEv2 MOBIKE
  • From the source address of authenticated packets
  • DNS only
  • It cannot — the peer must be reconfigured
• Which IPsec concept does WireGuard deliberately not expose?

  • Peer authentication
  • An SPD/IKE identity store with negotiated transforms
  • Tunnel IP addresses
  • A UDP underlay

Related

• IPsec

  ESP (or AH) protects packets under SAs negotiated by IKEv2; the SPD decides what enters, the SAD holds the keys.

• DMVPN

  mGRE plus NHRP plus (usually) IPsec: spokes register with a hub, and Phase 3 builds on-demand spoke-to-spoke shortcuts from NHRP redirect and shortcut switching.