draft-ietf-doh-dns-over-https-10.txt   draft-ietf-doh-dns-over-https-11.txt 
Network Working Group P. Hoffman Network Working Group P. Hoffman
Internet-Draft ICANN Internet-Draft ICANN
Intended status: Standards Track P. McManus Intended status: Standards Track P. McManus
Expires: December 3, 2018 Mozilla Expires: December 17, 2018 Mozilla
June 01, 2018 June 15, 2018
DNS Queries over HTTPS (DOH) DNS Queries over HTTPS (DoH)
draft-ietf-doh-dns-over-https-10 draft-ietf-doh-dns-over-https-11
Abstract Abstract
This document describes how to make DNS queries over HTTPS. This document describes how to make DNS queries over HTTPS.
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on December 3, 2018. This Internet-Draft will expire on December 17, 2018.
Copyright Notice Copyright Notice
Copyright (c) 2018 IETF Trust and the persons identified as the Copyright (c) 2018 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 11 skipping to change at page 2, line 11
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3
3. Protocol Requirements . . . . . . . . . . . . . . . . . . . . 3 3. Protocol Requirements . . . . . . . . . . . . . . . . . . . . 3
3.1. Non-requirements . . . . . . . . . . . . . . . . . . . . 4 3.1. Non-requirements . . . . . . . . . . . . . . . . . . . . 4
4. Selection of DNS API Server . . . . . . . . . . . . . . . . . 4 4. Selection of DoH Server . . . . . . . . . . . . . . . . . . . 4
5. The HTTP Exchange . . . . . . . . . . . . . . . . . . . . . . 4 5. The HTTP Exchange . . . . . . . . . . . . . . . . . . . . . . 4
5.1. The HTTP Request . . . . . . . . . . . . . . . . . . . . 4 5.1. The HTTP Request . . . . . . . . . . . . . . . . . . . . 4
5.1.1. HTTP Request Examples . . . . . . . . . . . . . . . . 5 5.1.1. HTTP Request Examples . . . . . . . . . . . . . . . . 5
5.2. The HTTP Response . . . . . . . . . . . . . . . . . . . . 7 5.2. The HTTP Response . . . . . . . . . . . . . . . . . . . . 7
5.2.1. HTTP Response Example . . . . . . . . . . . . . . . . 7 5.2.1. Handling DNS and HTTP Errors . . . . . . . . . . . . 7
5.2.2. HTTP Response Example . . . . . . . . . . . . . . . . 7
6. HTTP Integration . . . . . . . . . . . . . . . . . . . . . . 8 6. HTTP Integration . . . . . . . . . . . . . . . . . . . . . . 8
6.1. Cache Interaction . . . . . . . . . . . . . . . . . . . . 8 6.1. Cache Interaction . . . . . . . . . . . . . . . . . . . . 8
6.2. HTTP/2 . . . . . . . . . . . . . . . . . . . . . . . . . 10 6.2. HTTP/2 . . . . . . . . . . . . . . . . . . . . . . . . . 10
6.3. Server Push . . . . . . . . . . . . . . . . . . . . . . . 10 6.3. Server Push . . . . . . . . . . . . . . . . . . . . . . . 10
6.4. Content Negotiation . . . . . . . . . . . . . . . . . . . 10 6.4. Content Negotiation . . . . . . . . . . . . . . . . . . . 10
7. DNS Wire Format . . . . . . . . . . . . . . . . . . . . . . . 10 7. Definition of the application/dns-message media type . . . . 10
8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11
8.1. Registration of application/dns-message Media Type . . . 11 8.1. Registration of application/dns-message Media Type . . . 11
9. Security Considerations . . . . . . . . . . . . . . . . . . . 13 9. Security Considerations . . . . . . . . . . . . . . . . . . . 13
10. Operational Considerations . . . . . . . . . . . . . . . . . 13 10. Operational Considerations . . . . . . . . . . . . . . . . . 13
11. References . . . . . . . . . . . . . . . . . . . . . . . . . 15 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 15
11.1. Normative References . . . . . . . . . . . . . . . . . . 15 11.1. Normative References . . . . . . . . . . . . . . . . . . 15
11.2. Informative References . . . . . . . . . . . . . . . . . 16 11.2. Informative References . . . . . . . . . . . . . . . . . 16
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 17 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 17
Previous Work on DNS over HTTP or in Other Formats . . . . . . . 18 Previous Work on DNS over HTTP or in Other Formats . . . . . . . 18
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 18 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 18
skipping to change at page 3, line 17 skipping to change at page 3, line 21
interfering with DNS operations and allowing web applications to interfering with DNS operations and allowing web applications to
access DNS information via existing browser APIs in a safe way access DNS information via existing browser APIs in a safe way
consistent with Cross Origin Resource Sharing (CORS) [CORS]. No consistent with Cross Origin Resource Sharing (CORS) [CORS]. No
special effort has been taken to enable or prevent application to special effort has been taken to enable or prevent application to
other use cases. This document focuses on communication between DNS other use cases. This document focuses on communication between DNS
clients (such as operating system stub resolvers) and recursive clients (such as operating system stub resolvers) and recursive
resolvers. resolvers.
2. Terminology 2. Terminology
A server that supports this protocol is called a "DNS API server" to A server that supports this protocol is called a "DoH server" to
differentiate it from a "DNS server" (one that only provides DNS differentiate it from a "DNS server" (one that only provides DNS
service over one or more of the other transport protocols service over one or more of the other transport protocols
standardized for DNS). Similarly, a client that supports this standardized for DNS). Similarly, a client that supports this
protocol is called a "DNS API client". protocol is called a "DoH client".
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP "OPTIONAL" in this document are to be interpreted as described in BCP
14 [RFC2119] [RFC8174] when, and only when, they appear in all 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here. capitals, as shown here.
3. Protocol Requirements 3. Protocol Requirements
[[ RFC Editor: Please remove this entire section before publication. [[ RFC Editor: Please remove this entire section before publication.
skipping to change at page 4, line 17 skipping to change at page 4, line 21
3.1. Non-requirements 3.1. Non-requirements
o Supporting network-specific DNS64 [RFC6147] o Supporting network-specific DNS64 [RFC6147]
o Supporting other network-specific inferences from plaintext DNS o Supporting other network-specific inferences from plaintext DNS
queries queries
o Supporting insecure HTTP o Supporting insecure HTTP
4. Selection of DNS API Server 4. Selection of DoH Server
Configuration, discovery, and updating of the URI Template [RFC6570] Configuration, discovery, and updating of the URI Template [RFC6570]
(see Section 5.1) is done out of band from this protocol. Note that (see Section 5.1) is done out of band from this protocol. Note that
configuration might be manual (such as a user typing URI Templates in configuration might be manual (such as a user typing URI Templates in
a user interface for "options") or automatic (such as URI Templates a user interface for "options") or automatic (such as URI Templates
being supplied in responses from DHCP or similar protocols). DNS API being supplied in responses from DHCP or similar protocols). DoH
Servers MAY support more than one URI. This allows the different Servers MAY support more than one URI. This allows the different
endpoints to have different properties such as different endpoints to have different properties such as different
authentication requirements or service level guarantees. authentication requirements or service level guarantees.
A DNS API client uses configuration to select the URI, and thus the A DoH client uses configuration to select the URI, and thus the DoH
DNS API server, that is to be used for resolution. [RFC2818] defines server, that is to be used for resolution. [RFC2818] defines how
how HTTPS verifies the DNS API server's identity. HTTPS verifies the DoH server's identity.
A DNS API client MUST NOT use a different URI simply because it was A DoH client MUST NOT use a different URI simply because it was
discovered outside of the client's configuration, or because a server discovered outside of the client's configuration, or because a server
offers an unsolicited response that appears to be a valid answer to a offers an unsolicited response that appears to be a valid answer to a
DNS query. This specification does not extend DNS resolution DNS query. This specification does not extend DNS resolution
privileges to URIs that are not recognized by the DNS API client as privileges to URIs that are not recognized by the DoH client as
configured URIs. Such scenarios may create additional operational, configured URIs. Such scenarios may create additional operational,
tracking, and security hazards that require limitations for safe tracking, and security hazards that require limitations for safe
usage. A future specification may support this use case. usage. A future specification may support this use case.
5. The HTTP Exchange 5. The HTTP Exchange
5.1. The HTTP Request 5.1. The HTTP Request
A DNS API client encodes a single DNS query into an HTTP request A DoH client encodes a single DNS query into an HTTP request using
using either the HTTP GET or POST method and the other requirements either the HTTP GET or POST method and the other requirements of this
of this section. The DNS API server defines the URI used by the section. The DoH server defines the URI used by the request through
request through the use of a URI Template. the use of a URI Template.
The URI Template defined in this document is processed without any The URI Template defined in this document is processed without any
variables when the HTTP method is POST. When the HTTP method is GET 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 the single variable "dns" is defined as the content of the DNS
request (as described in Section 7), encoded with base64url request (as described in Section 7), encoded with base64url
[RFC4648]. [RFC4648].
Future specifications for new media types MUST define the variables Future specifications for new media types MUST define the variables
used for URI Template processing with this protocol. used for URI Template processing with this protocol.
DNS API servers MUST implement both the POST and GET methods. DoH servers MUST implement both the POST and GET methods.
When using the POST method the DNS query is included as the message When using the POST method the DNS query is included as the message
body of the HTTP request and the Content-Type request header body of the HTTP request and the Content-Type request header
indicates the media type of the message. POST-ed requests are indicates the media type of the message. POST-ed requests are
smaller than their GET equivalents. smaller than their GET equivalents.
Using the GET method is friendlier to many HTTP cache Using the GET method is friendlier to many HTTP cache
implementations. implementations.
The DNS API client SHOULD include an HTTP "Accept" request header to The DoH client SHOULD include an HTTP "Accept" request header to
indicate what type of content can be understood in response. indicate what type of content can be understood in response.
Irrespective of the value of the Accept request header, the client Irrespective of the value of the Accept request header, the client
MUST be prepared to process "application/dns-message" (as described MUST be prepared to process "application/dns-message" (as described
in Section 7) responses but MAY also process any other type it in Section 7) responses but MAY also process any other type it
receives. receives.
In order to maximize cache friendliness, DNS API clients using media In order to maximize cache friendliness, DoH clients using media
formats that include DNS ID, such as application/dns-message, SHOULD formats that include DNS ID, such as application/dns-message, SHOULD
use a DNS ID of 0 in every DNS request. HTTP correlates the request 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 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 such as application/dns-message. The use of a varying DNS ID can
cause semantically equivalent DNS queries to be cached separately. cause semantically equivalent DNS queries to be cached separately.
DNS API clients can use HTTP/2 padding and compression in the same DoH clients can use HTTP/2 padding and compression in the same way
way that other HTTP/2 clients use (or don't use) them. that other HTTP/2 clients use (or don't use) them.
5.1.1. HTTP Request Examples 5.1.1. HTTP Request Examples
These examples use HTTP/2 style formatting from [RFC7540]. These examples use HTTP/2 style formatting from [RFC7540].
These examples use a DNS API service with a URI Template of These examples use a DoH service with a URI Template of
"https://dnsserver.example.net/dns-query{?dns}" to resolve IN A "https://dnsserver.example.net/dns-query{?dns}" to resolve IN A
records. records.
The requests are represented as application/dns-message typed bodies. The requests are represented as application/dns-message typed bodies.
The first example request uses GET to request www.example.com The first example request uses GET to request www.example.com
:method = GET :method = GET
:scheme = https :scheme = https
:authority = dnsserver.example.net :authority = dnsserver.example.net
:path = /dns-query?dns=AAABAAABAAAAAAAAA3d3dwdleGFtcGxlA2NvbQAAAQAB :path = /dns-query?dns=AAABAAABAAAAAAAAA3d3dwdleGFtcGxlA2NvbQAAAQAB
skipping to change at page 7, line 7 skipping to change at page 7, line 7
:scheme = https :scheme = https
:authority = dnsserver.example.net :authority = dnsserver.example.net
:path = /dns-query? (no space or CR) :path = /dns-query? (no space or CR)
dns=AAABAAABAAAAAAAAAWE-NjJjaGFyYWN0ZXJsYWJl (no space or CR) dns=AAABAAABAAAAAAAAAWE-NjJjaGFyYWN0ZXJsYWJl (no space or CR)
bC1tYWtlcy1iYXNlNjR1cmwtZGlzdGluY3QtZnJvbS1z (no space or CR) bC1tYWtlcy1iYXNlNjR1cmwtZGlzdGluY3QtZnJvbS1z (no space or CR)
dGFuZGFyZC1iYXNlNjQHZXhhbXBsZQNjb20AAAEAAQ dGFuZGFyZC1iYXNlNjQHZXhhbXBsZQNjb20AAAEAAQ
accept = application/dns-message accept = application/dns-message
5.2. The HTTP Response 5.2. The HTTP Response
An HTTP response with a 2xx status code ([RFC7231] Section 6.3)
indicates a valid DNS response to the query made in the HTTP request.
A valid DNS response includes both success and failure responses.
For example, a DNS failure response such as SERVFAIL or NXDOMAIN will
be the message in a successful 2xx HTTP response even though there
was a failure at the DNS layer. Responses with non-successful HTTP
status codes do not contain DNS answers to the question in the
corresponding request. Some of these non-successful HTTP responses
(e.g., redirects or authentication failures) could mean that clients
need to make new requests to satisfy the original question.
Different response media types will provide more or less information
from a DNS response. For example, one response type might include
the information from the DNS header bytes while another might omit
it. The amount and type of information that a media type gives is
solely up to the format, and not defined in this protocol.
The only response type defined in this document is "application/dns- The only response type defined in this document is "application/dns-
message", but it is possible that other response formats will be message", but it is possible that other response formats will be
defined in the future. defined in the future. A DoH server MUST be able to process
application/dns-message request messages.
The DNS response for "application/dns-message" in Section 7 MAY have Different response media types will provide more or less information
one or more EDNS options [RFC6891], depending on the extension from a DNS response. For example, one response type might include
definition of the extensions given in the DNS request. information from the DNS header bytes while another might omit it.
The amount and type of information that a media type gives is solely
up to the format, and not defined in this protocol.
Each DNS request-response pair is matched to one HTTP exchange. The Each DNS request-response pair is matched to one HTTP exchange. The
responses may be processed and transported in any order using HTTP's responses may be processed and transported in any order using HTTP's
multi-streaming functionality ([RFC7540] Section 5). multi-streaming functionality ([RFC7540] Section 5).
Section 6.1 discusses the relationship between DNS and HTTP response Section 6.1 discusses the relationship between DNS and HTTP response
caching. caching.
A DNS API server MUST be able to process application/dns-message 5.2.1. Handling DNS and HTTP Errors
request messages.
A DNS API server SHOULD respond with HTTP status code 415 DNS response codes indicate either success or failure for the DNS
(Unsupported Media Type) upon receiving a media type it is unable to query. A successful HTTP response with a 2xx status code ([RFC7231]
process. Section 6.3) can be 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.
5.2.1. HTTP Response Example 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
authorization failures (HTTP status code 401 [RFC7235] Section 3.1).
It could also mean that the DoH client retries with a different DoH
server, such as for unsupported media types (HTTP status code 415,
[RFC7231] Section 6.5.13), or where the server cannot generate a
representation suitable for the client (HTTP status code 406,
[RFC7231] Section 6.5.6), and so on.
5.2.2. HTTP Response Example
This is an example response for a query for the IN A records for This is an example response for a query for the IN A records for
"www.example.com" with recursion turned on. The response bears one "www.example.com" with recursion turned on. The response bears one
record with an address of 192.0.2.1 and a TTL of 128 seconds. record with an address of 192.0.2.1 and a TTL of 128 seconds.
:status = 200 :status = 200
content-type = application/dns-message content-type = application/dns-message
content-length = 64 content-length = 64
cache-control = max-age=128 cache-control = max-age=128
skipping to change at page 8, line 22 skipping to change at page 8, line 22
07 65 78 61 6d 70 6c 65 03 63 6f 6d 00 00 01 00 07 65 78 61 6d 70 6c 65 03 63 6f 6d 00 00 01 00
01 03 77 77 77 07 65 78 61 6d 70 6c 65 03 63 6f 01 03 77 77 77 07 65 78 61 6d 70 6c 65 03 63 6f
6d 00 00 01 00 01 00 00 00 80 00 04 C0 00 02 01 6d 00 00 01 00 01 00 00 00 80 00 04 C0 00 02 01
6. HTTP Integration 6. HTTP Integration
This protocol MUST be used with the https scheme URI [RFC7230]. This protocol MUST be used with the https scheme URI [RFC7230].
6.1. Cache Interaction 6.1. Cache Interaction
A DOH exchange can pass through a hierarchy of caches that include A DoH exchange can pass through a hierarchy of caches that include
both HTTP and DNS specific caches. These caches may exist beteen the both HTTP and DNS specific caches. These caches may exist beteen the
DNS API server and client, or on the DNS API client itself. HTTP DoH server and client, or on the DoH client itself. HTTP caches are
caches are by design generic; that is, they do not understand this by design generic; that is, they do not understand this protocol.
protocol. Even if a DNS API client has modified its cache Even if a DoH client has modified its cache implementation to be
implementation to be aware of DOH semantics, it does not follow that aware of DoH semantics, it does not follow that all upstream caches
all upstream caches (for example, inline proxies, server-side (for example, inline proxies, server-side gateways and Content
gateways and Content Delivery Networks) will be. Delivery Networks) will be.
As a result, DNS API servers need to carefully consider the HTTP As a result, DoH servers need to carefully consider the HTTP caching
caching metadata they send in response to GET requests (POST requests metadata they send in response to GET requests (POST requests are not
are not cacheable unless specific response headers are sent; this is cacheable unless specific response headers are sent; this is not
not widely implemented, and not advised for DOH). widely implemented, and not advised for DoH).
In particular, DNS API servers SHOULD assign an explicit freshness In particular, DoH servers SHOULD assign an explicit freshness
lifetime ([RFC7234] Section 4.2) so that the DNS API client is more lifetime ([RFC7234] Section 4.2) so that the DoH client is more
likely to use fresh DNS data. This requirement is due to HTTP caches likely to use fresh DNS data. This requirement is due to HTTP caches
being able to assign their own heuristic freshness (such as that being able to assign their own heuristic freshness (such as that
described in [RFC7234] Section 4.2.2), which would take control of described in [RFC7234] Section 4.2.2), which would take control of
the cache contents out of the hands of the DNS API server. the cache contents out of the hands of the DoH server.
The assigned freshness lifetime of a DOH HTTP response SHOULD be the The assigned freshness lifetime of a DoH HTTP response SHOULD be the
smallest TTL in the Answer section of the DNS response. For example, smallest TTL in the Answer section of the DNS response. For example,
if a HTTP response carries three RRsets with TTLs of 30, 600, and if a HTTP response carries three RRsets with TTLs of 30, 600, and
300, the HTTP freshness lifetime should be 30 seconds (which could be 300, the HTTP freshness lifetime should be 30 seconds (which could be
specified as "Cache-Control: max-age=30"). The assigned freshness specified as "Cache-Control: max-age=30"). The assigned freshness
lifetime MUST NOT be greater than the smallest TTL in the Answer lifetime MUST NOT be greater than the smallest TTL in the Answer
section of the DNS response. This requirement helps assure that none section of the DNS response. This requirement helps assure that none
of the RRsets contained in a DNS response are served stale from an of the RRsets contained in a DNS response are served stale from an
HTTP cache. HTTP cache.
If the DNS response has no records in the Answer section, and the DNS If the DNS response has no records in the Answer section, and the DNS
response has an SOA record in the Authority section, the response response has an SOA record in the Authority section, the response
freshness lifetime MUST NOT be greater than the MINIMUM field from freshness lifetime MUST NOT be greater than the MINIMUM field from
that SOA record (see [RFC2308]). that SOA record (see [RFC2308]).
The stale-while-revalidate and stale-if-error Cache-Control The stale-while-revalidate and stale-if-error Cache-Control
directives ([RFC5861]) could be well suited to a DOH implementation directives ([RFC5861]) could be well suited to a DoH implementation
when allowed by server policy. Those mechanisms allow a client, at when allowed by server policy. Those mechanisms allow a client, at
the server's discretion, to reuse a cache entry that is no longer the server's discretion, to reuse a cache entry that is no longer
fresh. In such a case, the client reuses all of a cached entry, or fresh. In such a case, the client reuses all of a cached entry, or
none of it. none of it.
DNS API servers also need to consider caching when generating DoH servers also need to consider caching when generating responses
responses that are not globally valid. For instance, if a DNS API that are not globally valid. For instance, if a DoH server
server customizes a response based on the client's identity, it would customizes a response based on the client's identity, it would not
not want to allow global reuse of that response. This could be want to allow global reuse of that response. This could be
accomplished through a variety of HTTP techniques such as a Cache- accomplished through a variety of HTTP techniques such as a Cache-
Control max-age of 0, or by using the Vary response header ([RFC7231] Control max-age of 0, or by using the Vary response header ([RFC7231]
Section 7.1.4) to establish a secondary cache key ([RFC7234] Section 7.1.4) to establish a secondary cache key ([RFC7234]
Section 4.1). Section 4.1).
DNS API clients MUST account for the Age response header's value DoH clients MUST account for the Age response header's value
([RFC7234]) when calculating the DNS TTL of a response. For example, ([RFC7234]) when calculating the DNS TTL of a response. For example,
if a RRset is received with a DNS TTL of 600, but the Age header if a RRset is received with a DNS TTL of 600, but the Age header
indicates that the response has been cached for 250 seconds, the indicates that the response has been cached for 250 seconds, the
remaining lifetime of the RRset is 350 seconds. remaining lifetime of the RRset is 350 seconds.
DNS API clients can request an uncached copy of a response by using DoH clients can request an uncached copy of a response by using the
the "no-cache" request cache control directive ([RFC7234], "no-cache" request cache control directive ([RFC7234],
Section 5.2.1.4) and similar controls. Note that some caches might Section 5.2.1.4) and similar controls. Note that some caches might
not honor these directives, either due to configuration or not honor these directives, either due to configuration or
interaction with traditional DNS caches that do not have such a interaction with traditional DNS caches that do not have such a
mechanism. mechanism.
HTTP conditional requests ([RFC7232]) may be of limited value to DOH, HTTP conditional requests ([RFC7232]) may be of limited value to DoH,
as revalidation provides only a bandwidth benefit and DNS as revalidation provides only a bandwidth benefit and DNS
transactions are normally latency bound. Furthermore, the HTTP transactions are normally latency bound. Furthermore, the HTTP
response headers that enable revalidation (such as "Last-Modified" response headers that enable revalidation (such as "Last-Modified"
and "Etag") are often fairly large when compared to the overall DNS and "Etag") are often fairly large when compared to the overall DNS
response size, and have a variable nature that creates constant response size, and have a variable nature that creates constant
pressure on the HTTP/2 compression dictionary [RFC7541]. Other types pressure on the HTTP/2 compression dictionary [RFC7541]. Other types
of DNS data, such as zone transfers, may be larger and benefit more of DNS data, such as zone transfers, may be larger and benefit more
from revalidation. from revalidation.
6.2. HTTP/2 6.2. HTTP/2
HTTP/2 [RFC7540] is the minimum RECOMMENDED version of HTTP for use HTTP/2 [RFC7540] is the minimum RECOMMENDED version of HTTP for use
with DOH. with DoH.
The messages in classic UDP based DNS [RFC1035] are inherently The messages in classic UDP based DNS [RFC1035] are inherently
unordered and have low overhead. A competitive HTTP transport needs unordered and have low overhead. A competitive HTTP transport needs
to support reordering, parallelism, priority, and header compression to support reordering, parallelism, priority, and header compression
to achieve similar performance. Those features were introduced to to achieve similar performance. Those features were introduced to
HTTP in HTTP/2 [RFC7540]. Earlier versions of HTTP are capable of HTTP in HTTP/2 [RFC7540]. Earlier versions of HTTP are capable of
conveying the semantic requirements of DOH but may result in very conveying the semantic requirements of DoH but may result in very
poor performance. poor performance.
6.3. Server Push 6.3. Server Push
Before using DOH response data for DNS resolution, the client MUST Before using DoH response data for DNS resolution, the client MUST
establish that the HTTP request URI may be used for the DOH query. establish that the HTTP request URI may be used for the DoH query.
For HTTP requests initiated by the DNS API client this is implicit in For HTTP requests initiated by the DoH client this is implicit in the
the selection of URI. For HTTP server push ([RFC7540] Section 8.2) selection of URI. For HTTP server push ([RFC7540] Section 8.2) extra
extra care must be taken to ensure that the pushed URI is one that care must be taken to ensure that the pushed URI is one that the
the client would have directed the same query to if the client had client would have directed the same query to if the client had
initiated the request. initiated the request.
6.4. Content Negotiation 6.4. Content Negotiation
In order to maximize interoperability, DNS API clients and DNS API In order to maximize interoperability, DoH clients and DoH servers
servers MUST support the "application/dns-message" media type. Other MUST support the "application/dns-message" media type. Other media
media types MAY be used as defined by HTTP Content Negotiation types MAY be used as defined by HTTP Content Negotiation ([RFC7231]
([RFC7231] Section 3.4). Those media types MUST be flexible enough Section 3.4). Those media types MUST be flexible enough to express
to express every DNS query that would normally be sent in DNS over every DNS query that would normally be sent in DNS over UDP
UDP (including queries and responses that use DNS extensions, but not (including queries and responses that use DNS extensions, but not
those that require multiple responses). those that require multiple responses).
7. DNS Wire Format 7. Definition of the application/dns-message media type
The data payload is the DNS on-the-wire format defined in [RFC1035].
The format is for DNS over UDP. Note that this is different than the
wire format used in [RFC7858]. Also note that while [RFC1035] says
"Messages carried by UDP are restricted to 512 bytes", that was later
updated by [RFC6891]. This protocol allows DNS on-the-wire format
payloads of any size.
When using the GET method, the data payload MUST be encoded with The data payload for the application/dns-message media type is a
base64url [RFC4648] and then provided as a variable named "dns" to single message of the DNS on-the-wire format defined in section 4.2.1
the URI Template expansion. Padding characters for base64url MUST of [RFC1035]. The format was originally for DNS over UDP. Although
NOT be included. [RFC1035] says "Messages carried by UDP are restricted to 512 bytes",
that was later updated by [RFC6891]. This media type restricts the
maximum size of the DNS message to 65535 bytes. Note that the wire
format used in this media type is different than the wire format used
in [RFC7858] (which uses the format defined in section 4.2.2 of
[RFC1035]).
When using the POST method, the data payload MUST NOT be encoded and DoH clients using this media type MAY have one or more EDNS options
is used directly as the HTTP message body. [RFC6891] in the request. DoH servers using this media type MUST
ignore the value given for the EDNS UDP payload size in DNS requests.
DNS API clients using the DNS wire format MAY have one or more EDNS When using the GET method, the data payload for this media type MUST
options [RFC6891] in the request. be encoded with base64url [RFC4648] and then provided as a variable
named "dns" to the URI Template expansion. Padding characters for
base64url MUST NOT be included.
The media type is "application/dns-message". When using the POST method, the data payload for this media type MUST
NOT be encoded and is used directly as the HTTP message body.
8. IANA Considerations 8. IANA Considerations
8.1. Registration of application/dns-message Media Type 8.1. Registration of application/dns-message Media Type
To: ietf-types@iana.org To: ietf-types@iana.org
Subject: Registration of MIME media type Subject: Registration of MIME media type
application/dns-message application/dns-message
MIME media type name: application MIME media type name: application
skipping to change at page 13, line 16 skipping to change at page 13, line 16
Running DNS over HTTPS relies on the security of the underlying HTTP Running DNS over HTTPS relies on the security of the underlying HTTP
transport. This mitigates classic amplification attacks for UDP- transport. This mitigates classic amplification attacks for UDP-
based DNS. Implementations utilizing HTTP/2 benefit from the TLS based DNS. Implementations utilizing HTTP/2 benefit from the TLS
profile defined in [RFC7540] Section 9.2. profile defined in [RFC7540] Section 9.2.
Session level encryption has well known weaknesses with respect to Session level encryption has well known weaknesses with respect to
traffic analysis which might be particularly acute when dealing with traffic analysis which might be particularly acute when dealing with
DNS queries. HTTP/2 provides further advice about the use of DNS queries. HTTP/2 provides further advice about the use of
compression ([RFC7540] Section 10.6) and padding ([RFC7540] compression ([RFC7540] Section 10.6) and padding ([RFC7540]
Section 10.7 ). DNS API Servers can also add DNS padding [RFC7830] Section 10.7 ). DoH Servers can also add DNS padding [RFC7830] if
if the DNS API requests it in the DNS query. the DoH requests it in the DNS query.
The HTTPS connection provides transport security for the interaction The HTTPS connection provides transport security for the interaction
between the DNS API server and client, but does not provide the between the DoH server and client, but does not provide the response
response integrity of DNS data provided by DNSSEC. DNSSEC and DOH integrity of DNS data provided by DNSSEC. DNSSEC and DoH are
are independent and fully compatible protocols, each solving independent and fully compatible protocols, each solving different
different problems. The use of one does not diminish the need nor problems. The use of one does not diminish the need nor the
the usefulness of the other. It is the choice of a client to either usefulness of the other. It is the choice of a client to either
perform full DNSSEC validation of answers or to trust the DNS API perform full DNSSEC validation of answers or to trust the DoH server
server to do DNSSEC validation and inspect the AD (Authentic Data) to do DNSSEC validation and inspect the AD (Authentic Data) bit in
bit in the returned message to determine whether an answer was the returned message to determine whether an answer was authentic or
authentic or not. As noted in Section 5.2, different response media not. As noted in Section 5.2, different response media types will
types will provide more or less information from a DNS response so provide more or less information from a DNS response so this choice
this choice may be affected by the response media type. may be affected by the response media type.
Section 6.1 describes the interaction of this protocol with HTTP Section 6.1 describes the interaction of this protocol with HTTP
caching. An adversary that can control the cache used by the client caching. An adversary that can control the cache used by the client
can affect that client's view of the DNS. This is no different than can affect that client's view of the DNS. This is no different than
the security implications of HTTP caching for other protocols that the security implications of HTTP caching for other protocols that
use HTTP. use HTTP.
In the absence of DNSSEC information, a DNS API server can give a In the absence of DNSSEC information, a DoH server can give a client
client invalid data in response to a DNS query. Section 4 disallows invalid data in response to a DNS query. Section 4 disallows the use
the use of DOH DNS responses that do not originate from configured of DoH DNS responses that do not originate from configured servers.
servers. This prohibition does not guarantee protection against This prohibition does not guarantee protection against invalid data,
invalid data, but it does reduce the risk. but it does reduce the risk.
10. Operational Considerations 10. Operational Considerations
Local policy considerations and similar factors mean different DNS Local policy considerations and similar factors mean different DNS
servers may provide different results to the same query: for instance servers may provide different results to the same query: for instance
in split DNS configurations [RFC6950]. It logically follows that the in split DNS configurations [RFC6950]. It logically follows that the
server which is queried can influence the end result. Therefore a server which is queried can influence the end result. Therefore a
client's choice of DNS server may affect the responses it gets to its client's choice of DNS server may affect the responses it gets to its
queries. For example, in the case of DNS64 [RFC6147], the choice queries. For example, in the case of DNS64 [RFC6147], the choice
could affect whether IPv6/IPv4 translation will work at all. could affect whether IPv6/IPv4 translation will work at all.
The HTTPS channel used by this specification establishes secure two The HTTPS channel used by this specification establishes secure two
party communication between the DNS API client and the DNS API party communication between the DoH client and the DoH server.
server. Filtering or inspection systems that rely on unsecured Filtering or inspection systems that rely on unsecured transport of
transport of DNS will not function in a DNS over HTTPS environment. DNS will not function in a DNS over HTTPS environment.
Some HTTPS client implementations perform real time third party Some HTTPS client implementations perform real time third party
checks of the revocation status of the certificates being used by checks of the revocation status of the certificates being used by
TLS. If this check is done as part of the DNS API server connection TLS. If this check is done as part of the DoH server connection
procedure and the check itself requires DNS resolution to connect to procedure and the check itself requires DNS resolution to connect to
the third party a deadlock can occur. The use of OCSP [RFC6960] the third party a deadlock can occur. The use of OCSP [RFC6960]
servers or AIA for CRL fetching ([RFC5280] Section 4.2.2.1) are servers or AIA for CRL fetching ([RFC5280] Section 4.2.2.1) are
examples of how this deadlock can happen. To mitigate the examples of how this deadlock can happen. To mitigate the
possibility of deadlock, DNS API servers SHOULD NOT rely on DNS based possibility of deadlock, DoH servers SHOULD NOT rely on DNS based
references to external resources in the TLS handshake. For OCSP the references to external resources in the TLS handshake. For OCSP the
server can bundle the certificate status as part of the handshake server can bundle the certificate status as part of the handshake
using a mechanism appropriate to the version of TLS, such as using using a mechanism appropriate to the version of TLS, such as using
[RFC6066] Section 8 for TLS version 1.2. AIA deadlocks can be [RFC6066] Section 8 for TLS version 1.2. AIA deadlocks can be
avoided by providing intermediate certificates that might otherwise avoided by providing intermediate certificates that might otherwise
be obtained through additional requests. Note that these deadlocks be obtained through additional requests. Note that these deadlocks
also need to be considered for server that a DNS API server might also need to be considered for server that a DoH server might
redirect to. redirect to.
A DNS API client may face a similar bootstrapping problem when the A DoH client may face a similar bootstrapping problem when the HTTP
HTTP request needs to resolve the hostname portion of the DNS URI. request needs to resolve the hostname portion of the DNS URI. Just
Just as the address of a traditional DNS nameserver cannot be as the address of a traditional DNS nameserver cannot be originally
originally determined from that same server, a DNS API client cannot determined from that same server, a DoH client cannot use its DoH
use its DNS API server to initially resolve the server's host name server to initially resolve the server's host name into an address.
into an address. Alternative strategies a client might employ Alternative strategies a client might employ include making the
include making the initial resolution part of the configuration, IP initial resolution part of the configuration, IP based URIs and
based URIs and corresponding IP based certificates for HTTPS, or corresponding IP based certificates for HTTPS, or resolving the DNS
resolving the DNS API server's hostname via traditional DNS or API server's hostname via traditional DNS or another DoH server while
another DNS API server while still authenticating the resulting still authenticating the resulting connection via HTTPS.
connection via HTTPS.
HTTP [RFC7230] is a stateless application level protocol and HTTP [RFC7230] is a stateless application level protocol and
therefore DOH implementations do not provide stateful ordering therefore DoH implementations do not provide stateful ordering
guarantees between different requests. DOH cannot be used as a guarantees between different requests. DoH cannot be used as a
transport for other protocols that require strict ordering. transport for other protocols that require strict ordering.
A DNS API server is allowed to answer queries with any valid DNS A DoH server is allowed to answer queries with any valid DNS
response. For example, a valid DNS response might have the TC response. For example, a valid DNS response might have the TC
(truncation) bit set in the DNS header to indicate that the server (truncation) bit set in the DNS header to indicate that the server
was not able to retrieve a full answer for the query but is providing was not able to retrieve a full answer for the query but is providing
the best answer it could get. A DNS API server can reply to queries the best answer it could get. A DoH server can reply to queries with
with an HTTP error for queries that it cannot fulfill. In this same an HTTP error for queries that it cannot fulfill. In this same
example, a DNS API server could use an HTTP error instead of a non- example, a DoH server could use an HTTP error instead of a non-error
error response that has the TC bit set. response that has the TC bit set.
Many extensions to DNS, using [RFC6891], have been defined over the Many extensions to DNS, using [RFC6891], have been defined over the
years. Extensions that are specific to the choice of transport, such years. Extensions that are specific to the choice of transport, such
as [RFC7828], are not applicable to DOH. as [RFC7828], are not applicable to DoH.
11. References 11. References
11.1. Normative References 11.1. Normative References
[RFC1035] Mockapetris, P., "Domain names - implementation and [RFC1035] Mockapetris, P., "Domain names - implementation and
specification", STD 13, RFC 1035, DOI 10.17487/RFC1035, specification", STD 13, RFC 1035, DOI 10.17487/RFC1035,
November 1987, <https://www.rfc-editor.org/info/rfc1035>. November 1987, <https://www.rfc-editor.org/info/rfc1035>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
skipping to change at page 16, line 15 skipping to change at page 16, line 15
[RFC7232] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer [RFC7232] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
Protocol (HTTP/1.1): Conditional Requests", RFC 7232, Protocol (HTTP/1.1): Conditional Requests", RFC 7232,
DOI 10.17487/RFC7232, June 2014, DOI 10.17487/RFC7232, June 2014,
<https://www.rfc-editor.org/info/rfc7232>. <https://www.rfc-editor.org/info/rfc7232>.
[RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, [RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching", Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching",
RFC 7234, DOI 10.17487/RFC7234, June 2014, RFC 7234, DOI 10.17487/RFC7234, June 2014,
<https://www.rfc-editor.org/info/rfc7234>. <https://www.rfc-editor.org/info/rfc7234>.
[RFC7235] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
Protocol (HTTP/1.1): Authentication", RFC 7235,
DOI 10.17487/RFC7235, June 2014,
<https://www.rfc-editor.org/info/rfc7235>.
[RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext [RFC7540] Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext
Transfer Protocol Version 2 (HTTP/2)", RFC 7540, Transfer Protocol Version 2 (HTTP/2)", RFC 7540,
DOI 10.17487/RFC7540, May 2015, DOI 10.17487/RFC7540, May 2015,
<https://www.rfc-editor.org/info/rfc7540>. <https://www.rfc-editor.org/info/rfc7540>.
[RFC7541] Peon, R. and H. Ruellan, "HPACK: Header Compression for [RFC7541] Peon, R. and H. Ruellan, "HPACK: Header Compression for
HTTP/2", RFC 7541, DOI 10.17487/RFC7541, May 2015, HTTP/2", RFC 7541, DOI 10.17487/RFC7541, May 2015,
<https://www.rfc-editor.org/info/rfc7541>. <https://www.rfc-editor.org/info/rfc7541>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
skipping to change at page 17, line 47 skipping to change at page 17, line 52
and P. Hoffman, "Specification for DNS over Transport and P. Hoffman, "Specification for DNS over Transport
Layer Security (TLS)", RFC 7858, DOI 10.17487/RFC7858, May Layer Security (TLS)", RFC 7858, DOI 10.17487/RFC7858, May
2016, <https://www.rfc-editor.org/info/rfc7858>. 2016, <https://www.rfc-editor.org/info/rfc7858>.
Acknowledgments Acknowledgments
This work required a high level of cooperation between experts in This work required a high level of cooperation between experts in
different technologies. Thank you Ray Bellis, Stephane Bortzmeyer, different technologies. Thank you Ray Bellis, Stephane Bortzmeyer,
Manu Bretelle, Sara Dickinson, Tony Finch, Daniel Kahn Gilmor, Olafur Manu Bretelle, Sara Dickinson, Tony Finch, Daniel Kahn Gilmor, Olafur
Guomundsson, Wes Hardaker, Rory Hewitt, Joe Hildebrand, David Guomundsson, Wes Hardaker, Rory Hewitt, Joe Hildebrand, David
Lawrence, Eliot Lear, John Mattson, Alex Mayrhofer, Mark Nottingham, Lawrence, Eliot Lear, John Mattsson, Alex Mayrhofer, Mark Nottingham,
Jim Reid, Adam Roach, Ben Schwartz, Davey Song, Daniel Stenberg, Jim Reid, Adam Roach, Ben Schwartz, Davey Song, Daniel Stenberg,
Andrew Sullivan, Martin Thomson, and Sam Weiler. Andrew Sullivan, Martin Thomson, and Sam Weiler.
Previous Work on DNS over HTTP or in Other Formats Previous Work on DNS over HTTP or in Other Formats
The following is an incomplete list of earlier work that related to The following is an incomplete list of earlier work that related to
DNS over HTTP/1 or representing DNS data in other formats. DNS over HTTP/1 or representing DNS data in other formats.
The list includes links to the tools.ietf.org site (because these The list includes links to the tools.ietf.org site (because these
documents are all expired) and web sites of software. documents are all expired) and web sites of software.
 End of changes. 59 change blocks. 
153 lines changed or deleted 160 lines changed or added

This html diff was produced by rfcdiff 1.46. The latest version is available from http://tools.ietf.org/tools/rfcdiff/