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 2 December 2023.¶

Copyright Notice

Copyright (c) 2023 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 be however processed also programatically and also converted back to Wire Format unambiguously.¶

The EDNS[RFC6891] option pseudorecord 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 pseudorecord. It is advised to use this when displaying an OPT pseudorecord 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, which prevents reversing the conversion unambiguosly), but it did not define JSON representation of EDNS option pseudorecord. 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 documents 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 are to be interpreted as described in BCP 14 [RFC2119][RFC8174] when, and only when, they appear in all capitals, as shown here.¶

• EDNS(0) signifies EDNS version 0.¶
• "Decimal value" means an integer displayed in decimals with no leading zeroes.¶
• Base16 is the representation of arbitrary binary data by an even number of case-insensitive hexadecimal digits ([RFC4648], Section 8).¶
• "Followed by" in terms of strings denotes their concatenation, with no other characters nor space between them.¶
• Backslash is the character called also Reverse Solidus, ASCII code 0x5c.¶
• Zero-octet is an octet with all bits set to 0, i.e. ASCII code 0x00.¶
• "Note" denotes a sentence that is not normative. Instead, it points out some non-obvious consequences of previous statements.¶

3. Version-independent Presentation Format

EDNS versions other than 0 are not yet specified, but an OPT pseudorecord with version field set to value other than zero might in theory appear in DNS messages. This section specifies how to convert such OPT pseudorecord to Presentation format. This procedure SHOULD NOT be used for EDNS(0). One possible exception is displaying a malformed EDNS(0) record.¶

OPT pseudorecord 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 always . (DNS Root Domain Name) unless malformed.¶
• TTL is Decimal value of the 32-bit big-endian integer appearing at the TTL position of OPT pseudorecord Wire format, see [RFC6891], Section 6.1.3.¶
• CLASS is a text representation of the 16-bit integer at the CLASS position of OPT pseudorecord Wire format (UDP payload size happens to appear there). This will usually result in CLASS#### (where #### will be the Decimal value), 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 Decimal value, and data as Base16 as per [RFC3597], Section 5.¶

Example:¶

. 16859136 CLASS1232 TYPE41 \# 6 000F00020015

4. EDNS(0) Presentation Format

The EDNS(0) Presentation Format follows 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.¶

Depending on use-case, implementations MAY choose to display only RDATA. In the case 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 Version-independent Presentation Format (Section 3).¶
• CLASS MAY be omitted. If it is present, it MUST be ANY.¶
• TYPE MUST be EDNS0.¶

RDATA consists of at least three <character-string>s ([RFC1035], Section 5.1), one for each field. Each field consists of a Field-name, followed by an equal sign (=), followed by a Field-value. If the Field-value is empty or omitted, the equal sign MUST be omitted as well. For each field, the Field-name and the Field-value are defined by this document, or by the specification of the respective EDNS Option. If it is not, a generic Field-name and Field-value from Section 4.4 applies. However, those generics MAY be used for any Option at all times.¶

The first three fields, Flags (Section 4.1), Extended RCODE (Section 4.2), and UDP Payload Size (Section 4.3) MUST always be present. The rest of the fields are based on Options in the OPT record [RFC6891], Section 6.1.2. They MUST be presented in the same order as they appear in wire format. It is recommended to use the multi-line format with comments at each field, together with a more human-readable form of the contents of each option when available. See Examples (Section 5).¶

FLAGS=0

FLAGS=DO,BIT1

FLAGS=BIT3,BIT7,BIT15

RCODE=NXDOMAIN

RCODE=RCODE3841

RCODE=UNKNOWNRCODE3840

LLQ=1,1,0,0,3600

LLQ=1,LLQ-SETUP,NO-ERROR,0,3600

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

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

ECS=1.2.3.4/24

ECS=1234::2/56/48

ECS=000520000102030405060708

EDE=18 ; Prohibited

EDE=6 ; DNSSEC_Bogus
"EDETXT=signature too short"

5. Examples of EDNS(0) Presentation Format

The following examples shall illustrate the features of EDNS(0) Presentation format described above. They may not make really sense and should not appear in normal DNS operation.¶

. 0 IN EDNS0 (
    FLAGS=DO
    RCODE=BADCOOKIE
    UDPSIZE=1232
    EXPIRE=86400
    COOKIE=36714f2e8805a93d,4654b4ed3279001b
    EDE=18 ; Prohibited
    "EDETXT=bad cookie\000"
    OPT1234=000004d2
    PADDING=[113]
    )

. 0 IN EDNS0 ( FLAGS=0 RCODE=BADSIG UDPSIZE=4096 EXPIRE
               NSID=6578616d706c652e636f6d2e ; example.com.
               DAU=8,10 KEEPALIVE=60.0 CHAIN=zerobyte\000.com.
               KEYTAG=36651,6113 PADDING=df24d08b0258c7de )

6. Version-independent JSON representation

