1# Name 2 3dnscrypt-wrapper - A server-side dnscrypt proxy. 4 5[![Build Status](https://travis-ci.org/cofyc/dnscrypt-wrapper.png?branch=master)](https://travis-ci.org/cofyc/dnscrypt-wrapper) 6 7## Table of Contents 8 9* [Description](#description) 10* [Installation](#installation) 11* [Usage](#usage) 12 * [Quick start](#quick-start) 13 * [Running unauthenticated DNS and the dnscrypt service on the same port](#running-unauthenticated-dns-and-the-dnscrypt-service-on-the-same-port) 14 * [Key rotation](#key-rotation) 15* [Chinese](#chinese) 16* [See also](#see-also) 17 18## Description 19 20This is dnscrypt wrapper (server-side dnscrypt proxy), which helps to 21add dnscrypt support to any name resolver. 22 23This software is modified from 24[dnscrypt-proxy](https://github.com/jedisct1/dnscrypt-proxy). 25 26## Installation 27 28Install [libsodium](https://github.com/jedisct1/libsodium) and [libevent](http://libevent.org/) 2.1.1+ first. 29 30On Linux: 31 32 $ ldconfig # if you install libsodium from source 33 $ git clone git://github.com/cofyc/dnscrypt-wrapper.git 34 $ cd dnscrypt-wrapper 35 $ make configure 36 $ ./configure 37 $ make install 38 39On FreeBSD: 40 41 $ pkg install dnscrypt-wrapper 42 43On OpenBSD: 44 45 $ pkg_add -r gmake autoconf 46 $ pkg_add -r libevent 47 $ git clone git://github.com/cofyc/dnscrypt-wrapper.git 48 $ cd dnscrypt-wrapper 49 $ gmake LDFLAGS='-L/usr/local/lib/' CFLAGS=-I/usr/local/include/ 50 51On MacOS: 52 53 $ brew install dnscrypt-wrapper 54 55In Docker: 56 57 See https://github.com/jedisct1/dnscrypt-server-docker. 58 59## Usage 60 61### Quick Start 62 631) Generate the provider key pair: 64 65```sh 66$ dnscrypt-wrapper --gen-provider-keypair \ 67 --provider-name=2.dnscrypt-cert.<yourdomain> --ext-address=<external server ip> 68``` 69 70If your server doesn't store logs, add `--nolog` and if it supports DNSSEC, 71add `--dnssec`. 72 73This will create two files in the current directory: `public.key` and 74`secret.key`. 75 76This is a long-term key pair that is never supposed to change unless the 77secret key is compromised. Make sure that `secret.key` is securely 78stored and backuped. 79 80It will also print the stamp for dnscrypt-proxy version 2.x. 81 82If you forgot to save your provider public key: 83 84```sh 85$ dnscrypt-wrapper --show-provider-publickey --provider-publickey-file <your-publickey-file> 86``` 87 88This will print it out. 89 902) Generate a time-limited secret key, which will be used to encrypt 91and authenticate DNS queries. Also generate a certificate for it: 92 93```sh 94$ dnscrypt-wrapper --gen-crypt-keypair --crypt-secretkey-file=1.key 95$ dnscrypt-wrapper --gen-cert-file --crypt-secretkey-file=1.key --provider-cert-file=1.cert \ 96 --provider-publickey-file=public.key --provider-secretkey-file=secret.key 97``` 98 99In this example, the time-limited secret key will be saved as `1.key` 100and its related certificate as `1.cert` in the current directory. 101 102Time-limited secret keys and certificates can be updated at any time 103without requiring clients to update their configuration. 104 105NOTE: By default, secret key expires in 1 day (24 hours) for safety. You can 106change it by adding `--cert-file-expire-days=<your-expected-expiraiton-days>`, 107but it's better to use short-term secret key and use 108[key-rotation](#key-rotation) mechanism. 109 1103) Run the program with a given key, a provider name and the most recent certificate: 111 112```sh 113$ dnscrypt-wrapper --resolver-address=8.8.8.8:53 --listen-address=0.0.0.0:443 \ 114 --provider-name=2.dnscrypt-cert.<yourdomain> \ 115 --crypt-secretkey-file=1.key --provider-cert-file=1.cert 116``` 117 118The provider name can be anything; it doesn't have to be within an existing 119domain name. However, it has to start with `2.dnscrypt-cert.`, e.g. 120`2.dnscrypt-cert.example.com`. 121 122When the service is started with the `--provider-cert-file` switch, the 123proxy will automatically serve the certificate as a TXT record when a 124query for the provider name is received. 125 126As an alternative, the TXT record can be served by a name server for 127an actual DNS zone you are authoritative for. In that scenario, the 128`--provider-cert-file` option is not required, and instructions for 129Unbound and TinyDNS are displayed by the program when generating a 130provider certificate. 131 132You can get instructions later by running: 133 134```sh 135$ dnscrypt-wrapper --show-provider-publickey-dns-records 136 --provider-cert-file <path/to/your/provider_cert_file> 137``` 138 1394) Run dnscrypt-proxy to check if it works: 140 141```sh 142$ dnscrypt-proxy --local-address=127.0.0.1:55 --resolver-address=127.0.0.1:443 \ 143 --provider-name=2.dnscrypt-cert.<yourdomain> \ 144 --provider-key=<provider_public_key> 145$ dig -p 55 google.com @127.0.0.1 146``` 147 148`<provider_public_key>` is public key 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`. 149 150Optionally, add `-d/--daemonize` flag to run as a daemon. 151 152Run `dnscrypt-wrapper -h` to view command line options. 153 154### Running unauthenticated DNS and the dnscrypt service on the same port 155 156By default, and with the exception of records used for the 157certificates, only queries using the DNSCrypt protocol will be 158accepted. 159 160If you want to run a service only accessible using DNSCrypt, this is 161what you want. 162 163If you want to run a service accessible both with and without 164DNSCrypt, what you usually want is to keep the standard DNS port for 165the unauthenticated DNS service (53), and use a different port for 166DNSCrypt. You don't have to change anything for this either. 167 168However, if you want to run both on the same port, maybe because only 169port 53 is reachable on your server, you can add the `-U` 170(`--unauthenticated`) switch to the command-line. This is not 171recommended. 172 173### Key rotation 174 175Time-limited keys are bound to expire. 176 177`dnscrypt-proxy` can check if the current key for a given server is 178not going to expire soon: 179 180```sh 181$ dnscrypt-proxy --resolver-address=127.0.0.1:443 \ 182 --provider-name=2.dnscrypt-cert.<yourdomain> \ 183 --provider-key=<provider_public_key> \ 184 --test=10080 185``` 186 187The `--test` option is followed by a "grace margin". 188 189The command will immediately exit after verifying the certificate validity. 190 191The exit code is `0` if a valid certificate can be used, `2` if no valid 192certificates can be used, `3` if a timeout occurred, and `4` if a currently 193valid certificate is going to expire before the margin. 194 195The margin is always specified in minutes. 196 197This can be used in a cron tab to trigger an alert before a key is 198going to expire. 199 200In order to switch to a fresh new key: 201 202First, create a new time-limited key (do not change the provider key!) and 203its certificate: 204 205```sh 206$ dnscrypt-wrapper --gen-crypt-keypair --crypt-secretkey-file=2.key 207$ dnscrypt-wrapper --gen-cert-file --crypt-secretkey-file=2.key --provider-cert-file=2.cert \ 208 --provider-publickey-file=public.key --provider-secretkey-file=secret.key \ 209 --cert-file-expire-days=1 210``` 211 212Second, Tell new users to use the new certificate but still accept the old 213key until all clients have loaded the new certificate: 214 215```sh 216$ dnscrypt-wrapper --resolver-address=8.8.8.8:53 --listen-address=0.0.0.0:443 \ 217 --provider-name=2.dnscrypt-cert.<yourdomain> \ 218 --crypt-secretkey-file=1.key,2.key --provider-cert-file=1.cert,2.cert 219``` 220 221Note that both `1.key` and `2.key` have be specified, in order to 222accept both the previous and the current key. 223 224Third, Clients automatically check for new certificates every hour. So, 225after one hour, the old certificate can be refused, by leaving only 226the new one in the configuration: 227 228```sh 229$ dnscrypt-wrapper --resolver-address=8.8.8.8:53 --listen-address=0.0.0.0:443 \ 230 --provider-name=2.dnscrypt-cert.<yourdomain> \ 231 --crypt-secretkey-file=2.key --provider-cert-file=2.cert 232``` 233 234Please note that on Linux systems (kernel >= 3.9), multiples instances of 235`dnscrypt-wrapper` can run at the same time. Therefore, in order to 236switch to a new configuration, one can start a new daemon without 237killing the previous instance, and only kill the previous instance 238after the new one started. 239 240This also allows upgrades with zero downtime. 241 242## Blocking 243 244For servers willing to block specific domain names (ads, malware), the 245`--blacklist-file` parameter can be added. That blacklist file accepts 246patterns such as: 247 248- `example.com`: blocks `example.com` as well as `www.example.com` 249- `*.example.com`: identical, just more explicit 250- `*example*`: blocks the `example` substring no matter where it appears 251- `ads.*`: blocks the `ads.` prefix 252 253Prefix and suffix lookups are fast and can scale to very large lists. 254 255## Chinese 256 257- CentOS/Debian/Ubuntu 下编译 dnscrypt-wrapper: http://03k.org/centos-make-dnscrypt-wrapper.html 258- dnscrypt-wrapper 使用方法: http://03k.org/dnscrypt-wrapper-usage.html 259 260注:第三方文档可能未及时与最新版本同步,以 README.md 为准。 261 262## See also 263 264- https://dnscrypt.info/ 265- https://github.com/jedisct1/dnscrypt-proxy 266- https://github.com/cofyc/dnscrypt-wrapper 267