RFC 8484

DNS Queries over HTTPS (DoH)

📅 published October 2018, from ietf

DNS Queries over HTTPS (DoH) 🎀

Internet Engineering Task Force (IETF) 🌸

RFC 8484 is a Standards Track doc from October 2018 ✨, with ISSN 2070-1721.

Authors: P. Hoffman (ICANN) and P. McManus (Mozilla) 👑

Obsoletes/Updates: nothing is listed for this one in the title block, so there's no "Obsoletes" or "Updates" line to flag 🙈

Abstract ✨

Okay so this doc is all about a protocol for sending DNS queries and getting DNS responses over HTTPS 🌸. Each DNS query-response pair gets mapped into an HTTP exchange 🦋.

Status of This Memo 💅

This is an Internet Standards Track document, so it's the real deal 💅. It's a product of the IETF and it represents the consensus of the IETF community. It got public review and was approved for publication by the IESG (Internet Engineering Steering Group). If you want more on Internet Standards, check out Section 2 of RFC 7841 🧚.

Info about the current status of this doc, any errata, and how to send feedback lives at https://www.rfc-editor.org/info/rfc8484 💜.

Copyright (c) 2018 IETF Trust and the persons identified as the document authors. All rights reserved ©️.

This doc is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) as they're in effect on the date of publication. Please read these carefully, because they describe your rights and restrictions for this doc 🙈. Code Components pulled out of this doc must include Simplified BSD License text, as described in Section 4.e of the Trust Legal Provisions, and they come without warranty as described in the Simplified BSD License 🔥.

Table of Contents 📚

1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   3
2.  Terminology . . . . . . . . . . . . . . . . . . . . . . . . .   3
3.  Selection of DoH Server . . . . . . . . . . . . . . . . . . .   4
4.  The HTTP Exchange . . . . . . . . . . . . . . . . . . . . . .   4
  4.1.  The HTTP Request  . . . . . . . . . . . . . . . . . . . .   4
    4.1.1.  HTTP Request Examples . . . . . . . . . . . . . . . .   5
  4.2.  The HTTP Response . . . . . . . . . . . . . . . . . . . .   7
    4.2.1.  Handling DNS and HTTP Errors  . . . . . . . . . . . .   7
    4.2.2.  HTTP Response Example . . . . . . . . . . . . . . . .   8
5.  HTTP Integration  . . . . . . . . . . . . . . . . . . . . . .   8
  5.1.  Cache Interaction . . . . . . . . . . . . . . . . . . . .   8
  5.2.  HTTP/2  . . . . . . . . . . . . . . . . . . . . . . . . .  10
  5.3.  Server Push . . . . . . . . . . . . . . . . . . . . . . .  10
  5.4.  Content Negotiation . . . . . . . . . . . . . . . . . . .  10
6.  Definition of the "application/dns-message" Media Type  . . .  10
7.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .  11
  7.1.  Registration of the "application/dns-message" Media Type   11
8.  Privacy Considerations  . . . . . . . . . . . . . . . . . . .  12
  8.1.  On the Wire . . . . . . . . . . . . . . . . . . . . . . .  12
  8.2.  In the Server . . . . . . . . . . . . . . . . . . . . . .  12
9.  Security Considerations . . . . . . . . . . . . . . . . . . .  14
10. Operational Considerations  . . . . . . . . . . . . . . . . .  15
11. References  . . . . . . . . . . . . . . . . . . . . . . . . .  16
  11.1.  Normative References . . . . . . . . . . . . . . . . . .  16
  11.2.  Informative References . . . . . . . . . . . . . . . . .  18
Appendix A.  Protocol Development . . . . . . . . . . . . . . . .  20
Appendix B.  Previous Work on DNS over HTTP or in Other Formats .  20
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . .  21
Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  21

1. Introduction ✨

