RFC 8427

Representing DNS Messages in JSON

📅 published July 2018, from ietf

📜 RFC 8427: Representing DNS Messages in JSON 💖

Okay bestie, let's get into this one! 🎀 This is an Informational RFC (so it's not a Standards Track spec, it's here for info 🦋), written by P. Hoffman of ICANN, dated July 2018. It's not obsoleting or updating anything, and it's published under the IETF Trust's usual copyright and licence stuff 💅. The ISSN is 2070-1721 🌸.

Abstract ✨

Okay so some apps treat DNS messages (or bits of them) as plain data 📊. Like imagine a system that captures DNS queries and responses and wants to search through them without decoding every single message every time 🙈. Or a system that builds queries and responses back together from little pieces 🧩. This doc gives a general JSON format for DNS message data, and specific profiles built on top of it can be written in other docs for specific use cases 🫶.

Status of This Memo ✨

This doc is not an Internet Standards Track spec, it's just published for info purposes 📚. It is a product of the IETF and it represents the consensus of the IETF community 🌈. It got public review and was approved by the IESG 💜. Not every IESG-approved doc is a candidate for any level of Internet Standard, so check Section 2 of RFC 7841 if you're curious 🔍.

For current status, errata, and how to send feedback, go to https://www.rfc-editor.org/info/rfc8427 🔗.

Copyright (c) 2018 IETF Trust and the people listed as the document authors. All rights reserved 🎀.

This doc is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) as they stand on the publication date 💅. Please actually read those, bestie, because they spell out your rights and restrictions 🙏. Any Code Components pulled out of this doc must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions, and they come with no warranty as described in the Simplified BSD License 🧾.

Table of Contents 🗺️

  1. Introduction . . . 3 1.1. Design of the Format . . . 3 1.2. Terminology . . . 5
  2. JSON Format for DNS Messages . . . 5 2.1. Message Object Members . . . 5 2.2. Resource Record Object Members . . . 6 2.3. Specific RDATA Field Members . . . 7 2.4. The Message and Its Parts as Octets . . . 8 2.5. Additional Message Object Members . . . 8 2.6. Name Fields . . . 9
  3. JSON Format for a Paired DNS Query and Response . . . 9
  4. Streaming DNS Objects . . . 9
  5. Examples . . . 10 5.1. Example of the Format of a DNS Query . . . 10 5.2. Example of the Format of a Paired DNS Query and Response . . . 11
  6. Local Format Policy . . . 12
  7. IANA Considerations . . . 12 7.1. Media Type Registration of application/dns+json . . . 12
  8. Security Considerations . . . 13
  9. Privacy Considerations . . . 14
  10. References . . . 14 10.1. Normative References . . . 14 10.2. Informative References . . . 15 Acknowledgements . . . 15 Author's Address . . . 15

1. Introduction 🌷

Okay so the DNS message format is defined in [RFC1035] 📖. DNS queries and DNS responses have exactly the same structure 👯. A lot of the field names and data type names from [RFC1035] are super common in DNS chat, like "the query had a QNAME of 'example.com'" or "the RDATA has a simple structure" 💬.

There are hundreds of data-interchange formats for serializing structured data 😵‍💫. Right now JSON [RFC8259] is the big popular one, especially for data with named subfields and optional parts 💖.

So this doc uses JSON to describe DNS messages 🎀. It also explains how to describe a paired DNS query and response, and how to stream DNS objects 🌊.

1.1. Design of the Format 💅

