CiprianDorinCraciun/Notes/Public/DnsOverHttp

1.7.1.1   Endpoint resolution

...

1.7.1.2   Endpoint verification

...

1.7.1.3   REST-full endpoints

...

URL syntax

<rr-rest-url> ::=
    `/v1/rr/` <class> `/` <name> `/` <type>

1.7.1.4   RPC endpoints

...

URL syntax

<rr-rpc-url> ::= `/v1/rr`

1.7.3.1   Querying via GET requests

The HTTP transactions described in this section, MUST only be used for DNS operations that:

• MUST have a query semantic in the DNS sense; that is the operation MUST NOT have any side-effects, except possibly the caching of the response; for example the QUERY or IQUERY operations as described by [RFC-1034], [RFC-1035], and [RFC-6195];
• MUST map perfectly over the QUERY PDU; that is the operation MUST have the same flags, fields, and other structural elements, including having the same formal designation and semantic, as those described in [RFC-1034], [RFC-1035], and [RFC-6195] for the QUERY operation;

Informally, these GET transactions MUST only be used for DNS queries, or future query-like operations described in later RFC's, that are syntactically backward compatible.

Moreover, these GET transactions MUST only be used for DNS queries that require exactly one question record. This is due to the fact that the QNAME, QCLASS, and QTYPE PDU fields are obtained from the URL of the GET request.

These HTTP transactions MUST be implemented by any client or server that wants to be compliant with this document.

URL syntax

<query-url> ::=
     <rr-rest-url> ( `?` <query-url-arguments> )?

<query-url-arguments> ::=
    (
        ( `operation=` <query-operation> `&` )?
        ( `forward=` <forward> `&` )?
        ( `recursive=` <recursive> `&` )?
        ( `data-encoding=` <data-encoding> )?
    )

Where:

class

<class> ::= `*` | `ANY` | `IN` | ... | /^[A-Z0-9]([A-Z0-9-]+[A-Z0-9-])?$/ | /^\[[0-9a-f]{2}\]$/

• translates to the QCLASS field of the single QUESTION record in the PDU;
• the client MUST specify it, else the 400 HTTP status code MUST be returned;
• the client MUST use only those values that are allowed for the designated operation (see the operation query argument), else the 400 HTTP status code MUST be returned; (for example in case of QUERY operations, the allowed values are those in CLASS, or QCLASS categories);
• see [RFC-1034], [RFC-1035], [RFC-6195], and [IANA-dns-parameters];

type

<type> ::= `*` | `ALL` | `A` | ... |  /^[A-Z0-9]([A-Z0-9-]+[A-Z0-9-])?$/ | /^\[[0-9a-f]{2}\]$/

• translates to the QTYPE field of the single QUESTION record in the PDU;
• the client MUST specify it, else the 400 HTTP status code MUST be returned;
• the client MUST use only those values that are allowed for the designated operation (see the operation query argument), else the 400 HTTP status code MUST be returned; (for example in case of QUERY operations, the allowed values are those in TYPE, or QTYPE categories);
• see [RFC-1034], [RFC-1035], [RFC-6195], and [IANA-dns-parameters];

name and label

<name> ::= <preferred-name> | <arbitrary-name>

<preferred-name> ::= ( <preferred-label> <label-separator> )+
<preferred-label> ::= `*` | /^[a-z0-9_]([a-z0-9_-]+[a-z0-9])?$/

<arbitrary-name> ::= ( <arbitrary-label> <label-separator> )+
<arbitrary-label> ::= `*` | /^([a-z0-9_-]+|\[[0-9a-f]{2}+\])+$/

<label-separator> ::= `/`

• translates to the QNAME field of the single QUESTION record in the PDU;
• the client MUST specify it, else the 400 HTTP status code MUST be returned;
• each individual decoded label MUST NOT be longer than 63 bytes (excluding the length byte), else the 414 HTTP status code must be returned;
• the entire decoded name MUST NOT be longer than 255 bytes (including the length bytes), else the 414 HTTP status code must be returned;
• the client SHOULD use only those values that match the DNS preferred name syntax (the <preferred-name> non-terminal); however it MAY use the alternative escaping syntax (the <arbitrary-name> non-terminal);
• the order of the labels is reversed than in DNS; that is the TLD is at the left;
• see also the discussion in the observations section below;
• see [RFC-1034], [RFC-1035], and [RFC-6195];

query-operation

<query-operation> ::= `QUERY` | <positive-16bit-integer>

• translates to the OPCODE field in the PDU header;
• the client SHOULD specify it, else the value QUERY MUST be assumed by the server;
• the client MUST use only those values that designate query-like operations, as described in the introduction of this section, else the 405 HTTP status code must be returned;
• see [RFC-1034], [RFC-1035], [RFC-6195], and [IANA-dns-parameters];