This doc defines a specific protocol, DNS over HTTPS (DoH), for sending DNS [RFC1035] queries and getting DNS responses over HTTP [RFC7540] using https [RFC2818] URIs. That means you also get TLS [RFC8446] security for integrity and confidentiality 🔒. Each DNS query-response pair is mapped into an HTTP exchange 🦋.

It's way more than just a tunnel over HTTP 💖. It sets default media formatting types for requests and responses, but it uses normal HTTP content negotiation to pick alternatives that endpoints might prefer, in case they're serving new use cases. On top of that media type negotiation, it lines up with HTTP features like caching, redirection, proxying, authentication, and compression ✨.

The HTTP integration gives you a transport that works for both existing DNS clients and native web apps that want access to DNS 🫶.

Two primary use cases were considered during development 👑. The first is preventing on-path devices from messing with DNS operations. The second is letting web apps reach DNS info through existing browser APIs, in a safe way that's consistent with Cross Origin Resource Sharing (CORS) [FETCH]. No special effort was made to enable or prevent other use cases. This doc focuses on communication between DNS clients (like operating system stub resolvers) and recursive resolvers 💅.

2. Terminology 📖

A server that supports this protocol is called a "DoH server" to tell it apart from a "DNS server" (one that only provides DNS service over one or more of the other transport protocols standardized for DNS) 🦋. Likewise, a client that supports this protocol is called a "DoH client" 🎀.

Okay, so the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" get read as described in BCP 14 [RFC2119] [RFC8174], but only when they show up in all capitals, just like this 💜.

3. Selection of DoH Server 🧚

The DoH client is configured with a URI Template [RFC6570] that describes how to build the URL it uses for resolution. Configuration, discovery, and updating of the URI Template all happen out of band from this protocol 🙈. Configuration might be manual (like a user typing URI Templates into an "options" screen) or automatic (like URI Templates showing up in responses from DHCP or similar protocols). DoH servers MAY support more than one URI Template ✨. That lets different endpoints have different properties, like different authentication requirements or service-level guarantees 💖.

A DoH client uses its configuration to pick the URI, and therefore the DoH server, that gets used for resolution. [RFC2818] defines how HTTPS verifies the DoH server's identity 🔥.

A DoH client MUST NOT use a different URI simply because it was discovered outside of the client's configuration (like through HTTP/2 server push), or because a server offers an unsolicited response that looks like a valid answer to a DNS query 🙅. This specification doesn't extend DNS resolution privileges to URIs that the DoH client doesn't recognize as configured URIs 🚫. Scenarios like that may create additional operational, tracking, and security hazards that require limitations for safe usage 💀. A future specification may support this use case ✨.

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 plus the other requirements in this section 💅. The DoH server defines the URI the request uses through 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 goes in the message body of the HTTP request, and the Content-Type request header field says what media type the message is. 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 say what kind of content it can understand in the response. No matter what the Accept request header field says, the client MUST be prepared to process "application/dns-message" (as described in Section 6) responses, but it MAY also process other DNS-related media types it receives 🦋.

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, so the ID isn't needed in a media type like "application/dns-message". A varying DNS ID can cause semantically equivalent DNS queries to get 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 🧠.

Last one! It's a GET-based query for "a.62characterlabel-makes-base64url-distinct-from-standard-base64.example.com" 💅. It's here to show that the base64url encoding alphabet is different from regular base64, and that padding gets omitted 🦋.

The DNS query, expressed in DNS wire format, is 94 bytes, represented like this:

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

And the request looks like this 💖:

: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 ✨

okay so the only response type defined in this doc is "application/dns-message" 💅 but other formats might show up later 🦋 A DoH server MUST be able to process "application/dns-message" request messages. no cap, that's the baseline bestie 🫶

different response media types give you more or less info from a DNS response 🌸 one might keep the DNS header bytes while another leaves them out. how much info a media type gives, and what kind, is totally up to that format, and this protocol doesn't define the format ✨

