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