Strona Omówienie protokołu TLS zawiera przykłady korzystania z wiersza poleceń curl do używania zarówno interfejsów API, jak i szczegóły dotyczące TLS oraz innych funkcji wspólnych dla połączeń DNS przez TLS (DoT) i DoH.
Publiczny serwer DNS Google nie obsługuje niezabezpieczonych adresów URL http: w przypadku wywołań interfejsu API.
Metody HTTP
GET
Metoda GET może skrócić czas oczekiwania, ponieważ jest lepiej przechowywana w pamięci podręcznej.
Żądania GET RFC 8484 muszą mieć parametr zapytania ?dns= z wiadomością DNS zakodowaną w standardzie Base64Url.
Metoda GET to jedyna metoda obsługiwana w interfejsie JSON API.
POST
Metoda POST jest obsługiwana tylko przez interfejs RFC 8484 API i używa binarnego komunikatu DNS z aplikacją Content-Type/wiadomością dns w treści żądania i w odpowiedzi HTTP DoH.
HEAD
Element HEAD nie jest obecnie obsługiwany i zwraca błąd 400 „Nieprawidłowe żądanie”.
Inne metody zwracają błędy 501 „Nie zaimplementowano”.
Kody stanów HTTP
Google Public DNS DoH zwraca te kody stanu HTTP:
Gotowe
200 OK
Analiza składni HTTP i komunikacja z mechanizmem rozpoznawania nazw DNS zakończyła się powodzeniem, a treść odpowiedzi to odpowiedź DNS w kodowaniu binarnym lub JSON (w zależności od punktu końcowego zapytania, parametrów Accept nagłówka i parametrów GET).
Przekierowania
301 Przeniesiono na stałe
Klienci powinni spróbować ponownie, korzystając z adresu URL podanego w nagłówku Location:. Jeśli pierwotne zapytanie było żądaniem POST, klienci powinni ponawiać próbę użycia metody GET tylko wtedy, gdy nowy adres URL zawiera argument parametru GET dns. W przeciwnym razie klient powinien ponowić próbę użycia metody POST.
W przyszłości możesz używać innych kodów, takich jak 302 Found, 307 Temporary Redirect lub 308 Permanent Redirect, a klienty DoH powinny obsługiwać wszystkie 4 kody.
Odpowiedzi ze stałymi kodami 301 i 308 należy przechowywać w pamięci podręcznej w nieskończoność. W razie potrzeby użytkownicy mogą zostać poproszeni o zaktualizowanie pierwotnej konfiguracji przy użyciu nowego adresu URL.
Żądania POST, które otrzymują odpowiedzi 307 lub 308, należy zawsze ponowić z użyciem metody POST.
Błędy
Odpowiedzi związane z błędami będą zawierać wyjaśnienie stanu HTTP w treści HTML lub zwykłego tekstu.
400 Nieprawidłowe żądanie
Problemy z analizą parametrów GET lub komunikatem nieprawidłowego żądania DNS.
W przypadku nieprawidłowych parametrów GET treść HTTP powinna zawierać wyjaśnienie błędu. W przypadku większości nieprawidłowych wiadomości DNS zwracany jest błąd 200 OK z użyciem FORMERR. Błąd HTTP jest zwracany w przypadku nieczytelnych wiadomości bez sekcji Question, flagi QR wskazującej odpowiedź lub innych bezsensownych kombinacji flag z binarnymi błędami analizy DNS.
413 Za dużo ładunku
Treść żądania POST w standardzie RFC 8484 przekracza maksymalny rozmiar wiadomości wynoszący 512 bajtów.
414 Identyfikator URI jest za długi
Nagłówek zapytania GET był za duży lub parametr dns zawierał wiadomość DNS zakodowaną w standardzie Base64Url, która przekraczała maksymalny rozmiar 512 bajtów.
415 Nieobsługiwany typ multimediów
Treść POST nie miała nagłówka Content-Type application/dns-message.
429 Zbyt wiele żądań
Klient wysłał zbyt wiele żądań w danym okresie. Klienci powinni przestać wysyłać żądania do czasu określonego w nagłówku Retry-After (względnego czasu w sekundach).
500 Wewnętrzny błąd serwera
Błędy wewnętrznego DoH w publicznym DNS Google.
501 Nie zaimplementowano
Wdrożone są tylko metody GET i POST; w przypadku innych metod występuje ten błąd.
502 Nieprawidłowa brama
Usługa DoH nie mogła skontaktować się z publicznymi resolverami DNS Google.
W przypadku odpowiedzi 502 chociaż ponowienie próby na alternatywnym publicznym adresie DNS Google może pomóc, skuteczniejszą odpowiedzią jest skorzystanie z innej usługi DoH albo przejście na tradycyjny protokół UDP lub TCP DNS pod adresem 8.8.8.8.
Zalety DoH
Używanie protokołu HTTPS, nie tylko szyfrowania TLS, niesie ze sobą kilka praktycznych korzyści:
Powszechnie dostępne i dobrze obsługiwane interfejsy API HTTPS upraszczają wdrażanie zarówno na potrzeby publicznego serwera DNS Google, jak i potencjalnych klientów.
Usługa HTTPS zapewnia aplikacjom internetowym dostęp do wszystkich typów rekordów DNS, co pozwala uniknąć ograniczeń istniejących interfejsów API DNS w przeglądarce i systemie operacyjnym, które zwykle obsługują tylko wyszukiwanie informacji między hostami.
Klienty, które implementują obsługę protokołu HTTPS opartego na protokole QUIC UDP, mogą uniknąć problemów, takich jak blokowanie na początku wiersza, które mogą wystąpić podczas korzystania z transportu TCP.
Sprawdzone metody ochrony prywatności dotyczące organizacji DoH
Deweloperzy aplikacji DoH powinni wziąć pod uwagę sprawdzone metody ochrony prywatności opisane w RFC 8484 oraz poniżej:
Ograniczenie używania nagłówków HTTP
Nagłówki HTTP ujawniają informacje o implementacji DoH klienta i mogą służyć do anonimizacji klientów. Nagłówki takie jak Cookie, User-Agent i Accept-Language powodują najwięcej błędów, ale nawet zestaw wysyłanych nagłówków może być ujawniany. Aby zminimalizować to ryzyko, wysyłaj tylko nagłówki HTTP wymagane przez DoH: Host, Content-Type (POST) i w razie potrzeby – Accept.
We wszystkich wersjach programistycznych lub testowych należy uwzględnić klienta użytkownika.
Użyj opcji dopełnienia EDNS
Postępuj zgodnie ze wskazówkami zawartymi w RFC 8467, aby użyć opcji dopełnienia EDNS w celu wypełnienia zapytań DoH do kilku typowych długości, co zapewnia ochronę przed analizą ruchu. Użycie dopełnienia HTTP/2 jest również możliwe, ale w przeciwieństwie do dopełnienia EDNS nie wywołuje dopełnienia w odpowiedziach z serwerów DoH.
Używaj metody POST RFC 8484 tylko w przypadku trybów przeglądarki i aplikacji wymagających ochrony prywatności
Używanie metody POST w przypadku zapytań DoH zmniejsza możliwość buforowania odpowiedzi i może zwiększyć opóźnienie DNS, więc ogólnie nie jest zalecane. Jednak zmniejszenie ilości pamięci podręcznej jest prawdopodobnie korzystne w przypadku aplikacji wrażliwych na ochronę prywatności i może uchronić przed atakami polegającymi na synchronizacji z aplikacjami internetowymi, które próbują ustalić, jakie domeny ostatnio odwiedzał użytkownik.
[null,null,["Ostatnia aktualizacja: 2025-07-25 UTC."],[[["\u003cp\u003eGoogle Public DNS offers two DoH APIs: \u003ccode\u003edns.google/dns-query\u003c/code\u003e (RFC 8484, GET & POST) and \u003ccode\u003edns.google/resolve\u003c/code\u003e (JSON API, GET only).\u003c/p\u003e\n"],["\u003cp\u003eDoH supports both IPv4 and IPv6 using HTTPS for enhanced security and wider accessibility.\u003c/p\u003e\n"],["\u003cp\u003eFor privacy, minimize HTTP headers, utilize EDNS padding, and consider RFC 8484 POST for sensitive applications.\u003c/p\u003e\n"],["\u003cp\u003eGoogle Public DNS returns various HTTP status codes, including 200 OK for success (check DNS response code for errors) and error codes like 400, 413, 414, 415, 429, 500, 501, and 502.\u003c/p\u003e\n"],["\u003cp\u003eDoH benefits include wider API support, access to all DNS record types for web apps, and potential performance improvements with QUIC.\u003c/p\u003e\n"]]],["Google Public DNS offers two DoH APIs: one using RFC 8484 (supporting GET and POST) and a JSON API (GET only). GET requests use Base64Url-encoded DNS messages in the query parameters; POST requests use binary DNS messages. The service returns standard HTTP status codes, including 200 OK for success, and various error codes (400, 413, 414, 415, 429, 500, 501, 502), with 301, 307, and 308 for redirection. Privacy best practices include limiting HTTP headers, using EDNS padding, and employing POST for sensitive applications.\n"],null,["# DNS-over-HTTPS (DoH)\n\nGoogle Public DNS provides two distinct DoH APIs at these endpoints:\n\n- https://dns.google/dns-query -- [RFC 8484](https://tools.ietf.org/html/rfc8484) (GET and POST)\n- https://dns.google/resolve? -- [JSON API](/speed/public-dns/docs/doh/json) (GET)\n\n| **Note:** There is also a human-friendly web interface at \u003chttps://dns.google/\u003e. This web app displays JSON results in a browser but does not implement an API; do not confuse its https://dns.google/query? URLs with the two API URLs.\n\nThe [Secure Transports Overview](/speed/public-dns/docs/secure-transports#doh)\npage has `curl` command line examples for using both APIs as well as details of\nTLS and other features common to both DNS over TLS (DoT) and DoH.\n\nDoH is also supported for the IPv6-only\n[Google Public DNS64 service](/speed/public-dns/docs/dns64#secure).\n\nGoogle Public DNS does not support insecure `http:` URLs for API calls.\n\nHTTP methods\n------------\n\nGET\n: Using the GET method can reduce latency, as it is cached more effectively.\n RFC 8484 GET requests must have a `?dns=` query parameter with a\n Base64Url encoded DNS message.\n The GET method is the only method supported for the JSON API.\n\nPOST\n: The POST method is only supported for the RFC 8484 API and uses a binary DNS\n message with Content-Type application/dns-message in the request body and in\n the DoH HTTP response.\n\nHEAD\n: *HEAD is not currently supported, and returns a 400 Bad Request error*.\n\nOther methods return 501 Not Implemented errors.\n\nHTTP status codes\n-----------------\n\nGoogle Public DNS DoH returns the following HTTP status codes:\n\n### Success\n\n200 OK\n: HTTP parsing and communication with DNS resolver was successful, and the\n response body content is a DNS response in either binary or JSON encoding,\n depending on the query endpoint, Accept header and GET parameters.\n| **Note:** An HTTP success may still be a DNS failure. Check the DNS response code (JSON \"Status\" field) for the DNS errors SERVFAIL, FORMERR, REFUSED, and NOTIMP.\n\n### Redirections\n\n301 Moved Permanently\n: Clients should retry at the URL provided in the `Location:` header. If the\n original query was a POST request, clients should only retry with GET if the\n new URL specifies a `dns` GET parameter argument; otherwise clients should\n retry with POST.\n\nOther codes such as 302 Found, 307 Temporary Redirect or 308 Permanent Redirect\nmay be used in the future, and DoH clients should handle all four codes.\n\nResponses with the permanent 301 and 308 codes should be cached indefinitely,\nand if practical, users may be prompted to update their original configuration\nusing the new URL.\n\nPOST requests that get 307 or 308 responses should always be retried with POST.\n\n### Errors\n\nError responses will have an explanation of the HTTP status in the body,\nusing either HTML or plain text.\n\n400 Bad Request\n: Problems parsing the GET parameters, or an invalid DNS request message.\n For bad GET parameters, the HTTP body should explain the error. Most invalid\n DNS messages get a 200 OK with a FORMERR; the HTTP error is returned for\n garbled messages with no Question section, a QR flag indicating a reply, or\n other nonsensical flag combinations with binary DNS parse errors.\n\n413 Payload Too Large\n: An RFC 8484 POST request body exceeded the 512 byte maximum message size.\n\n414 URI Too Long\n: The GET query header was too large or the `dns` parameter had a Base64Url\n encoded DNS message exceeding the 512 byte maximum message size.\n\n415 Unsupported Media Type\n: The POST body did not have an `application/dns-message` Content-Type header.\n\n429 Too Many Requests\n: The client has sent too many requests in a given amount of time. Clients\n should stop sending requests until the time specified in the Retry-After\n header (a relative time in seconds).\n\n500 Internal Server Error\n: Google Public DNS internal DoH errors.\n\n501 Not Implemented\n: Only GET and POST methods are implemented, other methods get this error.\n\n502 Bad Gateway\n: The DoH service could not contact Google Public DNS resolvers.\n\nIn the case of a 502 response, although retrying on an alternate Google Public\nDNS address might help, a more effective fallback response would be to try\nanother DoH service, or to switch to traditional UDP or TCP DNS at 8.8.8.8.\n\nBenefits of DoH\n---------------\n\nUsing HTTPS, not just TLS encryption, has some practical benefits:\n\n- Widely available and well-supported HTTPS APIs simplify implementation for both Google Public DNS itself and potential clients.\n- An HTTPS service provides web apps with access to all DNS record types, avoiding the limitations of existing browser and OS DNS APIs, which generally support only host-to-address lookups.\n- Clients that implement QUIC UDP-based HTTPS support can avoid problems like head-of-line blocking that can occur when using TCP transport.\n\nPrivacy Best Practices for DoH\n------------------------------\n\nDevelopers of DoH applications should consider the privacy best practices\noutlined in [RFC 8484](https://tools.ietf.org/html/rfc8484#section-8) and\nexpanded below:\n\n- Limit use of HTTP Headers\n\n HTTP headers reveal information about the client's DoH implementation and\n can be used to deanonymize clients. Headers like Cookie, User-Agent, and\n Accept-Language are the worst offenders, but even the set of headers sent\n can be revealing. To minimize this risk, send only the HTTP headers required\n for DoH: Host, Content-Type (for POST), and if necessary, Accept.\n User-Agent should be included in any development or testing versions.\n- Use EDNS padding options\n\n Follow the guidance in [RFC 8467](https://tools.ietf.org/html/rfc8467) for\n use of EDNS padding options to pad DoH queries to a few common lengths to\n protect against traffic analysis. Use of HTTP/2 padding is also possible but\n unlike EDNS padding, will not elicit padding on responses from DoH servers.\n- Use RFC 8484 POST only for privacy sensitive applications or browser modes\n\n Using POST for DoH queries reduces the cacheability of responses and can\n increase DNS latency, so it is not generally recommended. However, reducing\n caching is probably desirable for privacy sensitive applications, and might\n protect against timing attacks from web apps trying to determine what\n domains the user has visited lately.\n\nIssues\n------\n\nTo report a bug or request a new feature, please open an [issue for DoH](https://issuetracker.google.com/issues/new?component=191657&template=1189745)."]]