each DNS request-response pair maps to one HTTP exchange 💜 the responses can be processed and transported in any order using HTTP's multi-streaming feature (see Section 5 of [RFC7540]). so many moving parts, so iconic 🎀

Section 5.1 covers how DNS and HTTP response caching work together 🧚

4.2.1. Handling DNS and HTTP Errors

okay this part is important 😭 DNS response codes tell you whether the DNS query succeeded or failed 🍓 a successful HTTP response with a 2xx status code (see Section 6.3 of [RFC7231]) is used for any valid DNS response, no matter what the DNS response code is. so even a DNS message with a failure code like SERVFAIL or NXDOMAIN still gets a successful 2xx status 💀 the vibe is "the HTTP part worked, the DNS answer is just a no" 🙈

HTTP responses with non-successful status codes do not contain replies to the original DNS question from the HTTP request 🥲 DoH clients need to handle non-successful status codes the same way any other HTTP client does 🔥 this could mean the DoH client retries the query with the same DoH server, like for authorization failures (HTTP status code 401; see Section 3.1 of [RFC7235]) 🔐 it could also mean the DoH client retries with a different DoH server, like for unsupported media types (HTTP status code 415; see Section 6.5.13 of [RFC7231]), or when the server can't 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 has one answer record with an address of 2001:db8:abcd: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

5. HTTP Integration

this protocol MUST be used with the https URI scheme [RFC7230] 🔒 no http, no drama 💖

Sections 8 and 9 talk about more things to think about when integrating with HTTP 🧁

5.1. Cache Interaction

okay caches are where things get messy 🌀 a DoH exchange can pass through a whole hierarchy of caches, including both HTTP-specific and DNS-specific ones 🕸️ these caches might sit between the DoH server and client, or live on the DoH client itself 🏠 HTTP caches are generic by design, which means they don't understand this protocol 🙃 even if a DoH client has changed its cache to understand DoH semantics, that doesn't mean every upstream cache (like inline proxies, server-side gateways, and content delivery networks) will too 🫠

