"Fossies" - the Fresh Open Source Software Archive

Member "bind-9.17.5/lib/dns/dnstap.proto" (4 Sep 2020, 11263 Bytes) of package /linux/misc/dns/bind9/9.17.5/bind-9.17.5.tar.xz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    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 
   17 package 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
   23 message 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.
   53 enum 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.
   60 enum 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.
   68 message 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