release/src/router/dnscrypt/src/include/dnscrypt/plugin.h

   1
   2 #ifndef __DNSCRYPT_PLUGIN_H__
   3 #define __DNSCRYPT_PLUGIN_H__ 1
   4
   5 /** @file dnscrypt/plugin.h
   6  *
   7  * Interface for dnscrypt-proxy plugins.
   8  *
   9  * A plugin can inspect and modify a request before it is authenticated and
  10  * sent to the upstream server (pre-filters), or/and after a reply has been
  11  * received and verified (post-filters).
  12  *
  13  * Plugins are modules that have to implement (at least) dcplugin_init().
  14  *
  15  * Plugins can be dynamicaly loaded by dnscrypt-proxy using
  16  * --plugin=library[,arguments]
  17  * Ex:
  18  * --plugin=/usr/local/lib/dnscrypt-proxy/test.dll,-a,-H,--user=42
  19  *
  20  * Multiple plugins can be chained, and queries will be sequentially passed
  21  * through all of them.
  22  *
  23  * The only header file you should include in a plugin is <dnscrypt/plugin.h>
  24  */
  25
  26 #include <assert.h>
  27 #include <string.h>
  28
  29 #include <dnscrypt/private.h>
  30 #include <dnscrypt/version.h>
  31
  32 #ifdef __cplusplus
  33 extern "C" {
  34 #endif
  35
  36 /**
  37  * This macro should be present once in every plugin.
  38  *
  39  * It basically defines all the symbols that have to be exported.
  40  *
  41  * @param ID a string identifier, only used for debugging. Can be __FILE__.
  42  */
  43 #define DCPLUGIN_MAIN(ID) DCPLUGIN_MAIN_PRIVATE(ID)
  44
  45 /**
  46  * A dnscrypt-proxy plugin object. This is an opaque structure that gets
  47  * passed to all callbacks.
  48  *
  49  * It includes a pointer to arbitrary user-supplied data.
  50  *
  51  * @see dcplugin_get_user_data(), dcplugin_set_user_data()
  52  */
  53 typedef struct DCPlugin_ DCPlugin;
  54
  55 /**
  56  * A DNS packet.
  57  *
  58  * It includes the data in wire format and the client address.
  59  * The data can be inspected or modified.
  60  */
  61 typedef struct DCPluginDNSPacket_ DCPluginDNSPacket;
  62
  63 /**
  64  * The return code from a filter should be one of these.
  65  *
  66  * DCP_SYNC_FILTER_RESULT_OK indicates that the filter was able to process
  67  * the data and that the next filter should be called.
  68  *
  69  * DCP_SYNC_FILTER_RESULT_DIRECT indicates that the filter built a response
  70  * that should be directly sent to the client. The content of the current
  71  * packet is this response. post-filters will not be triggered.
  72  *
  73  * DCP_SYNC_FILTER_RESULT_KILL indicates that the filter asks for the
  74  * query to be immediately terminated. The client will not receive any reply.
  75  *
  76  * DCP_SYNC_FILTER_RESULT_ERROR indicates that an error occurred.
  77  * The proxy will not be stopped, but the connection will be dropped.
  78  *
  79  * DCP_SYNC_FILTER_RESULT_FATAL should not be used by plugins.
  80  */
  81 typedef enum DCPluginSyncFilterResult_ {
  82     DCP_SYNC_FILTER_RESULT_OK,
  83     DCP_SYNC_FILTER_RESULT_DIRECT,
  84     DCP_SYNC_FILTER_RESULT_KILL,
  85     DCP_SYNC_FILTER_RESULT_ERROR,
  86     DCP_SYNC_FILTER_RESULT_FATAL
  87 } DCPluginSyncFilterResult;
  88
  89 /**
  90  * This is the entry point for a plugin.
  91  *
  92  * @param dcplugin a plugin object
  93  * @param argc the number of command-line arguments for this plugin
  94  * @param argv the command-line arguments for this plugin
  95  * @return 0 on success
  96  *
  97  * These can be parsed by getopt().
  98  */
  99 int dcplugin_init(DCPlugin *dcplugin, int argc, char *argv[]);
 100
 101 /**
 102  * This optional function is called when the plugin has to be unloaded.
 103  *
 104  * @param dcplugin a plugin object
 105  * @return 0 on success
 106  */
 107 int dcplugin_destroy(DCPlugin *dcplugin);
 108
 109 /**
 110  * This optional function returns a one-ine description of the plugin.
 111  *
 112  * @param dcplugin a plugin object
 113  * @return a human-readable one-line description of the plugin
 114  */
 115 const char *dcplugin_description(DCPlugin *dcplugin);
 116
 117 /**
 118  * This optional function returns a long description of the plugin.
 119  *
 120  * @param dcplugin a plugin object
 121  * @return a human-readable long, multiline description of the plugin
 122  */
 123 const char *dcplugin_long_description(DCPlugin *dcplugin);
 124
 125 /**
 126  * This optional function implements a pre-filter, for a query.
 127  *
 128  * This filter will be called after a client has sent a query, and before
 129  * this query has been forwarded to an upstream server.
 130  *
 131  * @param dcplugin a plugin object
 132  * @param dcp_packet a DNS packet
 133  * @return a valid return code
 134  */
 135 DCPluginSyncFilterResult
 136 dcplugin_sync_pre_filter(DCPlugin *dcplugin, DCPluginDNSPacket *dcp_packet);
 137
 138 /**
 139  * This optional function implements a post-filter, for a reply.
 140  *
 141  * This filter will be called after a server has sent a reply, and before
 142  * this reply has been sent to the client.
 143  *
 144  * @param dcplugin a plugin object
 145  * @param dcp_packet a DNS packet
 146  * @return a valid return code
 147  */
 148 DCPluginSyncFilterResult
 149 dcplugin_sync_post_filter(DCPlugin *dcplugin, DCPluginDNSPacket *dcp_packet);
 150
 151 /**
 152  * Get the user data of a plugin object.
 153  *
 154  * @param P a plugin object
 155  * @return the user data
 156  */
 157 #define dcplugin_get_user_data(P) ((P)->user_data)
 158
 159 /**
 160  * Set the user data of a plugin object.
 161  *
 162  * @param P a plugin object
 163  * @param V user data
 164  * @return the user data
 165  */
 166 #define dcplugin_set_user_data(P, V) ((P)->user_data = (V))
 167
 168 /**
 169  * Retrieve the client address.
 170  *
 171  * @param D a DCPluginDNSPacket object
 172  * @return a sockaddr_storage pointer
 173  */
 174 #define dcplugin_get_client_address(D) ((D)->client_sockaddr)
 175
 176 /**
 177  * Get the client address length.
 178  *
 179  * @param D a DCPluginDNSPacket object
 180  * @return the address length, as a size_t value
 181  */
 182 #define dcplugin_get_client_address_len(D) ((D)->client_sockaddr_len)
 183
 184 /**
 185  * Get the raw (wire format) content of the DNS packet.
 186  *
 187  * @param D a DCPluginDNSPacket object
 188  * @return a pointer to a uint8_t buffer with the data in wire format
 189  *
 190  * @see dcplugin_get_wire_data_len()
 191  */
 192 #define dcplugin_get_wire_data(D) ((D)->dns_packet)
 193
 194 /**
 195  * Change the content of the DNS packet.
 196  *
 197  * @param D a DCPluginDNSPacket object
 198  * @param V the new content as a pointer to a uint8_t * buffer
 199  * @param L the new length of the packet
 200  *
 201  * @see dcplugin_get_wire_data_len(), dcplugin_get_wire_data_max_len()
 202  */
 203 #define dcplugin_set_wire_data(D, V, L) do { \
 204       dcplugin_set_wire_data_len((D), (L)); \
 205       memcpy(dcplugin_get_wire_data(D), (V), (L)); \
 206     } while(0)
 207
 208 /**
 209  * Get the number of bytes of the raw DNS packet.
 210  * @param D a DCPluginDNSPacket object
 211  * @return the number of bytes in the packet as a size_t object
 212  *
 213  * @see dcplugin_get_wire_data(), dcplugin_set_wire_data_len()
 214  */
 215 #define dcplugin_get_wire_data_len(D) (*((D)->dns_packet_len_p))
 216
 217 /**
 218  * Update the size of the DNS packet.
 219  *
 220  * @param D a DCPluginDNSPacket object
 221  * @param L new size, that should always be smaller than the max allowed size
 222  *
 223  * @see dcplugin_get_wire_data_max_len(), dcplugin_get_wire_data_len()
 224  */
 225 #define dcplugin_set_wire_data_len(D, L) do { \
 226       assert(dcplugin_get_wire_data_max_len(D) >= (L)); \
 227       (*((D)->dns_packet_len_p)) = (L); \
 228     } while(0)
 229
 230 /**
 231  * Get the maximum allowed number of bytes for the DNS packet.
 232  *
 233  * @param D a DCPluginDNSPacket object
 234  * @return the max number of bytes as a size_t object
 235  *
 236  * @see dcplugin_set_wire_data_len()
 237  */
 238 #define dcplugin_get_wire_data_max_len(D) ((D)->dns_packet_max_len)
 239
 240 #ifdef __cplusplus
 241 }
 242 #endif
 243
 244 #endif