release/src/router/dnscrypt/README.markdown

   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, Bitrig,
  36 NetBSD, Dragonfly BSD, FreeBSD, Linux, iOS (requires a jailbroken
  37 device), and Windows (requires MingW).
  38
  39 Download the
  40 [latest version](https://github.com/opendns/dnscrypt-proxy/downloads)
  41 and extract it:
  42
  43     $ bunzip2 -cd dnscrypt-proxy-*.tar.bz2 | tar xvf -
  44     $ cd dnscrypt-proxy-*
  45
  46 Compile and install it using the standard procedure:
  47
  48     $ ./configure && make -j2
  49     # make install
  50
  51 Replace `-j2` with whatever number of CPU cores you want to use for the
  52 compilation process.
  53
  54 Running `make -j2 test` in the `src/libnacl` directory is also highly
  55 recommended.
  56
  57 The proxy will be installed as `/usr/local/sbin/dnscrypt-proxy` by default.
  58
  59 Command-line switches are documented in the `dnscrypt-proxy(8)` man page.
  60
  61 Usage
  62 -----
  63
  64 Having a dedicated system user, with no privileges and with an empty
  65 home directory, is highly recommended. For extra security, DNSCrypt
  66 will chroot() to this user's home directory and drop root privileges
  67 for this user's uid as soon as possible.
  68
  69 The easiest way to start the daemon is:
  70
  71     # dnscrypt-proxy --daemonize
  72
  73 The proxy will accept incoming requests on 127.0.0.1, tag them with an
  74 authentication code, forward them to OpenDNS resolvers, and validate
  75 each answer before passing it to the client.
  76
  77 Given such a setup, in order to actually start using DNSCrypt, you
  78 need to update your `/etc/resolv.conf` file and replace your current
  79 set of resolvers with:
  80
  81     nameserver 127.0.0.1
  82
  83 Other common command-line switches include:
  84
  85 * `--daemonize` in order to run the server as a background process.
  86 * `--local-address=<ip>[:port]` in order to locally bind a different IP
  87 address than 127.0.0.1
  88 * `--logfile=<file>` in order to write log data to a dedicated file. By
  89   default, logs are sent to stdout if the server is running in foreground,
  90   and to syslog if it is running in background.
  91 * `--max-active-requests=<count>` to set the maximum number of active
  92   requests. The default value is 250.
  93 * `--pid-file=<file>` in order to store the PID number to a file.
  94 * `--user=<user name>` in order to chroot()/drop privileges.
  95
  96 DNSCrypt comes pre-configured for OpenDNS, although the
  97 `--resolver-address=<ip>[:port]`,
  98 `--provider-name=<certificate provider FQDN>`
  99 and `--provider-key=<provider public key>` can be specified in
 100 order to change the default settings.
 101
 102 Using DNSCrypt in combination with a DNS cache
 103 ----------------------------------------------
 104
 105 The DNSCrypt proxy is **not** a DNS cache. This means that incoming
 106 queries will **not** be cached and every single query will require a
 107 round-trip to the upstream resolver.
 108
 109 For optimal performance, the recommended way of running DNSCrypt is to
 110 run it as a forwarder for a local DNS cache, like `unbound` or
 111 `powerdns-recursor`.
 112
 113 Both can safely run on the same machine as long as they are listening
 114 to different IP addresses (preferred) or different ports.
 115
 116 If your DNS cache is `unbound`, all you need is to edit the
 117 `unbound.conf` file and add the following lines at the end of the `server`
 118 section:
 119
 120     do-not-query-localhost: no
 121
 122     forward-zone:
 123       name: "."
 124       forward-addr: 127.0.0.1@40
 125
 126 The first line is not required if you are using different IP addresses
 127 instead of different ports.
 128
 129 Then start `dnscrypt-proxy`, telling it to use a specific port (`40`, in
 130 this example):
 131
 132     # dnscrypt-proxy --local-address=127.0.0.1:40 --daemonize
 133
 134 IPv6 support
 135 ------------
 136
 137 IPv6 is fully supported. IPv6 addresses with a port number should be
 138 specified as [ip]:port
 139
 140     # dnscrypt-proxy --local-address='[::1]:40' --daemonize
 141
 142 Queries using nonstandard ports / over TCP
 143 ------------------------------------------
 144
 145 Some routers and firewalls can block outgoing DNS queries or
 146 transparently redirect them to their own resolver. This especially
 147 happens on public Wifi hotspots, such as coffee shops.
 148
 149 As a workaround, the port number can be changed using
 150 the `--resolver-port=<port>` option. For example, OpenDNS servers
 151 reply to queries sent to ports 53, 443 and 5353.
 152
 153 By default, dnscrypt-proxy sends outgoing queries to UDP port 443.
 154
 155 In addition, the DNSCrypt proxy can force outgoing queries to be
 156 sent over TCP. For example, TCP port 443, which is commonly used for
 157 communication over HTTPS, may not be filtered.
 158
 159 The `--tcp-only` command-line switch forces this behavior. When
 160 an incoming query is received, the daemon immediately replies with a
 161 "response truncated" message, forcing the client to retry over TCP.
 162 The daemon then authenticates the query and forwards it over TCP
 163 to the resolver.
 164
 165 TCP is slower than UDP, and this workaround should never be used
 166 except when bypassing a filter is actually required. Moreover,
 167 multiple queries over a single TCP connections aren't supported yet.
 168
 169 EDNS payload size
 170 -----------------
 171
 172 DNS packets sent over UDP have been historically limited to 512 bytes,
 173 which is usually fine for queries, but sometimes a bit short for
 174 replies.
 175
 176 Most modern authoritative servers, resolvers and stub resolvers
 177 support the Extension Mechanism for DNS (EDNS) that, among other
 178 things, allows a client to specify how large a reply over UDP can be.
 179
 180 Unfortunately, this feature is disabled by default on a lot of
 181 operating systems. It has to be explicitly enabled, for example by
 182 adding `options edns0` to the `/etc/resolv.conf` file on most
 183 Unix-like operating systems.
 184
 185 `dnscrypt-proxy` can transparently rewrite outgoing packets before
 186 authenticating them, in order to add the EDNS0 mechanism. By
 187 default, a conservative payload size of 1280 bytes is advertised.
 188
 189 This size can be made larger by starting the proxy with the
 190 `--edns-payload-size=<bytes>` command-line switch. Values up to 4096
 191 are usually safe.
 192
 193 A value below or equal to 512 will disable this mechanism, unless a
 194 client sends a packet with an OPT section providing a payload size.
 195
 196 The `hostip` utility
 197 --------------------
 198
 199 The DNSCrypt proxy ships with a simple tool named `hostip` that
 200 resolves a name to IPv4 or IPv6 addresses.
 201
 202 This tool can be useful for starting some services before
 203 `dnscrypt-proxy`.
 204
 205 Queries made by `hostip` are not authenticated.
 206
 207 GUIs for dnscrypt-proxy
 208 -----------------------
 209
 210 If you need a simple graphical user interface in order to start/stop
 211 the proxy and change your DNS settings, check out the following
 212 projects:
 213
 214 - [DNSCrypt OSX Client](https://github.com/opendns/dnscrypt-osx-client):
 215 a preferences pane, a menu bar indicator and a service to change the
 216 DNS settings. OSX only, written in Objective C. 64-bit CPU required.
 217 Experimental.
 218
 219 - [DNSCrypt WinClient](https://github.com/Noxwizard/dnscrypt-winclient):
 220 Easily enable/disable DNSCrypt on multiple adapters. Supports
 221 different ports and protocols, IPv6, parental controls and the proxy
 222 can act as a gateway service. Windows only, written in .NET.
 223
 224 - [DNSCrypt Win Client](https://github.com/opendns/dnscrypt-win-client):
 225 Official GUI for Windows, by OpenDNS.
 226
 227 - dnscrypt-proxy is also available on Cydia, and it can be easily
 228 enabled using [GuizmoDNS](http://modmyi.com/cydia/com.guizmo.dns).
 229