/*

[0] Fix | Delete

* Copyright (C) Internet Systems Consortium, Inc. ("ISC")

[1] Fix | Delete

*

[2] Fix | Delete

* This Source Code Form is subject to the terms of the Mozilla Public

[3] Fix | Delete

* License, v. 2.0. If a copy of the MPL was not distributed with this

[4] Fix | Delete

* file, you can obtain one at https://mozilla.org/MPL/2.0/.

[5] Fix | Delete

*

[6] Fix | Delete

* See the COPYRIGHT file distributed with this work for additional

[7] Fix | Delete

* information regarding copyright ownership.

[8] Fix | Delete

*/

[9] Fix | Delete

[10] Fix | Delete

#ifndef _DNSTAP_H

[11] Fix | Delete

#define _DNSTAP_H

[12] Fix | Delete

[13] Fix | Delete

/*****

[14] Fix | Delete

***** Module Info

[15] Fix | Delete

*****/

[16] Fix | Delete

[17] Fix | Delete

/*! \file

[18] Fix | Delete

* \brief

[19] Fix | Delete

* The dt (dnstap) module provides fast passive logging of DNS messages.

[20] Fix | Delete

* Protocol Buffers. The protobuf schema for Dnstap messages is in the

[21] Fix | Delete

* file dnstap.proto, which is compiled to dnstap.pb-c.c and dnstap.pb-c.h.

[22] Fix | Delete

*/

[23] Fix | Delete

[24] Fix | Delete

#include <inttypes.h>

[25] Fix | Delete

#include <stdbool.h>

[26] Fix | Delete

[27] Fix | Delete

#ifdef HAVE_DNSTAP

[28] Fix | Delete

#include <fstrm.h>

[29] Fix | Delete

#include <protobuf-c/protobuf-c.h>

[30] Fix | Delete

#else

[31] Fix | Delete

struct fstrm_iothr_options;

[32] Fix | Delete

#endif /* HAVE_DNSTAP */

[33] Fix | Delete

[34] Fix | Delete

#include <isc/region.h>

[35] Fix | Delete

#include <isc/sockaddr.h>

[36] Fix | Delete

#include <isc/time.h>

[37] Fix | Delete

#include <isc/types.h>

[38] Fix | Delete

[39] Fix | Delete

#include <dns/name.h>

[40] Fix | Delete

#include <dns/rdataclass.h>

[41] Fix | Delete

#include <dns/rdatatype.h>

[42] Fix | Delete

#include <dns/types.h>

[43] Fix | Delete

[44] Fix | Delete

/*%

[45] Fix | Delete

* Dnstap message types:

[46] Fix | Delete

*

[47] Fix | Delete

* STUB QUERY: SQ

[48] Fix | Delete

* STUB RESPONSE: SR

[49] Fix | Delete

* CLIENT QUERY: CQ

[50] Fix | Delete

* CLIENT RESPONSE: CR

[51] Fix | Delete

* AUTH QUERY: AQ

[52] Fix | Delete

* AUTH RESPONSE: AR

[53] Fix | Delete

* RESOLVER QUERY: RQ

[54] Fix | Delete

* RESOLVER RESPONSE: RR

[55] Fix | Delete

* FORWARDER QUERY: FQ

[56] Fix | Delete

* FORWARDER RESPONSE: FR

[57] Fix | Delete

*/

[58] Fix | Delete

[59] Fix | Delete

#define DNS_DTTYPE_SQ 0x0001

[60] Fix | Delete

#define DNS_DTTYPE_SR 0x0002

[61] Fix | Delete

#define DNS_DTTYPE_CQ 0x0004

[62] Fix | Delete

#define DNS_DTTYPE_CR 0x0008

[63] Fix | Delete

#define DNS_DTTYPE_AQ 0x0010

[64] Fix | Delete

#define DNS_DTTYPE_AR 0x0020

[65] Fix | Delete

#define DNS_DTTYPE_RQ 0x0040

[66] Fix | Delete

#define DNS_DTTYPE_RR 0x0080

[67] Fix | Delete

#define DNS_DTTYPE_FQ 0x0100

[68] Fix | Delete

#define DNS_DTTYPE_FR 0x0200

[69] Fix | Delete

#define DNS_DTTYPE_TQ 0x0400

[70] Fix | Delete

#define DNS_DTTYPE_TR 0x0800

[71] Fix | Delete

[72] Fix | Delete

#define DNS_DTTYPE_QUERY \

[73] Fix | Delete

