#include <assert.h>
#include <string.h>
#include <dnscrypt/private.h>
#include <dnscrypt/version.h>

Macros
#define	DCPLUGIN_MAIN(ID) DCPLUGIN_MAIN_PRIVATE(ID)

#define	dcplugin_get_user_data(P) ((P)->user_data)

#define	dcplugin_set_user_data(P, V) ((P)->user_data = (V))

#define	dcplugin_get_client_address(D) ((D)->client_sockaddr)

#define	dcplugin_get_client_address_len(D) ((D)->client_sockaddr_len)

#define	dcplugin_get_wire_data(D) ((D)->dns_packet)

#define	dcplugin_set_wire_data(D, V, L)

#define	dcplugin_get_wire_data_len(D) (*((D)->dns_packet_len_p))

#define	dcplugin_set_wire_data_len(D, L)

#define	dcplugin_get_wire_data_max_len(D) ((D)->dns_packet_max_len)

Typedefs
typedef struct DCPlugin_	DCPlugin

typedef struct DCPluginDNSPacket_	DCPluginDNSPacket

typedef enum DCPluginSyncFilterResult_	DCPluginSyncFilterResult

Enumerations
enum	DCPluginSyncFilterResult_ { DCP_SYNC_FILTER_RESULT_OK, DCP_SYNC_FILTER_RESULT_DIRECT, DCP_SYNC_FILTER_RESULT_KILL, DCP_SYNC_FILTER_RESULT_ERROR, DCP_SYNC_FILTER_RESULT_FATAL }

Functions
int	dcplugin_init (DCPlugin dcplugin, int argc, char argv[])

int	dcplugin_destroy (DCPlugin *dcplugin)

const char *	dcplugin_description (DCPlugin *dcplugin)

const char *	dcplugin_long_description (DCPlugin *dcplugin)

DCPluginSyncFilterResult	dcplugin_sync_pre_filter (DCPlugin dcplugin, DCPluginDNSPacket dcp_packet)

DCPluginSyncFilterResult	dcplugin_sync_post_filter (DCPlugin dcplugin, DCPluginDNSPacket dcp_packet)

Detailed Description

Interface for dnscrypt-proxy plugins.

A plugin can inspect and modify a request before it is authenticated and sent to the upstream server (pre-filters), or/and after a reply has been received and verified (post-filters).

Plugins are modules that have to implement (at least) dcplugin_init().

Plugins can be dynamicaly loaded by dnscrypt-proxy using –plugin=library[,arguments] Ex: –plugin=/usr/local/lib/dnscrypt-proxy/test.dll,-a,-H,–user=42

Multiple plugins can be chained, and queries will be sequentially passed through all of them.

The only header file you should include in a plugin is <dnscrypt/plugin.h>

Macro Definition Documentation

#define dcplugin_get_client_address ( D ) ((D)->client_sockaddr)

Retrieve the client address.

Parameters

D	a DCPluginDNSPacket object

Returns: a sockaddr_storage pointer

#define dcplugin_get_client_address_len ( D ) ((D)->client_sockaddr_len)

Get the client address length.

Parameters

D	a DCPluginDNSPacket object

Returns: the address length, as a size_t value

#define dcplugin_get_user_data ( P ) ((P)->user_data)

Get the user data of a plugin object.

Parameters

P	a plugin object

Returns: the user data

#define dcplugin_get_wire_data ( D ) ((D)->dns_packet)

Get the raw (wire format) content of the DNS packet.

Parameters

D	a DCPluginDNSPacket object

Returns: a pointer to a uint8_t buffer with the data in wire format

See Also: dcplugin_get_wire_data_len()

#define dcplugin_get_wire_data_len ( D ) (*((D)->dns_packet_len_p))

Get the number of bytes of the raw DNS packet.

Parameters

D	a DCPluginDNSPacket object

Returns: the number of bytes in the packet as a size_t object

See Also: dcplugin_get_wire_data(), dcplugin_set_wire_data_len()

#define dcplugin_get_wire_data_max_len ( D ) ((D)->dns_packet_max_len)

Get the maximum allowed number of bytes for the DNS packet.

Parameters

D	a DCPluginDNSPacket object

Returns: the max number of bytes as a size_t object

See Also: dcplugin_set_wire_data_len()

#define DCPLUGIN_MAIN ( ID ) DCPLUGIN_MAIN_PRIVATE(ID)

This macro should be present once in every plugin.

It basically defines all the symbols that have to be exported.

Parameters

ID	a string identifier, only used for debugging. Can be FILE.

#define dcplugin_set_user_data	(	P,
		V
	)	((P)->user_data = (V))

Set the user data of a plugin object.

Parameters

P	a plugin object
V	user data