forward

<forward> = `forward=` ( <ip-address> | <fqdn> )

• not specified by any of the DNS standards, nor existing RFC's;
• the client MAY specify it, to indicate to the server that it MUST not execute the operation itself, instead it MUST act as a DNS forwarder, constructing the PDU and sending it to the target server; thus the forwarding MUST be done via the DNS protocol; however the server MAY refuse to allow the forwarding, in which case the 401, or 403 HTTP status code must be returned;

recursive

<recursive> ::= <boolean>

• translates to the RD flag in the PDU header;
• the client SHOULD specify it, else the value true MUST be assumed by the server;
• see [RFC-1034], [RFC-1035], [RFC-6195];

data-encoding

<data-encoding> ::= ( `json` ( `-` | `,` ) )? ( `base64` | `txt` )

• not specified by any of the DNS standards, nor existing RFC's;
• the client SHOULD specify it, else the value json-txt MUST be assumed by the server;
• it specifies the representation in which the various record data should be returned; for example:
  • json-txt implies the JSON representation described in this document, except for the unknown record types, for which the textual representation must be used;
  • json-base64 implies JSON as above, else the Base64 encoding;
  • txt implies only the textual representation, regardless of the record type;
  • json,base64 implies JSON, and also the Base64 encoding;
• see also the discussion in the observations section below;

Observations:

label case sensitivity

According to [RFC-1034] (section 3.1), although the label comparisons is done in a case insensitive manner, the transmission or storage should preserve the original casing. However in the context of this document, labels MUST respect the given syntax, which forbids the usage of upper case letters; but it also implies that arbitrary bytes MAY be encoded through the [xx..] syntax.

root label

According to [RFC-1034] (section 3.1), all names must end in the with the special root label (i.e. the empty label). However in the context of this document the root label is implied, thus it MUST not to be specified.

The rationale is that, by allowing empty labels, it would lead to awkward looking URL's --- such as /v1/rr/IN//com/example/A (note the double //) --- which would trigger suspicions, or even mangling, in many HTTP clients, servers, and proxies.

However when names are represented as strings (see the <name> non-terminal), it MUST be ended in a dot --- such as example.com..

preferred label syntax

According to [RFC-1034] (section 3.5), the preferred syntax of a label is, as a regular expression, ^[a-zA-Z]([a-zA-Z0-9-]*[a-zA-Z0-9])?$. However many DNS extensions --- such as ??? --- tend to include the underscore _ as a prefix to the label; thus this document allows some of these characters in a label, especially as they do not result in an invalid URL.

reversed label order

...

absolute and relative names

this document mandates that only absolute names MUST be used. This is also a constraint of the fact that the root label can not be expressed in URL's, as discussed above.

forwarding

...

Examples:

• /v1/rr/IN/com/example/www/A?recursive=true&data-encoding=json-txt;
• /v1/rr/IN/com/example/www/ALL?forward=8.8.8.8&recursive=false;
• /v1/rr/ANY/com/example/www/A;
• /v1/rr/ANY/com/example/www/ALL;

Request headers

See the Operation headers section.

Response status codes

See the Operation status codes section.

Response headers

See the Operation headers section.

Response body syntax

See the Response JSON encoding section.

1.7.3.2   Updating via POST requests

The HTTP transactions described in this section, MUST only be used for DNS operations that:

• MUST have an update semantic in the DNS sense; for example the UPDATE operation as described by [RFC-2136];
• MUST map perfectly over the UPDATE PDU; that is the operation MUST have the same flags, fields, and other structural elements, including having the same formal designation and semantic, as those described in [RFC-2136] for the UPDATE operation;

Informally, these POST transactions MUST only be used for DNS updates, or future update-like operations described in later RFC's, that are syntactically backward compatible.

Moreover, these POST transactions MUST only be used for DNS updates that require exactly one zone record. This is due to the fact that the ZNAME, ZCLASS, and ZTYPE PDU fields are obtained from the URL of the GET request.

These HTTP transactions SHOULD be implemented by any client or server that wants to be compliant with this document. However any server that does not implement these operations, upon receiving such a request MUST:

• return the 405 HTTP status code;
• return a proper body; that is an update failure response body, containing the NOTIMP value as the code attribute, among the other appropriate attributes;

URL syntax

<update-url> ::=
     <rr-rest-url> ( `?` <update-url-arguments> )?

