release/src/router/dnscrypt/README.markdown

   1 [![Build Status](https://travis-ci.org/jedisct1/dnscrypt-proxy.png?branch=master)](https://travis-ci.org/jedisct1/dnscrypt-proxy?branch=master)
   2
   3 [DNSCrypt](http://dnscrypt.org)
   4 ===============================
   5
   6 A tool for securing communications between a client and a DNS resolver.
   7
   8 Description
   9 -----------
  10
  11 dnscrypt-proxy provides local service which can be used directly as
  12 your local resolver or as a DNS forwarder, encrypting and
  13 authenticating requests using the DNSCrypt protocol and passing them
  14 to an upstream server, by default OpenDNS who run this on their
  15 resolvers.
  16
  17 The DNSCrypt protocol uses high-speed high-security elliptic-curve
  18 cryptography and is very similar to [DNSCurve](http://dnscurve.org/),
  19 but focuses on securing communications between a client and its first-level
  20 resolver.
  21
  22 While not providing end-to-end security, it protects the local
  23 network, which is often the weakest point of the chain, against
  24 man-in-the-middle attacks. It also provides some confidentiality to
  25 DNS queries.
  26
  27 Installation
  28 ------------
  29
  30 The daemon is known to work on recent versions of OSX, OpenBSD,
  31 Bitrig, NetBSD, Dragonfly BSD, FreeBSD, Linux, iOS (requires a
  32 jailbroken device), Android (requires a rooted device), Solaris
  33 (SmartOS) and Windows (requires MingW).
  34
  35 Download the [latest version](http://dnscrypt.org) and extract it:
  36
  37     $ bunzip2 -cd dnscrypt-proxy-*.tar.bz2 | tar xvf -
  38     $ cd dnscrypt-proxy-*
  39
  40 Compile and install it using the standard procedure:
  41
  42     $ ./configure && make -j2
  43     # make install
  44
  45 Replace `-j2` with whatever number of CPU cores you want to use for the
  46 compilation process.
  47
  48 Running `make -j2 check` in the `src/libsodium` directory is also highly
  49 recommended.
  50
  51 The proxy will be installed as `/usr/local/sbin/dnscrypt-proxy` by default.
  52
  53 Command-line switches are documented in the `dnscrypt-proxy(8)` man page.
  54
  55 *Note:* gcc 3.4.6 (and probably other similar versions) is known to
  56 produce broken code on Mips targets with the -Os optimization level.
  57 Use a different level (-O and -O2 are fine) or upgrade the compiler.
  58 Thanks to Adrian Kotelba for reporting this.
  59
  60 GUIs for dnscrypt-proxy
  61 -----------------------
  62
  63 If you need a simple graphical user interface in order to start/stop
  64 the proxy and change your DNS settings, check out the following
  65 projects:
  66
  67 - [DNSCrypt OSX Client](http://opendns.github.io/dnscrypt-osx-client/):
  68 A tool to easily use DNSCrypt with OpenDNS, configure plugins and
  69 define resolvers for specific domains. It has been implemented as a
  70 collection of shell scripts with a user interface in Objective C.
  71
  72 - [DNSCrypt WinClient](https://github.com/Noxwizard/dnscrypt-winclient):
  73 Easily enable/disable DNSCrypt on multiple adapters. Supports
  74 different ports and protocols, IPv6, parental controls and the proxy
  75 can act as a gateway service. Windows only, written in .NET.
  76
  77 - [DNSCrypt Win Client](https://github.com/opendns/dnscrypt-win-client):
  78 Official GUI for Windows, by OpenDNS. Also known as "OpenDNSCrypt".
  79
  80 - dnscrypt-proxy is also available on Cydia, and it can be easily
  81 enabled using [GuizmoDNS](http://modmyi.com/cydia/com.guizmo.dns).
  82
  83 Server-side proxy
  84 -----------------
  85
  86 [DNSCrypt-Wrapper](https://github.com/Cofyc/dnscrypt-wrapper) is a
  87 server-side dnscrypt proxy that works with any name resolver.
  88
  89 Usage
  90 -----
  91
  92 Having a dedicated system user, with no privileges and with an empty
  93 home directory, is highly recommended. For extra security, DNSCrypt
  94 will chroot() to this user's home directory and drop root privileges
  95 for this user's uid as soon as possible.
  96
  97 The easiest way to start the daemon is:
  98
  99     # dnscrypt-proxy --daemonize
 100
 101 The proxy will accept incoming requests on 127.0.0.1, tag them with an
 102 authentication code, forward them to OpenDNS resolvers, and validate
 103 each answer before passing it to the client.
 104
 105 Given such a setup, in order to actually start using DNSCrypt, you
 106 need to update your `/etc/resolv.conf` file and replace your current
 107 set of resolvers with:
 108
 109     nameserver 127.0.0.1
 110
 111 Other common command-line switches include:
 112
 113 * `--daemonize` in order to run the server as a background process.
 114 * `--local-address=<ip>[:port]` in order to locally bind a different IP
 115 address than 127.0.0.1
 116 * `--logfile=<file>` in order to write log data to a dedicated file. By
 117   default, logs are sent to stdout if the server is running in foreground,
 118   and to syslog if it is running in background.
 119 * `--loglevel=<level>` if you need less verbosity in log files.
 120 * `--max-active-requests=<count>` to set the maximum number of active
 121   requests. The default value is 250.
 122 * `--pid-file=<file>` in order to store the PID number to a file.
 123 * `--user=<user name>` in order to chroot()/drop privileges.
 124
 125 DNSCrypt comes pre-configured for OpenDNS, although the
 126 `--resolver-address=<ip>[:port]`,
 127 `--provider-name=<certificate provider FQDN>`
 128 and `--provider-key=<provider public key>` can be specified in
 129 order to change the default settings.
 130
 131 Installation as a service (Windows only)
 132 ----------------------------------------
 133
 134 The proxy can be installed as a Windows service.
 135
 136 Copy the `dnscrypt-proxy.exe` file to any location, then open a
 137 terminal and type (eventually with the full path to `dnscrypt-proxy.exe`):
 138
 139     dnscrypt-proxy.exe --install
 140
 141 It will install a new service named `dnscrypt-proxy`.
 142
 143 After being stopped, the service can be removed with:
 144
 145     dnscrypt-proxy.exe --uninstall
 146
 147 Using DNSCrypt in combination with a DNS cache
 148 ----------------------------------------------
 149
 150 The DNSCrypt proxy is **not** a DNS cache. This means that incoming
 151 queries will **not** be cached and every single query will require a
 152 round-trip to the upstream resolver.
 153
 154 For optimal performance, the recommended way of running DNSCrypt is to
 155 run it as a forwarder for a local DNS cache, like `unbound` or
 156 `powerdns-recursor`.
 157
 158 Both can safely run on the same machine as long as they are listening
 159 to different IP addresses (preferred) or different ports.
 160
 161 If your DNS cache is `unbound`, all you need is to edit the
 162 `unbound.conf` file and add the following lines at the end of the `server`
 163 section:
 164
 165     do-not-query-localhost: no
 166
 167     forward-zone:
 168       name: "."
 169       forward-addr: 127.0.0.1@40
 170
 171 The first line is not required if you are using different IP addresses
 172 instead of different ports.
 173
 174 Then start `dnscrypt-proxy`, telling it to use a specific port (`40`, in
 175 this example):
 176
 177     # dnscrypt-proxy --local-address=127.0.0.1:40 --daemonize
 178
 179 IPv6 support
 180 ------------
 181
 182 IPv6 is fully supported. IPv6 addresses with a port number should be
 183 specified as [ip]:port
 184
 185     # dnscrypt-proxy --local-address='[::1]:40' --daemonize
 186
 187 Queries using nonstandard ports / over TCP
 188 ------------------------------------------
 189
 190 Some routers and firewalls can block outgoing DNS queries or
 191 transparently redirect them to their own resolver. This especially
 192 happens on public Wifi hotspots, such as coffee shops.
 193
 194 As a workaround, the port number can be changed using
 195 the `--resolver-port=<port>` option. For example, OpenDNS servers
 196 reply to queries sent to ports 53, 443 and 5353.
 197
 198 By default, dnscrypt-proxy sends outgoing queries to UDP port 443.
 199
 200 In addition, the DNSCrypt proxy can force outgoing queries to be
 201 sent over TCP. For example, TCP port 443, which is commonly used for
 202 communication over HTTPS, may not be filtered.
 203
 204 The `--tcp-only` command-line switch forces this behavior. When
 205 an incoming query is received, the daemon immediately replies with a
 206 "response truncated" message, forcing the client to retry over TCP.
 207 The daemon then authenticates the query and forwards it over TCP
 208 to the resolver.
 209
 210 `--tcp-only` is slower than UDP because multiple queries over a single
 211 TCP connections aren't supported yet, and this workaround should
 212 never be used except when bypassing a filter is actually required.
 213
 214 EDNS payload size
 215 -----------------
 216
 217 DNS packets sent over UDP have been historically limited to 512 bytes,
 218 which is usually fine for queries, but sometimes a bit short for
 219 replies.
 220
 221 Most modern authoritative servers, resolvers and stub resolvers
 222 support the Extension Mechanism for DNS (EDNS) that, among other
 223 things, allows a client to specify how large a reply over UDP can be.
 224
 225 Unfortunately, this feature is disabled by default on a lot of
 226 operating systems. It has to be explicitly enabled, for example by
 227 adding `options edns0` to the `/etc/resolv.conf` file on most
 228 Unix-like operating systems.
 229
 230 `dnscrypt-proxy` can transparently rewrite outgoing packets before
 231 authenticating them, in order to add the EDNS0 mechanism. By
 232 default, a conservative payload size of 1252 bytes is advertised.
 233
 234 This size can be made larger by starting the proxy with the
 235 `--edns-payload-size=<bytes>` command-line switch. Values up to 4096
 236 are usually safe.
 237
 238 A value below or equal to 512 will disable this mechanism, unless a
 239 client sends a packet with an OPT section providing a payload size.
 240
 241 The `hostip` utility
 242 --------------------
 243
 244 The DNSCrypt proxy ships with a simple tool named `hostip` that
 245 resolves a name to IPv4 or IPv6 addresses.
 246
 247 This tool can be useful for starting some services before
 248 `dnscrypt-proxy`.
 249
 250 Queries made by `hostip` are not authenticated.