release/src/router/dnscrypt/TECHNOTES

   1
   2 Implementation details
   3 ======================
   4
   5 Cryptographic library
   6 ---------------------
   7
   8 - The wheel hasn't been reinvented.
   9
  10 - The crypto constructions come from [NaCl](http://nacl.cr.yp.to/) and
  11 the proxy leverages [libsodium](https://github.com/jedisct1/libsodium).
  12
  13 - Why NaCl? Unbloated, blazing fast, and less error-prone that other libraries.
  14   See http://cr.yp.to/highspeed/coolnacl-20111201.pdf
  15
  16 - crypto_box_curve25519xsalsa20poly1305_*() for authenticating/encrypting
  17   queries and replies, crypto_sign_ed25519_*() for signing certificates, and
  18   crypto_stream_salsa20() as a PRNG.
  19
  20   See the [libsodium documentation](http://www.libsodium.org/doc/) for details.
  21
  22 Event-notification library
  23 --------------------------
  24
  25 - Uses libevent2. Unbound's boilerplate is also excellent, but it hasn't been
  26   packaged as a standalone library yet.
  27
  28 - Because it is totally awesome for writing portable software.
  29
  30 - Bundled with dnscrypt, for now, because it's a modified version (so
  31   that evdns can cope with TXT records) and because some distributions
  32   are still shipping dead old versions.
  33
  34 Certificates
  35 ------------
  36
  37 The following information has to be provided to the proxy:
  38
  39 - The provider name
  40 - The provider public key
  41 - The resolver IP address
  42
  43 These information can be automatically retrieved from the global list
  44 (the `dnscrypt-proxy.csv` file) based on the name provided using the
  45 `-R` (`--resolver-name`) command-line option.
  46
  47 At startup and every 60 minute, the proxy directly connects to the specified
  48 resolver IP address and issues a TXT query for the provider name. The
  49 first component of the provider name indicates the latest protocol version,
  50 or the version range, supported by the client. Right now, this should
  51 be 2. Always.
  52
  53 One or more TXT records are returned, each containing a signed certificate.
  54 The provider public key is only used to verify a certificate, never for
  55 authenticating/encrypting queries.
  56
  57 Certificates have the following header:
  58 - 4 byte magic header DNSC
  59 - 2 byte major version
  60 - 2 byte minor version
  61
  62 Followed by signed content (the signature adds 512 bits to the payload):
  63 - server 256-bit public key
  64 - 8 byte magic header to use for queries using this specific key
  65 - 4 byte serial number
  66 - 4 + 4 byte validity period (two timestamps)
  67
  68 This is the current structure of the second version of the protocol.
  69 Don't assume anything about its length, it is very likely to change
  70 after a version bump.
  71
  72 The proxy drops invalid certificates for the current date, and picks the one
  73 with the highest serial number.
  74
  75 More than one certificate may be returned when keys rollovers or
  76 function changes are performed.
  77
  78 Resolvers are never signing certificates themselves, they are just providing
  79 pre-signed certificates.
  80
  81 Queries
  82 -------
  83
  84 Queries and replies are based on djb's dnscurve protocol:
  85 http://www.dnscurve.org/
  86
  87 The proxy always generates a new, in-memory only key pair at startup.
  88
  89 Random padding is added to queries and replies, using a 64 byte block size.
  90
  91 Encrypted queries are prefixed with the following header structure:
  92
  93 - 8 byte magic header (provided by the chosen certificate)
  94 - A 256 bit client public key
  95 - A 96 bit client nonce (64 bit monotically increasing timestamp +
  96   32 random bits)
  97 - A 128 bit Poly1305-AES MAC
  98
  99 Replies are prefixed with the following header structure:
 100
 101 - 8 byte static magic header r6fnvWJ8
 102 - A 192 bit nonce: the 96 bit client-supplied nonce + a 96 bit server
 103 nonce extension.
 104 - A 128 bit Poly1305-AES MAC.
 105
 106 The proxy immediately discards replies to queries made more than 10
 107 second ago and replies that don't match the client-supplied nonce.
 108
 109 Miscellaneous
 110 -------------
 111
 112 If you need extra monitoring/profiling, the proxy provides a bunch of
 113 dtrace probes on OSX, as the dnscrypt-proxy provider.
 114 See src/dnscrypt-proxy/probes_dnscrypt_proxy.d
 115
 116 The proxy doesn't cache replies. Neither does it perform any DNSSEC
 117 validation yet.
 118
 119 This is better handled by a separate process or by linking libunbound.
 120
 121 The proxy does alter queries, though, in order to:
 122
 123 - immediately reply with a "reply truncated" message to a UDP query when
 124 the --tcp-port switch has been turned on.
 125
 126 - add an empty OPT section in order to advertise a payload size unless
 127 an EDNS section was already present or unless --payload-size with a
 128 < 512 bytes size has been specified.
 129
 130 OSX Yosemite, OpenBSD/amd64 and Dragonfly BSD/amd64 are the primary
 131 development platforms, but the code has been designed to be as
 132 portable as possible, and patches to support other operating systems
 133 and architectures are more than welcome.