Returns: the user data

#define dcplugin_set_wire_data	(	D,
		V,
		L
	)

Value:

do { \
      dcplugin_set_wire_data_len((D), (L)); \
      memcpy(dcplugin_get_wire_data(D), (V), (L)); \
    } while(0)

Change the content of the DNS packet.

Parameters

D	a DCPluginDNSPacket object
V	the new content as a pointer to a uint8_t * buffer
L	the new length of the packet

See Also: dcplugin_get_wire_data_len(), dcplugin_get_wire_data_max_len()

#define dcplugin_set_wire_data_len	(	D,
		L
	)

Value:

do { \
      assert(dcplugin_get_wire_data_max_len(D) >= (L)); \
      (*((D)->dns_packet_len_p)) = (L); \
    } while(0)

Update the size of the DNS packet.

Parameters

D	a DCPluginDNSPacket object
L	new size, that should always be smaller than the max allowed size

See Also: dcplugin_get_wire_data_max_len(), dcplugin_get_wire_data_len()

Typedef Documentation

typedef struct DCPlugin_ DCPlugin

A dnscrypt-proxy plugin object. This is an opaque structure that gets passed to all callbacks.

It includes a pointer to arbitrary user-supplied data.

See Also: dcplugin_get_user_data(), dcplugin_set_user_data()

typedef struct DCPluginDNSPacket_ DCPluginDNSPacket

A DNS packet.

It includes the data in wire format and the client address. The data can be inspected or modified.

typedef enum DCPluginSyncFilterResult_ DCPluginSyncFilterResult

The return code from a filter should be one of these.

DCP_SYNC_FILTER_RESULT_OK indicates that the filter was able to process the data and that the next filter should be called.

DCP_SYNC_FILTER_RESULT_DIRECT indicates that the filter built a response that should be directly sent to the client. The content of the current packet is this response. post-filters will not be triggered.

DCP_SYNC_FILTER_RESULT_KILL indicates that the filter asks for the query to be immediately terminated. The client will not receive any reply.

DCP_SYNC_FILTER_RESULT_ERROR indicates that an error occurred. The proxy will not be stopped, but the connection will be dropped.

DCP_SYNC_FILTER_RESULT_FATAL should not be used by plugins.

Enumeration Type Documentation

enum DCPluginSyncFilterResult_

The return code from a filter should be one of these.

DCP_SYNC_FILTER_RESULT_OK indicates that the filter was able to process the data and that the next filter should be called.

DCP_SYNC_FILTER_RESULT_DIRECT indicates that the filter built a response that should be directly sent to the client. The content of the current packet is this response. post-filters will not be triggered.

DCP_SYNC_FILTER_RESULT_KILL indicates that the filter asks for the query to be immediately terminated. The client will not receive any reply.

DCP_SYNC_FILTER_RESULT_ERROR indicates that an error occurred. The proxy will not be stopped, but the connection will be dropped.

DCP_SYNC_FILTER_RESULT_FATAL should not be used by plugins.

Function Documentation

const char* dcplugin_description ( DCPlugin * dcplugin )

This optional function returns a one-ine description of the plugin.

Parameters

dcplugin a plugin object

Returns: a human-readable one-line description of the plugin

int dcplugin_destroy ( DCPlugin * dcplugin )

This optional function is called when the plugin has to be unloaded.

Parameters

dcplugin a plugin object

Returns: 0 on success

int dcplugin_init	(	DCPlugin *	dcplugin,
		int	argc,
		char *	argv[]
	)

This is the entry point for a plugin.

Parameters

dcplugin	a plugin object
argc	the number of command-line arguments for this plugin
argv	the command-line arguments for this plugin

Returns: 0 on success

These can be parsed by getopt().

const char* dcplugin_long_description ( DCPlugin * dcplugin )

This optional function returns a long description of the plugin.

Parameters

dcplugin a plugin object

Returns: a human-readable long, multiline description of the plugin

DCPluginSyncFilterResult dcplugin_sync_post_filter	(	DCPlugin *	dcplugin,
		DCPluginDNSPacket *	dcp_packet
	)

This optional function implements a post-filter, for a reply.

This filter will be called after a server has sent a reply, and before this reply has been sent to the client.

Parameters

dcplugin	a plugin object
dcp_packet	a DNS packet

Returns: a valid return code

DCPluginSyncFilterResult dcplugin_sync_pre_filter	(	DCPlugin *	dcplugin,
		DCPluginDNSPacket *	dcp_packet
	)

This optional function implements a pre-filter, for a query.

This filter will be called after a client has sent a query, and before this query has been forwarded to an upstream server.

Parameters

dcplugin	a plugin object
dcp_packet	a DNS packet

Returns: a valid return code

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation