|
| 1 | +DNSCrypt |
| 2 | +======== |
| 3 | + |
| 4 | +A tool for securing communications between a client and a DNS resolver. |
| 5 | + |
| 6 | +Description |
| 7 | +----------- |
| 8 | + |
| 9 | +DNSCrypt is a slight variation on [DNSCurve](http://www.dnscurve.org/). |
| 10 | + |
| 11 | +DNSCurve improves the confidentiality and integrity of DNS requests using |
| 12 | +high-speed high-security elliptic-curve cryptography. Best of all, |
| 13 | +DNSCurve has very low overhead and adds virtually no latency to |
| 14 | +queries. |
| 15 | + |
| 16 | +DNSCurve aims at securing the entire chain down to authoritative |
| 17 | +servers. However, it only works with authoritative servers that explicitly |
| 18 | +support the protocol. And unfortunately, DNSCurve hasn't received much |
| 19 | +adoption yet. |
| 20 | + |
| 21 | +The DNSCrypt protocol is very similar to DNSCurve, but focuses on |
| 22 | +securing communications between a client and its first-level resolver. |
| 23 | +While not providing end-to-end security, it protects the local |
| 24 | +network (which is often the weakest link in the chain) against |
| 25 | +man-in-the-middle attacks. It also provides some confidentiality to |
| 26 | +DNS queries. |
| 27 | + |
| 28 | +The DNSCrypt daemon acts as a DNS proxy between a regular client, like |
| 29 | +a DNS cache or an operating system stub resolver, and a DNSCrypt-aware |
| 30 | +resolver, like OpenDNS. |
| 31 | + |
| 32 | +Installation |
| 33 | +------------ |
| 34 | + |
| 35 | +The daemon is known to work on recent versions of OSX, OpenBSD, |
| 36 | +NetBSD, Dragonfly BSD, FreeBSD and Linux. |
| 37 | + |
| 38 | +Compile and install it using the standard procedure: |
| 39 | + |
| 40 | + $ ./configure && make -j2 |
| 41 | + # make install |
| 42 | + |
| 43 | +Replace `-j2` with whatever CPU cores you want to use for the |
| 44 | +compilation process. |
| 45 | + |
| 46 | +Running `make -j2 test` in the `src/libnacl` directory is also highly |
| 47 | +recommended. |
| 48 | + |
| 49 | +On BSD systems, _GNU Make_ should be installed prior to running the |
| 50 | +`./configure` script. |
| 51 | + |
| 52 | +The proxy will be installed as `/usr/local/sbin/dnscrypt-proxy` by default. |
| 53 | + |
| 54 | +Command-line switches are documented in the `dnscrypt-proxy(8)` man page. |
| 55 | + |
| 56 | +Usage |
| 57 | +----- |
| 58 | + |
| 59 | +Having a dedicated system user, with no privileges and with an empty |
| 60 | +home directory, is highly recommended. For extra security, DNSCrypt |
| 61 | +will chroot() to this user's home directory and drop root privileges |
| 62 | +for this user's uid as soon as possible. |
| 63 | + |
| 64 | +The easiest way to start the daemon is: |
| 65 | + |
| 66 | + # dnscrypt-proxy --daemonize |
| 67 | + |
| 68 | +The proxy will accept incoming requests on 127.0.0.1 and |
| 69 | +encrypt/decrypt them from/to OpenDNS resolvers. |
| 70 | + |
| 71 | +Given such a setup, in order to actually start using DNSCrypt, you |
| 72 | +need to update your `/etc/resolv.conf` file and replace your current |
| 73 | +set of resolvers with: |
| 74 | + |
| 75 | + nameserver 127.0.0.1 |
| 76 | + |
| 77 | +Other common command-line switches include: |
| 78 | + |
| 79 | +* `--daemonize` in order to run the server as a background process. |
| 80 | +* `--local-address=<ip>` in order to locally bind a different IP address than |
| 81 | + 127.0.0.1 |
| 82 | +* `--local-port=<port>` to change the local port to listen to. |
| 83 | +* `--logfile=<file>` in order to write log data to a dedicated file. By |
| 84 | + default, logs are sent to stdout if the server is running in foreground, |
| 85 | + and to syslog if it is running in background. |
| 86 | +* `--max-active-requests=<count>` to set the maximum number of active |
| 87 | + requests. The default value is 250. |
| 88 | +* `--pid-file=<file>` in order to store the PID number to a file. |
| 89 | +* `--user=<user name>` in order to chroot()/drop privileges. |
| 90 | + |
| 91 | +DNSCrypt comes pre-configured for OpenDNS, although the |
| 92 | +`--resolver-address=<ip>`, `--provider-name=<certificate provider FQDN>` |
| 93 | +and `--provider-key=<provider public key>` can be specified in |
| 94 | +order to change the default settings. |
| 95 | + |
| 96 | +Using DNSCrypt in combination with a DNS cache |
| 97 | +---------------------------------------------- |
| 98 | + |
| 99 | +The DNSCrypt proxy is **not** a DNS cache. This means that incoming |
| 100 | +queries will **not** be cached and every single query will require a |
| 101 | +round-trip to the upstream resolver. |
| 102 | + |
| 103 | +For optimal performance, the recommended way of running DNSCrypt is to |
| 104 | +run it as a forwarder for a local DNS cache, like `unbound`, `pdns` or |
| 105 | +`dnscache`. |
| 106 | + |
| 107 | +Both can safely run on the same machine as long as they are listening |
| 108 | +to different IP addresses or different ports. |
| 109 | + |
| 110 | +If your DNS cache is unbound, all you need is to edit the |
| 111 | +`unbound.conf` file and add the following lines to the `server` |
| 112 | +section: |
| 113 | + |
| 114 | + forward-zone: |
| 115 | + name: "." |
| 116 | + forward-addr: 127.0.0.1@40 |
| 117 | + |
| 118 | +Then start `dnscrypt-proxy`, telling it to use a specific port (`40`, in |
| 119 | +this example): |
| 120 | + |
| 121 | + # dnscrypt-proxy --local-port=40 --daemonize |
| 122 | + |
| 123 | +Queries over TCP |
| 124 | +---------------- |
| 125 | + |
| 126 | +Some routers and firewalls can block outgoing DNS queries or |
| 127 | +transparently redirect them to their own resolver. This especially |
| 128 | +happens on public Wifi hotspots, such as coffee shops. |
| 129 | + |
| 130 | +As a workaround, the DNSCrypt proxy can force outgoing queries to be |
| 131 | +sent over TCP. For example, TCP port 443, which is commonly used for |
| 132 | +communication over HTTPS, may not be filtered. |
| 133 | + |
| 134 | +The `tcp-port=<port>` command-line switch forces this behavior. When |
| 135 | +an incoming query is received, the daemon immediately replies with a |
| 136 | +"response truncated" message, forcing the client to retry over TCP. |
| 137 | +The daemon then encrypts and signs the query and forwards it over TCP |
| 138 | +to the resolver. |
| 139 | + |
| 140 | +TCP is slower than UDP, and this workaround should never be used |
| 141 | +except when bypassing a filter is actually required. Moreover, |
| 142 | +multiple queries over a single TCP connections aren't supported yet. |
| 143 | + |
| 144 | +EDNS payload size |
| 145 | +----------------- |
| 146 | + |
| 147 | +DNS packets sent over UDP have been historically limited to 512 bytes, |
| 148 | +which is usually fine for queries, but sometimes a bit short for |
| 149 | +replies. |
| 150 | + |
| 151 | +Most modern authoritative servers, resolvers and stub resolvers |
| 152 | +support the Extension Mechanism for DNS (EDNS) that, among other |
| 153 | +things, allows a client to specify how large a reply over UDP can be. |
| 154 | + |
| 155 | +Unfortunately, this feature is disabled by default on a lot of |
| 156 | +operating systems. It has to be explicitly enabled, for example by |
| 157 | +adding `options edns0` to the `/etc/resolv.conf` file on most |
| 158 | +Unix-like operating systems. |
| 159 | + |
| 160 | +`dnscrypt-proxy` can transparently rewrite outgoing packets before |
| 161 | +signing and encrypting them, in order to add the EDNS0 mechanism. By |
| 162 | +default, a conservative payload size of 1280 bytes is advertised. |
| 163 | + |
| 164 | +This size can be made larger by starting the proxy with the |
| 165 | +`--edns-payload-size=<bytes>` command-line switch. Values up to 4096 |
| 166 | +are usually safe. |
| 167 | + |
| 168 | +A value below or equal to 512 will disable this mechanism, unless a |
| 169 | +client sends a packet with an OPT section providing a payload size. |
0 commit comments