Migration to anycast and RFC 8484 DoH

As part of the launch of DoH on the dns.google domain and the well-known anycast IP addresses for Google Public DNS, the Beta DoH service on the dns.google.com domain using other IP addresses is now deprecated and will be turned down.

The experimental version of the RFC 8484 API is also deprecated; dns.google/experimental is not supported, and dns.google.com/experimental will be migrated to dns.google/dns-query.


Date Turndown step
2019-07-23 2019-08-01 dns.google.com/experimental redirects to dns.google/dns-queryDONE
2019-08-05 2019-08-21 dns.google.com resolves to Google Public DNS anycast IP addressesDONE
2019-09-24 Old IP addresses for dns.google.com redirect to dns.googleDONE
2020-06-23 dns.google.com redirects to dns.google everywhere

Changes to this timeline are updated here and posted to public-dns-announce. Subscribe to that low-volume mailing list for updates.

Thursday, August 1, 2019

Requests for https://dns.google.com/experimental get HTTP 301 redirects to https://dns.google/dns-query.

DoH applications using the JSON API at /resolve are not affected.

Wednesday, August 21, 2019

dns.google.com resolves to the Google Public DNS anycast IP addresses.

This is transparent for most DoH applications, with no changes needed.

Tuesday, September 24, 2019

DoH queries to former dns.google.com IP addresses get HTTP 301 redirects to https://dns.google/.

This may affect DoH applications using either the RFC 8484 or JSON API.

Applications that send DoH requests to hardcoded, configurable, or permanently cached IP addresses must support one or both of the following:

Tuesday, June 23, 2020

DoH queries to dns.google.com on anycast IP addresses get HTTP 301 redirects to dns.google.

This may affect DoH applications using either the RFC 8484 or JSON API.

To work with Google DoH, applications must support at least one of the following:

Changes for DoH clients

Follow HTTP redirects

DoH servers are just HTTP servers handling DNS queries. As such, they may return HTTP redirects (codes 301, 302, 307, or 308), and DoH clients should follow those redirects just like any other HTTP client.

Developers can check HTTP redirect support with or as the base for their DoH URLs; these return HTTP 301 redirects to https://dns.google/dns-query and https://dns.google/resolve (preserving any GET parameters).

Use dns.google domain for Google DoH

DoH applications should use dns.google instead of dns.google.com. Whether using the RFC 8484 or JSON API, any DoH applications with a hard-coded or configured list of DoH resolvers need to replace dns.google.com with dns.google in any URLs or URI templates.

Use Google Public DNS anycast IP addresses

DoH applications that send DoH requests to a hard-coded or configured list of IP addresses (even just for bootstrapping) need to replace former addresses of dns.google.com with the Google Public DNS anycast IP addresses.

URI Templates for configuration

DoH applications should provide configurability for endpoints; the preferred and standard way to do this is with URI templates. DoH application developers with full configurability should notify users of the new URL (URI template: https://dns.google/dns-query{?dns}).

Use https://dns.google/dns-query for RFC 8484 DoH

DoH applications with a hard-coded or configured list of DoH resolvers need to replace the https://dns.google.com/experimental URL for the internet-draft DoH API with https://dns.google/dns-query and confirm full RFC 8484 compliance.

The /experimental API (only available at dns.google.com) accepted queries using non-websafe Base64 encoding and application/dns-udpwireformat content type that are rejected by the /dns-query API (only available at dns.google). These differences are described in the following two sections.

Use Base64Url encoding for GET dns parameter

Use websafe Base64Url encoding for the dns parameter in GET requests, replacing Base64 (+ /) with (- _) and removing padding (=) characters.

Accept and send application/dns-message

Use application/dns-message in the Accept header (and for RFC 8484 POST, in the Content-Type header) and accept it as the Content-Type of responses.

Using the old Content-Type for POST will fail with 415 Unsupported Media Type.

Applications using the old Content-Type in the Accept header will get responses with Content-Type application/dns-message. DoH applications that accept these, and do not ignore them because of unexpected Content-Type, will still work.