]>
Commit | Line | Data |
---|---|---|
82a91ddf CH |
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/>. | |
a49ce700 | 16 | syntax = "proto2"; |
82a91ddf CH |
17 | |
18 | package 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 | |
24 | message 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. | |
54 | enum SocketFamily { | |
55 | INET = 1; // IPv4 (RFC 791) | |
56 | INET6 = 2; // IPv6 (RFC 2460) | |
57 | } | |
58 | ||
59 | // SocketProtocol: the transport protocol of a socket. This specifies how to | |
60 | // interpret "transport port" fields. | |
61 | enum SocketProtocol { | |
62 | UDP = 1; // User Datagram Protocol (RFC 768) | |
63 | TCP = 2; // Transmission Control Protocol (RFC 793) | |
64 | } | |
65 | ||
66 | // Message: a wire-format (RFC 1035 section 4) DNS message and associated | |
67 | // metadata. Applications generating "Message" payloads should follow | |
68 | // certain requirements based on the MessageType, see below. | |
69 | message Message { | |
70 | ||
71 | // There are eight types of "Message" defined that correspond to the | |
72 | // four arrows in the following diagram, slightly modified from RFC 1035 | |
73 | // section 2: | |
74 | ||
75 | // +---------+ +----------+ +--------+ | |
76 | // | | query | | query | | | |
77 | // | Stub |-SQ--------CQ->| Recursive|-RQ----AQ->| Auth. | | |
78 | // | Resolver| | Server | | Name | | |
79 | // | |<-SR--------CR-| |<-RR----AR-| Server | | |
80 | // +---------+ response | | response | | | |
81 | // +----------+ +--------+ | |
82 | ||
83 | // Each arrow has two Type values each, one for each "end" of each arrow, | |
84 | // because these are considered to be distinct events. Each end of each | |
85 | // arrow on the diagram above has been marked with a two-letter Type | |
86 | // mnemonic. Clockwise from upper left, these mnemonic values are: | |
87 | // | |
88 | // SQ: STUB_QUERY | |
89 | // CQ: CLIENT_QUERY | |
90 | // RQ: RESOLVER_QUERY | |
91 | // AQ: AUTH_QUERY | |
92 | // AR: AUTH_RESPONSE | |
93 | // RR: RESOLVER_RESPONSE | |
94 | // CR: CLIENT_RESPONSE | |
95 | // SR: STUB_RESPONSE | |
96 | ||
97 | // Two additional types of "Message" have been defined for the | |
98 | // "forwarding" case where an upstream DNS server is responsible for | |
99 | // further recursion. These are not shown on the diagram above, but have | |
100 | // the following mnemonic values: | |
101 | ||
102 | // FQ: FORWARDER_QUERY | |
103 | // FR: FORWARDER_RESPONSE | |
104 | ||
105 | // The "Message" Type values are defined below. | |
106 | ||
107 | enum Type { | |
108 | // AUTH_QUERY is a DNS query message received from a resolver by an | |
109 | // authoritative name server, from the perspective of the authorative | |
110 | // name server. | |
111 | AUTH_QUERY = 1; | |
112 | ||
113 | // AUTH_RESPONSE is a DNS response message sent from an authoritative | |
114 | // name server to a resolver, from the perspective of the authoritative | |
115 | // name server. | |
116 | AUTH_RESPONSE = 2; | |
117 | ||
118 | // RESOLVER_QUERY is a DNS query message sent from a resolver to an | |
119 | // authoritative name server, from the perspective of the resolver. | |
120 | // Resolvers typically clear the RD (recursion desired) bit when | |
121 | // sending queries. | |
122 | RESOLVER_QUERY = 3; | |
123 | ||
124 | // RESOLVER_RESPONSE is a DNS response message received from an | |
125 | // authoritative name server by a resolver, from the perspective of | |
126 | // the resolver. | |
127 | RESOLVER_RESPONSE = 4; | |
128 | ||
129 | // CLIENT_QUERY is a DNS query message sent from a client to a DNS | |
130 | // server which is expected to perform further recursion, from the | |
131 | // perspective of the DNS server. The client may be a stub resolver or | |
132 | // forwarder or some other type of software which typically sets the RD | |
133 | // (recursion desired) bit when querying the DNS server. The DNS server | |
134 | // may be a simple forwarding proxy or it may be a full recursive | |
135 | // resolver. | |
136 | CLIENT_QUERY = 5; | |
137 | ||
138 | // CLIENT_RESPONSE is a DNS response message sent from a DNS server to | |
139 | // a client, from the perspective of the DNS server. The DNS server | |
140 | // typically sets the RA (recursion available) bit when responding. | |
141 | CLIENT_RESPONSE = 6; | |
142 | ||
143 | // FORWARDER_QUERY is a DNS query message sent from a downstream DNS | |
144 | // server to an upstream DNS server which is expected to perform | |
145 | // further recursion, from the perspective of the downstream DNS | |
146 | // server. | |
147 | FORWARDER_QUERY = 7; | |
148 | ||
149 | // FORWARDER_RESPONSE is a DNS response message sent from an upstream | |
150 | // DNS server performing recursion to a downstream DNS server, from the | |
151 | // perspective of the downstream DNS server. | |
152 | FORWARDER_RESPONSE = 8; | |
153 | ||
154 | // STUB_QUERY is a DNS query message sent from a stub resolver to a DNS | |
155 | // server, from the perspective of the stub resolver. | |
156 | STUB_QUERY = 9; | |
157 | ||
158 | // STUB_RESPONSE is a DNS response message sent from a DNS server to a | |
159 | // stub resolver, from the perspective of the stub resolver. | |
160 | STUB_RESPONSE = 10; | |
161 | ||
162 | // TOOL_QUERY is a DNS query message sent from a DNS software tool to a | |
163 | // DNS server, from the perspective of the tool. | |
164 | TOOL_QUERY = 11; | |
165 | ||
166 | // TOOL_RESPONSE is a DNS response message received by a DNS software | |
167 | // tool from a DNS server, from the perspective of the tool. | |
168 | TOOL_RESPONSE = 12; | |
169 | } | |
170 | ||
171 | // One of the Type values described above. | |
172 | required Type type = 1; | |
173 | ||
174 | // One of the SocketFamily values described above. | |
175 | optional SocketFamily socket_family = 2; | |
176 | ||
177 | // One of the SocketProtocol values described above. | |
178 | optional SocketProtocol socket_protocol = 3; | |
179 | ||
180 | // The network address of the message initiator. | |
181 | // For SocketFamily INET, this field is 4 octets (IPv4 address). | |
182 | // For SocketFamily INET6, this field is 16 octets (IPv6 address). | |
183 | optional bytes query_address = 4; | |
184 | ||
185 | // The network address of the message responder. | |
186 | // For SocketFamily INET, this field is 4 octets (IPv4 address). | |
187 | // For SocketFamily INET6, this field is 16 octets (IPv6 address). | |
188 | optional bytes response_address = 5; | |
189 | ||
190 | // The transport port of the message initiator. | |
191 | // This is a 16-bit UDP or TCP port number, depending on SocketProtocol. | |
192 | optional uint32 query_port = 6; | |
193 | ||
194 | // The transport port of the message responder. | |
195 | // This is a 16-bit UDP or TCP port number, depending on SocketProtocol. | |
196 | optional uint32 response_port = 7; | |
197 | ||
198 | // The time at which the DNS query message was sent or received, depending | |
199 | // on whether this is an AUTH_QUERY, RESOLVER_QUERY, or CLIENT_QUERY. | |
200 | // This is the number of seconds since the UNIX epoch. | |
201 | optional uint64 query_time_sec = 8; | |
202 | ||
203 | // The time at which the DNS query message was sent or received. | |
204 | // This is the seconds fraction, expressed as a count of nanoseconds. | |
205 | optional fixed32 query_time_nsec = 9; | |
206 | ||
207 | // The initiator's original wire-format DNS query message, verbatim. | |
208 | optional bytes query_message = 10; | |
209 | ||
210 | // The "zone" or "bailiwick" pertaining to the DNS query message. | |
211 | // This is a wire-format DNS domain name. | |
212 | optional bytes query_zone = 11; | |
213 | ||
214 | // The time at which the DNS response message was sent or received, | |
215 | // depending on whether this is an AUTH_RESPONSE, RESOLVER_RESPONSE, or | |
216 | // CLIENT_RESPONSE. | |
217 | // This is the number of seconds since the UNIX epoch. | |
218 | optional uint64 response_time_sec = 12; | |
219 | ||
220 | // The time at which the DNS response message was sent or received. | |
221 | // This is the seconds fraction, expressed as a count of nanoseconds. | |
222 | optional fixed32 response_time_nsec = 13; | |
223 | ||
224 | // The responder's original wire-format DNS response message, verbatim. | |
225 | optional bytes response_message = 14; | |
226 | } | |
227 | ||
228 | // All fields except for 'type' in the Message schema are optional. | |
229 | // It is recommended that at least the following fields be filled in for | |
230 | // particular types of Messages. | |
231 | ||
232 | // AUTH_QUERY: | |
233 | // socket_family, socket_protocol | |
234 | // query_address, query_port | |
235 | // query_message | |
236 | // query_time_sec, query_time_nsec | |
237 | ||
238 | // AUTH_RESPONSE: | |
239 | // socket_family, socket_protocol | |
240 | // query_address, query_port | |
241 | // query_time_sec, query_time_nsec | |
242 | // response_message | |
243 | // response_time_sec, response_time_nsec | |
244 | ||
245 | // RESOLVER_QUERY: | |
246 | // socket_family, socket_protocol | |
247 | // query_message | |
248 | // query_time_sec, query_time_nsec | |
249 | // query_zone | |
250 | // response_address, response_port | |
251 | ||
252 | // RESOLVER_RESPONSE: | |
253 | // socket_family, socket_protocol | |
254 | // query_time_sec, query_time_nsec | |
255 | // query_zone | |
256 | // response_address, response_port | |
257 | // response_message | |
258 | // response_time_sec, response_time_nsec | |
259 | ||
260 | // CLIENT_QUERY: | |
261 | // socket_family, socket_protocol | |
262 | // query_message | |
263 | // query_time_sec, query_time_nsec | |
264 | ||
265 | // CLIENT_RESPONSE: | |
266 | // socket_family, socket_protocol | |
267 | // query_time_sec, query_time_nsec | |
268 | // response_message | |
269 | // response_time_sec, response_time_nsec |