so DoH servers need to think carefully about the HTTP caching metadata they send back for GET requests 🧠 (responses to POST requests aren't cacheable unless specific response header fields are sent; that isn't widely implemented and isn't advised for DoH) 🙅‍♀️

in particular, DoH servers SHOULD assign an explicit HTTP freshness lifetime (see Section 4.2 of [RFC7234]) so the DoH client is more likely to use fresh DNS data ✨ this matters because HTTP caches can assign their own heuristic freshness (like the one described in Section 4.2.2 of [RFC7234]), and then the DoH server loses control of what's in the cache 😤

the assigned freshness lifetime of a DoH HTTP response MUST be less than or equal to the smallest TTL in the Answer section of the DNS response 💅 an assigned freshness lifetime equal to the smallest TTL in the Answer section is RECOMMENDED 🎯 for example, if an HTTP response carries three RRsets with TTLs of 30, 600, and 300, the HTTP freshness lifetime should be 30 seconds (which could be written as Cache-Control: max-age=30) ⏰ this helps stop expired RRsets sitting in an HTTP cache from getting served by accident 🙅‍♀️

if the DNS response has no records in the Answer section, and it has an SOA record in the Authority section, the response freshness lifetime MUST NOT be greater than the MINIMUM field from that SOA record (see [RFC2308]) 📜

the stale-while-revalidate and stale-if-error Cache-Control directives [RFC5861] could be a great fit for a DoH implementation when the server policy allows it 🦋 those mechanisms let a client, at the server's discretion, reuse an HTTP cache entry that's no longer fresh 🍃 in that case, the client reuses either all of a cached entry or none of it 🫶

DoH servers also need to think about HTTP caching when they generate responses that aren't globally valid 🌍 for example, if a DoH server customizes a response based on the client's identity, it wouldn't want to allow global reuse of that response 🙈 this can be handled with a few HTTP techniques, like a Cache-Control max-age of 0, or by using the Vary response header field (see Section 7.1.4 of [RFC7231]) to set up a secondary cache key (see Section 4.1 of [RFC7234]) 🔑

DoH clients MUST account for the Age response header field's value [RFC7234] when calculating the DNS TTL of a response 🧮 for example, if an RRset comes in with a DNS TTL of 600, but the Age header field says the response has been cached for 250 seconds, the remaining lifetime of the RRset is 350 seconds ⏳ this applies to both DoH client HTTP caches and DoH client DNS caches 💜

DoH clients can ask for an uncached copy of an HTTP response by using the "no-cache" request Cache-Control directive (see Section 5.2.1.4 of [RFC7234]) and similar controls 🙋‍♀️ heads up though: some caches might not honor these directives, either because of configuration or because of how they interact with traditional DNS caches, which don't have a mechanism like this 😬

HTTP conditional requests [RFC7232] may be of limited value to DoH 🥱 revalidation only gives you a bandwidth benefit, and DNS transactions are usually latency bound 🐢 the HTTP response header fields that enable revalidation (like "Last-Modified" and "Etag") are often pretty big compared to the overall DNS response size, and they have a variable nature that keeps putting pressure on the HTTP/2 compression dictionary [RFC7541] 📚 other types of DNS data, like zone transfers, may be larger and get more out of revalidation 🌸

5.2. HTTP/2

HTTP/2 [RFC7540] is the minimum RECOMMENDED version of HTTP for use with DoH 🚀

classic UDP-based DNS [RFC1035] messages are inherently unordered and have low overhead 🏎️ a competitive HTTP transport needs to support reordering, parallelism, priority, and header compression to get similar performance 🔥 those features were introduced to HTTP in HTTP/2 [RFC7540] ✨ earlier versions of HTTP can still carry the semantic requirements of DoH, but they may result in very poor performance 😭

5.3. Server Push

before using DoH response data for DNS resolution, the client MUST establish that the HTTP request URI can be used for the DoH query 🔍 for HTTP requests the DoH client starts itself, this is implicit in the choice of URI 🫡 for HTTP server push (see Section 8.2 of [RFC7540]), extra care must be taken to make sure the pushed URI is one the client would have sent the same query to if it had started the request itself (on top of the other security checks normally needed for server push) 🛡️

5.4. Content Negotiation

to maximize interoperability, DoH clients and DoH servers MUST support the "application/dns-message" media type 🤝 other media types MAY be used as defined by HTTP Content Negotiation (see Section 3.4 of [RFC7231]) 🎀 those media types MUST be flexible enough to express every DNS query that would normally be sent over DNS over UDP (including queries and responses that use DNS extensions, but not ones that need multiple responses) 💫

6. Definition of the "application/dns-message" Media Type

the data payload for the "application/dns-message" media type is a single message in the DNS on-the-wire format defined in Section 4.2.1 of [RFC1035], which refers to the full wire format defined in Section 4.1 of that RFC 🧩

[RFC1035] says "Messages carried by UDP are restricted to 512 bytes", but that was later updated by [RFC6891] 🙌 this media type caps the maximum DNS message size at 65535 bytes 📏

note that the wire format used in this media type is different from the wire format used in [RFC7858] (which uses the format defined in Section 4.2.2 of [RFC1035] that includes two length bytes) ⚠️

DoH clients using this media type MAY have one or more Extension Mechanisms for DNS (EDNS) options [RFC6891] in the request 🌟 DoH servers using this media type MUST ignore the value given for the EDNS UDP payload size in DNS requests 🙈

when using the GET method, the data payload for this media type MUST 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 🫶

when using the POST method, the data payload for this media type MUST NOT be encoded, and it's used directly as the HTTP message body 📬

7. IANA Considerations

7.1. Registration of the "application/dns-message" Media Type

okay this is the official registry entry for the media type 📋 here it is, verbatim:

   Type name: application

   Subtype name: dns-message

   Required parameters: N/A

   Optional parameters: N/A

   Encoding considerations: This is a binary format.  The contents are a
      DNS message as defined in RFC 1035.  The format used here is for
      DNS over UDP, which is the format defined in the diagrams in
      RFC 1035.

   Security considerations: See RFC 8484.  The content is a DNS message
      and thus not executable code.

   Interoperability considerations: None.

   Published specification: RFC 8484.

   Applications that use this media type:
      Systems that want to exchange full DNS messages.

   Additional information:

      Deprecated alias names for this type: N/A
      Magic number(s): N/A
      File extension(s): N/A
      Macintosh file type code(s): N/A

   Person & email address to contact for further information:
      Paul Hoffman <paul.hoffman@icann.org>

   Intended usage: COMMON

   Restrictions on usage: N/A

   Author: Paul Hoffman <paul.hoffman@icann.org>

   Change controller: IESG

8. Privacy Considerations

[RFC7626] talks about DNS privacy considerations in both the "on the wire" context (Section 2.4 of [RFC7626]) and the "in the server" context (Section 2.5 of [RFC7626]) 🕵️‍♀️ that's a really useful framing for DoH's privacy considerations too 💖

8.1. On the Wire 🌸

okay so DoH encrypts DNS traffic AND requires authentication of the server 🔐. This mitigates both passive surveillance [RFC7258] and active attacks that try to divert DNS traffic to rogue servers (see Section 2.5.1 of [RFC7626]). DNS over TLS [RFC7858] gives similar protections, while direct UDP- and TCP-based transports are vulnerable to this class of attack 🙈. An experimental effort to offer guidance on choosing the padding length can be found in [RFC8467].

Also, using the HTTPS default port 443 and being able to mix DoH traffic with other HTTPS traffic on the same connection can deter unprivileged on-path devices from messing with DNS operations and make DNS traffic analysis harder 🧚.

8.2. In the Server 💜

the DNS wire format [RFC1035] has no client identifiers, BUT various transports of DNS queries and responses do provide data that can be used to correlate requests 👀. HTTPS brings new correlation considerations too, like explicit HTTP cookies and implicit fingerprinting of the unique set and ordering of HTTP request header fields.

A DoH implementation is built on IP, TCP, TLS, and HTTP. Each layer has one or more common features that can be used to correlate queries to the same identity 🕵️‍♀️. DNS transports will generally carry the same privacy properties as the layers used to implement them. For example, the properties of IP, TCP, and TLS apply to implementations of DNS over TLS.

The privacy considerations of using the HTTPS layer in DoH are incremental to those of DNS over TLS. DoH is not known to introduce new concerns beyond those associated with HTTPS ✨.

At the IP level, the client address is obvious correlation info 📍. This can be mitigated by using a NAT, proxy, VPN, or simple address rotation over time. It may be made worse by a DNS server that can correlate real-time addressing info with other personal identifiers, such as when a DNS server and DHCP server are run by the same entity.

DNS implementations that use one TCP connection for multiple DNS requests directly group those requests. Long-lived connections have better performance behaviors than short-lived ones; however, they group more requests, which can expose more info to correlation and consolidation 🧩. TCP-based solutions may also chase performance through TCP Fast Open [RFC7413]. The cookies used in TCP Fast Open allow servers to correlate TCP sessions.

TLS-based implementations often get better handshake performance through some form of session resumption mechanism, such as Section 2.2 of [RFC8446]. Session resumption creates trivial mechanisms for a server to correlate TLS connections together 😬.

HTTP's feature set can also be used for identification and tracking in a bunch of different ways 🍓. For example, Authentication request header fields explicitly identify profiles in use, and HTTP cookies are designed as an explicit state-tracking mechanism between the client and serving site. They're often used as an authentication mechanism too.

Also, the User-Agent and Accept-Language request header fields often convey specific info about the client version or locale. This facilitates content negotiation and operational workarounds for implementation bugs. Request header fields that control caching can expose state info about a subset of the client's history. Mixing DoH requests with other HTTP requests on the same connection also gives an opportunity for richer data correlation.

The DoH protocol design lets applications fully leverage the HTTP ecosystem, including features that aren't listed here. Using the full set of HTTP features makes DoH more than just an HTTP tunnel, but it comes at the cost of opening implementations up to the full set of HTTP privacy considerations 💅.

Implementations of DoH clients and servers need to consider the benefit and privacy impact of these features, and their deployment context, when deciding whether or not to enable them. Implementations are advised to expose the minimal set of data needed to achieve the desired feature set 🫶.

Figuring out whether a DoH implementation needs HTTP cookie [RFC6265] support is especially important, because HTTP cookies are the primary state-tracking mechanism in HTTP 🍪. HTTP cookies SHOULD NOT be accepted by DOH clients unless they are explicitly required by a use case.

9. Security Considerations 🔒

Running DNS over HTTPS relies on the security of the underlying HTTP transport. This mitigates classic amplification attacks for UDP-based DNS ✨. Implementations using HTTP/2 benefit from the TLS profile defined in Section 9.2 of [RFC7540].

Session-level encryption has well-known weaknesses with respect to traffic analysis, which might be especially intense when dealing with DNS queries 😭. HTTP/2 gives further advice about the use of compression (see Section 10.6 of [RFC7540]) and padding (see Section 10.7 of [RFC7540]). DoH servers can also add DNS padding [RFC7830] if the DoH client requests it in the DNS query. An experimental effort to offer guidance on choosing the padding length can be found in [RFC8467].

The HTTPS connection gives transport security for the interaction between the DoH server and client, but it does NOT provide the response integrity of DNS data that DNSSEC provides 🚨. DNSSEC and DoH are independent and fully compatible protocols, each solving different problems. Using one doesn't diminish the need for or the usefulness of the other 👑. It's the client's choice to either perform full DNSSEC validation of answers, or to trust the DoH server to do DNSSEC validation and inspect the AD (Authentic Data) bit in the returned message to figure out whether an answer was authentic. As noted in Section 4.2, different response media types give more or less info from a DNS response, so this choice may be affected by the response media type.

Section 5.1 describes how this protocol interacts 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 from the security implications of HTTP caching for other protocols that use HTTP.

Without DNSSEC info, a DoH server can give a client invalid data in response to a DNS query 💀. Section 3 disallows the use of DoH DNS responses that don't originate from configured servers. This prohibition doesn't guarantee protection against invalid data, but it does reduce the risk.

10. Operational Considerations ⚙️

Local policy and similar factors mean different DNS servers may give different results to the same query, for instance in split DNS configurations [RFC6950]. It logically follows that the server being queried can influence the end result. So a client's choice of DNS server may affect the responses it gets to its queries. For example, with DNS64 [RFC6147], that choice could decide whether IPv6/IPv4 translation works at all 🌈.

The HTTPS channel used by this specification sets up secure two-party communication between the DoH client and the DoH server 🫶. Filtering or inspection systems that rely on unsecured transport of DNS won't work in a DNS over HTTPS environment, because of the confidentiality and integrity protection TLS provides.

Some HTTPS client implementations do real-time third-party checks of the revocation status of the certificates used by TLS 🔎. If this check is part of the DoH server connection procedure, and the check itself needs DNS resolution to reach the third party, a deadlock can happen. Online Certificate Status Protocol (OCSP) [RFC6960] servers, or Authority Information Access (AIA) for Certificate Revocation List (CRL) fetching (see Section 4.2.2.1 of [RFC5280]), are examples of how this deadlock can happen. To mitigate the possibility of deadlock, the authentication given DoH servers SHOULD NOT rely on DNS-based references to external resources in the TLS handshake. For OCSP, the server can bundle the certificate status as part of the handshake using a mechanism suited to the version of TLS, such as Section 4.4.2.1 of [RFC8446] for TLS version 1.3. AIA deadlocks can be avoided by providing intermediate certificates that might otherwise be fetched through additional requests. Note that these deadlocks also need to be considered for servers that a DoH server might redirect to 🔁.

A DoH 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 can't be originally determined from that same server, a DoH client can't use its DoH server to initially resolve the server's hostname into an address. Alternative strategies a client might use include:

  1. making the initial resolution part of the configuration,
  2. IP-based URIs and corresponding IP-based certificates for HTTPS, or
  3. resolving the DNS API server's hostname via traditional DNS or another DoH server while still authenticating the resulting connection via HTTPS.

HTTP [RFC7230] is a stateless application-level protocol, so DoH implementations don't provide stateful ordering guarantees between different requests. DoH can't be used as a transport for other protocols that require strict ordering ⏳.

A DoH server is allowed to answer queries with any valid DNS response 🎀. For example, a valid DNS response might have the TC (truncation) bit set in the DNS header, to indicate that the server wasn't able to retrieve a full answer for the query but is providing the best answer it could get. A DoH server can reply to queries with an HTTP error for queries it can't fulfill. In that same example, a DoH server could use an HTTP error instead of a non-error response that has the TC bit set.

Lots of extensions to DNS, using [RFC6891], have been defined over the years 📚. Extensions specific to the choice of transport, such as [RFC7828], don't apply to DoH.

11. References 📖

11.1. Normative References 📚✨

okay bestie, these are the normative refs, which means the spec leans on them for real 💅 I'm keeping every entry exactly as written so nothing gets lost 🫶

11.2. Informative References 🌸

these ones are just good context, the vibe is more "read this for the lore" 🦋

Appendix A. Protocol Development 🧚

okay so this appendix is where the design goals for DoH get spilled 🍓 these are here so you can understand the protocol as it is now, NOT as a cage for how it could grow later 🦋 this appendix is non-normative, so no pressure, just vibes ✨

The protocol described in this document based 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 DNS query that would normally be sent in DNS over UDP (including queries and responses that use DNS extensions, but not those that require multiple responses).
  • The protocol must permit the addition of new formats for DNS queries and responses.
  • The protocol must ensure interoperability by specifying a single format for requests and responses that is mandatory to implement. That format must be able to support future modifications to the DNS protocol including the inclusion of one or more EDNS options (including those not yet defined).
  • The protocol must use a secure transport that meets the requirements for HTTPS.

The following were considered non-requirements:

  • Supporting network-specific DNS64 [RFC6147]
  • Supporting other network-specific inferences from plaintext DNS queries
  • Supporting insecure HTTP

Appendix B. Previous Work on DNS over HTTP or in Other Formats 🎀

the list below is incomplete (bestie, there was a LOT of earlier work 😭), and it's about DNS over HTTP/1 or putting DNS data into other formats. the tools.ietf.org links are there because those drafts are all expired, plus some software web sites 💜

Acknowledgments 🫶🌈

this work took a HIGH level of cooperation between experts in lots of different technologies, so big thank yous to everyone here 😭💖 Ray Bellis, Stephane Bortzmeyer, Manu Bretelle, Sara Dickinson, Massimiliano Fantuzzi, Tony Finch, Daniel Kahn Gilmor, Olafur Gudmundsson, Wes Hardaker, Rory Hewitt, Joe Hildebrand, David Lawrence, Eliot Lear, John Mattsson, Alex Mayrhofer, Mark Nottingham, Jim Reid, Adam Roach, Ben Schwartz, Davey Song, Daniel Stenberg, Andrew Sullivan, Martin Thomson, and Sam Weiler. legends, all of you 👑

Authors' Addresses 💌

  • Paul Hoffman ICANN Email: paul.hoffman@icann.org
  • Patrick McManus Mozilla Email: mcmanus@ducksong.com
📦 where this page comes from