<update-url-arguments> ::=
    (
        ( `operation=` <update-operation> `&` )?
        ( `forward=` <forward>` `&` )?
        ( `data-encoding=` <data-encoding> )?
    )

Where:

class

• abides by the same rules as described in the Querying via GET requests section;
• translates to the ZCLASS field of the single ZONE record in the PDU;
• the client MUST specify it, else the 400 HTTP status code MUST be returned;
• the client MUST use only those values that are allowed for the designated operation (see the operation query argument), else the 400 HTTP status code MUST be returned; (for example in case of UPDATE operations, the allowed value is IN);
• see [RFC-2136], [RFC-6195], and [IANA-dns-parameters];

type

• abides by the same rules as described in the Querying via GET requests section;
• translates to the ZCLASS field of the single ZONE record in the PDU;
• the client MUST specify it, else the 400 HTTP status code MUST be returned;
• the client MUST use only those values that are allowed for the designated operation (see the operation query argument), else the 400 HTTP status code MUST be returned; (for example in case of UPDATE operations, the allowed value is IN);
• see [RFC-2136], [RFC-6195], and [IANA-dns-parameters];

name

• abides by the same rules as described in the Querying via GET requests section;
• translates to the ZNAME field of the single ZONE record in the PDU;
• see [RFC-2136], and [RFC-6195];

update-operation

<update-operation> ::= `UPDATE` | <positive-16bit-integer>

• translates to the OPCODE field in the PDU header;
• the client SHOULD specify it, else the value UPDATE MUST be assumed by the server;
• the client MUST use only those values that designate update-like operations, as described in the introduction of this section, else the 405 HTTP status code must be returned;
• see [RFC-2136], [RFC-6195], and [IANA-dns-parameters];

forward, and data-encoding

MUST abide by the same rules as described in the Querying via GET requests section.

Observations:

non IN class, or non SOA type, for the UPDATE operation

The DNS specification [RFC-2136] mandates that in case of the UPDATE operation, only the IN class, and respectively the SOA type, must be used for the single zone record. Therefore clients SHOULD abide by this rule.

However the servers SHOULD accept different values, even for the UPDATE operation, and either:

• it MUST reply back with a 405 HTTP status code and a code of NOTIMP, if such a situation is not allowed;
• it MUST create the PDU containing all the records, forward it to the DNS server, and depending on the RCODE field in the response PDU, it should translate it to a proper HTTP status code, as discussed in the sections Querying via GET requests or Updating via POST requests;

Examples:

• /v1/rr/IN/com/example/SOA?data-encoding=json-txt;
• /v1/rr/IN/com/example/SOA?forward=8.8.8.8;
• /v1/rr/IN/com/example/SOA;

Request headers

...

Request body syntax

<update-request-body> ::= {
    "prerequisites" : [ <prerequisite>, ... ] | null | undefined,
    "updates" : [ <update>, ... ] | null | undefined,
    "additional" : [ <record>, ... ] | null | undefined,
}

<prerequisite> ::=
    | <exists>
    | <matches>

Where:

exists

<exists> ::= {
    "condition" : "record-exists",
    "name": <name>,
    "type" : <exists-type>,
    "expected" : <boolean>,
}

<exists-type> ::= ...

exists

<matches> ::= {
    "condition" : "record-matches",
    "name" : <name>,
    "type" : <type>,
    "data" : [ <data> | null, ... ] | null | undefined,
    "data:base64" : [ <data-base64> | null, ... ] | null | undefined,
    "data:txt" : [ <data-txt> | null, ... ] | null | undefined,
}

update

<update> ::=
    | <include>
    | <exclude>

include

<include> ::= {
    "action" : "record-include",
    "name" : <name>,
    "type" : <type>,
    "data" : [ <data> | null, ... ] | null | undefined,
    "data:base64" : [ <data-base64> | null, ... ] | null | undefined,
    "data:txt" : [ <data-txt> | null, ... ] | null | undefined,
    "ttl" : <ttl>,
}

exclude

<exclude> ::= {
    "action" : "record-exclude",
    "name" : <name>,
    "type" : <exclude-type> | null,
    "data" : [ <data> | null, ... ] | null | undefined,
    "data:base64" : [ <data-base64> | null, ... ] | null | undefined,
    "data:txt" : [ <data-txt> | null, ... ] | null | undefined,
}

<exclude-type> ::= ...

Response status codes

See the Operation status codes section.

Response headers

See the Operation headers section.

Response body syntax

See the Response JSON encoding section.

1.7.3.3   Operations via POST requests

...

These HTTP transactions SHOULD be implemented by any client or server that wants to be compliant with this document. However any server that does not implement these operations, upon receiving such a request MUST:

• return the 405 HTTP status code;
• return a proper body; that is, depending on the operation, either a query, or an update failure response body, containing the NOTIMP value as the code attribute, among the other appropriate attributes;

URL syntax

<operation-url> ::= <rr-rpc-url> ( `?` <operation-url-arguments> )?

<operation-url-arguments> ::=
    (
        ( `forward=` <forward> `&` )?
        ( `data-encoding=` <data-encoding> )?
    )

Where:

forward, and data-encoding

MUST abide by the same rules as described in the Querying via GET requests section.

Observations:

mapping of other query arguments

Although both query and update operations can be requested via this mechanism, all other URL path components or query arguments are mapped to attributes inside the request body.

Request headers

See the Operation headers section.

Request body syntax

<operation-request-body> ::= {
    "operation" : <operation>,
    @<operation-specific-request-body>
}

<operation-specific-request-body> ::=
    | <query-request-body>
    | <update-request-body>
    | <any-request-body>

Where:

operation

<operation> ::= "QUERY" | "UPDATE" | <positive-16bit-integer>

• translates to the OPCODE field in the PDU header;
• the client MUST specify it, else the 400 HTTP status code must be returned;
• the client MAY specify any possible symbolic or numeric value, constrained to the given syntax; however if the server does not implement, or known, the operation, the 405 HTTP status code and a proper body must be returned;
• see [RFC-1034], [RFC-1035], [RFC-6195], and [IANA-dns-parameters];

query-request-body

<query-request-body> ::= {
    "questions" : [ <question-record>, ... ],
    "additional" : [ <record>, ... ] | null | undefined,
    "recursive" : <boolean> | null | undefined,
}

<question-record> ::= {
    "class" : <class>,
    "name" : <name>,
    "type" : <type>,
}

• this body syntax MUST be used for the QUERY operation;
• this body syntax SHOULD be used for any other query-like operation, as was discussed in the beginning of the Querying via GET requests section;
• the attribute recursive translates to the RD flag in the PDU; thus it abides by the same rules, pertaining to the recursive query argument, as described in the Querying via GET requests section;
• the attribute questions translates to:
  • the length to the QCOUNT field in the PDU header;
  • each of the elements to one QUESTION record in the PDU; with the attributes name, class, and type translating to the QNAME, QCLASS, and respectively QTYPE, fields of each QUESTION record;
• the class, and type attributes abide by the same rules, pertaining to the class, and respectively type URL segments, as described in the Querying via GET requests section;
• the name attribute abides by the same rules, pertaining to the name URL segment, as described in the Querying via GET requests section, with three exceptions:
  • the label separator is the dot character (.), instead of the slash character (/);
  • the order of the label is that of DNS; that is the TLD is at the right;
  • the root label appears in the name; that is there is a dot character (.) at the end;
• the client SHOULD use only one question record; see the discussion in the observations section below;

update-request-body

<record-update-request-body> ::= {
    "zones" : [ <zone-record>, ... ],
    "prerequisites" : [ <prerequisite>, ... ] | null | undefined,
    "updates" : [ <update>, ... ] | null | undefined,
    "additional" : [ <record>, ... ] | null | undefined,
}

<zone-record> ::= {
    "class" : <class>,
    "name" : <name>,
    "type" : <type>,
}

• this body syntax MUST be used for the UPDATE operation;
• this body syntax SHOULD be used for any other update-like operation, as was discussed in the beginning of the Updating via POST requests section;
• the attribute zones translates to the ZONES records in the PDU, in a similar manner as in the previous query-request-body case;
• the class, and type attributes abide by the same rules, pertaining to the class, and respectively type URL segments, as described in the Updating via POST requests section;
• the name attribute abides by the same rules, pertaining to the name URL segment, as described in the Updating via POST requests section, with the same exceptions as in the previous query-request-body case;
• the client SHOULD use only one zone record; see the discussion in the observations section below;

Observations:

multiple query questions, or multiple update zones

The DNS specifications [RFC-1034], [RFC-1035], [RFC-2136], [RFC-6195], allow for multiple query questions, or respectively update zones, to be sent, all existing DNS servers forbid it, and respond with various RCODE``s, either ``NOTIMP, or most likely FORMERR. Therefore clients SHOULD send only one such record.

However the servers SHOULD accept multiple such records, and either:

• it MUST reply back with a 405 HTTP status code and a code of NOTIMP, if such a situation is not allowed;
• it MUST create the PDU containing all the records, forward it to the DNS server, and depending on the RCODE field in the response PDU, it should translate it to a proper HTTP status code, as discussed in the sections Querying via GET requests or Updating via POST requests;

Response status codes

See the Operation status codes section.

Response headers

See the Operation headers section.

Response body syntax

See the Response JSON encoding section.