(DNS_DTTYPE_SQ|DNS_DTTYPE_CQ|DNS_DTTYPE_AQ|\

[74] Fix | Delete

DNS_DTTYPE_RQ|DNS_DTTYPE_FQ|DNS_DTTYPE_TQ)

[75] Fix | Delete

#define DNS_DTTYPE_RESPONSE \

[76] Fix | Delete

(DNS_DTTYPE_SR|DNS_DTTYPE_CR|DNS_DTTYPE_AR|\

[77] Fix | Delete

DNS_DTTYPE_RR|DNS_DTTYPE_FR|DNS_DTTYPE_TR)

[78] Fix | Delete

#define DNS_DTTYPE_ALL \

[79] Fix | Delete

(DNS_DTTYPE_QUERY|DNS_DTTYPE_RESPONSE)

[80] Fix | Delete

[81] Fix | Delete

typedef enum {

[82] Fix | Delete

dns_dtmode_none = 0,

[83] Fix | Delete

dns_dtmode_file,

[84] Fix | Delete

dns_dtmode_unix

[85] Fix | Delete

} dns_dtmode_t;

[86] Fix | Delete

[87] Fix | Delete

typedef struct dns_dthandle dns_dthandle_t;

[88] Fix | Delete

[89] Fix | Delete

#ifdef HAVE_DNSTAP

[90] Fix | Delete

struct dns_dtdata {

[91] Fix | Delete

isc_mem_t *mctx;

[92] Fix | Delete

[93] Fix | Delete

void *frame;

[94] Fix | Delete

[95] Fix | Delete

bool query;

[96] Fix | Delete

bool tcp;

[97] Fix | Delete

dns_dtmsgtype_t type;

[98] Fix | Delete

[99] Fix | Delete

isc_time_t qtime;

[100] Fix | Delete

isc_time_t rtime;

[101] Fix | Delete

[102] Fix | Delete

isc_region_t qaddr;

[103] Fix | Delete

isc_region_t raddr;

[104] Fix | Delete

[105] Fix | Delete

uint32_t qport;

[106] Fix | Delete

uint32_t rport;

[107] Fix | Delete

[108] Fix | Delete

isc_region_t msgdata;

[109] Fix | Delete

dns_message_t *msg;

[110] Fix | Delete

[111] Fix | Delete

char namebuf[DNS_NAME_FORMATSIZE];

[112] Fix | Delete

char typebuf[DNS_RDATATYPE_FORMATSIZE];

[113] Fix | Delete

char classbuf[DNS_RDATACLASS_FORMATSIZE];

[114] Fix | Delete

};

[115] Fix | Delete

#endif /* HAVE_DNSTAP */

[116] Fix | Delete

[117] Fix | Delete

isc_result_t

[118] Fix | Delete

dns_dt_create(isc_mem_t *mctx, dns_dtmode_t mode, const char *path,

[119] Fix | Delete

struct fstrm_iothr_options **foptp, dns_dtenv_t **envp);

[120] Fix | Delete

/*%<

[121] Fix | Delete

* Create and initialize the dnstap environment.

[122] Fix | Delete

*

[123] Fix | Delete

* There should be a single global dnstap environment for the server;

[124] Fix | Delete

* copies of it will be attached to each view.

[125] Fix | Delete

*

[126] Fix | Delete

* Notes:

[127] Fix | Delete

*

[128] Fix | Delete

*\li 'path' refers to a UNIX domain socket by default. It may

[129] Fix | Delete

* optionally be prepended with "socket:" or "file:". If prepended

[130] Fix | Delete

* with "file:", then dnstap logs are sent to a file instead of a

[131] Fix | Delete

* socket.

[132] Fix | Delete

*

[133] Fix | Delete

*\li '*foptp' set the options for fstrm_iothr_init(). '*foptp' must have

[134] Fix | Delete

* have had the number of input queues set and this should be set

[135] Fix | Delete

* to the number of worker threads. Additionally the queue model

[136] Fix | Delete

* should also be set. Other options may be set if desired.

[137] Fix | Delete

* If dns_dt_create succeeds the *foptp is set to NULL.

[138] Fix | Delete

*

[139] Fix | Delete

* Requires:

[140] Fix | Delete

*

[141] Fix | Delete

*\li 'mctx' is a valid memory context.

[142] Fix | Delete

*

[143] Fix | Delete

*\li 'path' is a valid C string.

[144] Fix | Delete

*

[145] Fix | Delete

*\li 'fopt' is non NULL.

[146] Fix | Delete

*

[147] Fix | Delete

*\li envp != NULL && *envp == NULL

[148] Fix | Delete

*

[149] Fix | Delete

* Returns:

[150] Fix | Delete

*

[151] Fix | Delete

*\li #ISC_R_SUCCESS

[152] Fix | Delete

*\li #ISC_R_NOMEMORY

[153] Fix | Delete

*

[154] Fix | Delete

*\li Other errors are possible.

[155] Fix | Delete

*/

