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 On Windows, example plugins relying on the ldns library require two
  92 extra DLLs:
  93
  94 - `libgcc_s_dw2-1.dll`
  95 - `libeay32.dll`, from OpenSSL.
  96
  97 The plugin API
  98 --------------
  99
 100 When compiled with support for plugins, `dnscrypt-proxy` installs
 101 development headers (in `/usr/local/include/dnscrypt` with the default
 102 prefix).
 103
 104 In addition, the `dnscrypt-proxy` source code ships with a few example
 105 plugins in the `src/plugins` directory to get you started.
 106
 107 The `<dnscrypt/plugin.h>` header file is the only one you need to
 108 include in a plugin. Feel free to take a look at its Doxygen documentation.
 109
 110 The bare minimum a plugin needs is to mention `DCPLUGIN_MAIN(__FILE__)`
 111 and to implement is a `dcplugin_init()` function.
 112
 113 This function is evaluated when the proxy starts, and can optionally
 114 parse a list of arguments:
 115
 116     #include <dnscrypt/plugin.h>
 117
 118     DCPLUGIN_MAIN(__FILE__);
 119
 120     int
 121     dcplugin_init(DCPlugin * const dcplugin, int argc, char *argv[])
 122     {
 123         return 0;
 124     }
 125
 126 The DCPlugin type is an opaque structure that can store plugin-local
 127 data using the `dcplugin_get_user_data()` and `dcplugin_set_user_data()` macros.
 128
 129 A filter can implement a pre-filter, a post-filter, or both. The
 130 related functions are optional.
 131
 132     DCPluginSyncFilterResult
 133     dcplugin_sync_pre_filter(DCPlugin *dcplugin, DCPluginDNSPacket *dcp_packet);
 134
 135     DCPluginSyncFilterResult
 136     dcplugin_sync_post_filter(DCPlugin *dcplugin, DCPluginDNSPacket *dcp_packet);
 137
 138 These functions are given an opaque `DCPluginDNSPacket` type, storing
 139 the packet in wire format, and metadata, including the client IP address.
 140
 141 Avoid accessing these metadata directly, and use the macros defined in
 142 `dnscrypt/plugins.h` instead.
 143
 144 A filter can alter the content of the DNS packet, and change its
 145 length with `dcplugin_set_wire_data_len()`. However, the size of the
 146 packet should never be larger than the size returned by
 147 `dcplugin_get_wire_data_max_len`.
 148
 149 The return code of a filter can be either of:
 150 - `DCP_SYNC_FILTER_RESULT_OK`
 151 - `DCP_SYNC_FILTER_RESULT_DIRECT` (only in a pre-filter) to bypass the
 152 resolver and directly send the (possibly modified) packet to the client.
 153 Post-filters will be bypassed as well.
 154 - `DCP_SYNC_FILTER_RESULT_KILL` in order to drop the packet.
 155 - `DCP_SYNC_FILTER_RESULT_ERROR` to drop the packet and indicate that a
 156 non-fatal error occurred.
 157
 158 API documentation
 159 -----------------
 160
 161 For more info about the API, see the online [dnscrypt API
 162 documentation](https://dnscrypt.org/plugin-api/plugin_8h.html).
 163
 164 The `dnscrypt-proxy` source code also ships with example plugins you
 165 may want to take a look at, in the `src/plugins` directory.