release/src/router/dnscrypt/README-PLUGINS.markdown

   1 DNSCrypt Plugins
   2 ================
   3
   4 Overview
   5 --------
   6
   7 Starting with version 1.1.0, `dnscrypt-proxy` can be extended with
   8 plugins.
   9
  10 A plugin can implement *pre-filters* and *post-filters*.
  11
  12 A DNS query received by the proxy will pass through all *pre-filters*
  13 before being encrypted, signed, and sent to the upstream DNS resolver.
  14
  15 Once a response has been received by the proxy, this response is
  16 going to be validated and decrypted before passing through all
  17 *post-filters*, and eventually the end result will eventually be
  18 delivered to the client.
  19
  20 Filters are given the packets in wire format. Every filter can inspect and
  21 alter these packets at will. A filter can also tell the proxy to totally
  22 ignore a query.
  23
  24     query -> pre-plugins -> encryption/authentication -> resolver
  25
  26     client <- post-plugins <- verification/decryption <- resolver
  27
  28 Usage
  29 -----
  30
  31 Technically, a plugin is just a native shared library. A good old `.so` file on
  32 Unix, a `.dylib` file on OSX and a `.DLL` file on Windows.
  33
  34 Support for plugins is disabled by default, and has to be explicitly
  35 enabled at compilation time:
  36
  37     ./configure --enable-plugins
  38
  39 If the `ltdl` library is found on the system, it will be picked up. If
  40 not, a built-in copy will be used instead.
  41
  42 If you intend to distribute a binary package that should run on
  43 systems without the `ltdl` library (which is probably the case on
  44 Windows), add `--with-included-ltdl`:
  45
  46     ./configure --enable-plugins --with-included-ltdl
  47
  48 Plugins can inspect and mangle packets in any way, but before
  49 reinventing the wheel, take a look at what the `ldns` library has to
  50 offer. `ldns` makes it really easy to parse and build any kind of DNS
  51 packet, can validate DNSSEC records, and is rock solid.
  52
  53 If `ldns` is available on the current system, additional example
  54 plugins will be compiled.
  55
  56 If the `./configure` isn't given a different prefix, example plugins
  57 are installed in `/usr/local/lib/dnscrypt-proxy`.
  58
  59 `dnscrypt-proxy` can load any number of plugins using the `--plugin`
  60 switch, followed by the path to a plugin (library or libtool `.la` file):
  61
  62     dnscrypt-proxy \
  63         --plugin=/usr/local/lib/dnscrypt-proxy/libdcplugin_example.la \
  64         --plugin=/usr/local/lib/dnscrypt-proxy/libdcplugin_example2.la
  65
  66 A full path is actually not required for plugins sitting in the default
  67 plugins directory (`/usr/local/lib/dnscrypt-proxy` by default):
  68
  69     dnscrypt-proxy \
  70         --plugin=libdcplugin_example.la \
  71         --plugin=libdcplugin_example2.la
  72
  73 Filters will always be applied sequentially, in the given order.
  74
  75 On Unix systems, a file containing a `dnscrypt-proxy` plugin must be
  76 owned either by root, or by the user running the proxy.
  77
  78 You can relax this rule. This can be especially useful on OSX when using
  79 Homebrew, that encourages /usr/local to be owned by a non-root user.
  80 In order to relax this rule, use `--enable-relaxed-plugins-permissions`:
  81
  82     ./configure --enable-plugins --enable-relaxed-plugins-permissions
  83
  84 When run as a Windows service, the list of plugins to load should be
  85 given as a multi-strings (`REG_MULTI_SZ` value).
  86
  87 Each plugin can optionally parse one or more arguments:
  88
  89     --plugin=...libdcplugin_example.la,--one,--two,--three=4
  90     --plugin=...libdcplugin_example2.la,127.0.0.1
  91
  92 The plugin API
  93 --------------
  94
  95 When compiled with support for plugins, `dnscrypt-proxy` installs
  96 development headers (in `/usr/local/include/dnscrypt` with the default
  97 prefix).
  98
  99 In addition, the `dnscrypt-proxy` source code ships with a few example
 100 plugins in the `src/plugins` directory to get you started.
 101
 102 The `<dnscrypt/plugin.h>` header file is the only one you need to
 103 include in a plugin. Feel free to take a look at its Doxygen documentation.
 104
 105 The bare minimum a plugin needs is to mention `DCPLUGIN_MAIN(__FILE__)`
 106 and to implement is a `dcplugin_init()` function.
 107
 108 This function is evaluated when the proxy starts, and can optionally
 109 parse a list of arguments:
 110
 111     #include <dnscrypt/plugin.h>
 112
 113     DCPLUGIN_MAIN(__FILE__);
 114
 115     int
 116     dcplugin_init(DCPlugin * const dcplugin, int argc, char *argv[])
 117     {
 118         return 0;
 119     }
 120
 121 The DCPlugin type is an opaque structure that can store plugin-local
 122 data using the `dcplugin_get_user_data()` and `dcplugin_set_user_data()` macros.
 123
 124 A filter can implement a pre-filter, a post-filter, or both. The
 125 related functions are optional.
 126
 127     DCPluginSyncFilterResult
 128     dcplugin_sync_pre_filter(DCPlugin *dcplugin, DCPluginDNSPacket *dcp_packet);
 129
 130     DCPluginSyncFilterResult
 131     dcplugin_sync_post_filter(DCPlugin *dcplugin, DCPluginDNSPacket *dcp_packet);
 132
 133 These functions are given an opaque `DCPluginDNSPacket` type, storing
 134 the packet in wire format, and metadata, including the client IP address.
 135
 136 Avoid accessing these metadata directly, and use the macros defined in
 137 `dnscrypt/plugins.h` instead.
 138
 139 A filter can alter the content of the DNS packet, and change its
 140 length with `dcplugin_set_wire_data_len()`. However, the size of the
 141 packet should never be larger than the size returned by
 142 `dcplugin_get_wire_data_max_len`.
 143
 144 The return code of a filter can be either of:
 145 - `DCP_SYNC_FILTER_RESULT_OK`
 146 - `DCP_SYNC_FILTER_RESULT_DIRECT` (only in a pre-filter) to bypass the
 147 resolver and directly send the (possibly modified) packet to the client.
 148 Post-filters will be bypassed as well.
 149 - `DCP_SYNC_FILTER_RESULT_KILL` in order to drop the packet.
 150 - `DCP_SYNC_FILTER_RESULT_ERROR` to drop the packet and indicate that a
 151 non-fatal error occurred.
 152
 153 API documentation
 154 -----------------
 155
 156 For more info about the API, see the online [dnscrypt API
 157 documentation](http://dnscrypt.org/plugin-api/plugin_8h.html).
 158
 159 The `dnscrypt-proxy` source code also ships with example plugins you
 160 may want to take a look at, in the `src/plugins` directory.
 161
 162 Compiling ldns on Windows
 163 -------------------------
 164
 165 - Don't use the MSYS OpenSSL package. It is probably way out of date.
 166 - Download and extract the source code of the latest stable OpenSSL version.
 167 - `./config --shared --prefix=/usr/local && make && make install`
 168 - Download and extract the source code of the latest stable ldns version
 169 - `./configure && make install`