There are lots of ways to design a data format, but this doc uses one specific methodology based on the DNS format 🧁.

  • The format is built on JSON objects so a writer can include or leave out parts of the format whenever they want 🦋. No object members are ever required ✨.
  • This format is purposely overly general 🌈. An app that uses it is expected to use only a subset of the items defined here, and to define its own profile from this format 💜.
  • The format allows transformation through JSON that would permit re-creation of the wire content of the message 🔁.
  • All members whose values are always 16 bits or shorter are represented by JSON numbers with no minus sign, no fractional part (except in fields specifically noted below), and no exponent part 🔢. One-bit values are JSON numbers whose values are either 0 or 1 🎯. See Section 6 of [RFC8259] for more detail on JSON numbers 🤓.
  • The JSON representation of the objects in this doc is limited to the UTF-8 codepoints from U+0000 to U+007F 🙅‍♀️. This is done to prevent someone from trying to use a different encoding, like UTF-8, for octets in names or data 🚫.
  • Items with string values can have "HEX" appended to their names to indicate a non-ASCII encoding of the value 🔤. Names ending in "HEX" have values stored in base16 encoding (hex with uppercase letters) defined in [RFC4648] 🧮. This is especially handy for binary RDATA 💾.
  • All field names in this format are used as in [RFC1035], including their capitalization 🔠. Names not defined in [RFC1035] generally use "camel case" 🐫.
  • The same data may be represented in multiple object members, multiple times 👀. For example, there's a member for the octets of the DNS message header, and there are members for each named part of the header. A message object can therefore accidentally have inconsistent data, like a header member whose value doesn't match the first bits in the entire message member 😬.
  • It's totally fine that there are multiple ways to represent the same data 🌸. This lets app designers pick the fields that work best for them, and even allow multiple representations 💁‍♀️. There's no "better" way to represent DNS data, so this design doesn't prefer any specific representation 🤷‍♀️.
  • The design explicitly allows for describing malformed DNS messages 🕵️‍♀️. This matters for systems logging messages seen on the wire, especially messages that might be part of an attack ⚠️. A few examples of malformed DNS messages:
    • a resource record (RR) that has an RDLENGTH of 4 but an RDATA whose length is longer than 4 (if it is the last RR in a message) 🙃
    • a DNS message whose QDCOUNT is 0 🫠
    • a DNS message whose ANCOUNT is large but there are insufficient bytes after the header 😭
    • a DNS message whose length is less than 12 octets, meaning it doesn't even have a full header 💀
  • An object in this format can have zero or more of the members defined here, meaning no members are required by the format itself 🧸. Instead, profiles that use this format might have requirements for mandatory members, optional members, and prohibited members 📋. Also, this format does not prohibit members that aren't defined in it, so profiles are free to add new members 🪄.
  • This doc defines DNS messages, not the zone files described in [RFC1035] 📜. A different spec could be written to extend it to represent zone files 🛠️. Note that DNS zone files allow escaping of octet values using "\DDD" notation, but this spec does not allow that, so when encoding from a zone file to this JSON format, you need to do a conversion for many types of values 🔄.

1.2. Terminology 📚

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here 🎯.

2. JSON Format for DNS Messages 💌

The following gives all of the members defined for a DNS message. It's organized roughly by levels of the DNS message 🪜.

2.1. Message Object Members 🧾

  • ID - Integer whose value is 0 to 65535
  • QR - Boolean
  • Opcode - Integer whose value is 0 to 15
  • AA - Boolean
  • TC - Boolean
  • RD - Boolean
  • RA - Boolean
  • AD - Boolean
  • CD - Boolean
  • RCODE - Integer whose value is 0 to 15
  • QDCOUNT - Integer whose value is 0 to 65535
  • ANCOUNT - Integer whose value is 0 to 65535
  • NSCOUNT - Integer whose value is 0 to 65535
  • ARCOUNT - Integer whose value is 0 to 65535
  • QNAME - String of the name of the first Question section of the message; see Section 2.6 for a description of the contents
  • compressedQNAME - Object that describes the name with two optional values: "isCompressed" (0 for no, 1 for yes) and "length" (an integer giving the length in the message)
  • QTYPE - Integer whose value is 0 to 65535, the QTYPE of the first Question section of the message
  • QTYPEname - String whose value is from the IANA "Resource Record (RR) TYPEs" registry or has the format in [RFC3597]; this is case sensitive, so "AAAA", not "aaaa" 🔠
  • QCLASS - Integer whose value is 0 to 65535, the QCLASS of the first Question section of the message
  • QCLASSname - String whose value is "IN", "CH", or "HS" or that has the format in [RFC3597]
  • questionRRs - Array of zero or more resource records or rrSet objects in the Question section
  • answerRRs - Array of zero or more resource records or rrSet objects in the Answer section
  • authorityRRs - Array of zero or more resource records or rrSet objects in the Authority section
  • additionalRRs - Array of zero or more resource records or rrSet objects in the Additional section

