This is dnscrypt wrapper (server-side dnscrypt proxy), which helps to add dnscrypt support to any name resolver.
C Shell Makefile M4
Failed to load latest commit information.
argparse Fix compiler/linker flags handling Jul 8, 2016
example update example secret key / cert, etc. Jul 11, 2016
.gitignore add configure.ac Nov 27, 2013
.gitmodules clear argparse Aug 1, 2015
.travis.yml Travis build: Sodium 0.4.1 is very old. Use at least 1.0.0. Jul 5, 2015
COPYING dnsmasq and argparse are covered by this terrible viral license calle… Jun 6, 2013
Makefile Fix compiler/linker flags handling Jul 8, 2016
README.md update example secret key / cert, etc. Jul 11, 2016
TODO support tcp protocol Nov 22, 2012
cert.c Use the certificate timestamp as a serial number Jun 9, 2016
cert.h Backward compatibility Jul 4, 2015
compat.h Add debug facilities to log stack trace in case of segment fault. May 24, 2015
config.mak.in add configure.ac Nov 27, 2013
configure.ac update example secret key / cert, etc. Jul 11, 2016
debug.c debug: still return something on non-Intel Linux systems Feb 17, 2016
debug.h Add debug facilities to log stack trace in case of segment fault. May 24, 2015
dns-protocol.h check txt query for provider name Nov 19, 2012
dnscrypt.c Accept multiple keys. Jul 5, 2015
dnscrypt.h Compatibility with very old versions of Sodium (as on Travis, sigh) Jul 5, 2015
edns.c format code Nov 27, 2013
edns.h format code Nov 27, 2013
gen-version.sh fix version gen script Aug 7, 2015
logger.c Negative file descriptors are valid descriptors. Jul 5, 2015
logger.h Add debug facilities to log stack trace in case of segment fault. May 24, 2015
main.c update example secret key / cert, etc. Jul 11, 2016
pidfile.c format code Nov 27, 2013
pidfile.h format code Nov 27, 2013
rfc1035.c Don't return a valid hash in questions_hash() to signify an error Jan 5, 2015
rfc1035.h Don't return a valid hash in questions_hash() to signify an error Jan 5, 2015
safe_rw.c format code Nov 27, 2013
safe_rw.h format code Nov 27, 2013
tcp_request.c cleanup spaces Mar 3, 2016
tcp_request.h Reorder TCPRequest and UDPRequest fields to save space due to alignment Jan 5, 2015
test.sh Bash is not required to run these scripts. Jul 5, 2015
tree.h Replace the UDP request queue with a red-black tree Jan 5, 2015
udp_request.c Clear the answers count in truncated packets Feb 29, 2016
udp_request.h Send a short packet with TC set if the query_len < response_len Feb 17, 2016
version.h release: bumped version to 0.2.1 Jun 13, 2016

README.md

Name

dnscrypt-wrapper - A server-side dnscrypt proxy.

(c) 2012-2015 Yecheng Fu

Build Status

Description

This is dnscrypt wrapper (server-side dnscrypt proxy), which helps to add dnscrypt support to any name resolver.

This software is modified from dnscrypt-proxy.

Installation

Install libsodium and libevent 2.1.1+ first.

On Linux:

$ ldconfig # if you install libsodium from source
$ git clone --recursive git://github.com/cofyc/dnscrypt-wrapper.git
$ cd dnscrypt-wrapper
$ make configure
$ ./configure
$ make install

On FreeBSD:

$ pkg install dnscrypt-wrapper

On OpenBSD:

$ pkg_add -r gmake autoconf
$ pkg_add -r libevent
$ git clone --recursive git://github.com/cofyc/dnscrypt-wrapper.git
$ cd dnscrypt-wrapper
$ gmake LDFLAGS='-L/usr/local/lib/' CFLAGS=-I/usr/local/include/

On MacOS:

$ brew install dnscrypt-wrapper

In Docker:

See https://github.com/jedisct1/dnscrypt-server-docker.

Usage

1) Generate the provider key pair:

$ dnscrypt-wrapper --gen-provider-keypair

This will create two files in the current directory: public.key and secret.key.

This is a long-term key pair that is never supposed to change unless the secret key is compromised. Make sure that secret.key is securely stored and backuped.

If you forgot to save your provider public key fingerprint:

$ dnscrypt-wrapper --show-provider-publickey-fingerprint --provider-publickey-file <your-publickey-file>

This will print it out.

2) Generate a time-limited secret key, which will be used to encrypt and authenticate DNS queries. Also generate a certificate for it:

$ dnscrypt-wrapper --gen-crypt-keypair --crypt-secretkey-file=1.key
$ dnscrypt-wrapper --gen-cert-file --crypt-secretkey-file=1.key --provider-cert-file=1.cert \
    --provider-publickey-file=public.key --provider-secretkey-file=secret.key \
    --cert-file-expire-days=365

