A UDP-based, pre-shared-key (PSK), user-mode VPN written in Rust on the tokio async runtime.

ShadowVPN is a fixed point-to-point / multi-client tunnel. A TUN-based client reads IP packets from a virtual interface, encrypts each as a single UDP datagram, and sends it to the server; the server decrypts, routes, and tunnels return traffic back. It runs on macOS (utun) and Linux, and the client also runs on Windows (TUN via Wintun), including policy routing (below).

The on-wire crypto matches the shadowsocks.org AEAD UDP scheme exactly, so the construction is spec-correct and interoperable, with one deliberate, documented deviation (no SOCKS address header — see below).

Landing page: a visual overview lives at madeye.github.io/shadowvpn (source in docs/).

Each UDP datagram on the wire is:

[ salt (salt_len bytes) ] ++ [ AEAD ciphertext ++ tag (16 bytes) ]

• salt_len == key_len of the cipher: 16 bytes for aes-128-gcm, 32 bytes for aes-256-gcm and chacha20-poly1305. A fresh random salt is generated for every datagram.
• Subkey: subkey = HKDF-SHA1(ikm = master_key, salt = salt, info = "ss-subkey", L = key_len).
• Nonce: the all-zero 12-byte nonce for every UDP packet. This is safe because each datagram has a unique random salt and therefore a unique subkey, so the (subkey, nonce) pair is never reused.
• Master key: derived from the password string with shadowsocks' EVP_BytesToKey (the OpenSSL legacy MD5-based KDF): repeatedly compute d_0 = MD5(password), d_i = MD5(d_{i-1} ++ password), and concatenate until key_len bytes are available. (Implemented in-tree; no external crate.)
• Plaintext: the raw IP packet read from the TUN device. UDP datagram boundaries are the frame boundaries — there is no length prefix, no multiplexing, and no reassembly. One IP packet maps to exactly one datagram.

Standard shadowsocks UDP relays prepend a SOCKS-style target address to the plaintext. ShadowVPN does not. This is a fixed point-to-point tunnel, not a SOCKS proxy: the plaintext is exactly the raw IP packet, with no address header. Everything else (salt, HKDF-SHA1 "ss-subkey" subkey, zero nonce, AEAD tag) matches the shadowsocks UDP AEAD scheme byte-for-byte. This deviation is also documented in src/crypto.rs and src/protocol.rs.

The client periodically sends a tiny encrypted datagram (a 1-byte 0x00 plaintext) so that stateful NAT/firewall mappings stay open and the server learns the client's current source address before any real traffic flows. The server drops any decrypted payload smaller than a 20-byte IPv4 header, so the keepalive never reaches the TUN write path.

All ciphers are AEAD, from the RustCrypto project. Nonce length is 12 bytes and tag length is 16 bytes for all three.

The alias chacha20-ietf-poly1305 is accepted and treated as chacha20-poly1305. The default cipher (when none is specified) is chacha20-poly1305.

chacha20-poly1305 uses runtime SIMD feature detection, so it is fast out of the box on every target. AES-GCM uses AES-NI automatically on x86-64, but on aarch64 (Raspberry Pi, Apple Silicon, Windows-on-ARM) the ARMv8 AES backend is gated behind compile-time target features — a plain cargo build for ARM runs AES-GCM in slow constant-time software. So:

