A fork of MasterDnsVPN (a VPN tunnel carried in DNS queries and TXT answers), based on upstream commit b996849db0c1856024af6a00b39cd304e23dbe11.
The wire format of this fork is not compatible with upstream clients or servers. Do not point an upstream client at this server or the other way round.
- One credential per device. Each device has an 8-byte
kidand a 32-byte key. The server looks the device up bykidin an index that the embedding application can replace atomically; closing the sessions of one device does not touch another. Upstream has a single key shared by every client. - Authenticated encryption in both directions. Every session frame is ChaCha20-Poly1305; nothing of the tunnel except the session id and a frame counter is readable on the wire.
- Session setup with fresh keys. A timestamped INIT under the device key carries an ephemeral X25519 key, the answer carries the server's, and per-direction keys are derived with HKDF-SHA256. Recording the traffic and later stealing the device key does not reveal past sessions.
- Replay protection. A 32-bit frame counter doubles as the AEAD nonce; each side keeps a 2048-frame replay window. A replayed frame gets an empty answer. A replayed INIT gets the identical cached answer and no second session.
- One cipher. The other cipher modes, the shared key file, the session cookie, the header checksum and the compression (zstd, lz4, zlib, with their dependencies) are removed.
- Pre-session MTU probes are authenticated with the device key, are accepted once, only while fresh, and are limited to 60 per minute per device.
- A protocol version byte makes a future incompatible change refuse cleanly.
- A proper DNS server face. Answers use a compression pointer instead of repeating the question name (the answer carries about 35 % more payload: 865 instead of about 640 bytes at an EDNS size of 1232), have their own OPT record and echo none of the query's, and a zone is an authoritative zone: an SOA, NS and A record at the apex, empty NOERROR answers inside the zone, REFUSED outside it, TC=1 and TCP 53.
- The server cannot be used to amplify an attack. An answer to a query that did not authenticate is never longer than the query; otherwise it is an empty answer with TC=1. Answers per source network are capped. Details and the measured numbers are in
MISTGATE.md. - Embeddable. The server takes DNS messages from its host and opens no socket; the host supplies the
DialandResolveDNShooks that decide where tunneled connections and DNS queries go. The client opens tunneled connections asnet.Connvalues and needs no local proxy. - Smaller limits by default: 4 KiB read buffer, 1024-request queue, 64 streams per session, 64 sessions, 2 sessions per device, ARQ window 512, 20 s connect timeout, 2000 queries per second per session.
The ARQ, resolver balancing, discovery and MTU selection code is kept as upstream.
MISTGATE.md lists every changed file with the reason, the limits and the worst-case memory, and describes how newer upstream revisions are merged.
import mgdns "masterdnsvpn-go" (the module is masterdnsvpn-go, replaced by this repository in the embedding module's go.mod).
// server side: the host owns the sockets
server, _ := mgdns.NewServer(mgdns.ServerConfig{
Domains: []string{"k3x9ab.t.example.com"},
NSName: "ns-k3x9ab.t.example.com",
NSAddress: netip.MustParseAddr("192.0.2.10"),
CheckKey: key,
Dial: func(ctx context.Context, credentialID, network, address string) (net.Conn, error) { ... },
ResolveDNS: func(ctx context.Context, credentialID string, query []byte) ([]byte, error) { ... },
})
server.Start(ctx)
server.SetCredentialIndex(index) // mgdns.NewCredentialIndex(mgdns.ParseCredential("<kid>.<key>")...)
answer := server.HandleQuery(src, packet, 0, false) // UDP; true for a message read from a TCP frame
server.CloseCredential(id) // kick
server.Sessions() // credential, resolver address, age, counters// client side: no listener, no file
client, _ := mgdns.NewClient(mgdns.ClientConfig{
Domains: []string{"k3x9ab.t.example.com"},
Credential: "<kid>.<key>",
Resolvers: []netip.AddrPort{...}, // numbers; subnets are not expanded
Control: func(network, address string, c syscall.RawConn) error { ... }, // every resolver socket
LoadRanking: ..., SaveRanking: ...,
})
client.Start(ctx) // lazy: the session starts at the first dial
conn, err := client.DialContext(ctx, "tcp", "example.org:443") // the server resolves the name
answer, err := client.ResolveDNS(ctx, query)There is no UDP through the tunnel: only TCP streams and DNS queries.
cmd/server and cmd/client still run on their own for testing. Each reads one credential, DEVICE_CREDENTIAL = "<16 hex kid>.<key>", where the key is 64 hex characters or 43 base64url characters without padding, from its config (or the -device-credential flag). The server also answers over TCP on the same address and port (TCP_ENABLED). Applications that embed the server supply the whole credential set through the credential index instead.
git diff b996849d mistgate
MIT, unchanged. The upstream copyright notice is kept in LICENSE.