1276541Sdes// dnstap: flexible, structured event replication format for DNS software 2276541Sdes// 3276541Sdes// This file contains the protobuf schemas for the "dnstap" structured event 4276541Sdes// replication format for DNS software. 5276541Sdes 6276541Sdes// Written in 2013-2014 by Farsight Security, Inc. 7276541Sdes// 8276541Sdes// To the extent possible under law, the author(s) have dedicated all 9276541Sdes// copyright and related and neighboring rights to this file to the public 10276541Sdes// domain worldwide. This file is distributed without any warranty. 11276541Sdes// 12276541Sdes// You should have received a copy of the CC0 Public Domain Dedication along 13276541Sdes// with this file. If not, see: 14276541Sdes// 15276541Sdes// <http://creativecommons.org/publicdomain/zero/1.0/>. 16276541Sdes 17276541Sdespackage dnstap; 18276541Sdes 19276541Sdes// "Dnstap": this is the top-level dnstap type, which is a "union" type that 20276541Sdes// contains other kinds of dnstap payloads, although currently only one type 21276541Sdes// of dnstap payload is defined. 22276541Sdes// See: https://developers.google.com/protocol-buffers/docs/techniques#union 23276541Sdesmessage Dnstap { 24276541Sdes // DNS server identity. 25276541Sdes // If enabled, this is the identity string of the DNS server which generated 26276541Sdes // this message. Typically this would be the same string as returned by an 27276541Sdes // "NSID" (RFC 5001) query. 28276541Sdes optional bytes identity = 1; 29276541Sdes 30276541Sdes // DNS server version. 31276541Sdes // If enabled, this is the version string of the DNS server which generated 32276541Sdes // this message. Typically this would be the same string as returned by a 33276541Sdes // "version.bind" query. 34276541Sdes optional bytes version = 2; 35276541Sdes 36276541Sdes // Extra data for this payload. 37276541Sdes // This field can be used for adding an arbitrary byte-string annotation to 38276541Sdes // the payload. No encoding or interpretation is applied or enforced. 39276541Sdes optional bytes extra = 3; 40276541Sdes 41276541Sdes // Identifies which field below is filled in. 42276541Sdes enum Type { 43276541Sdes MESSAGE = 1; 44276541Sdes } 45276541Sdes required Type type = 15; 46276541Sdes 47276541Sdes // One of the following will be filled in. 48276541Sdes optional Message message = 14; 49276541Sdes} 50276541Sdes 51276541Sdes// SocketFamily: the network protocol family of a socket. This specifies how 52276541Sdes// to interpret "network address" fields. 53276541Sdesenum SocketFamily { 54276541Sdes INET = 1; // IPv4 (RFC 791) 55276541Sdes INET6 = 2; // IPv6 (RFC 2460) 56276541Sdes} 57276541Sdes 58276541Sdes// SocketProtocol: the transport protocol of a socket. This specifies how to 59276541Sdes// interpret "transport port" fields. 60276541Sdesenum SocketProtocol { 61276541Sdes UDP = 1; // User Datagram Protocol (RFC 768) 62276541Sdes TCP = 2; // Transmission Control Protocol (RFC 793) 63276541Sdes} 64276541Sdes 65276541Sdes// Message: a wire-format (RFC 1035 section 4) DNS message and associated 66276541Sdes// metadata. Applications generating "Message" payloads should follow 67276541Sdes// certain requirements based on the MessageType, see below. 68276541Sdesmessage Message { 69276541Sdes 70276541Sdes // There are eight types of "Message" defined that correspond to the 71276541Sdes // four arrows in the following diagram, slightly modified from RFC 1035 72276541Sdes // section 2: 73276541Sdes 74276541Sdes // +---------+ +----------+ +--------+ 75276541Sdes // | | query | | query | | 76276541Sdes // | Stub |-SQ--------CQ->| Recursive|-RQ----AQ->| Auth. | 77276541Sdes // | Resolver| | Server | | Name | 78276541Sdes // | |<-SR--------CR-| |<-RR----AR-| Server | 79276541Sdes // +---------+ response | | response | | 80276541Sdes // +----------+ +--------+ 81276541Sdes 82276541Sdes // Each arrow has two Type values each, one for each "end" of each arrow, 83276541Sdes // because these are considered to be distinct events. Each end of each 84276541Sdes // arrow on the diagram above has been marked with a two-letter Type 85276541Sdes // mnemonic. Clockwise from upper left, these mnemonic values are: 86276541Sdes // 87276541Sdes // SQ: STUB_QUERY 88276541Sdes // CQ: CLIENT_QUERY 89276541Sdes // RQ: RESOLVER_QUERY 90276541Sdes // AQ: AUTH_QUERY 91276541Sdes // AR: AUTH_RESPONSE 92276541Sdes // RR: RESOLVER_RESPONSE 93276541Sdes // CR: CLIENT_RESPONSE 94276541Sdes // SR: STUB_RESPONSE 95276541Sdes 96276541Sdes // Two additional types of "Message" have been defined for the 97276541Sdes // "forwarding" case where an upstream DNS server is responsible for 98276541Sdes // further recursion. These are not shown on the diagram above, but have 99276541Sdes // the following mnemonic values: 100276541Sdes 101276541Sdes // FQ: FORWARDER_QUERY 102276541Sdes // FR: FORWARDER_RESPONSE 103276541Sdes 104276541Sdes // The "Message" Type values are defined below. 105276541Sdes 106276541Sdes enum Type { 107276541Sdes // AUTH_QUERY is a DNS query message received from a resolver by an 108276541Sdes // authoritative name server, from the perspective of the authorative 109276541Sdes // name server. 110276541Sdes AUTH_QUERY = 1; 111276541Sdes 112276541Sdes // AUTH_RESPONSE is a DNS response message sent from an authoritative 113276541Sdes // name server to a resolver, from the perspective of the authoritative 114276541Sdes // name server. 115276541Sdes AUTH_RESPONSE = 2; 116276541Sdes 117276541Sdes // RESOLVER_QUERY is a DNS query message sent from a resolver to an 118276541Sdes // authoritative name server, from the perspective of the resolver. 119276541Sdes // Resolvers typically clear the RD (recursion desired) bit when 120276541Sdes // sending queries. 121276541Sdes RESOLVER_QUERY = 3; 122276541Sdes 123276541Sdes // RESOLVER_RESPONSE is a DNS response message received from an 124276541Sdes // authoritative name server by a resolver, from the perspective of 125276541Sdes // the resolver. 126276541Sdes RESOLVER_RESPONSE = 4; 127276541Sdes 128276541Sdes // CLIENT_QUERY is a DNS query message sent from a client to a DNS 129276541Sdes // server which is expected to perform further recursion, from the 130276541Sdes // perspective of the DNS server. The client may be a stub resolver or 131276541Sdes // forwarder or some other type of software which typically sets the RD 132276541Sdes // (recursion desired) bit when querying the DNS server. The DNS server 133276541Sdes // may be a simple forwarding proxy or it may be a full recursive 134276541Sdes // resolver. 135276541Sdes CLIENT_QUERY = 5; 136276541Sdes 137276541Sdes // CLIENT_RESPONSE is a DNS response message sent from a DNS server to 138276541Sdes // a client, from the perspective of the DNS server. The DNS server 139276541Sdes // typically sets the RA (recursion available) bit when responding. 140276541Sdes CLIENT_RESPONSE = 6; 141276541Sdes 142276541Sdes // FORWARDER_QUERY is a DNS query message sent from a downstream DNS 143276541Sdes // server to an upstream DNS server which is expected to perform 144276541Sdes // further recursion, from the perspective of the downstream DNS 145276541Sdes // server. 146276541Sdes FORWARDER_QUERY = 7; 147276541Sdes 148276541Sdes // FORWARDER_RESPONSE is a DNS response message sent from an upstream 149276541Sdes // DNS server performing recursion to a downstream DNS server, from the 150276541Sdes // perspective of the downstream DNS server. 151276541Sdes FORWARDER_RESPONSE = 8; 152276541Sdes 153276541Sdes // STUB_QUERY is a DNS query message sent from a stub resolver to a DNS 154276541Sdes // server, from the perspective of the stub resolver. 155276541Sdes STUB_QUERY = 9; 156276541Sdes 157276541Sdes // STUB_RESPONSE is a DNS response message sent from a DNS server to a 158276541Sdes // stub resolver, from the perspective of the stub resolver. 159276541Sdes STUB_RESPONSE = 10; 160276541Sdes } 161276541Sdes 162276541Sdes // One of the Type values described above. 163276541Sdes required Type type = 1; 164276541Sdes 165276541Sdes // One of the SocketFamily values described above. 166276541Sdes optional SocketFamily socket_family = 2; 167276541Sdes 168276541Sdes // One of the SocketProtocol values described above. 169276541Sdes optional SocketProtocol socket_protocol = 3; 170276541Sdes 171276541Sdes // The network address of the message initiator. 172276541Sdes // For SocketFamily INET, this field is 4 octets (IPv4 address). 173276541Sdes // For SocketFamily INET6, this field is 16 octets (IPv6 address). 174276541Sdes optional bytes query_address = 4; 175276541Sdes 176276541Sdes // The network address of the message responder. 177276541Sdes // For SocketFamily INET, this field is 4 octets (IPv4 address). 178276541Sdes // For SocketFamily INET6, this field is 16 octets (IPv6 address). 179276541Sdes optional bytes response_address = 5; 180276541Sdes 181276541Sdes // The transport port of the message initiator. 182276541Sdes // This is a 16-bit UDP or TCP port number, depending on SocketProtocol. 183276541Sdes optional uint32 query_port = 6; 184276541Sdes 185276541Sdes // The transport port of the message responder. 186276541Sdes // This is a 16-bit UDP or TCP port number, depending on SocketProtocol. 187276541Sdes optional uint32 response_port = 7; 188276541Sdes 189276541Sdes // The time at which the DNS query message was sent or received, depending 190276541Sdes // on whether this is an AUTH_QUERY, RESOLVER_QUERY, or CLIENT_QUERY. 191276541Sdes // This is the number of seconds since the UNIX epoch. 192276541Sdes optional uint64 query_time_sec = 8; 193276541Sdes 194276541Sdes // The time at which the DNS query message was sent or received. 195276541Sdes // This is the seconds fraction, expressed as a count of nanoseconds. 196276541Sdes optional fixed32 query_time_nsec = 9; 197276541Sdes 198276541Sdes // The initiator's original wire-format DNS query message, verbatim. 199276541Sdes optional bytes query_message = 10; 200276541Sdes 201276541Sdes // The "zone" or "bailiwick" pertaining to the DNS query message. 202276541Sdes // This is a wire-format DNS domain name. 203276541Sdes optional bytes query_zone = 11; 204276541Sdes 205276541Sdes // The time at which the DNS response message was sent or received, 206276541Sdes // depending on whether this is an AUTH_RESPONSE, RESOLVER_RESPONSE, or 207276541Sdes // CLIENT_RESPONSE. 208276541Sdes // This is the number of seconds since the UNIX epoch. 209276541Sdes optional uint64 response_time_sec = 12; 210276541Sdes 211276541Sdes // The time at which the DNS response message was sent or received. 212276541Sdes // This is the seconds fraction, expressed as a count of nanoseconds. 213276541Sdes optional fixed32 response_time_nsec = 13; 214276541Sdes 215276541Sdes // The responder's original wire-format DNS response message, verbatim. 216276541Sdes optional bytes response_message = 14; 217276541Sdes} 218276541Sdes 219276541Sdes// All fields except for 'type' in the Message schema are optional. 220276541Sdes// It is recommended that at least the following fields be filled in for 221276541Sdes// particular types of Messages. 222276541Sdes 223276541Sdes// AUTH_QUERY: 224276541Sdes// socket_family, socket_protocol 225276541Sdes// query_address, query_port 226276541Sdes// query_message 227276541Sdes// query_time_sec, query_time_nsec 228276541Sdes 229276541Sdes// AUTH_RESPONSE: 230276541Sdes// socket_family, socket_protocol 231276541Sdes// query_address, query_port 232276541Sdes// query_time_sec, query_time_nsec 233276541Sdes// response_message 234276541Sdes// response_time_sec, response_time_nsec 235276541Sdes 236276541Sdes// RESOLVER_QUERY: 237276541Sdes// socket_family, socket_protocol 238276541Sdes// query_name, query_type, query_class 239276541Sdes// query_message 240276541Sdes// query_time_sec, query_time_nsec 241276541Sdes// query_zone 242276541Sdes// response_address, response_port 243276541Sdes 244276541Sdes// RESOLVER_RESPONSE: 245276541Sdes// socket_family, socket_protocol 246276541Sdes// query_name, query_type, query_class 247276541Sdes// query_time_sec, query_time_nsec 248276541Sdes// query_zone 249276541Sdes// response_address, response_port 250276541Sdes// response_message 251276541Sdes// response_time_sec, response_time_nsec 252276541Sdes 253276541Sdes// CLIENT_QUERY: 254276541Sdes// socket_family, socket_protocol 255276541Sdes// query_message 256276541Sdes// query_time_sec, query_time_nsec 257276541Sdes 258276541Sdes// CLIENT_RESPONSE: 259276541Sdes// socket_family, socket_protocol 260276541Sdes// query_time_sec, query_time_nsec 261276541Sdes// response_message 262276541Sdes// response_time_sec, response_time_nsec 263