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 be however processed also programatically and also converted back to Wire Format unambiguously. The EDNS 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 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 unambiguosly), but it did not define JSON representation of EDNS option pseudorecord. 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 documents 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 are to be interpreted as described in BCP 14 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 (). "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.

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 . 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 . 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 . Example:

EDNS(0) Presentation Format The EDNS(0) Presentation Format follows RR format of the master file (), 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. 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 (), 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 applies. However, those generics MAY be used for any Option at all times. The first three fields, Flags, Extended RCODE, and UDP Payload Size MUST always be present. The rest of the fields are based on Options in the OPT record . 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.

Flags The first field's Field-name is FLAGS and its Field-value is 0 (zero) if the EDNS flags is zero. Otherwise, the Field-value consists of comma-separated list of the items BIT##, where ## is a Decimal value. BITn is present in the list if and only if n-th bit (the most significant bit being 0-th) of flags is set to 1. If the Flag of the bit is specified in , the Flag SHOULD be used instead of BIT##. (So far, the only known Flag is DO.) Examples:

Extended RCODE The second field's Field-name is RCODE and its Field-value is RCODE###, where ### stands for the DNS message extended RCODE as Decimal value, computed from both the OPT record and the DNS Message Header. If the lower four bits of extended RCODE in DNS Message Header can not be used, the Field-value is UNKNOWNRCODE###, where ### stands for the DNS message extended RCODE as Decimal value, with the lower four bits set to zero (i.e. the four-bit left shift still applies). If the extended RCODE has been computed completely and it is listed in , its Name should be used instead of RCODE###. The Name is case-insensitive. Examples:

UDP Payload Size The third field's Field-name is UDPSIZE and its Field-value is the UDP payload size as Decimal value.

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 this subsection. Other options (specified below or otherwise) MAY be displayed so as well. Unrecognized option Field-name is OPT##, where ## stands for its OPTION-CODE, and Field-value is its OPTION-VALUE displayed as Base16.

LLQ Option The LLQ (OPTION-CODE 1 ) Field-name is LLQ and Field-value is comma-separated tuple of LLQ-VERSION, LLQ-OPCODE, LLQ-ERROR, LLQ-ID, and LLQ-LEASE as Decimal values. The numeric values of LLQ-OPCODE and LLQ-ERROR MAY be substituted with their textual representations listed in . Examples:

NSID Option The NSID (OPTION-CODE 3 ) Field-name is NSID and Field-value is its OPTION-VALUE displayed as Base16. It is recommended to add a comment with ASCII representation of the value.

DAU, DHU and N3U Options The DAU, DHU, and N3U (OPTION-CODES 5, 6, 7, respectively ) Field-names are DAU, DHU, and N3U, respectively, and their Field-values consist of comma-separated lists of ALG-CODEs as Decimal values or the textual representations of the ALG-CODEs (called mnemonic in the referenced documents) found in their respective IANA registries . Examples:

Edns-Client-Subnet Option The EDNS Client Subnet (OPTION-CODE 8 ) Field-name is ECS and if FAMILY is neither IPv4 (1) nor IPv6 (2), its Field-value is the whole OPTION-VALUE as Base16. Otherwise, it consists of the textual IPv4 or IPv6 address (, ), followed by a slash (/), followed by SOURCE PREFIX-LENGTH as Decimal value, followed by another slash, followed by SCOPE PREFIX-LENGTH as Decimal value. If SCOPE PREFIX-LENGTH is zero, it MUST be omitted together with the second slash. Examples:

EDNS EXPIRE Option The EDNS EXPIRE (OPTION-CODE 9 ) Field-name is EXPIRE and its Field-value, if present, is displayed as Decimal value.

Cookie Option The DNS Cookie (OPTION-CODE 10 ) Field-name is COOKIE and its Field-value consists of the Client Cookie as Base16, followed by a comma, followed by the Server Cookie as Base16. The comma and Server Cookie are displayed only if OPTION-LENGTH is greater than 8.

Edns-Tcp-Keepalive Option The edns-tcp-keepalive (OPTION-CODE 11 ) Field-name is KEEPALIVE and its Field-value is the TIMEOUT in seconds displayed as decimal number with exactly one decimal digit and a dot as decimal separator.

