]>

12047B 36th Ave NE Seattle WA 98125 brian.peter.dickson@gmail.com

Internet dnsop DNSOP As part of the SPARTACUS DNS gateway system, building a full DNS parser was necessary. Parsing DNS packets is the only way to avoid propogating packets which are not correctly formatted DNS packets. In order to facilitate building a new parser from scratch, the author chose to build a parser-builder which takes as input, a description of the DNS wire format. This document describes the language created to facilitate this description, and includes the resulting DNS wire format description in this language. Intended Status: Informational.

DNS (The Domain Name System) has been around a long, long time. Over that time, the original Resource Record types have in some cases been made officially obsolete. Other, new Resource Records have been added. New definitions of bits in the header have arisen. There have even been extensions added, which are intended to be backward compatible. The OPT pseudo-resource record, in particular, overloads some of the standard field definitions in order to achieve its goals. The end result is a wire format which is potentially difficult to parse. In the interests of assisting future DNS endeavors, a complete description of the DNS wire format has been produced, and a comparitively simple language for facilitating this description has been created.

Re-inventing the wheel, figuratively speaking, is frowned upon. By providing a description of the DNS wire format, and a language to accomplish this description, the author hopes that future work in the DNS arena might be made easier, at least in some cases. The project which motivated this work, SPARTACUS (Secure, Private Aparatus for Resolution Transported Across Constraining and/or Unmaintained Systems), is intended to have multiple implementations in a variety of languages and environments. Creating a standard description of the DNS wire format, is intended to facilitate both an easier implementation effort, and a greater likelihood of compatible, interoprable implementations. The SPARTACUS project is intended to create bidirectional DNS gateways for transporting DNS over other protocols and encodings, such as JSON over HTTP(S). This is intended to create "bridges" between DNS speakers. THe goal is to transport DNS messages from any DNS client implementation to any DNS server implementation. Each gateway needs to be liberal in what it accepts (any valid DNS message conforming to the relevant RFCs) and conservative in what it sends (only packets which parse correctly). A secondary objective of the encoding in JSON is the use of the same names for data elements and structures as in the DNS RFCs. The idea is to provide human-readable JSON encodings, for easier diagnostics during development, and when investigating operational issues.

A variety of other work exists, and provided inspiration for the SPARTACUS work. This includes web/JSON DNS portals, for providing DNS query responses in JSON format, often with a "looking glass" functionality. Multi-location DNS Looking Glass - Tool for performing DNS queries via RESTful interface in multiple locations, returning results in JSON format DNS Looking Glass - Tool for performing DNS queries via RESTful interface, returning results in JSON format DNS JSON - Source code project from circa 2009, partially developed but incomplete/abandoned DNSSEC-trigger - embedded control function in NLnetlabs' Unbound resolver, for attempting DNS queries over TCP port 80 when DNSSEC problems are encountered Various other web-based DNS lookup tools

There has been at least one previous effort to develop code for a DNS-JSON encoding, which appears to have been abandoned after one-way encoding was done, circa 2009. The project focused on presenting results to DNS queries in JSON format, with an intention to create a client gateway, which never materialized. The project can be found in two places ( and ). One major difference is that DNS query response status is converted to HTTP error codes, rather than being embedded in the JSON answer. This makes it unsuitable for bidirectional use. Only a few DNS type codes were implemented. Another DNS JSON tool , similarly focuses only on answers, with a limited number of type codes. Yet another tool for looking up DNS via HTTP with JSON responses is the "dnsrest" . It too focuses only on answer values, and is similarly not able to fully produce results that can be turned back into DNS answer packets. The "DNS Looking Glass" , is primarily designed for returning DNS answer data. As such, it lacks encoding suitable for a bidirectional scheme. It is primarily focused on XML output, with JSON output organized around DNS resolution meta-data, plus answer data in a generic schema. (The schema itself is described in .) The "Multilocation DNS Looking Glass" , uses a RESTful query mechanism of "node/qname/qtypename" to request the looking glass (LG) to perform a DNS lookup for the qname and qtype, and returns the response in a JSON format. The JSON format is generic, encapsulating all types as string data in presentation format, with a generic label of "rdata". This does not facilitate decoding easily, as the JSON scheme provides no information for parsing the rdata field. The type (qtype for the query, or type for answer/authority/additional) is in string (symbolic) form, and the elements are objects and thus in unordered lists. The JSON scheme is fine for one-way encoding for human readability, but not suitable for two-way conversion back into DNS. DNSSEC-trigger can only be used in environments that use NLnetlabs' Unbound resolver, or where Unbound can be deployed as a replacement for existing recursive resolvers and/or stub resolvers. A variety of other web lookup tools exist, predominantly producing DNS validation (zone structure and hierarchy), maps, meta-data, or literal output from the 'dig' tool, in formats as varied as the purposes of the tools. Dig output, while being reasonably deterministic, is not sufficiently well-formed as to facilitate "screen scraping" as a parsing method.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in .

