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