• On ARM hardware that lacks (or isn't built for) AES acceleration, prefer chacha20-poly1305 — it is both faster and simpler there.
• To use AES-GCM at full speed on ARM, build with the crypto features enabled, e.g. RUSTFLAGS="-C target-feature=+aes,+neon" cargo build --release (or -C target-cpu=native when building on the device itself).

By default the UDP payload on the wire is the bare salt ++ AEAD envelope. The optional obfs field shapes that payload so it doesn't read as an opaque random-looking UDP blob, to evade naive protocol classification. It is selected with the obfs config field and both ends must agree — a mismatched peer just sees its traffic dropped.

This is cosmetic framing only: it adds no security. The AEAD envelope underneath is unchanged, and a wrong/absent obfuscation simply fails to decode (the packet is dropped before decryption).

Set it in both config files (it has no CLI flag):

{
  "server": "vpn.example.com:8388",
  "password": "correct horse battery staple",
  "obfs": "quic"
}

The server logs the active mode in its startup banner. The wire formats are documented in src/obfs.rs.

Configuration can come from a JSON config file, CLI flags, or both. CLI flags take precedence over JSON file values. Defaults are applied for anything not supplied.

On the server the server field is the UDP bind/listen address; on the client it is the remote server address to connect to. Both binaries accept -c, --config <PATH> to point at a JSON file.

{
  "server": "0.0.0.0:8388",
  "password": "correct horse battery staple",
  "cipher": "chacha20-poly1305",
  "tun_name": "utun7",
  "tun_ip": "10.9.0.1",
  "tun_netmask": "255.255.255.0",
  "peer_ip": "10.9.0.2",
  "mtu": 1400
}

{
  "server": "vpn.example.com:8388",
  "password": "correct horse battery staple",
  "cipher": "chacha20-poly1305",
  "tun_name": "utun7",
  "tun_ip": "10.9.0.2",
  "tun_netmask": "255.255.255.0",
  "peer_ip": "10.9.0.1",
  "mtu": 1400
}

Note how tun_ip and peer_ip are mirror images: the server's local tunnel IP is the client's peer, and vice versa.

A client config can be exported as a single shadowvpn:// URI (the config JSON, URL-safe Base64) and imported back — handy for moving a config to another device by copy-paste or by scanning a QR code. This lives in a separate shadowvpn-uri binary so the server/client builds stay lean; build it with the uri feature (off by default):

cargo build --release --features uri --bin shadowvpn-uri

# Print the shadowvpn:// URI for a config…
shadowvpn-uri export -c client.json

# …or also render a scannable QR code to the terminal:
shadowvpn-uri export -c client.json --qr

# Import a URI back into a JSON config (omit -o to print to stdout):
shadowvpn-uri import 'shadowvpn://…' -o client.json

# Import by decoding a QR-code image instead of pasting the URI:
shadowvpn-uri import --image config-qr.png -o client.json

# Render an existing shadowvpn:// URI as a terminal QR code (also reads stdin):
shadowvpn-uri qr 'shadowvpn://…'

The URI carries every config field, but file-path fields (gfwlist, chnroute, geoip, cache_file) are only meaningful on the host that has those files — re-point them after importing. When several clients share one server, either give each a distinct tun_ip, or run the server with --nat (below) so every client can share one identical config.

By default the server routes by learning each client's inner tunnel source IP, so clients must use distinct tun_ips. With --nat the server instead tells clients apart by their UDP endpoint and maps each onto a distinct internal IP drawn from the TUN subnet, rewriting inner addresses as packets pass through. Every client can then run the same static config (same placeholder tun_ip) — no per-client setup, and no IP-assignment handshake (0-RTT: a client just starts sending).

Server — add "nat": true (or --nat):

{
  "server": "0.0.0.0:8388",
  "password": "correct horse battery staple",
  "tun_ip": "10.9.0.1",
  "tun_netmask": "255.255.255.0",
  "peer_ip": "10.9.0.2",
  "nat": true
}

Clients — all run the ordinary static config, identical on every device:

{
  "server": "vpn.example.com:8388",
  "password": "correct horse battery staple",
  "tun_ip": "10.9.0.2",
  "tun_netmask": "255.255.255.0",
  "peer_ip": "10.9.0.1"
}

How it works: the server keys a mapping by the client's UDP 4-tuple, allocates a free internal IP from the subnet (network/broadcast/server excluded), and rewrites the inner source on ingress (placeholder → internal) and destination on egress (internal → placeholder), fixing IPv4/TCP/UDP checksums incrementally. Mappings are refreshed by traffic (data or the 25-second keepalive) and reclaimed after lease_ttl_secs idle (default 120). Trade-offs: clients cannot address each other (they share one placeholder — it's hub-and-spoke to the server and beyond), and ICMP error payloads that embed the original header aren't rewritten (tunnelled PMTU discovery may suffer). The per-packet cost is a couple of checksum deltas, negligible next to the AEAD.

Requires a recent stable Rust toolchain (edition 2021).

cargo build --release

This produces two binaries:

• target/release/shadowvpn-server
• target/release/shadowvpn-client

Run the test suite (crypto + config unit tests):

cargo test --lib

It also builds on Windows (x86_64-pc-windows-msvc / aarch64-pc-windows-msvc) with the MSVC toolchain; CI builds and tests the Windows target on every push. The client's TUN layer uses Wintun, whose wintun.dll is loaded at runtime and must sit next to shadowvpn-client.exe — download the build matching the CPU architecture and drop it alongside the binary. See scripts/ for a ready-made launcher.

A full data-path test lives under docker/. It builds both binaries, starts a server and a client container — each with its own TUN device — on a private bridge network, and then pings the server's in-tunnel address from the client. A successful, lossless ping exercises the entire path: TUN → encrypt → UDP → server → decrypt → TUN, and the reply all the way back.

./docker/run-e2e.sh                 # default cipher (chacha20-poly1305)
./docker/run-e2e.sh aes-256-gcm     # any supported cipher

