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