The syntax for the language is largely derived from only the abstract element types required to express data types and structures in DNS. In particular, the language has been kept as familiar and a simple as possible. Design choices were made to avoid over-abstracting elements which are by nature "difficult". Some objects have their size defined by other objects' values, or arithmetic expressions of values and literals. This includes array dimensions, and lengths of strings. The general syntactic style uses braces ("{" and "}"), similar to the config files for BIND, for structural items. Some familiarity with the DNS protocol is assumed.

The name space of this language is tailored to the specific environment. Names need only be unique within their specific scope. Since DNS messages are processed as "first in, first out" objects, the references to arrays have been simplified. Rather than keeping track of the index to an array, e.g. "a.b[3].c", the index is omitted, resulting in "a.b.c". Relative object naming works the same as DNS search-list processing, depth-first. For example, while parsing "a.b.c.d", the name "foo" would refer the first of the following that exists: "a.b.c.foo", "a.b.foo", "a.foo".

The syntactic elements of the language are base data types, structural elements, and preprocessing constructs. Additional elements provide the ability to annotate objects, and to define mnemonics for values.

Base data types are encoded as "name:type", for a small number of predefined types and appropriate presentation formats: bitN - N-bit value, with 1-bit encoded as TRUE/FALSE. intN - unsigned N-bit integer, N is one of 8, 16, 32, 48. dotquad - IPv4 address. quadhex8 - IPv6 address. quadhex4 - 64-bit value (IPv6 prefix or IPv6 host-part). hex-string@EXPR - binary data of EXPR-specified length. base64@EXPR - binary data of EXPR-specified length. string - one or more character strings of 8-bit length and N-byte string. string? - optional single string. fqdn - Fully Qualified Domain Name. mbox - Mailbox: Fully Qualified Domain Name preceded by username. Wire format is identical to fqdn. Example of a base64 object named "MAC" whose size is specified by "MACsize", in context:

When the parser decodes MACsize (e.g. as the unsigned integer "12"), it would then decode 12 bytes of data into MAC, and convert that data into base-64 (for encoding to JSON).

The remainder of the elements of the language exist to permit annotation of well-known values (such as "NXDOMAIN" for RCODE=3), and for providing human-friendly RFC references. These are: (RFC XXXX) - for any object name, associates a given RFC with it. Added by the parser to the corresponding JSON string. Enum ENUM_NAME - allows for integer types, to have mnemonics associated with them, as "value:name" pairs. Of ENUM_NAME - adds the name whenver the corresponding value is parsed (for this integer-type object). Example of RFC:

Example of enum:

When processing a CLASS object with value 1, the JSON encoding would be:

There are two structural elements: Structure - an ordered group of elements, including any combination of Data Types and further Structural elements. There is no limit on structure depth. Array - an Array has one child type, which can be either a Data Type, or simple Structure. The size of the array can be explicit, referencing the name of any integer type, or implicit, referencing the name of an integer whose value is the total length of the array. Switch and Case - similar to the C language elements, these provide a way of encoding a sparse array. The Switch object has a child Structure which consists only of Case objects. Each Case object associates a value with a named object (Structure or Data Type). The Switch references the name of an integer object type, which is compared to the Case objects (when parsing data). Example of simple structure:

Example of an array DAU_TYPES, in context:

Example of switch Field3 based on object TYPE, and corresponding cases ("case *" is equivalent to "default" in C):

When parsing data, if the TYPE had value 41, when converted to JSON, the object name "UDPSIZE" would appear, rather than "CLASS".

There are two elements which provide preprocessing capabilities: Define - objects are ways of doing logical cut/paste of input file contents. Reference - to the same named object created with a "define", results in a literal copy of the original range of file contents. This operates much like "#define" does in the C language. By doing this, identical structures and object types which occur in different places can be maintained in one section of the file. In partucular, the Resource Records from all three sections can be defined once. Example of one define and two references to RDATATYPE. Note that an object named RDLENGTH must be present in an ancestor of both parent objects:

None per se.

This document contains no IANA-specific material.

To be added later.

&rfc1033; &rfc1034; &rfc1035; &rfc2136; &rfc2181; &rfc2308; &rfc4033; &rfc4034; &rfc4035; &rfc5011; &rfc5155; &rfc2119; NLnet Labs

The entire encoding of the DNS message format follows.