The containers need NET_ADMIN and /dev/net/tun (the compose file requests both). The script exits non-zero if connectivity through the tunnel fails, so it doubles as the CI gate (see .github/workflows/ci.yml, which runs it across all three ciphers alongside fmt + clippy + unit tests).

A second, more demanding test proves ShadowVPN carries arbitrary UDP traffic by running real HTTP/3 (QUIC) through the tunnel. The server enables IP forwarding and masquerades the tunnel subnet to the internet; the client routes all egress through the tunnel (its default route is deleted, so the only way out is via ShadowVPN) and fetches a QUIC site with an HTTP/3-only curl:

./docker/run-e2e-http3.sh                       # default: https://www.cloudflare-quic.com/
TARGET_URL=https://cloudflare-quic.com/ ./docker/run-e2e-http3.sh aes-256-gcm

The test passes when the response is delivered over HTTP/3 (http_version=3); the application status code is irrelevant (Cloudflare may bot-block with 403 — the point is that the QUIC handshake and HTTP/3 exchange completed over the tunnel). It runs on a private bridge network with any host proxy neutralized, so QUIC must travel through ShadowVPN rather than around it. In CI this job runs on pushes to main and on manual dispatch (it depends on external connectivity).

Exercises policy routing end to end. The topology puts a source-IP echo server behind the tunnel and another on the LAN: a tunneled request shows up as the server's address, a direct one as the client's, so the two paths are unambiguous. It verifies that both modes tunnel the selected domain and leave the other direct:

./docker/run-e2e-policy.sh             # both gfwlist and chinadns
./docker/run-e2e-policy.sh gfwlist     # one mode

Fully self-contained (no external network), so CI runs it on every PR.

docker/run-bench.sh measures the data plane over an emulated internet path. A server and client container share a private bridge that stands in for the public internet; both apply a tc netem qdisc (delay, jitter, loss, bandwidth) to it. The client then measures latency and TCP/UDP throughput through the tunnel and, for comparison, directly over the same shaped link — so the gap is ShadowVPN's own overhead (crypto + obfs + MTU), not the link.

./docker/run-bench.sh                                 # ~100 Mbit broadband-ish
OBFS=quic CIPHER=aes-256-gcm ./docker/run-bench.sh    # with QUIC carrier shaping
DELAY=80ms LOSS=1% RATE=20mbit ./docker/run-bench.sh  # lossy mobile-ish link

Scenario knobs (all environment variables, with defaults): CIPHER, OBFS (none/quic/base64), MTU, DELAY (one-way; RTT ≈ 2×), JITTER, LOSS, RATE, DURATION, UDP_RATE. The run prints a summary table — for example, a clean ~100 Mbit/s broadband path (RTT ≈ 48 ms, 0 % loss) with the default cipher:

 Metric                       Tunnel        Direct(WAN)
 RTT (ms)                     45.2            47.4
 TCP upload   (Mbit/s)        87.6            92.8
 TCP download (Mbit/s)        88.2            83.0
 UDP @ 50M (Mbit/s)           50.0            50.0
 UDP loss (%)                 0.00            0.00

Both columns cross the same shaped link, so the gap is ShadowVPN's own overhead — at ~100 Mbit/s the tunnel runs at or near line rate. When the link is not the limit the data plane's own ceiling shows: the pipelined relay loops carry single- flow TCP at ~1 Gbit/s (≈3× a strict per-packet recv → crypt → send loop). Full results across ciphers, carrier framing, a lossy/high-latency link, and that ceiling comparison — plus how to read them — are in docs/BENCHMARKS.md.

Needs NET_ADMIN and /dev/net/tun (requested by the compose file). It is a measurement tool, not a CI gate — the absolute numbers depend on the host.

Creating a TUN device requires elevated privileges (root on Linux, sudo on macOS, Administrator on Windows). Both binaries log to stderr; set RUST_LOG=debug for verbose tracing.

sudo ./target/release/shadowvpn-server -c server.json

Or entirely via CLI flags:

sudo ./target/release/shadowvpn-server \
  --listen 0.0.0.0:8388 \
  --password "correct horse battery staple" \
  --cipher chacha20-poly1305 \
  --tun-ip 10.9.0.1 \
  --peer-ip 10.9.0.2

sudo ./target/release/shadowvpn-client -c client.json

Or via CLI flags:

sudo ./target/release/shadowvpn-client \
  --server vpn.example.com:8388 \
  --password "correct horse battery staple" \
  --cipher chacha20-poly1305 \
  --tun-ip 10.9.0.2 \
  --peer-ip 10.9.0.1