EDNS versions other than 0 are not yet specified, but an OPT pseudorecord with version field set to value other than zero might in theory appear in DNS messages. This section specifies how to represent such OPT pseudorecord in JSON. This procedure SHOULD NOT be used for EDNS(0). One possible exception is displaying a malformed EDNS(0) record.¶

The OPT pseudorecord is in this case represented in JSON as on object called EDNS with following members:¶

• NAME - String with the Owner Name of the OPT record. Note that this is always . (DNS Root Domain Name) unless malformed. See Section 10 for representing DNS names in JSON.¶
• TTL - Integer with the 32-bit big-endian value appearing at the TTL position of OPT pseudorecord Wire format, see [RFC6891], Section 6.1.3.¶
• CLASS - Integer with the 16-bit value at the CLASS position of OPT pseudorecord Wire format (UDP payload size happens to appear there).¶
• TYPE - Integer with the value 41. This member MAY be omitted.¶
• RDATAHEX - String with the pseudorecord RDATA formatted as Base16.¶

Example:¶

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

7. EDNS(0) Representation in JSON

The EDNS(0) OPT record can be represented in JSON as an object called EDNS0. It MUST contain the three members (name-value pairs), Flags (Section 7.1), Extended RCODE (Section 7.2), and UDP Payload Size (Section 7.3). The rest of the members are based on Options in the OPT record [RFC6891], Section 6.1.2. For each member, its name and value are defined by this document, or by the specification of the respective EDNS Option. If it is not, a generic name and value from Section 7.4 applies. However, those generics MAY be used for any Option at all times. Note that the order of members is not preserved in JSON.¶

"LLQ": { "LLQ-VERSION": 1, "LLQ-OPCODE": 1, "LLQ-ERROR": 0,
         "LLQ-ID": 0, "LLQ-LEASE": 3600 }

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

"ECS": {
    "FAMILY": 1,
    "IP": "1.2.3.4",
    "SOURCE": 24
}

"ECS": {
    "FAMILY": 2,
    "IP": "1234::2",
    "SOURCE": 56,
    "SCOPE": 48
}

"ECS": {
    "FAMILY": 5,
    "IP": "0102030405060708"
    "SOURCE": 32
}

8. Examples of EDNS(0) Representation in JSON

The following examples are the JSON representations of the examples in Section 5. They may not make really sense and should not appear in normal DNS operation.¶

"EDNS0": {
    "FLAGS": [ "DO" ],
    "RCODE": "BADCOOKIE",
    "UDPSIZE": 1232,
    "EXPIRE": 86400,
    "COOKIE": [ "36714f2e8805a93d", "4654b4ed3279001b" ],
    "EDE": {
        "INFO-CODE": 18,
        "Purpose": "Prohibited",
        "EXTRA-TEXT": "bad cookie\u0000"
    },
    "OPT1234": "000004d2",
    "PADDING": "[113]"
}

"EDNS0": { "FLAGS": [ ], "RCODE": "BADSIG", "UDPSIZE": 4096,
           "EXPIRE": null, "NSIDHEX": "6578616d706c652e636f6d2e",
           "NSID": "example.com.", "DAU": [ 8, 10 ], "KEEPALIVE": 60.0,
           "CHAIN": "zerobyte\\000.com.", "KEYTAG": [ 36651, 6113 ],
           "PADDING": "df24d08b0258c7de" }

9. Guidelines for Future EDNS(0) Options

This draft describes the presentation and JSON format of those ENDS(0) options which are known at the time of writing. Other EDNS(0) options fall in the category of Unrecognized Options (Section 4.4, Section 7.4), unless their specifications define a presentation and JSON formats explicitly. The following guidelines shall help defining them.¶

It is recommended to specify the presentation and JSON formats in every document defining new ENDS(0) options. Those formats should follow the semantics of the options' values rather than the syntax, in order to make them more human-readable. This includes displaying the values of enumerations in their text form rather than numeric (see how DAU option is treated Section 4.7, Section 7.7), converting numeric amounts to comprehensible units (see Edns-Tcp-Keepalive Option Section 4.11, Section 7.11) and adding explanatory comments if useful (see Extended DNS Error Section 4.15, Section 7.15).¶

The formats MUST be defined in a way that the reversing the process of conversion back to wire format is possible and unambiguous, with the exception that JSON is not able to preserve the order of members within objects. When a string is extracted from the wire format, the escaping rules for special characters MUST be considered. Treating malformed wire format input MUST be taken into consideration when defining the presentation and JSON format, but a simple fallback to Unrecognized Option format is a viable solution. See the above-defined presentation and JSON formats of existing EDNS(0) options for inspiration, analogies and tricks.¶

10. 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 of 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, 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 04005C2E2203646F6D00 can be represented in JSON as:¶

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

but also as (among other ways):¶

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

11. IANA Considerations

This document has no IANA actions.¶

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

13. Acknowledgements

TODO¶

14. Implementation Status

Note to the RFC Editor: please remove this entire appendix before publication.¶

None yet.¶

15. 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(0) Options, dummy IANA Considerations and Security Considerations.¶

Authors' Addresses