[156] Fix | Delete

[157] Fix | Delete

isc_result_t

[158] Fix | Delete

dns_dt_reopen(dns_dtenv_t *env, int roll);

[159] Fix | Delete

/*%<

[160] Fix | Delete

* Reopens files established by dns_dt_create().

[161] Fix | Delete

*

[162] Fix | Delete

* If 'roll' is non-negative and 'env->mode' is dns_dtmode_file,

[163] Fix | Delete

* then the file is automatically rolled over before reopening.

[164] Fix | Delete

* The value of 'roll' indicates the number of backup log files to

[165] Fix | Delete

* keep. If 'roll' is negative, or if 'env->mode' is dns_dtmode_unix,

[166] Fix | Delete

* then the channel is simply reopened.

[167] Fix | Delete

*

[168] Fix | Delete

* Note: dns_dt_reopen() must be called in task exclusive mode.

[169] Fix | Delete

*

[170] Fix | Delete

* Requires:

[171] Fix | Delete

*\li 'env' is a valid dnstap environment.

[172] Fix | Delete

*/

[173] Fix | Delete

[174] Fix | Delete

isc_result_t

[175] Fix | Delete

dns_dt_setidentity(dns_dtenv_t *env, const char *identity);

[176] Fix | Delete

isc_result_t

[177] Fix | Delete

dns_dt_setversion(dns_dtenv_t *env, const char *version);

[178] Fix | Delete

/*%<

[179] Fix | Delete

* Set the "identity" and "version" strings to be sent in dnstap messages.

[180] Fix | Delete

*

[181] Fix | Delete

* Requires:

[182] Fix | Delete

*

[183] Fix | Delete

*\li 'env' is a valid dnstap environment.

[184] Fix | Delete

*/

[185] Fix | Delete

[186] Fix | Delete

void

[187] Fix | Delete

dns_dt_attach(dns_dtenv_t *source, dns_dtenv_t **destp);

[188] Fix | Delete

/*%<

[189] Fix | Delete

* Attach '*destp' to 'source', incrementing the reference counter.

[190] Fix | Delete

*

[191] Fix | Delete

* Requires:

[192] Fix | Delete

*

[193] Fix | Delete

*\li 'source' is a valid dnstap environment.

[194] Fix | Delete

*

[195] Fix | Delete

*\li 'destp' is not NULL and '*destp' is NULL.

[196] Fix | Delete

*

[197] Fix | Delete

*\li *destp is attached to source.

[198] Fix | Delete

*/

[199] Fix | Delete

[200] Fix | Delete

void

[201] Fix | Delete

dns_dt_detach(dns_dtenv_t **envp);

[202] Fix | Delete

/*%<

[203] Fix | Delete

* Detach '*envp', decrementing the reference counter.

[204] Fix | Delete

*

[205] Fix | Delete

* Requires:

[206] Fix | Delete

*

[207] Fix | Delete

*\li '*envp' is a valid dnstap environment.

[208] Fix | Delete

*

[209] Fix | Delete

* Ensures:

[210] Fix | Delete

*

[211] Fix | Delete

*\li '*envp' will be destroyed when the number of references reaches zero.

[212] Fix | Delete

*

[213] Fix | Delete

*\li '*envp' is NULL.

[214] Fix | Delete

*/

[215] Fix | Delete

[216] Fix | Delete

isc_result_t

[217] Fix | Delete

dns_dt_getstats(dns_dtenv_t *env, isc_stats_t **statsp);

[218] Fix | Delete

/*%<

[219] Fix | Delete

* Attach to the stats struct if it exists.

[220] Fix | Delete

*

[221] Fix | Delete

* Requires:

[222] Fix | Delete

*

[223] Fix | Delete

*\li 'env' is a valid dnstap environment.

[224] Fix | Delete

*

[225] Fix | Delete

*\li 'statsp' is non NULL and '*statsp' is NULL.

[226] Fix | Delete

*

[227] Fix | Delete

* Returns:

[228] Fix | Delete

*

[229] Fix | Delete

*\li ISC_R_SUCCESS

[230] Fix | Delete

*

[231] Fix | Delete

*\li ISC_R_NOTFOUND

[232] Fix | Delete

*/

