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

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