// dnstap: flexible, structured event replication format for DNS software

//

// This file contains the protobuf schemas for the "dnstap" structured event

// replication format for DNS software.

// Written in 2013-2014 by Farsight Security, Inc.

//

// To the extent possible under law, the author(s) have dedicated all

// copyright and related and neighboring rights to this file to the public

// domain worldwide. This file is distributed without any warranty.

//

// You should have received a copy of the CC0 Public Domain Dedication along

// with this file. If not, see:

//

// <http://creativecommons.org/publicdomain/zero/1.0/>.

package dnstap;

// "Dnstap": this is the top-level dnstap type, which is a "union" type that

// contains other kinds of dnstap payloads, although currently only one type

// of dnstap payload is defined.

// See: https://developers.google.com/protocol-buffers/docs/techniques#union

message Dnstap {

// DNS server identity.

// If enabled, this is the identity string of the DNS server which generated

// this message. Typically this would be the same string as returned by an

// "NSID" (RFC 5001) query.

optional bytes identity = 1;

// DNS server version.

// If enabled, this is the version string of the DNS server which generated

// this message. Typically this would be the same string as returned by a

// "version.bind" query.

optional bytes version = 2;

// Extra data for this payload.

// This field can be used for adding an arbitrary byte-string annotation to

// the payload. No encoding or interpretation is applied or enforced.

optional bytes extra = 3;

// Identifies which field below is filled in.

enum Type {

MESSAGE = 1;

}

required Type type = 15;

// One of the following will be filled in.

optional Message message = 14;

}

// SocketFamily: the network protocol family of a socket. This specifies how

// to interpret "network address" fields.

enum SocketFamily {

INET = 1; // IPv4 (RFC 791)

INET6 = 2; // IPv6 (RFC 2460)

}

// SocketProtocol: the transport protocol of a socket. This specifies how to

// interpret "transport port" fields.

enum SocketProtocol {

UDP = 1; // User Datagram Protocol (RFC 768)

TCP = 2; // Transmission Control Protocol (RFC 793)

}

// Message: a wire-format (RFC 1035 section 4) DNS message and associated

// metadata. Applications generating "Message" payloads should follow

// certain requirements based on the MessageType, see below.

