DNS Queries over HTTPSICANNpaul.hoffman@icann.orgMozillapmcmanus@mozilla.com
Art
Internet-DraftThis document describes how to run DNS service over HTTP using
https:// URIs.[[ There is a repository for this draft at
https://github.com/dohwg/draft-ietf-doh-dns-over-https ]].The Internet does not always provide end to end reachability for
native DNS. On-path network devices may spoof DNS responses, block DNS
requests, or just redirect DNS queries to different DNS servers that
give less-than-honest answers. These are also sometimes delivered with poor
performance or reduced feature sets.Over time, there have been many proposals for using HTTP and HTTPS as
a substrate for DNS queries and responses. To date, none of those
proposals have made it beyond early discussion, partially due to
disagreement about what the appropriate formatting should be and
partially because they did not follow HTTP best practices.This document defines a specific protocol for sending DNS
queries and getting DNS responses over HTTP using https://
(and therefore TLS security for integrity and
confidentiality). Each DNS query-response pair is mapped into a HTTP
request-response pair.The described approach is more than a tunnel over HTTP. It establishes
default media formatting types for requests and responses but uses
normal HTTP content negotiation mechanisms for selecting alternatives
that endpoints may prefer in anticipation of serving new use cases. In
addition to this media type negotiation, it aligns itself with HTTP
features such as caching, redirection, proxying, authentication, and
compression.The integration with HTTP provides a transport suitable for both
traditional DNS clients and native web applications seeking access to
the DNS.Two primary uses cases were considered during this protocol’s
development. They included preventing on-path devices from interfering
with DNS operations and allowing web applications to access DNS
information via existing browser APIs in a safe way consistent with
Cross Origin Resource Sharing (CORS) . There are certainly
other uses for this work.A server that supports this protocol is called a “DNS API server” to
differentiate it from a “DNS server” (one that uses the regular DNS
protocol). Similarly, a client that supports this protocol is called a
“DNS API client”.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, RFC8174 when, and only when, they
appear in all capitals, as shown here.The protocol described here bases its design on the following protocol requirements:The protocol must use normal HTTP semantics.The queries and responses must be able to be flexible enough to express every normal
DNS query.The protocol must allow implementations to use HTTP’s content
negotiation mechanism.The protocol must ensure interoperable media formats through a
mandatory to implement format wherein a query must be able to
contain future modifications to the DNS protocol including the
inclusion of one or more EDNS extensions (including those not yet
defined).The protocol must use a secure transport that meets the
requirements for HTTPS.Supporting network-specific DNS64 Supporting other network-specific inferences from plaintext DNS queriesSupporting insecure HTTPSupporting legacy HTTP versionsTo make a DNS API query a DNS API 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 DNS API server defines the URI
used by the request. Configuration and discovery of the URI is done
out of band from this protocol.When using the POST method the DNS query is included as the message
body of the HTTP request and the Content-Type request header indicates
the media type of the message. POST-ed requests are smaller than their
GET equivalents.When using the GET method the URI path MUST contain a query parameter
name-value pair
with the name of “ct” and a value indicating the media-format used for
the dns parameter. The value may either be an explicit media type
(e.g. ct=application/dns-udpwireformat&dns=…) or it may be
empty. An empty value indicates the default
application/dns-udpwireformat type (e.g. ct&dns=…).When using the GET method the URI path MUST contain a query parameter
with the name of “dns”. The value of the parameter is the content of
the request potentially encoded with base64url
. Specifications that define media types for use with DOH,
such as DNS Wire Format of this document, MUST indicate if
the dns parameter uses base64url encoding.Using the GET method is friendlier to many HTTP cache implementations.The DNS API client SHOULD include an HTTP “Accept:” request header to
say what type of content can be understood in response. The client
MUST be prepared to process “application/dns-udpwireformat”
responses but MAY process any other type it receives.In order to maximize cache friendliness, DNS API clients using media
formats that include DNS ID, such as application/dns-udpwireformat,
SHOULD use a DNS ID of 0 in every DNS request. HTTP correlates
request and response, thus eliminating the need for the ID in a media
type such as application/dns-udpwireformat and the use of a varying
DNS ID can cause semantically equivalent DNS queries to be cached
separately.DNS API clients can use HTTP/2 padding and compression in the same way
that other HTTP/2 clients use (or don’t use) them.The data payload is the DNS on-the-wire format defined in .
The format is for DNS over UDP. (Note that this is different than the
wire format used in .When using the GET method, the data payload MUST be encoded with
base64url and then placed as a name value pair in the
query portion of the URI with name “dns”. Padding characters for
base64url MUST NOT be included.When using the POST method, the data payload MUST NOT be encoded and
is used directly as the HTTP message body.DNS API clients using the DNS wire format MAY have one or more EDNS
extensions in the request.The media type is “application/dns-udpwireformat”.These examples use HTTP/2 style formatting from .These examples use a DNS API service located at
https://dnsserver.example.net/dns-query to resolve the IN A records.The requests are represented as application/dns-udpwirefomat typed
bodies.The first example request uses GET to request www.example.comThe same DNS query for www.example.com, using the POST method would be: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 is 94 bytes represented by the following hex encodingAn HTTP response with a 2xx status code ( 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
allow clients 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.At the time this is published, the response types are works in
progress. The only response type defined in this document is
“application/dns-udpwireformat”, but it is possible that other
response formats will be defined in the future.The DNS response for “application/dns-udpwireformat” in
MAY have one or more EDNS extensions, depending on the
extension definition of the extensions given in the DNS request.Each DNS request-response pair is matched to one HTTP request-response
pair. The responses may be processed and transported in any order
using HTTP’s multi-streaming functionality ( Section 5}).The Answer section of a DNS response can contain zero or more RRsets.
(RRsets are defined in .) According to , each
resource record in an RRset has Time To Live (TTL)
freshness information. Different RRsets in the Answer section can
have different TTLs, although it is only possible for the HTTP response
to have a single freshness lifetime. The HTTP response freshness lifetime
( Section 4.2) should be coordinated with the RRset
with the smallest TTL in the Answer section of the response.
Specifically, the HTTP freshness lifetime SHOULD be set to expire at the same time
any of the DNS resource records in the Answer section reach a 0 TTL.
The response freshness lifetime
MUST NOT be greater than that indicated by the DNS resoruce record with the
smallest TTL in the response.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
freshness lifetime MUST NOT be greater than the MINIMUM field from that SOA
record. Otherwise, the HTTP response MUST set a freshness lifetime
( Section 4.2) of 0 by using a mechanism such as
“Cache-Control: no-cache” ( Section 5.2.1.4).A DNS API client that receives a response without an explicit
freshness lifetime MUST NOT assign that response a heuristic
freshness ( Section 4.2.2.) greater than that indicated by
the DNS Record with the smallest TTL in the response.A DNS API server MUST be able to process application/dns-udpwireformat
request messages.A DNS API server SHOULD respond with HTTP status code 415 (Unsupported
Media Type) upon receiving a media type it is unable to process.This document does not change the definition of any HTTP response codes or
otherwise proscribe their use.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
record with an address of 192.0.2.1 and a TTL of 128 seconds.This protocol MUST be used with the https scheme URI .A DOH API client may utilize a hierarchy of caches that include both
HTTP and DNS specific caches. HTTP cache entries may be bypassed with
HTTP mechanisms such as the “Cache-Control no-cache” directive; however
DNS caches do not have a similar mechanism.A DOH response that was previously stored in an HTTP cache will
contain the Age response header indicating the elapsed
time between when the entry was placed in the HTTP cache and the
current DOH response. DNS API clients should subtract this time from
the DNS TTL if they are re-sharing the information in a non HTTP
context (e.g. their own DNS cache) to determine the remaining time to
live of the DNS record.HTTP revalidation (e.g. via If-None-Match request headers) of cached
DNS information may be of limited value to DOH as revalidation
provides only a bandwidth benefit and DNS transactions are normally
latency bound. Furthermore, the HTTP response headers that enable
revalidation (such as “Last-Modified” and “Etag”) are often fairly
large when compared to the overall DNS response size, and have a
variable nature that creates constant pressure on the HTTP/2
compression dictionary . Other types of DNS data, such as
zone transfers, may be larger and benefit more from revalidation. DNS
API servers may wish to consider whether providing these validation
enabling response headers is worthwhile.The stale-while-revalidate and stale-if-error cache control directives
may be well suited to a DOH implementation when allowed by server
policy. Those mechanisms allow a client, at the server’s discretion,
to reuse a cache entry that is no longer fresh under some extenuating
circumstances defined in .All HTTP servers, including DNS API servers, need to consider cache
interaction when they generate responses that are not globally
valid. For instance, if a DNS API server customized a response based
on the client’s identity then it would not want to globally allow
reuse of that response. This could be accomplished through a variety
of HTTP techniques such as a Cache-Control max-age of 0, or perhaps by
the Vary response header.The minimum version of HTTP used by DOH SHOULD be HTTP/2 .The messages in classic UDP based DNS are inherently
unordered and have low overhead. A competitive HTTP transport needs to
support reordering, parallelism, priority, and header compression to
achieve similar performance. Those features were introduced to HTTP in
HTTP/2 . Earlier versions of HTTP are capable of conveying
the semantic requirements of DOH but may result in very poor
performance for many uses cases.Before using DOH response data for DNS resolution, the client MUST
establish that the HTTP request URI is a trusted service for the DOH
query. For HTTP requests initiated by the DNS API client this trust is
implicit in the selection of URI. For HTTP server push (
Section 8.2) extra care must be taken to ensure that the pushed URI is
one that the client would have directed the same query to if the
client had initiated the request. This specification does not extend
DNS resolution privileges to URIs that are not recognized by the
client as trusted DNS API servers.Running DNS over HTTPS relies on the security of the underlying
HTTP transport. This mitigates classic amplication
attacks for UDP-based DNS. Implementations utilizing HTTP/2 benefit from the TLS
profile defined in Section 9.2.Session level encryption has well known weaknesses with respect to
traffic analysis which might be particularly acute when dealing with
DNS queries.
HTTP/2 provides further advice about the use of compression
(Section 10.6 of ) and padding (Section 10.7 of ).The HTTPS connection provides transport security for the interaction
between the DNS API server and client, but does not inherently ensure
the authenticity of DNS data. A DNS API client may also perform full
DNSSEC validation of answers received from a DNS API server or it may
choose to trust answers from a particular DNS API server, much as a
DNS client might choose to trust answers from its recursive DNS
resolver. This capability might be affected by the response media
type. describes the interaction of this protocol with HTTP
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 the security implications of HTTP caching for other protocols
that use HTTP.A server that is acting both as a normal web server and a DNS API
server is in a position to choose which DNS names it forces a
client to resolve (through its web service) and also be the one to
answer those queries (through its DNS API service). An untrusted
DNS API server can thus easily cause damage by poisoning a client’s
cache with names that the DNS API server chooses to poison. A
client MUST NOT trust a DNS API server simply because it was
discovered, or because the client was told to trust the DNS API
server by an untrusted party. Instead, a client MUST only trust DNS
API server that is configured as trustworthy.A client can use DNS over HTTPS as one of multiple mechanisms to obtain DNS
data. If a client of this protocol encounters an HTTP error after sending
a DNS query, and then falls back to a different DNS retrieval mechanism,
doing so can weaken the privacy expected by the user of the client.Local policy considerations and similar factors mean different DNS
servers may provide different results to the same query: for instance
in split DNS configurations . It logically follows that
the 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
queries.
For example, in the case of DNS64 , the choice could affect
whether IPv6/IPv4 translation will work at all.The HTTPS channel used by this specification establishes secure two
party communication between the DNS API client and the DNS API server.
Filtering or inspection systems that rely on unsecured transport of
DNS will not function in a DNS over HTTPS environment.Many HTTPS implementations perform real time third party 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 procedure and the
check itself requires DNS resolution to connect to the third party a
deadlock can occur. The use of an OCSP server is one
example of how this can happen. DNS API servers SHOULD utilize OCSP
Stapling to provide the client with certificate revocation
information that does not require contacting a third party.A DNS API client may face a similar bootstrapping problem when the
HTTP request needs to resolve the hostname portion of the DNS
URI. Just as the address of a traditional DNS nameserver cannot be
originally determined from that same server, a DOH client cannot use
its DOH server to initially resolve the server’s host name into an
address. Alternative strategies a client might employ include making
the initial resolution part of the configuration, IP based URIs and
corresponding IP based certificates for HTTPS, or resolving the DNS
API server’s hostname via traditional DNS or another DOH server while
still authenticating the resulting connection via HTTPS.HTTP is a stateless application level protocol and
therefore DOH implementations do not provide stateful ordering
guarantees between different requests. DOH cannot be used as a
transport for other protocols that require strict ordering.Joe Hildebrand contributed lots of material for a different iteration of this document.
Helpful early comments were given by Ben Schwartz and Mark Nottingham.Domain names - implementation and specificationThis RFC is the revised specification of the protocol and format used in the implementation of the Domain Name System. It obsoletes RFC-883. This memo documents the details of the domain name client - server communication.The Base16, Base32, and Base64 Data EncodingsThis document describes the commonly used base 64, base 32, and base 16 encoding schemes. It also discusses the use of line-feeds in encoded data, use of padding in encoded data, use of non-alphabet characters in encoded data, use of different encoding alphabets, and canonical encodings. [STANDARDS-TRACK]The Transport Layer Security (TLS) Protocol Version 1.2This document specifies Version 1.2 of the Transport Layer Security (TLS) protocol. The TLS protocol provides communications security over the Internet. The protocol allows client/server applications to communicate in a way that is designed to prevent eavesdropping, tampering, or message forgery. [STANDARDS-TRACK]X.509 Internet Public Key Infrastructure Online Certificate Status Protocol - OCSPThis document specifies a protocol useful in determining the current status of a digital certificate without requiring Certificate Revocation Lists (CRLs). Additional mechanisms addressing PKIX operational requirements are specified in separate documents. This document obsoletes RFCs 2560 and 6277. It also updates RFC 5912.The Transport Layer Security (TLS) Multiple Certificate Status Request ExtensionThis document defines the Transport Layer Security (TLS) Certificate Status Version 2 Extension to allow clients to specify and support several certificate status methods. (The use of the Certificate Status extension is commonly referred to as "OCSP stapling".) Also defined is a new method based on the Online Certificate Status Protocol (OCSP) that servers can use to provide status information about not only the server's own certificate but also the status of intermediate certificates in the chain.Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and RoutingThe Hypertext Transfer Protocol (HTTP) is a stateless application-level protocol for distributed, collaborative, hypertext information systems. This document provides an overview of HTTP architecture and its associated terminology, defines the "http" and "https" Uniform Resource Identifier (URI) schemes, defines the HTTP/1.1 message syntax and parsing requirements, and describes related security concerns for implementations.Hypertext Transfer Protocol (HTTP/1.1): Semantics and ContentThe Hypertext Transfer Protocol (HTTP) is a stateless \%application- level protocol for distributed, collaborative, hypertext information systems. This document defines the semantics of HTTP/1.1 messages, as expressed by request methods, request header fields, response status codes, and response header fields, along with the payload of messages (metadata and body content) and mechanisms for content negotiation.Hypertext Transfer Protocol (HTTP/1.1): CachingThe Hypertext Transfer Protocol (HTTP) is a stateless \%application- level protocol for distributed, collaborative, hypertext information systems. This document defines HTTP caches and the associated header fields that control cache behavior or indicate cacheable response messages.Hypertext Transfer Protocol Version 2 (HTTP/2)This specification describes an optimized expression of the semantics of the Hypertext Transfer Protocol (HTTP), referred to as HTTP version 2 (HTTP/2). HTTP/2 enables a more efficient use of network resources and a reduced perception of latency by introducing header field compression and allowing multiple concurrent exchanges on the same connection. It also introduces unsolicited push of representations from servers to clients.This specification is an alternative to, but does not obsolete, the HTTP/1.1 message syntax. HTTP's existing semantics remain unchanged.HPACK: Header Compression for HTTP/2This specification defines HPACK, a compression format for efficiently representing HTTP header fields, to be used in HTTP/2.Ambiguity of Uppercase vs Lowercase in RFC 2119 Key WordsRFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings.Clarifications to the DNS SpecificationThis document considers some areas that have been identified as problems with the specification of the Domain Name System, and proposes remedies for the defects identified. [STANDARDS-TRACK]HTTP Cache-Control Extensions for Stale ContentThis document defines two independent HTTP Cache-Control extensions that allow control over the use of stale responses by caches. This document is not an Internet Standards Track specification; it is published for informational purposes.DNS64: DNS Extensions for Network Address Translation from IPv6 Clients to IPv4 ServersDNS64 is a mechanism for synthesizing AAAA records from A records. DNS64 is used with an IPv6/IPv4 translator to enable client-server communication between an IPv6-only client and an IPv4-only server, without requiring any changes to either the IPv6 or the IPv4 node, for the class of applications that work through NATs. This document specifies DNS64, and provides suggestions on how it should be deployed in conjunction with IPv6/IPv4 translators. [STANDARDS-TRACK]Extension Mechanisms for DNS (EDNS(0))The Domain Name System's wire protocol includes a number of fixed fields whose range has been or soon will be exhausted and does not allow requestors to advertise their capabilities to responders. This document describes backward-compatible mechanisms for allowing the protocol to grow.This document updates the Extension Mechanisms for DNS (EDNS(0)) specification (and obsoletes RFC 2671) based on feedback from deployment experience in several implementations. It also obsoletes RFC 2673 ("Binary Labels in the Domain Name System") and adds considerations on the use of extended labels in the DNS.Architectural Considerations on Application Features in the DNSA number of Internet applications rely on the Domain Name System (DNS) to support their operations. Many applications use the DNS to locate services for a domain; some, for example, transform identifiers other than domain names into formats that the DNS can process, and then fetch application data or service location data from the DNS. Proposals incorporating sophisticated application behavior using DNS as a substrate have raised questions about the role of the DNS as an application platform. This document explores the architectural consequences of using the DNS to implement certain application features, and it provides guidance to future application designers as to the limitations of the DNS as a substrate and the situations in which alternative designs should be considered.DNS TerminologyThe DNS is defined in literally dozens of different RFCs. The terminology used by implementers and developers of DNS protocols, and by operators of DNS systems, has sometimes changed in the decades since the DNS was first defined. This document gives current definitions for many of the terms used in the DNS in a single document.Specification for DNS over Transport Layer Security (TLS)This document describes the use of Transport Layer Security (TLS) to provide privacy for DNS. Encryption provided by TLS eliminates opportunities for eavesdropping and on-path tampering with DNS queries in the network, such as discussed in RFC 7626. In addition, this document specifies two usage profiles for DNS over TLS and provides advice on performance considerations to minimize overhead from using TCP and TLS with DNS.This document focuses on securing stub-to-recursive traffic, as per the charter of the DPRIVE Working Group. It does not prevent future applications of the protocol to recursive-to-authoritative traffic.Cross-Origin Resource Sharingapplication/x-www-form-urlencoded ParsingThe following is an incomplete list of earlier work that related to DNS over HTTP/1 or representing DNS
data in other formats.The list includes links to the tools.ietf.org site (because these documents
are all expired) and web sites of software.https://tools.ietf.org/html/draft-mohan-dns-query-xmlhttps://tools.ietf.org/html/draft-daley-dnsxmlhttps://tools.ietf.org/html/draft-dulaunoy-dnsop-passive-dns-cofhttps://tools.ietf.org/html/draft-bortzmeyer-dns-jsonhttps://www.nlnetlabs.nl/projects/dnssec-trigger/