In this example, the time-limited secret key will be saved as 1.key and its related certificate as 1.cert in the current directory.

Time-limited secret keys and certificates can be updated at any time without requiring clients to update their configuration.

3) Run the program with a given key, a provider name and the most recent certificate:

# dnscrypt-wrapper --resolver-address=8.8.8.8:53 --listen-address=0.0.0.0:443 \
                   --provider-name=2.dnscrypt-cert.yechengfu.com \
                   --crypt-secretkey-file=1.key --provider-cert-file=1.cert

The provider name can be anything; it doesn't have to be within an existing domain name. However, it has to start with 2.dnscrypt-cert..

When the service is started with the --provider-cert-file switch, the proxy will automatically serve the certificate as a TXT record when a query for the provider name is received.

As an alternative, the TXT record can be served by a name server for an actual DNS zone you are authoritative for. In that scenario, the --provider-cert-file option is not required, and instructions for Unbound and TinyDNS are displayed by the program when generating a provider certificate.

4) Run dnscrypt-proxy to check if it works:

# dnscrypt-proxy --local-address=127.0.0.1:55 --resolver-address=127.0.0.1:443 \
                 --provider-name=2.dnscrypt-cert.yechengfu.com \
                 --provider-key=<provider_public_key_fingerprint>
$ dig -p 55 google.com @127.0.0.1

<provider_public_key_fingerprint> is public key fingerprint generated by dnscrypt-wrapper --gen-provider-keypair, which looks like 4298:5F65:C295:DFAE:2BFB:20AD:5C47:F565:78EB:2404:EF83:198C:85DB:68F1:3E33:E952.

Optionally, add -d/--daemonize flag to run as a daemon.

Run dnscrypt-wrapper -h to view command line options.

Running unauthenticated DNS and the dnscrypt service on the same port

By default, and with the exception of records used for the certificates, only queries using the DNSCrypt protocol will be accepted.

If you want to run a service only accessible using DNSCrypt, this is what you want.

If you want to run a service accessible both with and without DNSCrypt, what you usually want is to keep the standard DNS port for the unauthenticated DNS service (53), and use a different port for DNSCrypt. You don't have to change anything for this either.

However, if you want to run both on the same port, maybe because only port 53 is reachable on your server, you can add the -U (--unauthenticated) switch to the command-line. This is not recommended.

Key rotation

Time-limited keys are bound to expire.

dnscrypt-proxy can check if the current key for a given server is not going to expire soon:

$ dnscrypt-proxy --resolver-address=127.0.0.1:443 \
                 --provider-name=2.dnscrypt-cert.yechengfu.com \
                 --provider-key=<provider_public_key_fingerprint> \
                 --test=10080

The --test option is followed by a "grace margin".

The command will immediately exit after verifying the certificate validity.

The exit code is 0 if a valid certificate can be used, 2 if no valid certificates can be used, 3 if a timeout occurred, and 4 if a currently valid certificate is going to expire before the margin.

The margin is always specificied in minutes.

This can be used in a cron tab to trigger an alert before a key is going to expire.

In order to switch to a fresh new key:

1) Create a new time-limited key (do not change the provider key!) and its certificate:

$ dnscrypt-wrapper --gen-crypt-keypair --crypt-secretkey-file=2.key
$ dnscrypt-wrapper --gen-cert-file --crypt-secretkey-file=2.key --provider-cert-file=2.cert

2) Tell new users to use the new certificate but still accept the old key until all clients have loaded the new certificate:

# dnscrypt-wrapper --resolver-address=8.8.8.8:53 --listen-address=0.0.0.0:443 \
                   --provider-name=2.dnscrypt-cert.yechengfu.com \
                   --crypt-secretkey-file=1.key,2.key --provider-cert-file=2.cert

Note that both 1.key and 2.key have be specified, in order to accept both the previous and the current key.

3) Clients automatically check for new certificates every hour. So, after one hour, the old certificate can be refused, by leaving only the new one in the configuration:

# dnscrypt-wrapper --resolver-address=8.8.8.8:53 --listen-address=0.0.0.0:443 \
                   --provider-name=2.dnscrypt-cert.yechengfu.com \
                   --crypt-secretkey-file=2.key --provider-cert-file=2.cert

Please note that on Linux systems (kernel >= 3.9), multiples instances of dnscrypt-wrapper can run at the same time. Therefore, in order to switch to a new configuration, one can start a new daemon without killing the previous instance, and only kill the previous instance after the new one started.

This also allows upgrades with zero downtime.

中文文档

注:第三方文档可能未及时与最新版本同步,以 README.md 为准。

See also