Part 1 of 3 done 🎀. Say "continue" for part 2, bestie 💜🦋.

2.2. Resource Record Object Members 🎀

okay so a resource record is represented as an object with these members 💅

  • NAME - String of the NAME field of the resource record; see Section 2.6 for a description of the contents
  • compressedNAME - Object that describes the name with two optional values: "isCompressed" (with a value of 0 for no and 1 for yes) and "length" (with an integer giving the length in the message)
  • TYPE - Integer whose value is 0 to 65535
  • TYPEname - String whose value is from the IANA "Resource Record (RR) TYPEs" registry or has the format in [RFC3597]; this is case sensitive, so "AAAA", not "aaaa" 🫶
  • CLASS - Integer whose value is 0 to 65535
  • CLASSname - String whose value is "IN", "CH", or "HS" or has the format in [RFC3597]
  • TTL - Integer whose value is -2147483648 to 2147483647 (it will only be 0 to 2147483647 in normal circumstances) ⏰
  • RDLENGTH - Integer whose value is 0 to 65535. Applications using this format are unlikely to use this value directly, and instead calculate the value from the RDATA. 🧮
  • RDATAHEX - Hex-encoded string (base16 encoding, described in [RFC4648]) of the octets of the RDATA field of the resource record. The data in some common RDATA fields are also described in their own members; see Section 2.3 ✨
  • rrSet - List of objects that have RDLENGTH and RDATA members

bestie, a Question section can be expressed as a resource record too 🦋 when you do that, the TTL, RDLENGTH, and RDATA members make no sense 💀

2.3. Specific RDATA Field Members 🌸

so these are the common RDATA types and how to write them as JSON members 🍓 the name of each member contains the name of the RDATA type. the data type for every one of these is a string. each name gets prefaced with "rdata" so it can't collide with fields that might get defined later with the same name as the raw type name 🛡️

  • rdataA - IPv4 address, such as "192.168.33.44"
  • rdataAAAA - IPv6 address, such as "fe80::a65e:60ff:fed6:8aaf", as defined in [RFC5952] 💜
  • rdataCNAME - A domain name
  • rdataDNAME - A domain name
  • rdataNS - A domain name
  • rdataPTR - A domain name
  • rdataTXT - A text value

in addition, each of the following members has a value that is a space-separated string that matches the display format definition in the RFC that defines that RDATA type. it is not expected that every receiving application will know how to parse these values 🙈

rdataCDNSKEY, rdataCDS, rdataCSYNC, rdataDNSKEY, rdataHIP, rdataIPSECKEY, rdataKEY, rdataMX, rdataNSEC, rdataNSEC3, rdataNSEC3PARAM, rdataOPENPGPKEY, rdataRRSIG, rdataSMIMEA, rdataSPF, rdataSRV, rdataSSHFP, rdataTLSA

2.4. The Message and Its Parts as Octets 🦋

the following can be members of a message object. all of these are encoded in base16 encoding, described in [RFC4648], and every single item is a string 🫧

  • messageOctetsHEX - The octets of the message
  • headerOctetsHEX - The first 12 octets of the message (or fewer, if the message is truncated)
  • questionOctetsHEX - The octets of the Question section
  • answerOctetsHEX - The octets of the Answer section
  • authorityOctetsHEX - The octets of the Authority section
  • additionalOctetsHEX - The octets of the Additional section

the following can be a member of a resource record object 🎀

  • rrOctetsHEX - The octets of a particular resource record

