A working userspace VPN in Go — both server (responder) and client
(initiator), written from scratch and depending only on the pure-Go
golang.org/x modules (x/crypto, and x/net for QUIC), no cgo. It speaks
sixteen production protocols, client and server for every one — IKEv2/ESP,
WireGuard, OpenVPN, SSTP, SSH, L2TP/IPsec, L2TPv3 Ethernet pseudowire,
AnyConnect, Nebula, MASQUE (CONNECT-IP and CONNECT-UDP over HTTP/3), Fortinet,
GlobalProtect, Cisco IPsec, Ivanti Connect Secure, SoftEther VPN (SE-VPN) and
AmneziaWG — each verified in Docker against a real third-party implementation
and against itself. That sentence used to carry an exception for SoftEther,
whose server direction had no cell; it now has one, against SoftEther's own
vpnclient, and the sentence stands without qualification.
Every layer is covered by tests, including full VPN integration tests:
TestFullVPNFlow drives a client through the handshake and verifies a real IP
packet traverses the ESP data path onto the server's TUN, and TestClientConnectPSK
drives the production client against the live server and checks bidirectional ESP.
- What it does — the protocol capability table
- Cryptography — algorithms, dependencies, security boundaries
- Architecture — the package tree and the protocol-agnostic boundary
- Install — apt repository and packaged releases
- Build and Run — building the binary; per-protocol runbooks
- The example protocol — TOY, the insecure teaching example
- Using the bundled client — CLI client, embedding, NetworkManager
- Testing — highlights and the live interop matrix
- Benchmarks — representative numbers (full table in
doc/benchmarks.md) - Scope and limitations
Deeper docs live under doc/: per-protocol usage,
architecture, security,
testing and benchmarks. What might be
added next, and what was considered and rejected, is in
doc/protocol-roadmap.md.
veepin speaks sixteen production protocols — client and server for every one — plus one deliberately insecure teaching example. Each protocol is verified in Docker against a real third-party implementation and against itself (see the Interoperability matrix). The table is the summary; each row links to that protocol's own package documentation, which carries the wire detail, caveats and API surface.
| Protocol | Authentication | Data path | Verified against | Docs |
|---|---|---|---|---|
| IKEv2/ESP | PSK, EAP-MSCHAPv2, X.509 certificate (RFC 7427) | ESP-in-UDP, RFC 4303 (NAT-T, dual-stack v4/v6 CP address assignment, RFC 9347 AGGFRAG, RFC 8229/9329 over TCP) | strongSwan, libreswan | ikev2 |
| WireGuard | Noise_IKpsk2 static keys | ChaCha20-Poly1305, cryptokey routing (both families), client rekey | wireguard-go | wireguard |
| OpenVPN | mutual TLS certificates | AES-256-GCM / -CBC; plain, tls-auth, tls-crypt (both roles) |
openvpn |
openvpn |
| SSTP | MS-CHAPv2 over PPP | PPP/IPCP over TLS, SHA-256 crypto binding | SoftEther, sstpc/pppd |
sstp |
| SSH | public key / password | IP over tun@openssh.com (layer-3) |
OpenSSH sshd / ssh -w |
ssh |
| L2TP/IPsec | IKEv1 PSK + MS-CHAPv2 | L2TP/PPP inside an ESP transport SA (NAT-T) | strongSwan + xl2tpd | l2tp |
| L2TPv3 | none — static config, cookie is a check value | Ethernet frames over UDP/1701 on a TAP device (RFC 3931 + 4719), layer 2 | Linux kernel (ip l2tp) |
l2tpv3 |
| AnyConnect | password | CSTP over TLS, with DTLS 1.2 PSK fallback | ocserv, openconnect | anyconnect |
| Nebula | certificate PKI, per host | Noise IX mesh, AES-GCM / ChaCha20; relay fallback when hole punching fails | slackhq/nebula | nebula |
| MASQUE | proxy TLS | IP (CONNECT-IP) and UDP (CONNECT-UDP) over HTTP/3, capsule mode | aioquic | masque |
| Fortinet | password, optional 2FA (TOTP) | PPP over TLS, with cert-based DTLS 1.2 fallback | openconnect | fortinet |
| GlobalProtect | password | RFC 4303 ESP over UDP, keyed by the config document, with a framed layer-3 TLS tunnel as fallback | openconnect | gp |
| Cisco IPsec | group PSK + XAuth password | IKEv1 Aggressive Mode, Mode-Config, tunnel-mode ESP-in-UDP | strongSwan | cisco |
| Ivanti Connect Secure | password (EAP over IF-T/TLS) | RFC 4303 ESP over UDP, with the IF-T/TLS connection as fallback | openconnect | pulse |
| SoftEther VPN | password (SHA-0 challenge) | Ethernet frames over TLS in counted blocks, PACK control over HTTP, layer-2 TAP | SoftEther VPN Server and its vpnclient |
softether |
| AmneziaWG | Noise_IKpsk2 static keys | WireGuard's ChaCha20-Poly1305 unchanged; obfuscated headers, padding and junk packets | amneziawg-go |
amneziawg |
Both roles share one registry API (client.Register/client.RegisterServer),
so veepin connect <proto> and veepin serve <proto> dispatch generically and
adding a protocol changes no caller. A seventeenth registered protocol, TOY,
provides no security — it is a worked example of the protocol shape, not a
real protocol; see The example protocol.
| Category | Supported |
|---|---|
| DH groups | Curve25519 (31), ECP-256/384/521 (19/20/21), MODP-2048 (14) |
| PRF | HMAC-SHA1, HMAC-SHA2-256/384/512 |
| IKE/ESP ciphers | AES-GCM-16 (AEAD, RFC 5282), ChaCha20-Poly1305 (AEAD, RFC 7634), AES-CBC + HMAC-SHA2 (encrypt-then-MAC) |
| Integrity | HMAC-SHA1-96, HMAC-SHA2-256-128/384-192/512-256 |
Post-quantum key exchange is on by default nearly everywhere, and in two
independent ways. IKEv2 negotiates ML-KEM-768 over RFC 9370 + RFC 9242 with
-pq, verified against strongSwan in both directions. And every TLS 1.3 path in
the tree is hybrid X25519MLKEM768 without asking, because Go's crypto/tls has
led its defaults with it since Go 1.24 and veepin pins CurvePreferences
nowhere — a guard test enforces that it stays that way. That covers MASQUE and
the OpenVPN server unconditionally, and AnyConnect, Fortinet, GlobalProtect,
Ivanti, SSTP, SoftEther and the OpenVPN client whenever the peer speaks TLS 1.3.
Authentication can be post-quantum too, as of Go 1.27: point a server at an
ML-DSA (FIPS 204) certificate and key and both halves of the handshake are
post-quantum — key exchange and signature — with no dependency outside the
standard library. See doc/security.md for what each half
does and does not protect.
Everything above is a default, and a default can be negotiated away: a peer that offers only classical mechanisms still gets a working tunnel, just a weaker one. Ten protocols therefore carry a second registry name under which post-quantum cryptography is mandatory and anything less is refused:
veepin serve pq-ikev2 -psk … -identity vpn.example # refuses a classical initiator
veepin connect pq-sstp -server vpn.example -user alice| Variant | Forces | Also forces |
|---|---|---|
pq-ikev2 |
ML-KEM-768 via ADDKE1 (RFC 9370), ML-DSA in the RFC 7427 AUTH payload | refuses EAP-MSCHAPv2 |
pq-openvpn |
TLS 1.3, ML-KEM key exchange, ML-DSA certificates both ends (mutual TLS) | |
pq-sstp, pq-gp, pq-pulse, pq-softether, pq-masque |
TLS 1.3, ML-KEM key exchange, ML-DSA server certificate | pq-masque clients authenticate with a bearer token, not a certificate |
pq-anyconnect, pq-fortinet |
the same | -no-dtls, because the DTLS 1.2 data channel has no post-quantum path |
pq-ssh |
mlkem768x25519-sha256 |
key exchange only — see below |
They are names rather than flags for one reason: a flag is a modifier an operator can forget, and forgetting it yields the weaker behaviour silently. A name cannot be forgotten. It also earns each variant a row in the interop matrix, which a flag would not get.
Three things worth stating plainly:
- A
pq-server refuses to start without an ML-DSA certificate, before the TUN is opened and before anything binds — not at the first client's handshake. A listener created under apq-name in the management panel generates an ML-DSA-65 chain automatically. - PSK authentication still works under
pq-ikev2. A pre-shared key is symmetric and is not broken by a quantum adversary; that is the entire premise of RFC 8784. Whatpq-ikev2refuses is classical public-key authentication. pq-sshcarries only half the contract, because SSH has no post-quantum signature algorithm in any specification or implementation — OpenSSH says so itself. The exemption is recorded by name ininternal/pqpolicyand a test holds that list at one entry.
Six protocols have no pq- variant and cannot have one. WireGuard and
AmneziaWG fix X25519 in Noise_IKpsk2 and negotiate nothing; Nebula is plain
Noise_IX; Cisco IPsec and L2TP/IPsec are IKEv1, which has no additional
key-exchange mechanism; L2TPv3 has no cryptography at all. Those absences are
structural, not a backlog. The variants are also not counted among the
sixteen production protocols — pq-ikev2 is IKEv2 with a floor under it, not a
seventeenth protocol. The design and its evidence are in
doc/pq-variants-plan.md.
AES from the standard library; ChaCha20-Poly1305 from x/crypto (the same AEAD
WireGuard already pulls in). ChaCha20-Poly1305 for IKEv2/ESP shares AES-GCM-16's
exact framing — a 4-octet implicit salt, an 8-octet explicit IV and a 16-octet
tag — so both run through one generic AEAD path in cryptoutil, and it is
offered after AES-GCM (which is faster where the CPU has AES-NI) and ahead of
AES-CBC.
The module depends only on the pure-Go golang.org/x modules: x/crypto,
x/net (for QUIC), and x/sys and x/text that those pull in. Nothing outside
the golang.org/x namespace, and no cgo.
x/crypto exists first for WireGuard, which fixes its crypto and does not
negotiate it. It mandates ChaCha20-Poly1305 and BLAKE2s, and Go ships neither
in the standard library, so WireGuard cannot be built on stdlib alone. IKEv2
reaches the same x/crypto ChaCha20-Poly1305 for its own RFC 7634 suite — an
AEAD Go's standard library still omits — but everything else IKEv2 negotiates is
covered by crypto/aes and crypto/sha256, so that one AEAD is the whole of
its dependency beyond stdlib.
x/net exists for a second: MASQUE runs over HTTP/3, and Go ships no QUIC.
x/net/quic is the Go team's own pure-Go implementation, so the alternative —
hand-rolling a QUIC stack or vendoring a third-party one — is avoided the same
way x/crypto avoids hand-rolling ChaCha20. (x/net/http3 is not used: its
public surface exports nothing and it has no CONNECT/datagram/capsule support,
so the HTTP/3 layer MASQUE needs is built from scratch on the quic package —
see internal/masque/http3.) Only MASQUE imports it; the other fifteen protocols
still reach no further than x/crypto.
The alternative was hand-rolling both. That was rejected: x/crypto is the Go
team's own module and carries the AVX2/NEON assembly, which measures ~1.9 GB/s
for ChaCha20-Poly1305 on the data path against the several-times-slower pure-Go
implementation we would have written — and an AEAD protecting every packet is a
far larger security surface than the bundled MD4 in internal/ikev2/eap, which
is a legacy hash confined to one corner of MSCHAPv2.
Everything is still CGO-free, and the nm/ plugin remains a separate module so
the core does not inherit its D-Bus and GTK dependencies.
EAP-MSCHAPv2 additionally uses MD4 (for the NT password hash) and single-DES
(for the challenge response), as the protocol mandates. Go's standard library
has DES but not MD4, so a compact RFC 1320 MD4 is included in internal/ikev2/eap;
these legacy primitives are used only where MSCHAPv2 requires them, never for
transport security.
Three boundaries are worth stating outright, because each is the kind of thing a reader may otherwise assume is handled — and none is an oversight:
- Key material is not zeroed after use. veepin does not claim protection against an attacker who can read process memory (core dump, debugger, swap).
- Throughput is bounded by one core per direction. The data path runs one TUN-reader goroutine and one socket-reader goroutine per server, shared across all clients — a scaling ceiling, not a correctness problem.
- MASQUE carries every inner packet on one reliable QUIC stream (capsule mode), so it reintroduces head-of-line blocking on a lossy path.
The reasoning behind each — why Go's memory model makes zeroization unreliable,
and why the MASQUE boundary is a performance limit rather than a correctness one —
is in doc/security.md.
The tree separates machinery any VPN protocol needs from what is specific to one
protocol. Each protocol is a sibling under internal/, with a thin public
package exposing Dial and NewServer; the shared machinery — TUN handling,
address pools, the packet pump, admission control, MTU derivation — lives in
dataplane and internal/cryptoutil and is written once.
cmd/veepin CLI: connect / serve / probe subcommands, flags, routing
client protocol registry (client + server) + the Session/Result/Server contracts
ikev2 public IKEv2 entry point: Dial + NewServer, Config
wireguard public WireGuard entry point: Dial + NewServer, Config, wg-quick parser
openvpn public OpenVPN entry point: Dial + NewServer, Config, .ovpn parser
sstp public SSTP entry point: Dial + NewServer, Config, crypto binding
ssh public SSH entry point: Dial + NewServer, Config (x/crypto/ssh)
l2tp public L2TP/IPsec entry point: Dial + NewServer, Config
anyconnect public AnyConnect entry point: Dial + NewServer, Config
nebula public Nebula entry point: Dial + NewServer (lighthouse), Config
masque public MASQUE entry point: Dial + NewServer (CONNECT-IP proxy), Config
fortinet public Fortinet entry point: Dial + NewServer (SSL VPN gateway), Config
toy public TOY entry point: Dial + NewServer — an INSECURE teaching example
dataplane TUN device, address pool, packet pump (demux + routing), client routing
admission control, ICMP/PMTU, MTU derivation, source-preserving PacketConn
downstream flow shaping (padding away the inner traffic's size pattern)
internal/cryptoutil DH, PRF + prf+, integrity, SK/ESP ciphers, ChaCha20-Poly1305, BLAKE2s
internal/replay the anti-replay window shared by nebula and toy
internal/ikev2/payload wire codec: header, payloads, SA/KE/Nonce/Notify/ID/AUTH/TS/Delete/CP
internal/ikev2/transform IANA transform ID -> cryptoutil primitive
internal/ikev2/eap EAP packet codec + EAP-MSCHAPv2 (MD4/DES/SHA1, MSK derivation)
internal/ikev2/esp ESP encapsulate/decapsulate + anti-replay
internal/ikev2/ike negotiation, SK seal/open, NAT-T, CP, exchange handlers, keymat, Client
internal/wireguard/wire message codec: the four types, fixed layouts, demux, TAI64N
internal/wireguard/noise Noise_IKpsk2 handshake (initiator), KDF, MAC
internal/wireguard/transport type-4 transport crypto: counter nonce, padding, replay window
internal/openvpn/wire packet codec: opcode byte, session IDs, control/ACK framing
internal/openvpn/reliable control-channel reliability: window, retransmit, reorder, ACKs
internal/openvpn/control TLS control channel: a net.Conn over the reliability layer
internal/openvpn/tlswrap tls-auth/tls-crypt: static-key HMAC and AES-256-CTR control wrapping
internal/openvpn/keys key method 2 exchange + TLS 1.0 PRF key derivation
internal/openvpn/data P_DATA_V2 seal/open (AES-256-GCM and AES-256-CBC) + anti-replay window
internal/sstp/wire SSTP packet codec: control/data framing, attributes, crypto binding
internal/ppp PPP client + server: LCP, MS-CHAPv2 auth, IPCP (transport-neutral)
internal/mschap MS-CHAPv2 primitives + MPPE/HLAK key derivation
internal/sshtun OpenSSH tun@openssh.com framing: channel-open data + AF packet frames
internal/anyconnect CSTP framing, the config-auth XML exchange, the DTLS channel, and the client/server engines
internal/dtls DTLS 1.2 PSK: record layer, handshake flights, fragmentation, anti-replay
internal/nebula minimal protobuf codec, v1 certificates + CA pool, Noise IX, 16-octet header,
AEAD data path with anti-replay, the mesh host engine and the lighthouse protocol
internal/masque CONNECT-IP + CONNECT-UDP: capsules, the HTTP-Datagram payload, the TUN
client/server engines, and the CONNECT-UDP relay + local UDP forwarder
internal/masque/http3 from-scratch HTTP/3 on x/net/quic: varints, minimal QPACK (zero dynamic table),
SETTINGS/control streams, Extended CONNECT, capsules over DATA frames
internal/toy the TOY example protocol + SPEC.md — NO SECURITY; the smallest complete
illustration of a veepin protocol (handshake, Tunnel, pump, both roles)
internal/ikev1 ISAKMP/IKEv1: payload codec, Main + Quick mode, SKEYID/KEYMAT, CBC IV chaining
internal/l2tp RFC 2661 header/AVP codec, reliable control channel, PPP data channel,
plus the client/server engines binding IKEv1 + ESP + L2TP + PPP to a TUN
internal/fortinet FortiOS SSL VPN: the 6-octet PPP framing, the logincheck/SVPNCOOKIE
login, the fortisslvpn_xml config, the PPP-over-TLS client/server,
and the DTLS data channel with its GFtype cookie exchange
internal/udpmux one UDP socket demultiplexed into per-peer net.Conns, shared by the
AnyConnect and Fortinet DTLS listeners
internal/otp HOTP (RFC 4226) and TOTP (RFC 6238), generation and constant-time
verification — the second factor behind Fortinet's ret=2 challenge
dataplane and internal/cryptoutil are protocol-agnostic: neither imports
anything else in this module, and neither knows IKEv2 exists. That boundary — how
the pump demuxes inbound packets with a protocol-supplied Demux, how outbound
routing picks a tunnel by most-specific route, and how a packet flows end to end —
is written up in doc/architecture.md.
On Debian/Ubuntu — any Debian release architecture (amd64, arm64, armhf, armel, i386, ppc64el, riscv64, s390x) — the signed APT repository tracks the latest release:
sudo curl -fsSL https://xen0bit.github.io/veepin/veepin-archive-keyring.gpg \
-o /usr/share/keyrings/veepin-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/veepin-archive-keyring.gpg] https://xen0bit.github.io/veepin stable main" \
| sudo tee /etc/apt/sources.list.d/veepin.list
sudo apt update && sudo apt install veepin veepin-nmveepin is the CLI (server + client; no library dependencies — it does shell
out to ip/iptables/sysctl on Linux and ifconfig/route/networksetup on
macOS, all of which are part of the base system); veepin-nm
adds the NetworkManager desktop integration (built for the same architectures;
the amd64/arm64 builds load on Ubuntu 22.04+, the cross-built rest on
Debian 12+ / Ubuntu 24.04+). The repository signing
key ships in packaging/apt-signing-key.asc as
the out-of-band trust anchor, and the release workflow refuses to publish a
repository signed by anything else:
EE96 B9F0 28F5 7D11 5A8D 1509 889E D9E8 95D7 E72C
That key replaced the previous one on 2026-09-02. If you added the repository
before then, re-run the curl above; the old keyring cannot verify the current
InRelease, and apt update will say so.
The package ships a systemd template unit — drop arguments in
/etc/veepin/<name>.conf and systemctl enable --now veepin@<name> (see
/usr/share/doc/veepin/veepin.conf.example); it grants the daemon the
capabilities it needs, so no root shell or setcap step.
Each GitHub release carries checksums.txt, a cosign signature over it, and a
CycloneDX SBOM per binary. The signature is keyless: it is bound to this
repository's release workflow through GitHub's OIDC identity, so there is no
long-lived signing key to trust, and verification checks which workflow built
the artifact rather than who holds a key.
cosign verify-blob checksums.txt \
--certificate checksums.txt.pem \
--signature checksums.txt.sig \
--certificate-identity-regexp 'https://github[.]com/xen0bit/veepin/[.]github/workflows/release[.]yml@.*' \
--certificate-oidc-issuer https://token.actions.githubusercontent.com
sha256sum -c checksums.txt --ignore-missingOne signature over the checksum file rather than one per artifact: the checksums already cover every artifact, so verifying the signature and then the checksums gives the same guarantee.
The SBOM is short — golang.org/x/{crypto,net,sys,text} and the standard
library — which is the point of publishing it. The dependency claim at the top
of this file is then something a scanner can check rather than a sentence you
have to take on trust.
.deb/.rpm/.apk packages and plain tarballs for every version are on
GitHub Releases
(apt install ./veepin_<ver>_linux_<arch>.deb works directly).
Requires Go 1.27+ (crypto/mldsa; developed against Go 1.27).
go build ./...
go test ./...
go build -o veepin ./cmd/veepinOne binary does everything, dispatching on a subcommand and a protocol:
veepin connect <protocol> [flags] bring up a tunnel to a server
veepin serve <protocol> [flags] run a VPN server
veepin probe <protocol> [flags] diagnostic: handshake + one data packet
Every protocol — the sixteen production ones and the TOY example — is registered
for both connect and serve; veepin with no
arguments lists what is registered.
Creating a TUN device needs CAP_NET_ADMIN. Either run as root, or grant the
binary the capability once:
sudo setcap cap_net_admin+ep ./veepinOn any serve subcommand, -setup-nat -wan <iface> auto-configures the tunnel
interface, enables IP forwarding, and installs a MASQUERADE rule for that WAN
interface; omit it and the server prints the exact ip/iptables lines to run
by hand. Each protocol's connect/serve runbook — its flags, config-file
formats, and what it interoperates with — has its own page:
| Protocol | Runbook |
|---|---|
| IKEv2/ESP (incl. EAP-MSCHAPv2) | doc/usage/ikev2.md |
| WireGuard | doc/usage/wireguard.md |
| OpenVPN | doc/usage/openvpn.md |
| SSTP | doc/usage/sstp.md |
| SSH | doc/usage/ssh.md |
| L2TP/IPsec | doc/usage/l2tp.md |
| AnyConnect | doc/usage/anyconnect.md |
| Nebula | doc/usage/nebula.md |
| MASQUE (CONNECT-IP + CONNECT-UDP) | doc/usage/masque.md |
| Fortinet | doc/usage/fortinet.md |
| GlobalProtect | doc/usage/gp.md |
| Cisco IPsec | doc/usage/cisco.md |
| Ivanti Connect Secure | doc/usage/pulse.md |
| SoftEther VPN | doc/usage/softether.md |
| AmneziaWG | doc/usage/amneziawg.md |
| L2TPv3 Ethernet pseudowire | doc/usage/l2tpv3.md |
The pq- variants (all ten) |
doc/usage/pq-variants.md |
Every protocol that authenticates a person by password — AnyConnect, Cisco
IPsec, Fortinet, GlobalProtect, Ivanti, L2TP/IPsec, SSH and SSTP — takes
-users-file, a file of username:secret lines:
# /etc/veepin/users, mode 0600
alice:$2a$12$K3sQ8xVn0zL7pR2fT9mYue1Wj4hC6bD5aE8gN0oS2uX7vZ1qM3rGy
bob:hunter2
-user/-pass remain the one-user shorthand, and where a name is in both the
command line wins. veepin passwd prints a verifier for the first form,
reading the password from stdin so it never enters the process table; at a
terminal it turns echo off and asks twice, and a piped password is read once and
unchanged. The format is bcrypt's own, so htpasswd -B works too.
Whether the secret may be a verifier is a property of the protocol rather than a setting. SSTP and L2TP/IPsec are MS-CHAPv2: both ends derive their response from the password, so those files hold plaintext passwords and veepin refuses a hash at startup rather than accepting one and failing every login. See doc/security.md for the table and what it costs.
To run a fleet of servers in one process with a localhost management API
and embedded web panel, the supervisor mode is additive to the bare
single-protocol command: see Running the supervisor
and the veepin mgmt CLI.
To use veepin as a client, the NetworkManager plugin is the simplest path on a Linux desktop — it configures all sixteen protocols from the native VPN UI. The Using the bundled client section below walks the CLI client through end to end. Stock OS built-in VPN clients (Windows, macOS/iOS, Android, strongSwan) can also connect to the veepin IKEv2 server directly — see doc/usage/ikev2.md.
TOY provides no security — its "encryption" is a repeating XOR pad and its
"authentication" is a hash-table hash, so anyone who can see the traffic can read
and forge it. It is not one of the sixteen real protocols; it is the shape of a
veepin protocol with the cryptography replaced by placeholders simple enough to
read in one sitting — a handshake producing a client.Result, a data
10BC8
plane.Pump
data path, and both roles on the client registry. Its interop cells talk to an
independent Python implementation written from the spec, so they test the
document rather than the code.
If you are adding a real protocol, start here:
internal/toy/README.md and
internal/toy/SPEC.md, which document the wire format,
enumerate the concrete ways the cryptography fails, and map each to what a real
protocol here does instead.
veepin connect is a full VPN client: it connects to a server, obtains an
address, brings up a local TUN, installs routes, and tunnels the host's traffic.
Like the server it needs CAP_NET_ADMIN (for the TUN device and routing table):
sudo ./veepin connect ikev2 -server vpn.example.com -psk 'a-strong-preshared-key' \
-id client.example.com -server-id vpn.example.comBy default it installs a full-tunnel default route (all traffic through the VPN) plus a host route to the server via the existing gateway, so the encapsulated ESP packets don't recurse into the tunnel. It also installs the resolvers the server handed out, for the tunnel's lifetime — a full tunnel that keeps the host's old resolver leaks every query it was meant to hide, in plaintext, from the host's real address. On disconnect (Ctrl-C) both are reverted. Useful flags:
-user/-pass— authenticate with EAP-MSCHAPv2 username/password instead of the client PSK (the server PSK still authenticates the server).-full-tunnel=false— only bring up the interface/address.- Under the default full tunnel, an address family the tunnel carries no
address in is made unreachable rather than left on the physical link: a
v4-only tunnel on a dual-stack host otherwise sends every IPv6 flow out in the
clear.
-allow-unrouted-familyrestores the old behaviour. -route <cidr>— send this prefix through the tunnel (repeatable). Implies-full-tunnel=false, since naming what to route means not routing everything.-exclude <cidr>— keep this prefix off the tunnel (repeatable), by routing it via the physical gateway — the same mechanism that keeps the tunnel's own packets from recursing into it. A bare address is read as a host route.-no-route— connect and establish the data path but make no routing or DNS changes (useful for testing, or when another process manages both).-no-dns— keep the routes but leave the host's resolvers alone, for the operator who manages their own.-retry=false/-retry-max <n>— see below.-kill-switch— fail closed if the tunnel drops, rather than letting traffic resume in plaintext. See below.-server-id— verify the server presents this identity in its IDr.-log-level/-log-format— see Logging.
A dropped tunnel is re-dialled by default, with jittered exponential backoff
from one second to a minute, resetting after a session that stayed up for a
minute. A laptop changing Wi-Fi networks or a tether that drops for four
seconds reconnects on its own; the host's routes, addresses and resolvers come
all the way down between attempts, so a failed re-dial leaves nothing behind.
A rejected credential is never retried — that is a lockout on any server
that counts failures, and client.ErrAuth is what distinguishes it. -retry=false
returns to the shell on the first drop, and -retry-max <n> bounds the
attempts, for scripts and CI that need a failure to be a failure.
-kill-switch makes an unintended teardown fail closed. It installs the same
two /1 halves the full tunnel uses, as blackholes at a worse metric, while the
tunnel is healthy — so they are inert until the kernel drops the TUN's routes
with its device, and the handover has no window. A host route to the server is
held alongside them, or the re-dial could not reach the server it is trying to
reach. It is off by default, because a kill switch nobody asked for strands a
machine you may only be able to reach over the network it just blackholed; when
it engages it logs the command to reopen the host by hand, since the moment you
need that is the moment you cannot look it up. It needs a full tunnel and a
protocol with one outer server address, and refuses rather than half-delivering
for a split tunnel or a mesh — and it cannot be combined with -no-route, since
the switch is routing and there is nothing to fail closed with the routing
table left alone. Both address families are closed whichever the
tunnel carries — a family the tunnel does not carry is exactly a family that
escapes it — so a v4-only tunnel blackholes IPv6 for its lifetime, which the log
says out loud.
Which mechanism installs the resolvers depends on the host, and the connect log
line names the one that ran. Where systemd-resolved is running the servers are
set on the tunnel link with resolvectl, and a full tunnel additionally claims
the ~. routing domain — without which resolved keeps answering from the other
link's servers no matter what /etc/resolv.conf says. Everywhere else
/etc/resolv.conf is rewritten, with the original copied to
/etc/resolv.conf.veepin.bak and restored on teardown; a resolv.conf that is
a symlink into /run belongs to another daemon and veepin refuses it rather
than clobbering its state.
The client speaks the same PSK and EAP-MSCHAPv2 flows the server accepts, so
veepin connect ↔ veepin serve interoperate directly, and the client also works
against other RFC 7296 responders that accept these authentication methods.
The client runs on Linux and macOS. Linux is what CI and the interop matrix
exercise; macOS is dataplane/tun_darwin.go (a utun control socket via
x/sys/unix — no cgo, no new dependency) plus ifconfig/route/networksetup
for host networking. It compiles in CI for darwin/amd64 and darwin/arm64,
which proves it type-checks and nothing more: no one has run it yet, and
doc/verifying-macos.md is the procedure for the person
who does. Three things are knowingly absent there — the kill switch (the BSD
routing table has no per-route metrics to arm one safely), the layer-2 protocols
(macOS has no in-kernel TAP), and GSO (a Linux offload).
The server is Linux only: internal/hostnet speaks iptables and sysctl.
Windows is out of scope, and the reason is not the one this used to give. wintun
is loaded at runtime through LoadLibrary, not linked, so the pure-Go claim
would survive it — wireguard-go does exactly this on Windows without cgo. What
is true is the rest: shipping and trusting a signed third-party DLL is a real
runtime dependency and a real supply-chain surface, and the TUN is only the
visible half. The other half is internal/hostnet, which speaks iptables and
sysctl and would need a second backend in netsh or WFP.
The reason that outranks all of those: the macOS client compiles, is shipped, and has never been run by anyone. Adding a second unverified platform before the first one is verified turns two bugs into one indistinguishable failure.
connect and serve take -log-format text|json and -log-level debug|info|warn|error. text is the default and is exactly the timestamped
line the command has always printed; json emits one log/slog record per
line, for a log shipper. debug turns on protocol-level detail — one switch,
replacing the VEEPIN_SSTP_DEBUG-shaped environment variables that had started
to accumulate one per protocol (the old spellings still work, and VEEPIN_DEBUG
is the general one, for a Go program embedding a protocol package directly).
The level filters per line, not per stream: at -log-level warn the
informational stream goes away and a protocol reporting a real problem still
prints. That is internal/vlog, which is log/slog with the Printf-shaped
calls the data paths make and a level chosen at the call site. A fatal error
never depends on any of it — it returns to main and reaches stderr directly.
A facade's Logger field is an *slog.Logger, so a Go program embedding a
protocol package hands in a standard-library logger and nothing else.
serve takes two Linux-only switches for the boundary
doc/security.md opens by naming — the one it refuses to
defend by zeroing key material, because Go's collector makes that a gesture
rather than a guarantee:
-lock-memory—mlockall, so no page reaches swap and key material cannot be recovered from a swap file afterwards. NeedsCAP_IPC_LOCKorRLIMIT_MEMLOCKheadroom.-no-core-dumps—prctl(PR_SET_DUMPABLE, 0), so a crash writes no core file carrying live session keys and a same-uid process cannotptracein.
Both are off by default because each trades something real, and both abort the
server if refused rather than warning and carrying on. A hardening switch that
silently does nothing is worse than no switch: the appearance invites confidence
the process has not earned. Neither reduces what a debugger with
CAP_SYS_PTRACE, a hypervisor, or code execution in the process can reach.
The handshake and data path are a reusable library: Dial performs the handshake
and brings up the ESP data path over a TUN without installing routes,
returning the assigned address/DNS/gateway for the caller to apply. veepin connect is a thin wrapper over it. Go code that knows which protocol it wants
imports the protocol package for a typed config:
import "github.com/xen0bit/veepin/ikev2"
sess, res, err := ikev2.Dial(ctx, ikev2.Config{
Server: "vpn.example.com", PSK: "…", LocalID: "client.example.com",
})
defer sess.Close()
// apply res.AssignedIP / res.DNS / res.Gateway yourselfCallers whose parameters arrive as strings (a CLI's flags, NetworkManager's settings dictionary) dial by name, selecting protocols by importing them:
import (
"github.com/xen0bit/veepin/client"
_ "github.com/xen0bit/veepin/ikev2" // registers "ikev2"
)
sess, res, err := client.Dial(ctx, "ikev2", map[string]string{
"gateway": "vpn.example.com", "psk": "…", "local-id": "client.example.com",
})client.Result and client.Session are protocol-agnostic, so code that applies
a Result or manages a Session does not change when a protocol is added. A server
is the same shape: ikev2.NewServer(ikev2.ServerConfig{…}) wires the TUN,
address pool and data path, and leaves host routing/NAT to the caller.
A NetworkManager VPN plugin brings the tunnel up and down from a Linux desktop's
native VPN UI (GNOME / Pop!_OS), with no dependency on strongSwan. It lives
in the nested nm/ module — kept out of the core build so the veepin binary
does not inherit its D-Bus and GTK dependencies — and registers all sixteen
protocols as separate VPN types, so each is its own entry in the desktop's
Add VPN list rather than a "veepin" entry that asks which protocol next:
cd nm && make build && sudo make install && sudo systemctl reload NetworkManager
nmcli connection add type vpn con-name home-veepin ifname '*' \
vpn-type org.freedesktop.NetworkManager.veepin.ikev2 \
vpn.data 'protocol=ikev2, gateway=vpn.example.com, local-id=client.example.com, full-tunnel=yes'
nmcli connection modify home-veepin vpn.secrets 'psk=a-strong-preshared-key'
nmcli connection up home-veepinSwitching protocol is the same command with a different vpn-type suffix, a
matching protocol= key and that protocol's own option names; graphically it is
a different entry in the Add VPN list, each with only its own fields.
See doc/networkmanager-plugin.md for
the full design, the D-Bus contract, the per-protocol key reference, and the
runbook.
go test -race ./... # correctness
./bench.sh # performance (see Benchmarks below)
make interop # Docker interop suite (build tag `interop`)Per-package test highlights — the end-to-end IKEv2 and production-client flows,
the EAP/MD4 vectors, the dataplane round-trips and the codec coverage — are
collected in doc/testing.md.
The Docker interop tests prove each protocol against a real third-party implementation and against itself, both roles. The matrix is regenerated by CI from the live interop run on every push to main — each ✓ is a Docker test that passed in that run, not a claim.
Two of those cells are also recorded. Their peer traffic is committed as a
golden corpus and replayed offline by the ordinary go test ./..., so a
regression against a real strongSwan or a real wireguard-go fails in
milliseconds on a laptop rather than in a fifteen-minute Docker shard — and the
same assertions run against a live peer in CI, because a recording pins the peer
as it was on the capture date and is never allowed to stand in for the cell. See
doc/replaying-the-peer.md.
| Protocol | veepin client ↔ real server | real client ↔ veepin server | veepin ↔ veepin (self) |
|---|---|---|---|
| IKEv2 | ✓ strongSwan (PSK + pubkey ECDSA/RSA, RFC 7383 frag, AES-GCM + ChaCha20, dual-stack, v6 underlay, ML-KEM-768, IP-TFS incl. constant-rate, recorded) + libreswan (incl. RFC 8229/9329 over TCP) | ✓ strongSwan (+ EAP-MSCHAPv2, pubkey RSA, RFC 7383 frag both ways, dual-stack, v6 underlay, TFC-padded, ML-KEM-768, IP-TFS) + libreswan (incl. RFC 8229/9329 over TCP) | ✓ (+ IP-TFS) |
| WireGuard | ✓ wireguard-go (+ IPv6 inner) | ✓ wireguard-go (+ padded, IPv6 inner, cookie-challenged, recorded) | ✓ |
| OpenVPN | ✓ openvpn (×4 variants) |
✓ openvpn (+ tls-auth, tls-crypt, padded, IPv6 inner) |
✓ |
| SSTP | ✓ SoftEther | ✓ sstpc/pppd (+ PPP-padded) |
✓ |
| SSH | ✓ sshd (PermitTunnel) |
✓ ssh -w |
✓ |
| L2TP/IPsec | ✓ strongSwan + xl2tpd | ✓ strongSwan + xl2tpd (+ PPP-padded) | ✓ |
| AnyConnect | ✓ ocserv | ✓ openconnect (TLS, DTLS, CSTP-padded) | ✓ |
| Nebula | ✓ nebula (lighthouse, shaped) |
✓ nebula (host) |
✓ (via lighthouse; relayed with the direct path blocked) |
| MASQUE-IP | ✓ aioquic CONNECT-IP | ✓ aioquic CONNECT-IP | ✓ |
| MASQUE-UDP | ✓ aioquic CONNECT-UDP | ✓ aioquic CONNECT-UDP | ✓ |
| Fortinet | —† | ✓ openconnect (TLS, DTLS, 2FA, PPP-padded) | ✓ (over DTLS) |
| GlobalProtect | —† | ✓ openconnect (SSL tunnel, ESP, padded) | ✓ (over ESP) |
| Cisco IPsec | ✓ strongSwan (aggressive + XAuth) | ✓ strongSwan (Mode-Config, TFC-padded) | ✓ |
| Ivanti Connect Secure | —† | ✓ openconnect (IF-T/TLS, ESP, padded) | ✓ (over ESP) |
| SoftEther VPN | ✓ SoftEther VPN Server (native SE-VPN, SecureNAT) | ✓ SoftEther VPN vpnclient |
✓ (layer 2, switched; shaped) |
| AmneziaWG | ✓ amneziawg-go | ✓ amneziawg-go | ✓ (H1-H4, S1-S4, junk) |
| L2TPv3 | ✓ Linux kernel (ip l2tp, 8-octet asymmetric cookies) |
✓ Linux kernel (ip l2tp) |
✓ (shaped) |
| pq-ikev2 | —† | ✓ strongSwan (ML-KEM-768 required, and a classical initiator refused) | ✓ |
| pq-openvpn | ✓ openvpn 2.6.14 (ML-DSA-65 mutual, ML-KEM-only groups) |
✓ openvpn 2.6.14 (ML-DSA-65 mutual, ML-KEM-only groups) |
✓ |
| pq-ssh | ✓ OpenSSH 10.0 requiring mlkem768x25519-sha256 (kex only) |
✓ OpenSSH 10.0 requiring mlkem768x25519-sha256 (kex only) |
✓ |
| pq-anyconnect | —† | —† | ✓ (over TLS: -no-dtls is forced) |
| pq-fortinet | —† | —† | ✓ (over TLS: -no-dtls is forced) |
| pq-gp | —† | —† | ✓ (over ESP) |
| pq-pulse | —† | —† | ✓ (over ESP) |
| pq-sstp | —† | —† | ✓ |
| pq-masque | —† | —† | ✓ |
| pq-softether | —† | —† | ✓ (layer 2, switched) |
| TOY* | ✓ independent Python peer | ✓ independent Python peer | ✓ |
Generated by the interop workflow from 7c4eaf8 on 2026-10-20.
* TOY is a deliberately insecure example protocol, not a real one (see
The example protocol). † marks a cell with no
open-source peer to test against — a fact about what exists, not work
outstanding. It applies in two places. Fortinet is asymmetric: no open-source
FortiOS gateway exists for the client direction, so the openconnect client
against the veepin server is the independent proof. And most of the pq- rows
carry it on both directions, because in 2026 almost nothing else speaks ML-DSA:
openconnect links GnuTLS, which has no ML-KEM group at all; sstp-client and
SoftEther are older still; and aioquic brings its own hand-written TLS. Those
rows are veepin↔veepin evidence only, which proves the two halves agree with
each other and not that they are right — the weaker standard this tree normally
refuses, accepted here because the alternative is not shipping the guarantee,
and stated rather than glossed. See
doc/security.md.
There is no longer a ‡: it marked a cell that was work outstanding rather than
a limitation, and the last one carrying it — SoftEther's own vpnclient against
veepin's server — is built.
The three pq- rows that do have a peer are where the guarantee is actually
proven. pq-openvpn runs against openvpn 2.6.14 on OpenSSL 3.5.7 in both
directions with mutual ML-DSA-65 authentication and an ML-KEM-only group
list, so each end's post-quantum signature is verified by the other
implementation. pq-ssh runs against OpenSSH 10.0 with KexAlgorithms pinned
to one name in both directions. And pq-ikev2's server cell is the one that
distinguishes the variant from its base at all: a real strongSwan initiator
proposing everything the passing cell proposes minus ke1_mlkem768 must be
refused, and a server that merely prefers post-quantum passes the positive
cell identically and fails that one.
Both SoftEther cross-implementation cells are worth reading as one story. The
client direction carried ‡ on the reasoning that nothing structural blocked it
and nobody had spent the afternoon. Building it found that five layers of the
wire format had never been interoperable — PACK's integer byte order, its three
disagreeing string encodings, the SHA-0 password construction, the HTTP layer in
front of the control messages, and the block framing of the data path — each of
them invisible to the self cell, because both ends were wrong in the same
direction every time.
The server direction then carried ‡ with two specific blockers named, which
is a stronger claim than "nobody has spent the afternoon" and was wrong twice
over. Neither was real — a welcome without SoftEther's policy structure parses
fine, and a client told max_connection=1 opens no additional connections — and
the one thing that did block it had not been guessed at: vpnclient opens the
connection with GET / and posts the signature second, where veepin's server
read a single request and judged it. Every real client was refused on its
opening move. Together they are the clearest illustration on this page of why
the matrix exists, and the second is the sharper half: reasoning carefully about
a peer produced two confident blockers, neither of them the one. The full
rationale,
the registry API behind the cells, and the interop harness are in
doc/testing.md and
tests/interop/README.md.
The same matrix, but measured: during each interop run an iperf3 flow is pushed
across every tunnel that came up, and the received rate is committed back here on
push to main. The numbers are relative — a shared CI runner, a short window, one
TCP stream — so read them as an order-of-magnitude comparison between carriers,
not a benchmark of the wire.
A dash means iperf3 does not apply to that cell: a peer with no bindable
tunnel address (SoftEther's SecureNAT gateway, which the daemon synthesises
rather than putting on an interface), the CONNECT-UDP datagram cells (which
forward datagrams rather than route IP), or a cell with no peer to run against —
the Fortinet client, and the pq- directions marked † above.
A ✗ means it does apply, was attempted across a tunnel that came up, and
produced no number — a measurement that is broken rather than absent. The two
used to render identically, which presented a broken measurement as a deliberate
omission; the interop harness now logs the difference.
| Protocol | veepin client ↔ real server | real client ↔ veepin server | veepin ↔ veepin (self) |
|---|---|---|---|
| IKEv2 | 526 Mbit/s | 1.6 Gbit/s | 879 Mbit/s |
| WireGuard | 426 Mbit/s | 916 Mbit/s | 644 Mbit/s |
| OpenVPN | 542 Mbit/s | 432 Mbit/s | 422 Mbit/s |
| SSTP | — | 186 Mbit/s | 343 Mbit/s |
| SSH | 660 Mbit/s | 223 Mbit/s | 220 Mbit/s |
| L2TP/IPsec | 178 Mbit/s | 461 Mbit/s | 252 Mbit/s |
| AnyConnect | 673 Mbit/s | 698 Mbit/s | 485 Mbit/s |
| Nebula | 1.18 Gbit/s | 1.71 Gbit/s | 987 Mbit/s |
| MASQUE-IP | 22.6 Mbit/s | 37.7 Mbit/s | 294 Mbit/s |
| MASQUE-UDP | — | — | — |
| Fortinet | — | 466 Mbit/s | 308 Mbit/s |
| GlobalProtect | — | 484 Mbit/s | 397 Mbit/s |
| Cisco IPsec | 372 Mbit/s | 878 Mbit/s | 593 Mbit/s |
| Ivanti Connect Secure | — | 788 Mbit/s | 703 Mbit/s |
| SoftEther VPN | — | 1.29 Gbit/s | 1.11 Gbit/s |
| AmneziaWG | 557 Mbit/s | 955 Mbit/s | 557 Mbit/s |
| L2TPv3 | 383 Mbit/s | 1.31 Gbit/s | 387 Mbit/s |
| pq-ikev2 | — | 757 Mbit/s | 390 Mbit/s |
| pq-openvpn | 982 Mbit/s | 979 Mbit/s | 802 Mbit/s |
| pq-ssh | 347 Mbit/s | 127 Mbit/s | 98.9 Mbit/s |
| pq-anyconnect | — | — | 683 Mbit/s |
| pq-fortinet | — | — | 360 Mbit/s |
| pq-gp | — | — | 745 Mbit/s |
| pq-pulse | — | — | 663 Mbit/s |
| pq-sstp | — | — | 341 Mbit/s |
| pq-masque | — | — | 545 Mbit/s |
| pq-softether | — | — | 1.07 Gbit/s |
| TOY* | 25.8 Mbit/s | 26 Mbit/s | 671 Mbit/s |
Generated by the interop workflow from 7c4eaf8 on 2026-10-20.
The suite includes detailed benchmarks covering the two performance-critical paths — per-packet data-plane throughput and per-connection handshake cost — plus the underlying primitives. Run them all with:
./bench.sh # all benchmarks
./bench.sh -benchtime 3s # longer runs for stable numbers
BENCH=ESP ./bench.sh # only ESP data-plane benchmarksor directly with go test -bench . -benchmem ./....
They measure the data plane (ESP/pump, WireGuard, OpenVPN, Nebula and DTLS across 64/576/1400-byte packets), the per-protocol framing paths, the IKEv2/IKEv1 handshakes, and the asymmetric/login/codec primitives. Representative results (Intel Xeon @ 2.8 GHz, Go 1.26, single core):
| Benchmark | Throughput / latency | Allocs | Notes |
|---|---|---|---|
| ESP decap AES-256-GCM, 1400 B | ~2030 MB/s | 1 | inbound data-plane cipher |
| ESP encap AES-256-GCM, 1400 B | ~1640 MB/s | 2 | outbound data-plane cipher |
| Pump inbound AES-256-GCM, 1400 B | ~1990 MB/s | 1 | demux + decap + TUN write |
| ESP decap AES-256-CBC+SHA256, 1400 B | ~190 MB/s | 3 | ~10× slower than GCM |
| DH Curve25519 (generate + compute) | ~53 µs each | — | handshake asymmetric cost |
| DH MODP-2048 compute | ~3.9 ms | — | ~70× slower than Curve25519 |
| Full PSK handshake | ~370 µs | 406 | end-to-end over UDP loopback |
| Full EAP-MSCHAPv2 auth | ~16 µs | — | per-login CPU cost |
| Parse IKE_SA_INIT message | ~270 ns | 4 | codec |
Two takeaways the numbers make concrete: AES-GCM is dramatically faster than AES-CBC+HMAC on this data path (hence the GCM-first default), and the elliptic- curve groups are orders of magnitude cheaper than MODP-2048 for the handshake (hence Curve25519 first).
The complete go test -bench result set — regenerated by CI on every push to
main — the per-package breakdown of what each benchmark covers, and the data-plane
allocation-tuning writeup are in doc/benchmarks.md.
These are deliberate boundaries for a readable, self-contained implementation — each a localized extension point, not a structural rework:
- Client and server, Linux data path. Both roles are implemented, but the TUN
data path and route installation are Linux-only (other platforms compile;
OpenTUNand routing return errors). The IKE/handshake code is portable. - PSK, EAP-MSCHAPv2 and X.509 certificate auth. Certificate authentication
is the RFC 7427 Digital Signature (AUTH method 14) with RSA or ECDSA, plus the
legacy RSA method (1) for a peer that does not offer RFC 7427 — client and
server, mutually verified against a CA and bound to the peer's IKE identity;
it interoperates with strongSwan's
pubkeyauth. The classic per-curve ECDSA methods (9/10/11) and RSA-PSS are not produced, and EAP remains MSCHAPv2 only (TLS/PEAP/GTC out of scope). MSCHAPv2 is dated and needs recoverable passwords server-side, but it is the interoperable username/password choice. - Child SA rekey is fresh-only.
CREATE_CHILD_SAtreats rekey as a fresh child and the message-ID window accepts only the next expected request. IKEv2 does implement MOBIKE (RFC 4555UPDATE_SA_ADDRESSES, so a roaming peer survives an address change without re-handshaking), IKE fragmentation (RFC 7383 — it negotiates support, reassembles inbound SKF fragments, and fragments its own output above 1280 octets, which certificate authentication needs: an RSA chain puts IKE_AUTH near 2 KB in both directions) and the RFC 7296 §2.6 cookie exchange; every server bounds unauthenticated work throughdataplane.Gate. - IPsec through a network that blocks UDP.
-tcpcarries IKE and ESP over one length-prefixed TCP connection (RFC 8229, updated by RFC 9329), verified against libreswan in both roles — the only open-source implementation of either. On the server it is additive: the UDP sockets stay bound and a peer is answered on whichever transport it arrived on, so turning it on cannot break an existing deployment. On the client-portthen names the TCP port and defaults to 4500, so a network permitting only 443 outbound needs one flag. It is a worse transport than UDP wherever UDP works — a datagram protocol on a reliable ordered stream blocks head-of-line — anddoc/security.mdsays what it does and does not buy. - Client liveness and SA rekey are unified across protocols. A
cross-protocol monitor (
client.Prober, applied automatically byclient.Dial) detects a dead peer and tears the tunnel down for a clean re-dial. IKEv2 runs RFC 7296 dead-peer detection (an emptyINFORMATIONALthe server must answer); WireGuard probes with a handshake, which doubles as a rekey; pump-based protocols expose an authenticated-idle signal (dataplane.Pump.IdleFor), which TOY uses. Reliable-transport protocols (SSTP, SSH, AnyConnect, MASQUE, Fortinet) surface a dead peer through the transport's own read failure, so they need no probe. IKEv2 also rekeys both its SAs proactively before their soft lifetimes: the Child SA with aCREATE_CHILD_SAwhose fresh keys are swapped into the data path before the old SA is deleted, and the IKE SA itself (RFC 7296 §2.18) with a fresh Diffie-Hellman exchange for a new control channel — the Child SAs inherited unchanged, so the data path never pauses. Neither lets a long-lived tunnel expire in place. - Dual-stack inner traffic, IPv4 or IPv6 underlay; single IKE SA per Child.
IKEv2 carries both IPv4 and IPv6 inner traffic over one Child SA: the server
assigns a v4 and a v6 address via config mode (
INTERNAL_IP4_*and theINTERNAL_IP6_ADDRESSaddress+prefix, RFC 7296 3.15), offers v4+v6 traffic selectors, and the data path tags each packet with the ESP next-header its version implies (4 or 41); oversized inner v6 gets an ICMPv6 Packet Too Big, the v6 counterpart of the IPv4 fragmentation-needed path. The outer transport runs over either family too: the client dials a v4 or v6 server, and the server binds the family of its-listenaddress (0.0.0.0for IPv4 by default,::for an IPv6/dual-stack socket that serves both). Serving both families simultaneously is what the one::dual-stack socket provides; separate v4+v6 sockets per port are not added. This is one IKE SA per Child, which is deliberately road-warrior rather than a site-to-site multi-SA gateway — see doc/security.md for what that forecloses and why the boundary is drawn there. - Downstream flow shaping is opt-in, and covers sizes rather than timing.
One inner packet becomes one outer datagram, so the size pattern of an inner
TLS handshake otherwise survives encapsulation — the fingerprint of
USENIX Security '24,
which byte-level obfuscation does not address.
veepin serve <protocol> -shape <bytes>pads the first N bytes of each inner flow out to the tunnel MTU on all sixteen protocols — RFC 4303 §2.7 TFC padding for ESP (IKEv2, Cisco IPsec, GlobalProtect, Ivanti), trailing octets for WireGuard and AmneziaWG, the RFC 1661 §5.1 PPP Information field for SSTP, Fortinet and L2TP/IPsec, the length-delimited data payload for AnyConnect and OpenVPN, and trailing filler on the IP-bearing frames of an L2TPv3 pseudowire or a SoftEther layer-2 segment, trailing filler on an SSH tunnel channel, and — inside the sealed or length-covered payload, because neither has room after it — a Nebula transport message and a MASQUE DATAGRAM capsule. All are inert to a conforming receiver, which delimits the real packet by the inner IP header, so stock clients benefit unmodified; and because the attack targets handshakes, the cost is per-flow rather than per-byte, leaving bulk throughput untouched. It does not shape packet counts or timing, does not cover the upstream direction unless the client is also veepin, and is not probe resistance. Packet counts and timing are a different mechanism and IKEv2 now has one:-iptfs -iptfs-ratetransmits at a fixed rate regardless of load (RFC 9347), so the datagram stream stops depending on the traffic inside it. It is IKEv2 only, costs its rate continuously, and is off by default — seedoc/security.md. Interop cells prove strongSwan, wireguard-go,openvpn, pppd and openconnect all accept the padding and trim it correctly; it stays off by default because the vendor OS stacks it is meant to protect are untested —doc/verifying-shaping.mdis the procedure for changing that, and it needs a person with a device rather than more code. Seedoc/traffic-shaping.mdfor the design and for what it does not hide. - AnyConnect's DTLS needs TLS 1.3 or Extended Master Secret (RFC 7627) — Go's
crypto/tlswill not run the RFC 5705 exporter otherwise, so against such a peer the client stays on TLS. Only PSK-NEGOTIATE mode; auth is username/password only (no client certificates or SSO flows). - L2TP/IPsec requires UDP-encapsulated ESP. No raw IP-protocol-50 path, so it always forces the NAT-T float to UDP/4500. IKEv1 is Main Mode + PSK only (no Aggressive Mode, certificates, or Quick-Mode PFS), one child SA with no phase-2 rekey, MS-CHAPv2 only.
The security boundaries — no key zeroization, single-core throughput, and
MASQUE's capsule-mode head-of-line blocking — are stated separately in
doc/security.md.