EDNS Presentation and JSON Format

Introduction A DNS record of any type can be converted between its binary Wire format and textual Presentation format. The Wire format is used in DNS messages transferred over the Internet, while the Presentation format is used not only in Zone Files (called "master files" in the referenced document), but also to display the contents of DNS messages to humans by debugging utilities and possible other use-cases. The Presentation format can, however, be processed programatically and also converted back to Wire Format unambiguously. The EDNS option pseudo-record does not appear in Zone Files, but it sometimes needs to be converted to human-readable or even machine-readable textual representation. This document describes such a Presentation Format of the OPT pseudo-record. It is advised to use this when displaying an OPT pseudo-record to humans. It is recommended to use this when the textual format is expected to be machine-processed further. The JSON representation of DNS messages is also helpful as both human-readable and machine-readable format (despite the limitation in non-preservation of the order of options, which prevents reversing the conversion unambiguously), but it did not define a JSON representation of EDNS option pseudo-record. This document defines it. The aforementioned document also defined ambiguous and possibly conflicting rules for escaping special characters when representing DNS names in JSON. This document modifies and clarifies those rules.

Terminology The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document is to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here. Base16 is the representation of arbitrary binary data by an even number of case-insensitive hexadecimal digits (). Backslash is the character, also called Reverse Solidus, ASCII code 0x5c. ID-string is a string of characters containing only (uppercase or lowercase) letters, digits, dashes, and underscores, and its first character is a (uppercase or lowercase) letter. "Note" denotes a sentence that is not normative. Instead, it points out some non-obvious consequences of previous statements.

Generic EDNS Presentation Format A malformed EDNS record or a record of an unsupported EDNS version can be converted to Presentation format using this generic method. OPT pseudo-record is, in this case, represented the same way as a RR of unknown type according to . In specific: Owner Name is the Owner Name of the OPT record. Note that this is usually . (DNS Root Domain Name) unless malformed. TTL is the 32-bit big-endian integer appearing at the TTL position of the OPT pseudo-record Wire format, see . CLASS is a text representation of the 16-bit integer at the CLASS position of the OPT pseudo-record Wire format (UDP payload size happens to appear there). This will usually result in CLASS#### (where #### will be the integer), but it might also result, for example in IN or CH if the value is 1 or 4, respectively. TYPE is either TYPE41 or OPT. RDATA is formatted by \#, its length as a decadic number, and data as Base16 as per . Example:

Generic EDNS JSON representation A malformed EDNS record or a record of an unsupported EDNS version can be converted to JSON using this generic method. The OPT pseudo-record is, in this case, represented in JSON as an object with following members: NAME - String with the Owner Name of the OPT record. Note that this is usually . (DNS Root Domain Name) unless malformed. See for representing DNS names in JSON. TTL - Integer with the 32-bit big-endian value appearing at the TTL position of the OPT pseudo-record Wire format, see . CLASS - Integer with the 16-bit value at the CLASS position of the OPT pseudo-record Wire format (UDP payload size happens to appear there). TYPE - Integer with the value 41. RDATAHEX - String with the pseudo-record RDATA formatted as Base16. Example:

Common Concept Let's first divide the information contained in the EDNS record into FIELDs: Version, FLAGS, RCODE, and UDPSIZE FIELDs are based on the OPT record header, one other FIELD is based on every EDNS option that appears in the OPT record RDATA. Each FIELD has a defined FIELD-NAME, which is an ID-string, and FIELD-VALUE of type FIELD-TYPE, which is one of the following: int, a non-negative integer ID-NAME, a mnemonic string denoting a numeric value defined by this document, other referenced RFC, and/or referenced IANA table; mnemonics that are not ID-strings MUST NOT be used ID-CODE, a non-negative integer prefixed with a fixed ID-string mixed, a variant type that can be any of the above-defined types base16, an even number of hexadecimal (case-insensitive) digits representing a string of arbitrary octets list, a variable-sized (possibly empty) list of values of homogenous type defined above (possibly mixed) dname, a Fully-Qualified Domain Name string, a string of arbitrary octets where quoting and escaping is used to represent it as ASCII string object, a defined fixed number of SUBFIELDs, each having its FIELD-NAME and FIELD-TYPE defined according to the rules above (nested objects are forbidden)