message Message {

// There are eight types of "Message" defined that correspond to the

// four arrows in the following diagram, slightly modified from RFC 1035

// section 2:

// +---------+ +----------+ +--------+

// | | query | | query | |

// | Stub |-SQ--------CQ->| Recursive|-RQ----AQ->| Auth. |

// | Resolver| | Server | | Name |

// | |<-SR--------CR-| |<-RR----AR-| Server |

// +---------+ response | | response | |

// +----------+ +--------+

// Each arrow has two Type values each, one for each "end" of each arrow,

// because these are considered to be distinct events. Each end of each

// arrow on the diagram above has been marked with a two-letter Type

// mnemonic. Clockwise from upper left, these mnemonic values are:

//

// SQ: STUB_QUERY

// CQ: CLIENT_QUERY

// RQ: RESOLVER_QUERY

// AQ: AUTH_QUERY

// AR: AUTH_RESPONSE

// RR: RESOLVER_RESPONSE

// CR: CLIENT_RESPONSE

// SR: STUB_RESPONSE

// Two additional types of "Message" have been defined for the

// "forwarding" case where an upstream DNS server is responsible for

// further recursion. These are not shown on the diagram above, but have

// the following mnemonic values:

// FQ: FORWARDER_QUERY

// FR: FORWARDER_RESPONSE

// The "Message" Type values are defined below.

enum Type {

// AUTH_QUERY is a DNS query message received from a resolver by an

// authoritative name server, from the perspective of the authorative

// name server.

AUTH_QUERY = 1;

// AUTH_RESPONSE is a DNS response message sent from an authoritative

// name server to a resolver, from the perspective of the authoritative

// name server.

AUTH_RESPONSE = 2;

// RESOLVER_QUERY is a DNS query message sent from a resolver to an

// authoritative name server, from the perspective of the resolver.

// Resolvers typically clear the RD (recursion desired) bit when

// sending queries.

RESOLVER_QUERY = 3;

// RESOLVER_RESPONSE is a DNS response message received from an

// authoritative name server by a resolver, from the perspective of

// the resolver.

RESOLVER_RESPONSE = 4;

// CLIENT_QUERY is a DNS query message sent from a client to a DNS

// server which is expected to perform further recursion, from the

// perspective of the DNS server. The client may be a stub resolver or

// forwarder or some other type of software which typically sets the RD

// (recursion desired) bit when querying the DNS server. The DNS server

// may be a simple forwarding proxy or it may be a full recursive

// resolver.

CLIENT_QUERY = 5;

// CLIENT_RESPONSE is a DNS response message sent from a DNS server to

// a client, from the perspective of the DNS server. The DNS server

// typically sets the RA (recursion available) bit when responding.

CLIENT_RESPONSE = 6;

// FORWARDER_QUERY is a DNS query message sent from a downstream DNS

// server to an upstream DNS server which is expected to perform

// further recursion, from the perspective of the downstream DNS

// server.

FORWARDER_QUERY = 7;

// FORWARDER_RESPONSE is a DNS response message sent from an upstream

// DNS server performing recursion to a downstream DNS server, from the

// perspective of the downstream DNS server.

FORWARDER_RESPONSE = 8;

// STUB_QUERY is a DNS query message sent from a stub resolver to a DNS

// server, from the perspective of the stub resolver.

STUB_QUERY = 9;

// STUB_RESPONSE is a DNS response message sent from a DNS server to a

// stub resolver, from the perspective of the stub resolver.

STUB_RESPONSE = 10;

// TOOL_QUERY is a DNS query message sent from a DNS software tool to a

// DNS server, from the perspective of the tool.

TOOL_QUERY = 11;

// TOOL_RESPONSE is a DNS response message received by a DNS software

// tool from a DNS server, from the perspective of the tool.

TOOL_RESPONSE = 12;

}

// One of the Type values described above.

required Type type = 1;

// One of the SocketFamily values described above.

optional SocketFamily socket_family = 2;

// One of the SocketProtocol values described above.

optional SocketProtocol socket_protocol = 3;

// The network address of the message initiator.

// For SocketFamily INET, this field is 4 octets (IPv4 address).

// For SocketFamily INET6, this field is 16 octets (IPv6 address).

optional bytes query_address = 4;

// The network address of the message responder.

// For SocketFamily INET, this field is 4 octets (IPv4 address).

// For SocketFamily INET6, this field is 16 octets (IPv6 address).

optional bytes response_address = 5;

// The transport port of the message initiator.

// This is a 16-bit UDP or TCP port number, depending on SocketProtocol.

optional uint32 query_port = 6;

// The transport port of the message responder.

// This is a 16-bit UDP or TCP port number, depending on SocketProtocol.

optional uint32 response_port = 7;

// The time at which the DNS query message was sent or received, depending

// on whether this is an AUTH_QUERY, RESOLVER_QUERY, or CLIENT_QUERY.

// This is the number of seconds since the UNIX epoch.

optional uint64 query_time_sec = 8;

// The time at which the DNS query message was sent or received.

// This is the seconds fraction, expressed as a count of nanoseconds.

optional fixed32 query_time_nsec = 9;

// The initiator's original wire-format DNS query message, verbatim.

optional bytes query_message = 10;

// The "zone" or "bailiwick" pertaining to the DNS query message.

// This is a wire-format DNS domain name.

optional bytes query_zone = 11;

// The time at which the DNS response message was sent or received,

// depending on whether this is an AUTH_RESPONSE, RESOLVER_RESPONSE, or

// CLIENT_RESPONSE.

// This is the number of seconds since the UNIX epoch.

optional uint64 response_time_sec = 12;

// The time at which the DNS response message was sent or received.

// This is the seconds fraction, expressed as a count of nanoseconds.

optional fixed32 response_time_nsec = 13;

// The responder's original wire-format DNS response message, verbatim.

optional bytes response_message = 14;

}

// All fields except for 'type' in the Message schema are optional.

// It is recommended that at least the following fields be filled in for

// particular types of Messages.

// AUTH_QUERY:

// socket_family, socket_protocol

// query_address, query_port

// query_message

// query_time_sec, query_time_nsec

// AUTH_RESPONSE:

// socket_family, socket_protocol

// query_address, query_port

// query_time_sec, query_time_nsec

// response_message

// response_time_sec, response_time_nsec

// RESOLVER_QUERY:

// socket_family, socket_protocol

// query_message

// query_time_sec, query_time_nsec

// query_zone

// response_address, response_port

// RESOLVER_RESPONSE:

// socket_family, socket_protocol

// query_time_sec, query_time_nsec

// query_zone

// response_address, response_port

// response_message

// response_time_sec, response_time_nsec

// CLIENT_QUERY:

// socket_family, socket_protocol

// query_message

// query_time_sec, query_time_nsec

// CLIENT_RESPONSE:

// socket_family, socket_protocol

// query_time_sec, query_time_nsec

// response_message

// response_time_sec, response_time_nsec