contrib/unbound/dnstap/dnstap.proto

   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 syntax = "proto2";
  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 authoritative
 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
 163     // One of the Type values described above.
 164     required Type               type = 1;
 165
 166     // One of the SocketFamily values described above.
 167     optional SocketFamily       socket_family = 2;
 168
 169     // One of the SocketProtocol values described above.
 170     optional SocketProtocol     socket_protocol = 3;
 171
 172     // The network address of the message initiator.
 173     // For SocketFamily INET, this field is 4 octets (IPv4 address).
 174     // For SocketFamily INET6, this field is 16 octets (IPv6 address).
 175     optional bytes              query_address = 4;
 176
 177     // The network address of the message responder.
 178     // For SocketFamily INET, this field is 4 octets (IPv4 address).
 179     // For SocketFamily INET6, this field is 16 octets (IPv6 address).
 180     optional bytes              response_address = 5;
 181
 182     // The transport port of the message initiator.
 183     // This is a 16-bit UDP or TCP port number, depending on SocketProtocol.
 184     optional uint32             query_port = 6;
 185
 186     // The transport port of the message responder.
 187     // This is a 16-bit UDP or TCP port number, depending on SocketProtocol.
 188     optional uint32             response_port = 7;
 189
 190     // The time at which the DNS query message was sent or received, depending
 191     // on whether this is an AUTH_QUERY, RESOLVER_QUERY, or CLIENT_QUERY.
 192     // This is the number of seconds since the UNIX epoch.
 193     optional uint64             query_time_sec = 8;
 194
 195     // The time at which the DNS query message was sent or received.
 196     // This is the seconds fraction, expressed as a count of nanoseconds.
 197     optional fixed32            query_time_nsec = 9;
 198
 199     // The initiator's original wire-format DNS query message, verbatim.
 200     optional bytes              query_message = 10;
 201
 202     // The "zone" or "bailiwick" pertaining to the DNS query message.
 203     // This is a wire-format DNS domain name.
 204     optional bytes              query_zone = 11;
 205
 206     // The time at which the DNS response message was sent or received,
 207     // depending on whether this is an AUTH_RESPONSE, RESOLVER_RESPONSE, or
 208     // CLIENT_RESPONSE.
 209     // This is the number of seconds since the UNIX epoch.
 210     optional uint64             response_time_sec = 12;
 211
 212     // The time at which the DNS response message was sent or received.
 213     // This is the seconds fraction, expressed as a count of nanoseconds.
 214     optional fixed32            response_time_nsec = 13;
 215
 216     // The responder's original wire-format DNS response message, verbatim.
 217     optional bytes              response_message = 14;
 218 }
 219
 220 // All fields except for 'type' in the Message schema are optional.
 221 // It is recommended that at least the following fields be filled in for
 222 // particular types of Messages.
 223
 224 // AUTH_QUERY:
 225 //      socket_family, socket_protocol
 226 //      query_address, query_port
 227 //      query_message
 228 //      query_time_sec, query_time_nsec
 229
 230 // AUTH_RESPONSE:
 231 //      socket_family, socket_protocol
 232 //      query_address, query_port
 233 //      query_time_sec, query_time_nsec
 234 //      response_message
 235 //      response_time_sec, response_time_nsec
 236
 237 // RESOLVER_QUERY:
 238 //      socket_family, socket_protocol
 239 //      query_name, query_type, query_class
 240 //      query_message
 241 //      query_time_sec, query_time_nsec
 242 //      query_zone
 243 //      response_address, response_port
 244
 245 // RESOLVER_RESPONSE:
 246 //      socket_family, socket_protocol
 247 //      query_name, query_type, query_class
 248 //      query_time_sec, query_time_nsec
 249 //      query_zone
 250 //      response_address, response_port
 251 //      response_message
 252 //      response_time_sec, response_time_nsec
 253
 254 // CLIENT_QUERY:
 255 //      socket_family, socket_protocol
 256 //      query_message
 257 //      query_time_sec, query_time_nsec
 258
 259 // CLIENT_RESPONSE:
 260 //      socket_family, socket_protocol
 261 //      query_time_sec, query_time_nsec
 262 //      response_message
 263 //      response_time_sec, response_time_nsec