EDNS Presentation Format The EDNS Presentation Format follows the RR format of the master file (), including quotation of non-printable characters, multi-line format using round brackets, and semicolons denoting comments. However, one difference is that <character-string>s are not limited in size (to 255 represented octets). Depending on the use-case, implementations MAY choose to display only RDATA. In the event that the resource-record-like Presentation format is desired, the following applies: Owner Name MUST be . (DNS Root Domain Name). TTL MAY be omitted. If it is present, it MUST be 0 (zero). Note that this differs from DNS RR wire-to-text conversion as well as Generic Presentation Format. CLASS MAY be omitted. If it is present, it MUST be ANY. TYPE MUST be EDNS. RDATA consists of <character-string>s, each FIELD is represented by at least two of them. First represented FIELDs are Version, FLAGS, RCODE, and UDPSIZE in this order; however, Version MAY be omitted if the EDNS Version is zero. The rest of FIELDs respect the EDNS options in the same order as they appear in the OPT record, including possibly repeated options. The following paragraph defines how a single FIELD is represented with <character-string>s. The first <character-string> is the FIELD-NAME concatenated (no spaces in between) with a colon (:) and SHOULD NOT be enclosed in quotes. The rest depends on the FIELD-TYPE: int is represented as a decadic number with no leading zeroes ID-NAME or ID-CODE is represented as-is base16 is represented as-is, zero-length base16 as an empty string enclosed in quotes ("") list is represented as a comma-separated list of its items with no spaces; an empty list as an empty string enclosed in quotes ("") dname is represented according to the rules of representing Domain names in the master file (); Internationalized Domain Name (IDN) labels MAY be expressed in their U-label form, as described in . string is represented as <character-string> according to ; and SHOULD be enclosed in quotes even when not containing any spaces object is represented by the same number of <character-string>s as how many SUBFIELDs it has; their FIELD-NAMEs are ignored and FIELD-VALUEs are represented in their defined order Note that each object has fixed number of <character-string>s, other types have one. This is cruical for parsing, the colon plays only decorative role, strings might also end with a colon.

EDNS Representation in JSON The EDNS OPT record can be represented in JSON as an object called EDNS. Each FIELD is represented as one object member (name-value pair) ,where the name is FIELD-NAME and the value depends on FIELD-TYPE: int is represented as an Integer ID-NAME, ID-CODE or base16 is represented as a String mixed is represented as a String even when it happens to be int list is represented as a JSON Array containing its members in specified order dname is represented as a String with quotation rules in string is represented as a String according to object is represented as a JSON object with each SUBFIELD represented as one of its member according to rules above (note that nested objects are forbidden) Note that the order of members is not preserved in JSON. The FIELDs FLAGS, RCODE, and UDPSIZE MUST be represented, Version MAY be omitted if the EDNS Version is zero.

Field Definitions

Version EDNS Version is represented by FIELD-NAME Version, its FIELD-TYPE is int and FIELD-VALUE is the EDNS Version.

Flags EDNS FLAGS is represented by FIELD-NAME FLAGS and its FIELD-TYPE is a list of mixed: ID-NAME DO if the DO bit is set ID-CODE BITn for each n-th bit (other than DO) set Examples of Presentation format:

Extended RCODE Extended RCODE is represented by FIELD-NAME RCODE and its FIELD-TYPE is a mixed. For the sake of readability, it is RECOMMENDED to compute the whole DNS Message Extended RCODE from both the OPT record and the DNS Message Header. If the whole DNS Message Extended RCODE is computed and has a mnemonic in , the FIELD-VALUE MAY be this mnemonic as ID-NAME. If the whole DNS Message Extended RCODE is computed and no mnemonic is available (or used), the FIELD-VALUE is an int with the computed Extended RCODE. If the whole DNS Message Extended RCODE cannot be computed, the FIELD-VALUE is an ID-CODE EXT##, where ## stands for DNS Message Extended RCODE with the lower four bits set to zero (i.e. the four-bit left shift still applies). Examples of Presentation format:

UDP Payload Size UDP Payload Size is represented by FIELD-NAME UDPSIZE, its FIELD-TYPE is int and FIELD-VALUE is the UDP Payload Size.