Once the tunnel is up you can verify connectivity with a ping across the tunnel addresses, e.g. from the client ping 10.9.0.1.

Put shadowvpn-client.exe, wintun.dll (matching the CPU architecture), and your client.json in one folder, then run from an elevated PowerShell:

.\shadowvpn-client.exe -c client.json

Wintun and the routing/DNS changes need Administrator, so launch the terminal with Run as administrator. Stop the client with Ctrl-C for a graceful shutdown (it restores the system resolver, removes the per-destination routes, and saves the DNS cache); avoid taskkill /F, which skips that cleanup.

The scripts/ folder has a self-elevating launcher that does this for you — shadowvpn-client.cmd (or shadowvpn-client.ps1 -Config <path>); see scripts/README.md.

Example service definitions live in dist/: systemd units for the Linux server and client, and a launchd daemon for the macOS client. See dist/README.md for install steps. Stopping the client service is graceful — it restores the system resolver, removes the tunnel routes, and saves the DNS cache. On Windows, use the launcher in scripts/ (foreground; stop with Ctrl-C).

By default the client is a full tunnel: every packet that reaches the TUN is encrypted to the server, and what you route into the TUN is your business (see the next section). For the common case of "send only some destinations through the tunnel", the client has a built-in policy-routing mode — no external daemon, and no ipset/iptables/nft required.

A small split-DNS proxy runs inside the client. For each query it decides whether the name should be tunneled and, for those that should be, programs a per-destination host route (<ip>/32) into the tun device using the OS's native routing socket — rtnetlink on Linux, PF_ROUTE on macOS — so the work is done entirely in user mode. The route's source is the tun address, so the server's masquerade matches with no client-side NAT. Direct (non-tunneled) traffic stays on the normal kernel path untouched, and every route added is removed again on exit.

The proxy is built for low latency:

• Cache — answers are cached (TTL-respecting, like dnsmasq) so repeat lookups skip the upstream round-trip.
• chinadns fast-path — the local and clean resolvers are queried concurrently, but a domestic answer returns immediately instead of waiting for the slower tunneled upstream, so China sites resolve at local-DNS speed.
• Pre-warm — on startup a built-in list of common domains is resolved in the background, so their first real lookup (and their tunnel routes) are already hot. Customize with the prewarm config list or disable with --no-prewarm.
• Persistence — the cache is saved on exit and reloaded on startup (--cache-file, default dns-cache.json next to the binary; --no-cache-persist to disable), so a restart doesn't start cold.

Two modes:

# gfwlist mode: tunnel only the domains in gfwlist.txt
sudo ./target/release/shadowvpn-client -c client.json \
  --mode gfwlist --gfwlist /etc/shadowvpn/gfwlist.txt

# chinadns mode: tunnel everything that isn't a China IP (CIDR file)
sudo ./target/release/shadowvpn-client -c client.json \
  --mode chinadns --chnroute /etc/shadowvpn/chnroute.txt

# chinadns mode: derive the China set from a GeoLite2 database instead
sudo ./target/release/shadowvpn-client -c client.json \
  --mode chinadns --geoip /etc/shadowvpn/GeoLite2-Country.mmdb

# chinadns mode + a gfwlist force list: domains on the list always tunnel,
# even if the domestic resolver returns an in-China (poisoned) address
sudo ./target/release/shadowvpn-client -c client.json \
  --mode chinadns --geoip /etc/shadowvpn/GeoLite2-Country.mmdb \
  --gfwlist /etc/shadowvpn/gfwlist.txt

Policy routing only takes effect for names resolved through the proxy (that's what installs the routes), so the system resolver must point at it. By default the client does this for you: on startup it points the OS resolver at the proxy (networksetup on macOS, /etc/resolv.conf on Linux) and restores the previous setting on exit — including on Ctrl-C / SIGTERM, which it handles for a clean shutdown. Pass --no-set-dns to manage DNS yourself instead. Automatic setup only applies when dns_listen uses port 53 (the OS resolver can't target a custom port) — which is the default, so it works out of the box; if you move the proxy to another port, point your resolver at it manually.

Relevant config / flags (all client-only; CLI overrides JSON):

• gfwlist file — one domain per line; #/! comments and a leading *./. are accepted (the plain list produced by gfwlist2dnsmasq, not the base64 blob). A name matches if it equals or is a subdomain of a listed suffix.
• chnroute file — one a.b.c.d/len per line (the classic APNIC-derived chnroute.txt).
• geoip database — a MaxMind GeoLite2-Country.mmdb (or paid GeoIP2). On startup every IPv4 network whose country is --geoip-country (default CN) is enumerated and merged into the China set, so you don't have to maintain a CIDR file. Takes precedence over --chnroute when both are given.

