EDNS Presentation and JSON Format

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶

This Internet-Draft will expire on 21 October 2024.¶

Copyright Notice

Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved.¶

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶

Table of Contents

1. Introduction

A DNS record[RFC1035] 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[RFC6891] 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[RFC8259] representation[RFC8427] 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 and possible issues with repeated 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[RFC8427] also defined ambiguous and possibly conflicting rules for escaping special characters when representing DNS names in JSON. This document modifies and clarifies those rules.¶

2. 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 [RFC2119][RFC8174] 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 ([RFC4648], Section 8).¶

• 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.¶

3. 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 [RFC3597], Section 5. 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 [RFC6891], Section 6.1.3.¶

• 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 [RFC3597], Section 5.¶

Example:¶

. 16859136 CLASS1232 TYPE41 \# 6 000F00020015

4. 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 Section 13 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 [RFC6891], Section 6.1.3.¶

• 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:¶

{
    "NAME": ".",
    "TTL": 16859136,
    "CLASS": 1232,
    "TYPE": 41,
    "RDATAHEX": "000f00020015"
}

5. Common Concept

In order to represent the binary data from EDNS option textually, we first define the abstract concept of FIELDs. First four FIELDs represent the OPT record header, one more FIELD represents every EDNS option that appears in the OPT record RDATA. Each FIELD has a defined FIELD-NAME, which is an ID-string; a specific FIELD-TYPE from the list below; and prescribed way how to construct the FIELD-VALUE from given binary data. Based on those, the Presentaion and JSON formats are defined in Section 6 and Section 7, respectively.¶

The FIELD-NAMEs of FIELDs representing the OPT record header are version, flags, rcode and udpsize. The FIELD-NAMEs of FIELDs representing EDNS options are defined as their Mnemonics according to [IANA.EDNS.Options] (see also Section 14).¶

A FIELD-TYPE can be one of 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)¶

The FIELD-TYPE and the construction of FIELD-VALUE of each FIELD is defined in Section 8.¶

6. EDNS Presentation Format

The EDNS Presentation Format follows the RR format of the master file ([RFC1035], Section 5.1), 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 (Section 3).¶

• 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 ([RFC1035], Section 5.1); Internationalized Domain Name (IDN) labels MAY be expressed in their U-label form, as described in [RFC5890].¶

• string is represented as <character-string> according to [RFC1035], Section 5.1; 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.¶

7. 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 Section 13¶

• string is represented as a String according to [RFC8259], Section 7¶

• 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 and that repeated options might cause issues in JSON. The FIELDs flags, rcode, and udpsize MUST be represented, version MAY be omitted if the EDNS Version is zero.¶

8. Field Definitions

flags: ""

flags: DO,BIT1

flags: BIT3,BIT7,BIT14

rcode: NXDOMAIN

rcode: 3841

rcode: EXT3840

DAU: 8,10,13,14,15
DHU: 1,2,4
N3U: 1

DAU: RSASHA256,RSASHA512,ECDSAP256SHA256,ECDSAP384SHA384,ED25519
DHU: SHA-1,SHA-256,SHA-384
N3U: SHA-1

ECS: "1.2.3.4/24"

ECS: "1234::2/56/48"

ECS: "000520000102030405060708"

EDE: 18 "Prohibited" ""

EDE: 6 "DNSSEC Bogus" "signature too short"

"REPORT": "back\\\\slash.example.com."

9. 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.¶

. 0 ANY EDNS (
    version: 0
    flags: DO
    rcode: BADCOOKIE
    udpsize: 1232
    EXPIRE: 86400
    COOKIE: 36714f2e8805a93d,4654b4ed3279001b
    EDE: 18 "Prohibited" "bad cookie\000"
    OPT1234: 000004d2
    PADDING: 113 ""
    )

. 0 ANY EDNS ( flags: 0 rcode: BADSIG udpsize: 4096 EXPIRE: NONE
               NSID: 6578616d706c652e636f6d2e "example.com."
               DAU: 8,10 KEEPALIVE: 600 CHAIN: zerobyte\000.com.
               KEYTAG: 36651,6113 PADDING: 8 "df24d08b0258c7de" )

10. Examples of EDNS Representation in JSON

The following examples are the JSON equivalents of the examples in Section 9. They may not make much sense and should not appear in normal DNS operation.¶

"EDNS": {
    "version": 0,
    "flags": [ "DO" ],
    "rcode": "BADCOOKIE",
    "udpsize": 1232,
    "EXPIRE": 86400,
    "COOKIE": [ "36714f2e8805a93d", "4654b4ed3279001b" ],
    "EDE": {
        "CODE": 18,
        "Purpose": "Prohibited",
        "TEXT": "bad cookie\u0000"
    },
    "OPT1234": "000004d2",
    "PADDING": {
        "LENGTH": 113
    }
}

"EDNS": { "flags": [ ], "rcode": "BADSIG", "udpsize": 4096,
          "EXPIRE": "NONE", "NSID": { "HEX": "6578616d706c652e636f6d2e",
          "TXT": "example.com." }, "DAU": [ 8, 10 ], "KEEPALIVE": 600,
          "CHAIN": "zerobyte\\000.com.", "KEYTAG": [ 36651, 6113 ],
          "PADDING": { "LENGTH": 8, "HEX": "df24d08b0258c7de" } }

11. 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 (Section 8.5), 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.¶

The FIELD-NAME MUST always be an ID-string and MUST be added as new option's Mnemonic when requesting IANA to add respective entry to the table [IANA.EDNS.Options].¶

12. 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 (Section 11). This is, again, beneficial for human readers, as otherwise all new EDNS options would have to be represented as Unrecognized Options (Section 8.5). 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.¶

13. Update Representing DNS Messages in JSON

This section is not related to EDNS. This section updates [RFC8427], Section 2.6, 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 [RFC1035], Section 5.1 (called master file format in the referenced document), and the resulting <character-string> subsequently is inserted into JSON as String ([RFC8259], Section 7).¶

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 [RFC8427] 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 [RFC5890].¶

Example: the name with the Wire format 04005C2E2203636F6D00 can be represented in JSON as:¶

"NAME": "\\000\\\\\\046\".com."

but also as (among other ways):¶

"NAME": "\\000\\092\\.\\\".c\\om."

14. IANA Considerations

IANA is requested to augment the table [IANA.EDNS.Options] with a new column titled "Mnemonic", possibly as third column between "Name" and "Status". The initial values for existing entries are according to the table below:¶

The values for entries and rows that are unassigned, reserved or on-hold are to be left blank with no Mnemonic defined.¶

15. 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.¶

16. Acknowledgements

TODO¶

17. 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.¶

18. 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.¶

• edns-presentation-format-03¶

• Added IANA Actions for additional column for Mnemonic. Added Report-Channel option and removed LLQ. Improved Common concept, tiny fixes.¶

Authors' Addresses