[233] Fix | Delete

[234] Fix | Delete

void

[235] Fix | Delete

dns_dt_shutdown(void);

[236] Fix | Delete

/*%<

[237] Fix | Delete

* Shuts down dnstap and frees global resources. This function must only

[238] Fix | Delete

* be called immediately before server shutdown.

[239] Fix | Delete

*/

[240] Fix | Delete

[241] Fix | Delete

void

[242] Fix | Delete

dns_dt_send(dns_view_t *view, dns_dtmsgtype_t msgtype,

[243] Fix | Delete

isc_sockaddr_t *qaddr, isc_sockaddr_t *dstaddr,

[244] Fix | Delete

bool tcp, isc_region_t *zone, isc_time_t *qtime,

[245] Fix | Delete

isc_time_t *rtime, isc_buffer_t *buf);

[246] Fix | Delete

/*%<

[247] Fix | Delete

* Sends a dnstap message to the log, if 'msgtype' is one of the message

[248] Fix | Delete

* types represented in 'view->dttypes'.

[249] Fix | Delete

*

[250] Fix | Delete

* Parameters are: 'qaddr' (query address, i.e, the address of the

[251] Fix | Delete

* query initiator); 'raddr' (response address, i.e., the address of

[252] Fix | Delete

* the query responder); 'tcp' (boolean indicating whether the transaction

[253] Fix | Delete

* was over TCP); 'zone' (the authoritative zone or bailiwick, in

[254] Fix | Delete

* uncompressed wire format), 'qtime' and 'rtime' (query and response

[255] Fix | Delete

* times; if NULL, they are set to the current time); and 'buf' (the

[256] Fix | Delete

* DNS message being logged, in wire format).

[257] Fix | Delete

*

[258] Fix | Delete

* Requires:

[259] Fix | Delete

*

[260] Fix | Delete

*\li 'view' is a valid view, and 'view->dtenv' is NULL or is a

[261] Fix | Delete

* valid dnstap environment.

[262] Fix | Delete

*/

[263] Fix | Delete

[264] Fix | Delete

isc_result_t

[265] Fix | Delete

dns_dt_parse(isc_mem_t *mctx, isc_region_t *src, dns_dtdata_t **destp);

[266] Fix | Delete

/*%<

[267] Fix | Delete

* Converts a raw dnstap frame in 'src' to a parsed dnstap data structure

[268] Fix | Delete

* in '*destp'.

[269] Fix | Delete

*

[270] Fix | Delete

* Requires:

[271] Fix | Delete

*\li 'src' is not NULL

[272] Fix | Delete

*

[273] Fix | Delete

*\li 'destp' is not NULL and '*destp' points to a valid buffer.

[274] Fix | Delete

*

[275] Fix | Delete

* Returns:

[276] Fix | Delete

*\li #ISC_R_SUCCESS on success

[277] Fix | Delete

*

[278] Fix | Delete

*\li Other errors are possible.

[279] Fix | Delete

*/

[280] Fix | Delete

[281] Fix | Delete

isc_result_t

[282] Fix | Delete

dns_dt_datatotext(dns_dtdata_t *d, isc_buffer_t **dest);

[283] Fix | Delete

/*%<

[284] Fix | Delete

* Converts a parsed dnstap data structure 'd' to text, storing

[285] Fix | Delete

* the result in the buffer 'dest'. If 'dest' points to a dynamically

[286] Fix | Delete

* allocated buffer, then it may be reallocated as needed.

[287] Fix | Delete

*

[288] Fix | Delete

* (XXX: add a 'long_form' option to generate a detailed listing of

[289] Fix | Delete

* dnstap data instead * of a one-line summary.)

[290] Fix | Delete

*

[291] Fix | Delete

* Requires:

[292] Fix | Delete

*\li 'd' is not NULL

[293] Fix | Delete

*

[294] Fix | Delete

*\li 'dest' is not NULL and '*dest' points to a valid buffer.

[295] Fix | Delete

*

[296] Fix | Delete

* Returns:

[297] Fix | Delete

*\li #ISC_R_SUCCESS on success

[298] Fix | Delete

*\li #ISC_R_NOSPACE if buffer is not dynamic and runs out of space

[299] Fix | Delete

*\li #ISC_R_NOMEMORY if buffer is dynamic but memory could not be allocated

[300] Fix | Delete

*

[301] Fix | Delete

*\li Other errors are possible.

[302] Fix | Delete

*/

