HTTP交换

4. The HTTP Exchange

4.1. The HTTP Request

A DoH client encodes a single DNS query into an HTTP request using either the HTTP GET or POST method and the other requirements of this section. The DoH server defines the URI used by the request through the use of a URI Template.

The URI Template defined in this document is processed without any variables when the HTTP method is POST. When the HTTP method is GET, the single variable "dns" is defined as the content of the DNS request (as described in Section 6), encoded with base64url [RFC4648].

Future specifications for new media types for DoH MUST define the variables used for URI Template processing with this protocol.

DoH servers MUST implement both the POST and GET methods.



When using the POST method, the DNS query is included as the message body of the HTTP request, and the Content-Type request header field indicates the media type of the message. POSTed requests are generally smaller than their GET equivalents.

Using the GET method is friendlier to many HTTP cache implementations.

The DoH client SHOULD include an HTTP Accept request header field to indicate what type of content can be understood in response. Irrespective of the value of the Accept request header field, the client MUST be prepared to process "application/dns-message" (as described in Section 6) responses but MAY also process other DNS- related media types it receives.

In order to maximize HTTP cache friendliness, DoH clients using media formats that include the ID field from the DNS message header, such as "application/dns-message", SHOULD use a DNS ID of 0 in every DNS request. HTTP correlates the request and response, thus eliminating the need for the ID in a media type such as "application/dns- message". The use of a varying DNS ID can cause semantically equivalent DNS queries to be cached separately.

DoH clients can use HTTP/2 padding and compression [RFC7540] in the same way that other HTTP/2 clients use (or don't use) them.

4.1.1. HTTP Request Examples

These examples use HTTP/2-style formatting from [RFC7540].

These examples use a DoH service with a URI Template of "https://dnsserver.example.net/dns-query\\\{?dns\\\}" to resolve IN A records.

The requests are represented as bodies with media type "application/ dns-message".

The first example request uses GET to request "www.example.com".

:method = GET :scheme = https :authority = dnsserver.example.net :path = /dns-query?dns=AAABAAABAAAAAAAAA3d3dwdleGFtcGxlA2NvbQAAAQAB accept = application/dns-message



The same DNS query for "www.example.com", using the POST method would be:

:method = POST :scheme = https :authority = dnsserver.example.net :path = /dns-query accept = application/dns-message content-type = application/dns-message content-length = 33

<33 bytes represented by the following hex encoding>
00 00 01 00 00 01 00 00  00 00 00 00 03 77 77 77
07 65 78 61 6d 70 6c 65  03 63 6f 6d 00 00 01 00
01

In this example, the 33 bytes are the DNS message in DNS wire format [RFC1035], starting with the DNS header.

Finally, a GET-based query for "a.62characterlabel-makes-base64url- distinct-from-standard-base64.example.com" is shown as an example to emphasize that the encoding alphabet of base64url is different than regular base64 and that padding is omitted.

The DNS query, expressed in DNS wire format, is 94 bytes represented by the following:

00 00 01 00 00 01 00 00 00 00 00 00 01 61 3e 36 32 63 68 61 72 61 63 74 65 72 6c 61 62 65 6c 2d 6d 61 6b 65 73 2d 62 61 73 65 36 34 75 72 6c 2d 64 69 73 74 69 6e 63 74 2d 66 72 6f 6d 2d 73 74 61 6e 64 61 72 64 2d 62 61 73 65 36 34 07 65 78 61 6d 70 6c 65 03 63 6f 6d 00 00 01 00 01

:method = GET :scheme = https :authority = dnsserver.example.net :path = /dns-query? (no space or Carriage Return (CR)) dns=AAABAAABAAAAAAAAAWE-NjJjaGFyYWN0ZXJsYWJl (no space or CR) bC1tYWtlcy1iYXNlNjR1cmwtZGlzdGluY3QtZnJvbS1z (no space or CR) dGFuZGFyZC1iYXNlNjQHZXhhbXBsZQNjb20AAAEAAQ accept = application/dns-message



4.2. The HTTP Response

The only response type defined in this document is "application/dns- message", but it is possible that other response formats will be defined in the future. A DoH server MUST be able to process "application/dns-message" request messages.

Different response media types will provide more or less information from a DNS response. For example, one response type might include information from the DNS header bytes while another might omit it. The amount and type of information that a media type gives are solely up to the format, which is not defined in this protocol.

Each DNS request-response pair is mapped to one HTTP exchange. The responses may be processed and transported in any order using HTTP's multi-streaming functionality (see Section 5 of [RFC7540]).

Section 5.1 discusses the relationship between DNS and HTTP response caching.

4.2.1. Handling DNS and HTTP Errors

DNS response codes indicate either success or failure for the DNS query. A successful HTTP response with a 2xx status code (see Section 6.3 of [RFC7231]) is used for any valid DNS response, regardless of the DNS response code. For example, a successful 2xx HTTP status code is used even with a DNS message whose DNS response code indicates failure, such as SERVFAIL or NXDOMAIN.

HTTP responses with non-successful HTTP status codes do not contain replies to the original DNS question in the HTTP request. DoH clients need to use the same semantic processing of non-successful HTTP status codes as other HTTP clients. This might mean that the DoH client retries the query with the same DoH server, such as if there are authorization failures (HTTP status code 401; see Section 3.1 of [RFC7235]). It could also mean that the DoH client retries with a different DoH server, such as for unsupported media types (HTTP status code 415; see Section 6.5.13 of [RFC7231]), or where the server cannot generate a representation suitable for the client (HTTP status code 406; see Section 6.5.6 of [RFC7231]), and so on.



4.2.2. HTTP Response Example

This is an example response for a query for the IN AAAA records for "www.example.com" with recursion turned on. The response bears one answer record with an address of 2001:db8🔡12:1:2:3:4 and a TTL of 3709 seconds.

:status = 200 content-type = application/dns-message content-length = 61 cache-control = max-age=3709

<61 bytes represented by the following hex encoding>
00 00 81 80 00 01 00 01  00 00 00 00 03 77 77 77
07 65 78 61 6d 70 6c 65  03 63 6f 6d 00 00 1c 00
01 c0 0c 00 1c 00 01 00  00 0e 7d 00 10 20 01 0d
b8 ab cd 00 12 00 01 00  02 00 03 00 04