wireguard-go — Overview#

Identity#

  • Module path: golang.zx2c4.com/wireguard
  • Go version: 1.23.1
  • License: MIT (Copyright 2017–2025 WireGuard LLC)
  • Repository: https://git.zx2c4.com/wireguard-go (mirrored at GitHub)

Purpose#

wireguard-go is a pure-Go userspace implementation of the WireGuard VPN protocol. It targets developers and platform integrators who need WireGuard on operating systems where the kernel module is unavailable (macOS, Windows, FreeBSD, OpenBSD) or who want to embed WireGuard functionality as a Go library. It implements the complete WireGuard data-plane: cryptographic handshakes, packet encryption/decryption, peer management, and TUN device handling.

Significance#

WireGuard has become one of the most influential VPN protocols of the decade, now merged into the Linux kernel. The Go implementation is the canonical cross-platform reference used by high-profile products such as Tailscale and the official WireGuard Windows app. Being authored and maintained by WireGuard LLC (Jason Donenfeld), it carries the authority of the protocol’s designers. Its clean package decomposition and use of platform-specific files make it a widely studied example of Go networking code.

Key metrics#

  • Go files: 100
  • Top-level directories: conn, device, ipc, ratelimiter, replay, rwcancel, tai64n, tests, tun
  • Direct dependencies: 5 (golang.org/x/crypto, golang.org/x/net, golang.org/x/sys, golang.zx2c4.com/wintun, gvisor.dev/gvisor)
  • Indirect dependencies: 2 (github.com/google/btree, golang.org/x/time)
  • Version at snapshot: 0.0.20250522 (date-versioned snapshot releases)

Notable characteristics#

  • Minimal dependency footprint: Only 7 total dependencies (5 direct), almost entirely the golang.org/x suite plus gVisor for netstack support. No logging frameworks, no CLI libraries — stdlib log and flag only.
  • Extensive platform abstraction via build tags: The tun and conn packages contain multiple platform-specific files (_linux.go, _darwin.go, _windows.go, _freebsd.go, _openbsd.go) with a clean interface that unifies them.
  • Security-critical cryptographic core: The device package implements the WireGuard noise handshake, session management, and packet routing. It uses golang.org/x/crypto (ChaCha20-Poly1305, BLAKE2s, Curve25519) directly without a higher-level TLS stack.
  • Self-contained utility packages: ratelimiter, replay (anti-replay sliding window), and tai64n (TAI64N timestamp encoding) are small, focused packages with no intra-project dependencies — textbook single-responsibility design.
  • gVisor netstack integration: Includes optional support for running WireGuard over a userspace TCP/IP stack (gVisor’s netstack), enabling use cases like container networking without kernel privileges.
Backward Tailscale — Testing wireguard-go — Structure Forward