[303] Fix | Delete

[304] Fix | Delete

void

[305] Fix | Delete

dns_dtdata_free(dns_dtdata_t **dp);

[306] Fix | Delete

/*%<

[307] Fix | Delete

* Frees the specified dns_dtdata structure and all its members,

[308] Fix | Delete

* and sets *dp to NULL.

[309] Fix | Delete

*/

[310] Fix | Delete

[311] Fix | Delete

isc_result_t

[312] Fix | Delete

dns_dt_open(const char *filename, dns_dtmode_t mode,

[313] Fix | Delete

isc_mem_t *mctx, dns_dthandle_t **handlep);

[314] Fix | Delete

/*%<

[315] Fix | Delete

* Opens a dnstap framestream at 'filename' and stores a pointer to the

[316] Fix | Delete

* reader object in a dns_dthandle_t structure.

[317] Fix | Delete

*

[318] Fix | Delete

* The caller is responsible for allocating the handle structure.

[319] Fix | Delete

*

[320] Fix | Delete

* (XXX: Currently only file readers are supported, not unix-domain socket

[321] Fix | Delete

* readers.)

[322] Fix | Delete

*

[323] Fix | Delete

* Requires:

[324] Fix | Delete

*

[325] Fix | Delete

*\li 'filename' is not NULL.

[326] Fix | Delete

*

[327] Fix | Delete

*\li 'handlep' is not NULL and '*handlep' is NULL.

[328] Fix | Delete

*

[329] Fix | Delete

*\li '*mctx' is not a valid memory context.

[330] Fix | Delete

*

[331] Fix | Delete

* Returns:

[332] Fix | Delete

*

[333] Fix | Delete

*\li #ISC_R_SUCCESS on success

[334] Fix | Delete

*\li #ISC_R_NOTIMPLEMENTED if 'mode' is not dns_dtmode_file. (XXX)

[335] Fix | Delete

*\li #ISC_R_NOMEMORY if the fstrm library was unable to allocate a

[336] Fix | Delete

* reader or options structure

[337] Fix | Delete

*\li #ISC_R_FAILURE if 'filename' could not be opened.

[338] Fix | Delete

*\li #DNS_R_BADDNSTAP if 'filename' does not contain a dnstap

[339] Fix | Delete

* framestream.

[340] Fix | Delete

*/

[341] Fix | Delete

[342] Fix | Delete

isc_result_t

[343] Fix | Delete

dns_dt_getframe(dns_dthandle_t *handle, uint8_t **bufp, size_t *sizep);

[344] Fix | Delete

/*%<

[345] Fix | Delete

* Read a dnstap frame from the framstream reader in 'handle', storing

[346] Fix | Delete

* a pointer to it in '*bufp' and its size in '*sizep'.

[347] Fix | Delete

*

[348] Fix | Delete

* Requires:

[349] Fix | Delete

*

[350] Fix | Delete

*\li 'handle' is not NULL

[351] Fix | Delete

*\li 'bufp' is not NULL

[352] Fix | Delete

*\li 'sizep' is not NULL

[353] Fix | Delete

*

[354] Fix | Delete

* Ensures:

[355] Fix | Delete

* \li if returning ISC_R_SUCCESS then '*bufp' is not NULL

[356] Fix | Delete

*

[357] Fix | Delete

* Returns:

[358] Fix | Delete

*

[359] Fix | Delete

*\li #ISC_R_SUCCESS on success

[360] Fix | Delete

*\li #ISC_R_NOMORE at the end of the frame stream

[361] Fix | Delete

*\li #ISC_R_FAILURE for any other failure

[362] Fix | Delete

*/

[363] Fix | Delete

[364] Fix | Delete

void

[365] Fix | Delete

dns_dt_close(dns_dthandle_t **handlep);

[366] Fix | Delete

/*%<

[367] Fix | Delete

* Closes the dnstap file referenced by 'handle'.

[368] Fix | Delete

*

[369] Fix | Delete

* Requires:

[370] Fix | Delete

*

[371] Fix | Delete

*\li '*handlep' is not NULL

[372] Fix | Delete

*/

[373] Fix | Delete

[374] Fix | Delete

#endif /* _DNSTAP_H */

[375] Fix | Delete

[376] Fix | Delete