Unrecognized Option EDNS options that are not part of this specification, and their own specifications do not specify their FIELD-NAME and FIELD-VALUE MUST be displayed according to this subsection. Other options (specified below or otherwise) MAY be displayed so as well. Unrecognized EDNS option is represented by FIELD-NAME OPT##, where ## stands for its OPTION-CODE, its FIELD-TYPE is base16 and FIELD-VALUE is its OPTION-VALUE encoded as Base16.

LLQ Option The LLQ (OPTION-CODE 1 ) option is represented by FIELD-NAME LLQ and its FIELD-VALUE is a list of ints with LLQ-VERSION, LLQ-OPCODE, LLQ-ERROR, LLQ-ID, and LLQ-LEASE in this order. Example of Presentation format:

NSID Option The NSID (OPTION-CODE 3 ) option is represented by FIELD-NAME NSID and its FIELD-VALUE is an object with two SUBFIELDs in the following order: first FIELD-NAME is HEX and FIELD-VALUE is a base16 representation of the OPTION-VALUE second FIELD-NAME is TEXT and FIELD-VALUE is a string representation of the OPTION-VALUE The TEXT value MAY be substituted with an empty string (for example, if the OPTION-VALUE contains non-printable characters). Within JSON, the TEXT SUBFIELD MAY be omitted if it is an empty string.

DAU, DHU and N3U Options The DAU, DHU, and N3U (OPTION-CODES 5, 6, 7, respectively ) options are represented by FIELD-NAMEs DAU, DHU, and N3U, respectively, and their FIELD-VALUES are lists of ints with their ALG-CODEs. Within Presentation format, their FIELD-VALUEs MAY be substituted with lists of ID-NAMEs with the textual mnemonics of the ALG-CODEs found in their respective IANA registries . Examples of Presentation format:

Edns-Client-Subnet Option The EDNS Client Subnet (OPTION-CODE 8 ) option is represented by FIELD-NAME ECS and its FIELD-TYPE is a string. If FAMILY is either IPv4 (1) or IPv6 (2) and the OPTION-LENGTH matches the expected length, the FIELD-VALUE is a slash-separated (no spaces) tuple of: the textual IPv4 or IPv6 address (, ), respectively SOURCE PREFIX-LENGTH as a decadic number SCOPE PREFIX-LENGTH as a decadic number, SHOULD be omitted (including the separating slash) if zero Otherwise, the FIELD-VALUE is a string with base16-representation of the OPTION-VALUE. Examples of Presentation format:

EDNS EXPIRE Option The EDNS EXPIRE (OPTION-CODE 9 ) option is represented by FIELD-NAME EXPIRE and its FIELD-VALUE is a mixed: ID-NAME NONE if OPTION-LENGTH is zero int with EXPIRE value otherwise

Cookie Option The DNS Cookie (OPTION-CODE 10 ) option is represented by FIELD-NAME COOKIE and its FIELD-VALUE is a list of base16 with the Client Cookie and, if OPTION-LENGTH is greater than 8, the Server Cookie.

Edns-Tcp-Keepalive Option The edns-tcp-keepalive (OPTION-CODE 11 ) option is represented by FIELD-NAME KEEPALIVE and its FIELD-VALUE is an int with the TIMEOUT in tenths of seconds.

Padding Option The Padding (OPTION-CODE 12 ) option is represented by FIELD-NAME PADDING and its FIELD-VALUE is an object with two SUBFIELDs: first FIELD-NAME is LENGTH and its FIELD-VALUE is the OPTION-LENGTH as int second FIELD-NAME is HEX and its FIELD-VALUE is a string with base16-representation of OPTION-DATA If the OPTION-DATA consists only of zeroes (0x00 octets), the HEX SUBFIELD SHOULD be an empty string. Within JSON, the HEX SUBFIELD MAY be omitted if it is an empty string.

CHAIN Option The CHAIN (OPTION-CODE 13 ) option is represented by FIELD-NAME CHAIN and its FIELD-VALUE is the Closest trust point as dname.

Edns-Key-Tag Option The edns-key-tag (OPTION-CODE 14 ) option is represented by FIELD-NAME KEYTAG and its FIELD-VALUE is the list of Key Tag values as list of ints.