these items are super useful in applications for canonically reproducing what appeared on the wire 🔁 like, an application that converts wire-format requests and responses might decompress names, but the system reading the converted data may want to be sure the decompression was done correctly. that system would need to see the part of the message where the decompressed labels lived, like one of the items in this section 🕵️‍♀️

2.5. Additional Message Object Members 💜

the following are members that might show up in a message object ✨

  • dateString - The date that the message was sent or received, given as a string in the standard format described in [RFC3339] and refined by Section 3.3 of [RFC4287].
  • dateSeconds - The date that the message was sent or received, given as a JSON number that is the number of seconds since 1970-01-01T00:00Z in UTC time; this number can be fractional. This number must have no minus sign, can have an optional fractional part, and can have no exponent part. 🔢
  • comment - An unstructured comment as a string. 💬

2.6. Name Fields 🍓

names are represented by JSON strings 🍓 the rules for how names get encoded are in Section 1.1. (to recap: it's limited to the UTF-8 codepoints from U+0000 to U+007F.) the contents of these fields are always uncompressed, which means that after [RFC1035], name compression has been removed 🧼

there are two encodings for names:

  • If the member name does not end in "HEX", the value is a domain name encoded as DNS labels consisting of UTF-8 codepoints from U+0000 to U+007F. Within a label, codepoints above U+007F and the codepoint U+002E (ASCII period) MUST be expressed using JSON's escaping rules within this set of codepoints. Separation between labels is indicated with a period (codepoint U+002E). Internationalized Domain Name (IDN) labels are always expressed in their A-label form, as described in [RFC5890]. 🌐
  • If the member name ends in "HEX", the value is the wire format for an entire domain name stored in base16 encoding, which is described in [RFC4648]. 🧱

3. JSON Format for a Paired DNS Query and Response 👑

a paired DNS query and response is represented as an object. two optional members of this object are named "queryMessage" and "responseMessage", and each one has a value that is a message object. this design was chosen (as compared to the more obvious array of two values) so that a paired DNS query and response could be told apart from a stream of DNS messages whose length happens to be two 👯‍♀️

4. Streaming DNS Objects 🧚

streaming of DNS objects is performed using JSON text sequences [RFC7464] 🌊

5. Examples ⭐

5.1. Example of the Format of a DNS Query 💖

the following is an example of a query for the A record of example.com.

{ "ID": 19678, "QR": 0, "Opcode": 0,
  "AA": 0, "TC": 0, "RD": 0, "RA": 0, "AD": 0, "CD": 0, "RCODE": 0,
  "QDCOUNT": 1, "ANCOUNT": 0, "NSCOUNT": 0, "ARCOUNT": 0,
  "QNAME": "example.com", "QTYPE": 1, "QCLASS": 1
}

as I said earlier, all members of an object are optional 🙌 this example object could have one or more of the following members as well:

"answerRRs": []
"authorityOctetsHEX": ""
"comment": "Something pithy goes here"
"dateSeconds": 1408504748.657783
"headerOctetsHEX": "4CDE00000001000000000000"
"QNAMEHEX": "076578616D706C6503636F6D00",
"compressedQNAME": { "isCompressed": 0 },
"messageOctetsHEX":
     "4CDE00000001000000000000076578616D706C6503636F6D0000010001"
"questionOctetsHEX": "076578616D706C6503636F6D0000010001"
"questionRRs": [ { "NAMEHEX": "076578616D706C6503636F6D00",
               "TYPE": 1, "CLASS": 1, "hostNAME" : "example.com." } ]
"questionRRs": [ { "NAME": "example.com.", "TYPE": 1,
               "CLASS": 1, } ]

(note that this is an incomplete list of what else could be in the object 👀)

5.2. Example of the Format of a Paired DNS Query and Response 🦋

the following is a paired DNS query and response for a query for the A record of example.com. 📬

{
  "queryMessage": { "ID": 32784, "QR": 0, "Opcode": 0, "AA": 0,
                   "TC": 0, "RD": 0, "RA": 0, "AD": 0, "CD": 0,
                   "RCODE": 0, "QDCOUNT": 1, "ANCOUNT": 0,
                   "NSCOUNT": 0, "ARCOUNT": 0,
                   "QNAME": "example.com.",
                   "QTYPE": 1, "QCLASS": 1 },
  "responseMessage": { "ID": 32784, "QR": 1, "AA": 1, "RCODE": 0,
                      "QDCOUNT": 1, "ANCOUNT": 1, "NSCOUNT": 1,
                      "ARCOUNT": 0,
                      "answerRRs": [ { "NAME": "example.com.",
                                       "TYPE": 1, "CLASS": 1,
                                       "TTL": 3600,
                                       "RDATAHEX": "C0000201" },
                                     { "NAME": "example.com.",
                                       "TYPE": 1, "CLASS": 1,
                                       "TTL": 3600,
                                       "RDATAHEX": "C000AA01" } ],
                       "authorityRRs": [ { "NAME": "ns.example.com.",
                                           "TYPE": 1, "CLASS": 1,
                                           "TTL": 28800,
                                           "RDATAHEX": "CB007181" } ]
                    }
}

the Answer section could instead be given with an rrSet:

"answerRRs": [ { "NAME": "example.com.",
                 "TYPE": 1, "CLASS": 1,
                 "TTL": 3600,
                 "rrSet": [ { "RDATAHEX": "C0000201" },
                            { "RDATAHEX": "C000AA01" } ] } ],

(note that this is an incomplete list of what else could be in the Answer section 🫶)

6. Local Format Policy 🔥

systems using the format in this document will likely have policy about what must be in the objects 📋 those policies are outside the scope of this document.

for example, passive DNS systems such as those described in [PASSIVE-DNS] cover just DNS responses 📡 such a system might have a policy that makes QNAME, QTYPE, and answerRRs mandatory. that document also describes two mandatory times that are not in this format, so the policy would possibly also define those members and make them mandatory. the policy could also define additional members that might appear in a record 🗂️

as another example, a program that uses this format for configuring what a test client sends on the wire might have a policy of "each record object can have as few members as it wants; all unstated members are filled in from previous records" 🧪

7. IANA Considerations 🌈

7.1. Media Type Registration of application/dns+json 💅

Type name: application

Subtype name: dns+json

Required parameters: N/A

Optional parameters: N/A

Encoding considerations: Encoding considerations are identical to those specified for the "application/json" media type.

Security considerations: This document specifies the security considerations for the format.

Interoperability considerations: This document specifies format of conforming messages and the interpretation thereof.

Published specification: This document

Applications that use this media type: Systems that want to exchange DNS messages

Fragment identifier considerations: None

Additional information:

  • Deprecated alias names for this type: N/A
  • Magic number(s): N/A
  • File extension(s): This document uses the media type to refer to protocol messages and thus does not require a file extension.
  • Macintosh file type code(s): N/A

Person & email address to contact for further information: Paul Hoffman, paul.hoffman@icann.org

Intended usage: COMMON

Restrictions on usage: N/A

Author: Paul Hoffman, paul.hoffman@icann.org

Change controller: Paul Hoffman, paul.hoffman@icann.org

8. Security Considerations 🔐

Okay bestie, this part is serious. As we saw in Section 1.1, a message object can be inconsistent, like an ANCOUNT of 1 with an empty answerRRs array, or an answerRRs array with two or more RRs. 😬 Other messes look like RRs whose RDLENGTH doesn't match the length of the decoded RDATAHEX value, or a record whose header fields don't line up with headerOctetsHEX. The vibe is: a reader of this format must never assume that all of the data in an object is consistent with itself. Trust nothing blindly, babe! 🙅‍♀️

This format is a format, not a profile of a format, and that gap can cause security problems. Say a system has a filter for JSON DNS packets. That filter needs the same semantics for the output JSON as the consumer does, or it's giving loophole. Unless the profile is really tight, a producer could sneak in fields with different contents (using the HEX and regular formats together), fields with malformed lengths, and more. Chaotic! 💀

Numbers in JSON also have zero bounds checking. So an integer might be totally invalid, like an ID field with a value greater than or equal to 2^16, or a QR field set to 2. Not it. 🙈

9. Privacy Considerations 🕵️‍♀️

The values that can live in this format might contain privacy-sensitive info, and that's a whole mood. For example, a profile of this format used for logging the queries sent to recursive resolvers could end up holding source IP addresses. Those can reveal where the person who sent the DNS query is located. So be careful with your logs, bestie! 🫶

10. References 📚

10.1. Normative References

   [RFC1035]  Mockapetris, P., "Domain names - implementation and
              specification", STD 13, RFC 1035, DOI 10.17487/RFC1035,
              November 1987, <https://www.rfc-editor.org/info/rfc1035>.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997,
              <https://www.rfc-editor.org/info/rfc2119>.

   [RFC3339]  Klyne, G. and C. Newman, "Date and Time on the Internet:
              Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002,
              <https://www.rfc-editor.org/info/rfc3339>.

   [RFC3597]  Gustafsson, A., "Handling of Unknown DNS Resource Record
              (RR) Types", RFC 3597, DOI 10.17487/RFC3597, September
              2003, <https://www.rfc-editor.org/info/rfc3597>.

   [RFC4287]  Nottingham, M., Ed. and R. Sayre, Ed., "The Atom
              Syndication Format", RFC 4287, DOI 10.17487/RFC4287,
              December 2005, <https://www.rfc-editor.org/info/rfc4287>.

   [RFC4648]  Josefsson, S., "The Base16, Base32, and Base64 Data
              Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006,
              <https://www.rfc-editor.org/info/rfc4648>.

   [RFC5890]  Klensin, J., "Internationalized Domain Names for
              Applications (IDNA): Definitions and Document Framework",
              RFC 5890, DOI 10.17487/RFC5890, August 2010,
              <https://www.rfc-editor.org/info/rfc5890>.

   [RFC5952]  Kawamura, S. and M. Kawashima, "A Recommendation for IPv6
              Address Text Representation", RFC 5952,
              DOI 10.17487/RFC5952, August 2010,
              <https://www.rfc-editor.org/info/rfc5952>.

   [RFC7464]  Williams, N., "JavaScript Object Notation (JSON) Text
              Sequences", RFC 7464, DOI 10.17487/RFC7464, February 2015,
              <https://www.rfc-editor.org/info/rfc7464>.

   [RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
              2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
              May 2017, <https://www.rfc-editor.org/info/rfc8174>.

   [RFC8259]  Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
              Interchange Format", STD 90, RFC 8259,
              DOI 10.17487/RFC8259, December 2017,
              <https://www.rfc-editor.org/info/rfc8259>.

10.2. Informative References

   [DNS-QUERY]
              Parthasarathy, M. and P. Vixie, "Representing DNS messages
              using XML", Work in Progress,
              draft-mohan-dns-query-xml-00, September 2011.

   [DNSXML]   Daley, J., Morris, S., and J. Dickinson, "dnsxml - A
              standard XML representation of DNS data", Work in
              Progress, draft-daley-dnsxml-00, July 2013.

   [PASSIVE-DNS]
              Dulaunoy, A., Kaplan, A., Vixie, P., and H. Stern,
              "Passive DNS - Common Output Format", Work in Progress,
              draft-dulaunoy-dnsop-passive-dns-cof-04, June 2018.

Acknowledgements 🫶

Some of the ideas here were inspired by earlier work that got abandoned, like [DNSXML], [DNS-QUERY], and [PASSIVE-DNS]. ✨ The document was also inspired by early ideas from Stephane Bortzmeyer. 🌸 And a huge shoutout to the people in the Domain Name System Operations (DNSOP) and DNS Over HTTPS (DOH) working groups, who contributed really useful ideas, even though this wasn't a WG work item. Legends! 👑

Author's Address 💌

Paul Hoffman ICANN

Email: paul.hoffman@icann.org

📦 where this page comes from