This needs root / Administrator (to create the tun and edit the routing table) and runs on Linux, macOS, and Windows; routes are programmed directly via the OS routing interface (rtnetlink, PF_ROUTE, or the Windows IP Helper API), so no ipset/iptables/route/netsh binaries are involved for routing. The docker/run-e2e-policy.sh test exercises both modes end to end. (The server still needs forwarding + NAT so tunneled traffic can egress — see below.)

ShadowVPN brings the TUN interface up (address, netmask, peer, MTU) but deliberately does not touch the system routing table or sysctl. Doing so silently is dangerous and platform-specific. The steps below are what you run outside the process. The binaries also print these hints at startup.

So that tunneled clients can reach the wider network through the server, the server host must forward packets and NAT (masquerade) them out its WAN interface. Replace <wan-if> with the server's real outbound interface (e.g. eth0).

Linux:

sudo sysctl -w net.ipv4.ip_forward=1
sudo iptables -t nat -A POSTROUTING -s 10.9.0.0/24 -o <wan-if> -j MASQUERADE

macOS:

sudo sysctl -w net.inet.ip.forwarding=1
# Configure pf NAT, e.g. add to /etc/pf.conf:
#   nat on <wan-if> from 10.9.0.0/24 to any -> (<wan-if>)
# then: sudo pfctl -f /etc/pf.conf -e

The client must keep a host route to the server's IP via the real gateway (otherwise the encrypted UDP would loop back into the tunnel), then route the desired destinations via the tunnel peer. The two /1 routes below override the default route without deleting it.

Linux:

# Keep the server reachable over your real link (replace GW/DEV):
sudo ip route add <SERVER_IP>/32 via <YOUR_DEFAULT_GW> dev <YOUR_WAN_DEV>
# Route everything through the tunnel peer:
sudo ip route add 0.0.0.0/1 via 10.9.0.1
sudo ip route add 128.0.0.0/1 via 10.9.0.1

macOS:

# Keep the server reachable over your real link (replace GW):
sudo route -n add -host <SERVER_IP> <YOUR_DEFAULT_GW>
# Route everything through the tunnel peer:
sudo route -n add -net 0.0.0.0/1 10.9.0.1
sudo route -n add -net 128.0.0.0/1 10.9.0.1

Windows (elevated prompt):

:: Keep the server reachable over your real link (replace GW):
route add <SERVER_IP> mask 255.255.255.255 <YOUR_DEFAULT_GW>
:: Route everything through the tunnel peer:
route add 0.0.0.0 mask 128.0.0.0 10.9.0.1
route add 128.0.0.0 mask 128.0.0.0 10.9.0.1

To stop using the tunnel, delete the routes you added. If the server is given as a hostname rather than a literal IP, resolve it first and add the host route for that resolved IP.

src/
  lib.rs          crate root + module docs
  crypto.rs       Cipher enum, EVP_BytesToKey, HKDF-SHA1 subkey, AEAD seal/open
  net.rs          UDP socket construction with enlarged SO_RCVBUF/SO_SNDBUF
  protocol.rs     tunnel framing constants and buffer sizing
  config.rs       JSON file + clap CLI config, merge/validate
  tun_device.rs   async TUN wrapper (tun-rs: macOS utun, Linux, Windows Wintun)
  policy/         client policy routing (gfwlist / chinadns, user-mode)
    mod.rs        Mode, PolicyConfig, orchestration
    gfwlist.rs    domain-suffix matching
    chnroute.rs   China IP range lookup
    geoip.rs      build the China set from a GeoLite2 .mmdb
    dns.rs        minimal DNS wire parsing
    cache.rs      TTL-respecting DNS answer cache
    proxy.rs      split-DNS proxy + routing decisions (IpSink trait)
    route.rs      per-dest routes into the tun (rtnetlink / PF_ROUTE / IP Helper API)
    dnsconf.rs    point the system resolver at the proxy (networksetup / resolv.conf / netsh)
  bin/server.rs   server binary: UDP<->TUN forwarding + client routing table
  bin/client.rs   client binary: TUN<->UDP relay loops + keepalive + policy
docs/
  index.html      landing page (GitHub Pages)
  architecture.svg, wire.svg, policy-routing.svg   diagrams
dist/
  systemd/        Linux service units (server + client)
  launchd/        macOS client daemon
scripts/
  shadowvpn-client.ps1   self-elevating Windows client launcher
  shadowvpn-client.cmd   execution-policy-bypass wrapper for the launcher

MIT — see LICENSE.