Auf der Seite Übersicht über sichere Transporte finden Sie curl-Befehlszeilenbeispiele für die Verwendung beider APIs sowie Details zu TLS und anderen gemeinsamen Funktionen von DNS über TLS (DoT) und DoH.
Google Public DNS unterstützt keine unsicheren http:-URLs für API-Aufrufe.
HTTP-Methoden
GET
Die GET-Methode kann die Latenz reduzieren, da sie effektiver zwischengespeichert wird.
RFC 8484-GET-Anfragen müssen einen ?dns=-Abfrageparameter mit einer base64Url-codierten DNS-Nachricht enthalten.
Die GET-Methode ist die einzige unterstützte Methode für die JSON API.
POST
Die POST-Methode wird nur für die RFC 8484 API unterstützt und verwendet eine binäre DNS-Nachricht mit „Content-Type application/dns-message“ im Anfragetext und in der DoH-HTTP-Antwort.
HEAD
HEAD wird derzeit nicht unterstützt und gibt einen „400 Bad Request“-Fehler zurück.
Bei anderen Methoden wird der Fehler „501 Not Implemented“ zurückgegeben.
HTTP-Statuscodes
Google Public DNS DoH gibt die folgenden HTTP-Statuscodes zurück:
Abgeschlossen
200 OK
Das HTTP-Parsing und die Kommunikation mit dem DNS-Resolver waren erfolgreich. Der Inhalt des Antworttexts ist eine DNS-Antwort in Binär- oder JSON-Codierung, abhängig vom Abfrageendpunkt, dem Accept-Header und den GET-Parametern.
Weiterleitungen
301-Fehler dauerhaft verschoben
Clients sollten den Vorgang unter der im Location:-Header angegebenen URL wiederholen. Wenn die ursprüngliche Abfrage eine POST-Anfrage war, sollten Clients den Vorgang nur mit GET wiederholen, wenn die neue URL das GET-Parameterargument dns angibt. Andernfalls sollten Clients es noch einmal mit POST versuchen.
Andere Codes wie 302 Found, 307 Temporary Redirect oder 308 Permanent Redirect können in Zukunft verwendet werden. DoH-Clients sollten alle vier Codes verarbeiten.
Antworten mit den permanenten 301- und 308-Codes sollten für unbegrenzte Zeit im Cache gespeichert werden. Nutzer können gegebenenfalls aufgefordert werden, ihre ursprüngliche Konfiguration mithilfe der neuen URL zu aktualisieren.
POST-Anfragen, die 307- oder 308-Antworten erhalten, sollten immer mit POST wiederholt werden.
Fehler
In Fehlerantworten wird der HTTP-Status im Text entweder im HTML-Text oder im Nur-Text-Format erklärt.
400 Fehlerhafte Anfrage
Probleme beim Parsen der GET-Parameter oder eine ungültige Nachricht zur DNS-Anfrage
Bei fehlerhaften GET-Parametern sollte der Fehler im HTTP-Text angegeben werden. Die meisten ungültigen DNS-Nachrichten erhalten mit einem FORMERR 200 OK. Der HTTP-Fehler wird bei unleserlichen Nachrichten ohne Frageabschnitt, bei einem QR-Flag, das eine Antwort anzeigt, oder bei anderen unsinnigen Flag-Kombinationen mit binären DNS-Parsing-Fehlern zurückgegeben.
413 Payload Too Large (Nutzlast zu groß)
Ein RFC 8484-POST-Anfragetext überschreitet die maximale Nachrichtengröße von 512 Byte.
414 URI Too Long (URI zu lang)
Der GET-Abfrageheader war zu groß oder der Parameter dns enthielt eine Base64Url-codierte DNS-Nachricht, die die maximale Nachrichtengröße von 512 Byte überschreitet.
415 Nicht unterstützter Medientyp
Der POST-Textkörper hatte keinen application/dns-message Content-Type-Header.
429 Zu viele Anfragen
Der Client hat zu viele Anfragen in einem bestimmten Zeitraum gesendet. Clients sollten das Senden von Anfragen bis zu dem im Header „Wiederholen“ angegebenen Zeitpunkt stoppen (eine relative Zeit in Sekunden).
500 Interner Serverfehler
Interne DoH-Fehler bei Google Public DNS.
501 Nicht implementiert
Nur GET- und POST-Methoden sind implementiert, andere Methoden erhalten diesen Fehler.
502 Fehlerhaftes Gateway
Der DoH-Dienst konnte keine Google Public DNS-Resolver kontaktieren.
Bei einer 502-Antwort wäre ein Versuch mit einer alternativen Google Public DNS-Adresse hilfreich, eine effektivere Fallback-Antwort wäre es jedoch, einen anderen DoH-Dienst zu verwenden oder zum traditionellen UDP- oder TCP-DNS unter 8.8.8.8 zu wechseln.
Vorteile des DoH
Die Verwendung von HTTPS und nicht nur der TLS-Verschlüsselung bietet einige praktische Vorteile:
Breiter verfügbare und gut unterstützte HTTPS-APIs vereinfachen die Implementierung sowohl für Google Public DNS selbst als auch für potenzielle Clients.
Ein HTTPS-Dienst bietet Webanwendungen Zugriff auf alle DNS-Eintragstypen und vermeidet so die Einschränkungen vorhandener Browser- und Betriebssystem-DNS-APIs, die im Allgemeinen nur Host-zu-Adress-Lookups unterstützen.
Clients, die QUIC-UDP-basierte HTTPS-Unterstützung implementieren, können Probleme wie die Head-of-Line-Blockierung vermeiden, die bei der Verwendung von TCP-Transport auftreten können.
Best Practices für Datenschutz bei DoH
Entwickler von DoH-Anwendungen sollten die Best Practices zum Datenschutz berücksichtigen, die in RFC 8484 beschrieben sind und weiter unten aufgeführt sind:
Verwendung von HTTP-Headern einschränken
HTTP-Header enthalten Informationen zur DoH-Implementierung des Clients und können zur Deanonymisierung von Clients verwendet werden. Header wie Cookie, User-Agent und Accept-Language sind die schlimmsten Verstöße, aber selbst die gesendeten Header können verwirrend sein. Senden Sie nur die HTTP-Header, die für DoH erforderlich sind, um dieses Risiko zu minimieren: Host, Content-Type (für POST) und ggf. Accept.
Der User-Agent sollte in allen Entwicklungs- oder Testversionen enthalten sein.
EDNS-Padding-Optionen verwenden
Folgen Sie der Anleitung in RFC 8467 für die Verwendung von EDNS-Padding-Optionen, um DoH-Abfragen mit einigen gängigen Längen aufzufüllen, um sich vor Traffic-Analysen zu schützen. Die Verwendung von HTTP/2-Padding ist ebenfalls möglich. Im Gegensatz zum EDNS-Padding wird bei Antworten von DoH-Servern jedoch kein Padding ausgelöst.
Verwenden Sie RFC 8484 POST nur für Anwendungen, die vertrauliche Daten enthalten, oder für Browsermodi.
Die Verwendung von POST für DoH-Abfragen reduziert die Cache-Fähigkeit von Antworten und kann die DNS-Latenz erhöhen. Daher wird POST generell nicht empfohlen. Bei datenschutzempfindlichen Anwendungen ist eine Reduzierung des Cachings jedoch wahrscheinlich wünschenswert und kann vor zeitlichen Angriffen von Webanwendungen schützen, die versuchen zu ermitteln, welche Domains der Nutzer in letzter Zeit besucht hat.
[null,null,["Zuletzt aktualisiert: 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)."]]
