The DNSCrypt Protocol for Developers: Spec, Stamps and Servers

Hop 01

The dnscrypt protocol message flow

A client starts with a provider name, a 32-byte Ed25519 provider public key and the server’s address. It sends a plain TXT query for the provider name, of the form 2.dnscrypt-cert.example.com, first over UDP and over TCP on failure. Every TXT record in the answer holds one binary certificate, never hex or base64 encoded.

A certificate starts with the magic bytes 0x44 0x4e 0x53 0x43, followed by the encryption system version, a minor version, a 64-byte Ed25519 signature, the resolver’s short-term public key, an 8-byte client magic, a serial and a validity window. For the Box-XChaChaPoly system it is 124 bytes without extensions. The client verifies the signature and keeps the highest valid serial.

An encrypted query is the client magic, the client’s X25519 public key, half of the nonce and the boxed DNS message. The plaintext is padded in ISO/IEC 7816-4 style, a 0x80 byte followed by zeros. The resolver answers with its own magic and the other nonce half, and refuses anything with a bad key exchange, tag or padding.

Transport rules are short. Clients and resolvers must support TCP and should support UDP, with port 443 recommended for both. Responses that do not fit are truncated with the TC bit set before padding and encryption, so the client retries over TCP. Certificates must be refreshed before they expire, and the draft considers an hourly refresh suitable.

Hop 02

libsodium and the dnscrypt protocol primitives

Everything the classical encryption system needs is in libsodium, a portable fork of NaCl: X25519 for key exchange, XChaCha20 and XSalsa20 stream ciphers, Poly1305 authentication and Ed25519 signatures. Its default crypto_box is X25519 with XSalsa20 and Poly1305, the older DNSCrypt construction, so the current XChaCha20 system needs the dedicated XChaCha20 functions instead.

dnscrypt-wrapper, a server written in C, requires libsodium and libevent, and the original C version of dnscrypt-proxy depended on libsodium as well. The v1 wiki comparison notes that its XChaCha20 support only worked when compiled against a recent libsodium. Recent libsodium documentation also covers ML-KEM-768, one half of the post-quantum construction.

Hop 03

DNSCrypt server implementations

The table summarises the server side as listed on dnscrypt.info/implementations and checked against each project’s own documentation in October 2026. Any of them can turn an existing recursive resolver into a dnscrypt server; only some of them can also act as an Anonymized DNSCrypt relay or generate their own provider keys.

Server	Language	DNSCrypt notes
encrypted-dns-server	Rust	DNSCrypt v2 incl. PQDNSCrypt, Anonymized DNSCrypt relay, DoH forwarding on the same port; needs a recursive resolver such as Unbound, Knot or PowerDNS
dnscrypt-server-docker	Docker image	Bundles a caching resolver with encrypted-dns-server and setup scripts
dnscrypt-wrapper	C	Server-side proxy in front of any resolver; requires libsodium and libevent
dnsdist	C++	DNSCrypt binds via addDNSCryptBind() or YAML binds; generates provider keys from its console
Unbound	C	Built with --enable-dnscrypt; options dnscrypt-enable, dnscrypt-port, dnscrypt-provider; keys come from dnscrypt-wrapper

encrypted-dns-server covers the most ground in the table: it serves DNSCrypt, Anonymized DNSCrypt relaying and DoH forwarding on one port, usually 443, and detects the protocol per client. Unbound’s manual is strict about details, such as the provider name having to end with a dot. For a first public server, the Docker image is the shortest path.

Hop 04

DNS stamps: one string per server

DNS stamps encode connection parameters as sdns:// followed by base64url of a binary record. The first byte names the protocol: 0x01 DNSCrypt, 0x02 DoH, 0x03 DoT, 0x04 DoQ, 0x05 an ODoH target, 0x81 an Anonymized DNSCrypt relay, 0x85 an ODoH relay and 0x00 plain DNS. Length-prefixed fields follow, and base64 is applied only once, to the whole record.

For DNSCrypt, a stamp holds a 64-bit properties field, the address with an optional port, the raw provider key and the provider name. Property bits mark DNSSEC support (1), no logging (2) and no intentional blocking (4). The stamps specification lists libraries for Go, Rust, .NET, Python, JavaScript and Swift, and stamps.dnscrypt.info decodes or builds a stamp in the browser.

Hop 05

From the v1 plugin API to v2 Go code

dnscrypt-proxy 1.x was written in C and offered a plugin API in C, which in practice required libldns to handle DNS packets. The v2 rewrite in Go replaced it: custom additions are simple Go structures built on the miekg/dns library. The project wiki’s comparison of the two versions lists this change alongside asynchronous filters and multicore support.

Hop 06

Where to start

Read the draft end to end, then decode a few real stamps from the resolver directory to see live parameters. Implement certificate retrieval first and test it against a public server before encrypting anything. The DNSCrypt vs DoH comparison and the glossary cover the terms used throughout the dnscrypt protocol specification.