release/src/router/dnscrypt/TECHNOTES

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