Extended DNS Error Option The Extended DNS Error (OPTION-CODE 15 ) option is represented by FIELD-NAME EDE and its FIELD-VALUE is an object with three SUBFIELDs: first FIELD-NAME is CODE and its FIELD-VALUE is the INFO-CODE as int second FIELD-NAME is Purpose and its FIELD-VALUE is the Purpose (first presented in and then governed by ) as string, or an empty string third FIELD-NAME is TEXT and its FIELD-VALUE is the EXTRA-TEXT as string (possibly of zero length) Within JSON, the Purpose SUBFIELD MAY be omitted if it is an empty string. The same applies for TEXT SUBFIELD. Examples of Presentation format:

Examples of EDNS Presentation Format The following examples shall illustrate the features of EDNS Presentation format described above. They may not make much sense and should not appear in normal DNS operation.

Examples of EDNS Representation in JSON The following examples are the JSON equivalents of the examples in . They may not make much sense and should not appear in normal DNS operation.

Guidelines for Future EDNS Options This draft describes the presentation and JSON format of those ENDS options that are known at the time of writing. Other EDNS options fall in the category of Unrecognized Options (), unless specified otherwise. The following guidelines shall help define them. When defining new EDNS options, it is recommended to specify their FIELD-NAMEs, FIELD-TYPEs and the construction of FIELD-VALUEs so that the EDNS Presentation and JSON format comprehensibly handles them. Those formats should follow the semantics of the options' values rather than the syntax in order to make them more human-readable. If it is necessary to define a new FIELD-TYPE, care must be taken to define its representation in Presentation and JSON format in a similar fashion like in this document.

Forward-Compatibility Considerations This specification of ENDS Presentation and JSON format prefers displaying textual mnemonics over potentially cryptic numeric values wherever possible, which is desirable for human readers. It refers to several IANA tables collecting the definitions of those mnemonics. Those tables may be getting updated throughout time, and for human readers, it is still beneficial that the EDNS formats reflect those updates. However, this may cause difficulties for algorithms implementing the reverse process of converting EDNS Presentation and/or JSON format back to wire format, because they might not understand some new mnemonics. This limitation has to be taken into consideration. Similarly, new documents may define Presentation and JSON format of newly defined EDNS options according to (or not according to) the guidelines above (). This is, again, beneficial for human readers, as otherwise all new EDNS options would have to be represented as Unrecognized Options (). However, this may also cause difficulties for algorithms implementing the reverse process of converting EDNS Presentation and/or JSON format back to wire format, because they might not understand some new options.

Update Representing DNS Messages in JSON This section is not related to EDNS. This section updates , including erratum 5439, which introduced contradicting MUSTs for escaping backslashes. In order to solve this contradiction and correctly represent a DNS name in JSON, it MUST be first converted to textual Presentation format according to (called master file format in the referenced document), and the resulting <character-string> subsequently is inserted into JSON as String (). Note that the previous paragraph prescribes the following escaping strategy: In the first step, every problematic character (non-printable, backslash, dot within Label, or any octet) is either substituted with the sequence \DDD, where DDD is the three-digit decimal ASCII code, or in some cases (backslash, dot, any printable character) just prepended with a backslash. In the second step, every quote (") and backslash (\) in the resulting <character-string> is prepended with another backslash. Note that the JSON escaping sequence \uXXXX (where XXXX is a hexadecimal Unicode code) is thus never needed. Moreover, the following requirements from still hold: The name MUST be represented as an absolute Fully-Qualified Domain Name. Internationalized Domain Name (IDN) labels MUST be expressed in their A-label form, as described in . Example: the name with the Wire format 04005C2E2203636F6D00 can be represented in JSON as:

but also as (among other ways):

IANA Considerations This document has no IANA actions.

Security Considerations This document only describes the textual representation of binary data and therefore has no security impact on related protocols. When implementing software, care must be taken to handle possibly inconsistent or broken input data.

Acknowledgements TODO

Implementation Status Note to the RFC Editor: Please remove this entire appendix before publication. This version of this specification draft-peltan-edns-presentation-format-02 has been implemented in Knot DNS 3.3.2.

Change History Note to the RFC Editor: Please remove this entire appendix before publication. edns-presentation-format-00

Initial public draft.

edns-presentation-format-01

Added Guidelines for Future EDNS Options, dummy IANA Considerations and Security Considerations.

edns-presentation-format-02

Substantial re-work with common FIELD-TYPE specifications, bigger changes in presentation format and smaller in JSON.