Padding Option The Padding (OPTION-CODE 12 ) Field-name is PADDING and its Field-value is its OPTION-VALUE displayed as Base16. If the OPTION-VALUE consists only of zero-octets, it SHOULD be substituted with an alternative Field-value [###], where ### stands for OPTION-LENGTH as Decimal value.

CHAIN Option The CHAIN (OPTION-CODE 13 ) Field-name is CHAIN and its Field-value, the Closest trust point, is displayed as a textual Fully-Qualified Domain Name.

Edns-Key-Tag Option The edns-key-tag (OPTION-CODE 14 ) Field-name is KEYTAG and its Field-value is displayed as a comma-separated list of Decimal values.

Extended DNS Error Option The Extended DNS Error (OPTION-CODE 15 ) Field-name is EDE and the Field-value is its INFO-CODE as Decimal value. It is recommended to add a comment with the Purpose of the given code (first presented in and then governed by ). If the EXTRA-TEXT is nonempty, it MUST be displayed as another field, with Field-name EDETXT and Field-value being the EXTRA-TEXT string as-is. Note that RFC1035-style escaping applies to all non-printable and non-ASCII characters, including some eventual UTF-8 bi-characters and possible trailing zero-octet. Also note that any presence of spaces requires the whole <character-string> to be enclosed in quotes, not just the Field-value. Examples:

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.

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 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 . 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(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, Extended RCODE, and UDP Payload Size. The rest of the members are based on Options in the OPT record . 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 applies. However, those generics MAY be used for any Option at all times. Note that the order of members is not preserved in JSON.

Flags The JSON member name is FLAGS and its value is an Array of Strings BIT##, where ## is a Decimal value. BITn is present in the Array if and only if n-th bit (the most significant bit being 0-th) of flags is set to 1. If the Flag of the bit is specified in , the Flag SHOULD be used instead of BIT##. (So far, the only known Flag is DO.)

Extended RCODE The JSON member name is RCODE and its value is a String containing Field-value from .

UDP Payload Size The JSON member name is UDPSIZE and its value is an Integer with UDP payload size.

Unrecognized Option EDNS options that are not part of this specification and their own specifications do not specify their JSON member name and value MUST be displayed according this subsection. Other options (specified below or otherwise) MAY be displayed so as well. Unrecognized option JSON member name is OPT##, where ## stands for its OPTION-CODE as Decimal value, and its value is a String containing its OPTION-VALUE encoded as Base16.

LLQ Option The LLQ (OPTION-CODE 1 ) JSON member name is LLQ and its value is an Object with members LLQ-VERSION, LLQ-OPCODE, LLQ-ERROR, LLQ-ID, and LLQ-LEASE, each representing the respective value as Integer. Note that only numeric representation of these values is possible. Example:

NSID Option The NSID (OPTION-CODE 3 ) JSON member name is NSIDHEX and its value is a String with OPTION-VALUE encoded as Base16. Optionally, one more member of EDNS0 Object MAY be added as well, with the name NSID and the value being a String with the OPTION-VALUE interpreted as UTF-8. Note that in that case, JSON escaping routines () take place, possibly using the \uXXXX notation.

DAU, DHU and N3U Options The DAU, DHU, and N3U (OPTION-CODES 5, 6, 7, respectively ) JSON member names are DAU, DHU, and N3U, respectively, and their values are Arrays of Integers with ALG-CODEs. Example:

Edns-Client-Subnet Option The EDNS Client Subnet (OPTION-CODE 8 ) JSON member name is ECS and its value is an Object with following members: FAMILY - Integer with FAMILY IP - String with the textual IPv4 or IPv6 address (, ), or a String with ADDRESS encoded as Base16 if FAMILY is neither 1 or 2 SOURCE - Integer with SOURCE PREFIX-LENGTH SCOPE - Integer with SCOPE PREFIX-LENGTH, omitted if zero Examples:

EDNS EXPIRE Option The EDNS EXPIRE (OPTION-CODE 9 ) JSON member name is EXPIRE and its value is either an Integer or null.

Cookie Option The DNS Cookie (OPTION-CODE 10 ) JSON member name is COOKIE and its value is an Array containing a String with the Client Cookie encoded as Base16 and, if present, another String with Server Cookie encoded as Base16.

Edns-Tcp-Keepalive Option The edns-tcp-keepalive (OPTION-CODE 11 ) JSON member name is KEEPALIVE and its value is the TIMEOUT in seconds formatted as a Number (possibly a non-Integer).

Padding Option The Padding (OPTION-CODE 12 ) JSON member name is PADDING and its value is a String containing Field-value from .

CHAIN Option The CHAIN (OPTION-CODE 13 ) JSON member name is CHAIN and its value is a String with the OPTION-VALUE in the form of a textual Fully-Qualified Domain Name. See for representing DNS names in JSON.

Edns-Key-Tag Option The edns-key-tag (OPTION-CODE 14 ) JSON member name is KEYTAG and its value is an Array of Integers.

Extended DNS Error Option The Extended DNS Error (OPTION-CODE 15 ) JSON member name is EDE and its value is an Object with following members: INFO-CODE - Integer with the INFO-CODE Purpose - String with Purpose of the INFO-CODE (, Section 5.2) EXTRA-TEXT - String with the EXTRA-TEXT The EXTRA-TEXT member MUST be omitted if empty. If its value contains non-printable or special (backslash, quote) characters, they MUST be escaped by the means of JSON Strings ().

Examples of EDNS(0) Representation in JSON The following examples are the JSON representations of the examples in . They may not make really sense and should not appear in normal DNS operation.

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 (, ), 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 , ), converting numeric amounts to comprehensible units (see Edns-Tcp-Keepalive Option , ) and adding explanatory comments if useful (see Extended DNS Error , ). 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.

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 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 (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, 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 04005C2E2203646F6D00 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. None yet.

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.