xref: /freebsd/contrib/unbound/dnstap/dnstap.proto (revision aa1a8ff2d6dbc51ef058f46f3db5a8bb77967145)
1// dnstap: flexible, structured event replication format for DNS software
2//
3// This file contains the protobuf schemas for the "dnstap" structured event
4// replication format for DNS software.
5
6// Written in 2013-2014 by Farsight Security, Inc.
7//
8// To the extent possible under law, the author(s) have dedicated all
9// copyright and related and neighboring rights to this file to the public
10// domain worldwide. This file is distributed without any warranty.
11//
12// You should have received a copy of the CC0 Public Domain Dedication along
13// with this file. If not, see:
14//
15// <http://creativecommons.org/publicdomain/zero/1.0/>.
16
17syntax = "proto2";
18package dnstap;
19
20// "Dnstap": this is the top-level dnstap type, which is a "union" type that
21// contains other kinds of dnstap payloads, although currently only one type
22// of dnstap payload is defined.
23// See: https://developers.google.com/protocol-buffers/docs/techniques#union
24message Dnstap {
25    // DNS server identity.
26    // If enabled, this is the identity string of the DNS server which generated
27    // this message. Typically this would be the same string as returned by an
28    // "NSID" (RFC 5001) query.
29    optional bytes      identity = 1;
30
31    // DNS server version.
32    // If enabled, this is the version string of the DNS server which generated
33    // this message. Typically this would be the same string as returned by a
34    // "version.bind" query.
35    optional bytes      version = 2;
36
37    // Extra data for this payload.
38    // This field can be used for adding an arbitrary byte-string annotation to
39    // the payload. No encoding or interpretation is applied or enforced.
40    optional bytes      extra = 3;
41
42    // Identifies which field below is filled in.
43    enum Type {
44        MESSAGE = 1;
45    }
46    required Type       type = 15;
47
48    // One of the following will be filled in.
49    optional Message    message = 14;
50}
51
52// SocketFamily: the network protocol family of a socket. This specifies how
53// to interpret "network address" fields.
54enum SocketFamily {
55    INET = 1;   // IPv4 (RFC 791)
56    INET6 = 2;  // IPv6 (RFC 2460)
57}
58
59// SocketProtocol: the protocol used to transport a DNS message.
60enum SocketProtocol {
61    UDP = 1;         // DNS over UDP transport (RFC 1035 section 4.2.1)
62    TCP = 2;         // DNS over TCP transport (RFC 1035 section 4.2.2)
63    DOT = 3;         // DNS over TLS (RFC 7858)
64    DOH = 4;         // DNS over HTTPS (RFC 8484)
65    DNSCryptUDP = 5; // DNSCrypt over UDP (https://dnscrypt.info/protocol)
66    DNSCryptTCP = 6; // DNSCrypt over TCP (https://dnscrypt.info/protocol)
67    DOQ = 7;         // DNS over QUIC (RFC 9250)
68}
69
70// Policy: information about any name server operator policy
71// applied to the processing of a DNS message.
72message Policy {
73
74    // Match: what aspect of the message or message exchange
75    // triggered the application of the Policy.
76    enum Match {
77        QNAME = 1;       // Name in question section of query
78        CLIENT_IP = 2;   // Client IP address
79        RESPONSE_IP = 3; // Address in A/AAAA RRSet
80        NS_NAME = 4;     // Authoritative name server, by name
81        NS_IP = 5;       // Authoritative name server, by IP address
82    }
83
84    // The Action taken to implement the Policy.
85    enum Action {
86        NXDOMAIN = 1;   // Respond with NXDOMAIN
87        NODATA = 2;     // Respond with empty answer section
88        PASS = 3;       // Do not alter the response (passthrough)
89        DROP = 4;       // Do not respond.
90        TRUNCATE = 5;   // Truncate UDP response, forcing TCP retry
91        LOCAL_DATA = 6; // Respond with local data from policy
92    }
93
94    // type: the type of policy applied, e.g. "RPZ" for a
95    // policy from a Response Policy Zone.
96    optional string type = 1;
97
98    // rule: the rule matched by the message.
99    //
100    // In a RPZ context, this is the owner name of the rule in
101    // the Reponse Policy Zone in wire format.
102    optional bytes rule = 2;
103
104    // action: the policy action taken in response to the
105    // rule match.
106    optional Action action = 3;
107
108    // match: the feature of the message exchange which matched the rule.
109    optional Match match = 4;
110
111    // The matched value. Format depends on the matched feature .
112    optional bytes value = 5;
113}
114
115// Message: a wire-format (RFC 1035 section 4) DNS message and associated
116// metadata. Applications generating "Message" payloads should follow
117// certain requirements based on the MessageType, see below.
118message Message {
119
120    // There are eight types of "Message" defined that correspond to the
121    // four arrows in the following diagram, slightly modified from RFC 1035
122    // section 2:
123
124    //    +---------+               +----------+           +--------+
125    //    |         |     query     |          |   query   |        |
126    //    | Stub    |-SQ--------CQ->| Recursive|-RQ----AQ->| Auth.  |
127    //    | Resolver|               | Server   |           | Name   |
128    //    |         |<-SR--------CR-|          |<-RR----AR-| Server |
129    //    +---------+    response   |          |  response |        |
130    //                              +----------+           +--------+
131
132    // Each arrow has two Type values each, one for each "end" of each arrow,
133    // because these are considered to be distinct events. Each end of each
134    // arrow on the diagram above has been marked with a two-letter Type
135    // mnemonic. Clockwise from upper left, these mnemonic values are:
136    //
137    //   SQ:        STUB_QUERY
138    //   CQ:      CLIENT_QUERY
139    //   RQ:    RESOLVER_QUERY
140    //   AQ:        AUTH_QUERY
141    //   AR:        AUTH_RESPONSE
142    //   RR:    RESOLVER_RESPONSE
143    //   CR:      CLIENT_RESPONSE
144    //   SR:        STUB_RESPONSE
145
146    // Two additional types of "Message" have been defined for the
147    // "forwarding" case where an upstream DNS server is responsible for
148    // further recursion. These are not shown on the diagram above, but have
149    // the following mnemonic values:
150
151    //   FQ:   FORWARDER_QUERY
152    //   FR:   FORWARDER_RESPONSE
153
154    // The "Message" Type values are defined below.
155
156    enum Type {
157        // AUTH_QUERY is a DNS query message received from a resolver by an
158        // authoritative name server, from the perspective of the authoritative
159        // name server.
160        AUTH_QUERY = 1;
161
162        // AUTH_RESPONSE is a DNS response message sent from an authoritative
163        // name server to a resolver, from the perspective of the authoritative
164        // name server.
165        AUTH_RESPONSE = 2;
166
167        // RESOLVER_QUERY is a DNS query message sent from a resolver to an
168        // authoritative name server, from the perspective of the resolver.
169        // Resolvers typically clear the RD (recursion desired) bit when
170        // sending queries.
171        RESOLVER_QUERY = 3;
172
173        // RESOLVER_RESPONSE is a DNS response message received from an
174        // authoritative name server by a resolver, from the perspective of
175        // the resolver.
176        RESOLVER_RESPONSE = 4;
177
178        // CLIENT_QUERY is a DNS query message sent from a client to a DNS
179        // server which is expected to perform further recursion, from the
180        // perspective of the DNS server. The client may be a stub resolver or
181        // forwarder or some other type of software which typically sets the RD
182        // (recursion desired) bit when querying the DNS server. The DNS server
183        // may be a simple forwarding proxy or it may be a full recursive
184        // resolver.
185        CLIENT_QUERY = 5;
186
187        // CLIENT_RESPONSE is a DNS response message sent from a DNS server to
188        // a client, from the perspective of the DNS server. The DNS server
189        // typically sets the RA (recursion available) bit when responding.
190        CLIENT_RESPONSE = 6;
191
192        // FORWARDER_QUERY is a DNS query message sent from a downstream DNS
193        // server to an upstream DNS server which is expected to perform
194        // further recursion, from the perspective of the downstream DNS
195        // server.
196        FORWARDER_QUERY = 7;
197
198        // FORWARDER_RESPONSE is a DNS response message sent from an upstream
199        // DNS server performing recursion to a downstream DNS server, from the
200        // perspective of the downstream DNS server.
201        FORWARDER_RESPONSE = 8;
202
203        // STUB_QUERY is a DNS query message sent from a stub resolver to a DNS
204        // server, from the perspective of the stub resolver.
205        STUB_QUERY = 9;
206
207        // STUB_RESPONSE is a DNS response message sent from a DNS server to a
208        // stub resolver, from the perspective of the stub resolver.
209        STUB_RESPONSE = 10;
210
211        // TOOL_QUERY is a DNS query message sent from a DNS software tool to a
212        // DNS server, from the perspective of the tool.
213        TOOL_QUERY = 11;
214
215        // TOOL_RESPONSE is a DNS response message received by a DNS software
216        // tool from a DNS server, from the perspective of the tool.
217        TOOL_RESPONSE = 12;
218
219        // UPDATE_QUERY is a Dynamic DNS Update request (RFC 2136) received
220        // by an authoritative name server, from the perspective of the
221        // authoritative name server.
222        UPDATE_QUERY = 13;
223
224        // UPDATE_RESPONSE is a Dynamic DNS Update response (RFC 2136) sent
225        // from an authoritative name server, from the perspective of the
226        // authoritative name server.
227        UPDATE_RESPONSE = 14;
228    }
229
230    // One of the Type values described above.
231    required Type               type = 1;
232
233    // One of the SocketFamily values described above.
234    optional SocketFamily       socket_family = 2;
235
236    // One of the SocketProtocol values described above.
237    optional SocketProtocol     socket_protocol = 3;
238
239    // The network address of the message initiator.
240    // For SocketFamily INET, this field is 4 octets (IPv4 address).
241    // For SocketFamily INET6, this field is 16 octets (IPv6 address).
242    optional bytes              query_address = 4;
243
244    // The network address of the message responder.
245    // For SocketFamily INET, this field is 4 octets (IPv4 address).
246    // For SocketFamily INET6, this field is 16 octets (IPv6 address).
247    optional bytes              response_address = 5;
248
249    // The transport port of the message initiator.
250    // This is a 16-bit UDP or TCP port number, depending on SocketProtocol.
251    optional uint32             query_port = 6;
252
253    // The transport port of the message responder.
254    // This is a 16-bit UDP or TCP port number, depending on SocketProtocol.
255    optional uint32             response_port = 7;
256
257    // The time at which the DNS query message was sent or received, depending
258    // on whether this is an AUTH_QUERY, RESOLVER_QUERY, or CLIENT_QUERY.
259    // This is the number of seconds since the UNIX epoch.
260    optional uint64             query_time_sec = 8;
261
262    // The time at which the DNS query message was sent or received.
263    // This is the seconds fraction, expressed as a count of nanoseconds.
264    optional fixed32            query_time_nsec = 9;
265
266    // The initiator's original wire-format DNS query message, verbatim.
267    optional bytes              query_message = 10;
268
269    // The "zone" or "bailiwick" pertaining to the DNS query message.
270    // This is a wire-format DNS domain name.
271    optional bytes              query_zone = 11;
272
273    // The time at which the DNS response message was sent or received,
274    // depending on whether this is an AUTH_RESPONSE, RESOLVER_RESPONSE, or
275    // CLIENT_RESPONSE.
276    // This is the number of seconds since the UNIX epoch.
277    optional uint64             response_time_sec = 12;
278
279    // The time at which the DNS response message was sent or received.
280    // This is the seconds fraction, expressed as a count of nanoseconds.
281    optional fixed32            response_time_nsec = 13;
282
283    // The responder's original wire-format DNS response message, verbatim.
284    optional bytes              response_message = 14;
285
286    // Operator policy applied to the processing of this message, if any.
287    optional Policy             policy = 15;
288}
289
290// All fields except for 'type' in the Message schema are optional.
291// It is recommended that at least the following fields be filled in for
292// particular types of Messages.
293
294// AUTH_QUERY:
295//      socket_family, socket_protocol
296//      query_address, query_port
297//      query_message
298//      query_time_sec, query_time_nsec
299
300// AUTH_RESPONSE:
301//      socket_family, socket_protocol
302//      query_address, query_port
303//      query_time_sec, query_time_nsec
304//      response_message
305//      response_time_sec, response_time_nsec
306
307// RESOLVER_QUERY:
308//      socket_family, socket_protocol
309//      query_message
310//      query_time_sec, query_time_nsec
311//      query_zone
312//      response_address, response_port
313
314// RESOLVER_RESPONSE:
315//      socket_family, socket_protocol
316//      query_time_sec, query_time_nsec
317//      query_zone
318//      response_address, response_port
319//      response_message
320//      response_time_sec, response_time_nsec
321
322// CLIENT_QUERY:
323//      socket_family, socket_protocol
324//      query_message
325//      query_time_sec, query_time_nsec
326
327// CLIENT_RESPONSE:
328//      socket_family, socket_protocol
329//      query_time_sec, query_time_nsec
330//      response_message
331//      response_time_sec, response_time_nsec
332