La page de présentation des transferts sécurisés contient des exemples de ligne de commande curl permettant d'utiliser les deux API, ainsi que des informations sur TLS et d'autres fonctionnalités communes au DNS sur TLS (DoT) et à DoH.
Le DNS public de Google n'accepte pas les URL http: non sécurisées pour les appels d'API.
Méthodes HTTP
GET
La méthode GET permet de réduire la latence, car elle est mise en cache de manière plus efficace.
Les requêtes GET RFC 8484 doivent comporter un paramètre de requête ?dns= avec un message DNS encodé en Base64Url.
La méthode GET est la seule méthode compatible avec l'API JSON.
POST
La méthode POST n'est compatible qu'avec l'API RFC 8484 et utilise un message DNS binaire avec Content-Type application/dns-message dans le corps de la requête et la réponse HTTP DoH.
HEAD
La balise HEAD n'est pas acceptée pour le moment et renvoie une erreur "400 Bad Request".
D'autres méthodes renvoient des erreurs "501 Not Implemented".
Codes d'état HTTP
Google Public DNS DoH renvoie les codes d'état HTTP suivants:
Réussite
200 OK
L'analyse HTTP et la communication avec le résolveur DNS ont abouti, et le corps de la réponse est une réponse DNS au format binaire ou JSON, en fonction du point de terminaison de la requête, de l'en-tête Accept et des paramètres GET.
Redirections
301 (Changement d'adresse définitif)
Les clients doivent réessayer à l'URL fournie dans l'en-tête Location:. Si la requête d'origine était une requête POST, les clients ne doivent effectuer une nouvelle tentative avec GET que si la nouvelle URL spécifie un argument de paramètre GET dns. Sinon, ils doivent effectuer une nouvelle tentative avec POST.
D'autres codes tels que "302 Found", "307 Temporary Redirect" ou "308 Permanent Redirect" peuvent être utilisés à l'avenir. Les clients DoH doivent gérer les quatre codes.
Les réponses contenant les codes permanents 301 et 308 doivent être mises en cache indéfiniment. Si possible, les utilisateurs peuvent être invités à mettre à jour leur configuration d'origine à l'aide de la nouvelle URL.
Les requêtes POST qui reçoivent des réponses 307 ou 308 doivent toujours être relancées avec la méthode POST.
Erreurs
Les réponses d'erreur contiendront une explication de l'état HTTP dans le corps, au format HTML ou texte brut.
400 Requête incorrecte
Problèmes lors de l'analyse des paramètres GET ou message de requête DNS non valide.
En cas de paramètres GET incorrects, le corps HTTP doit expliquer l'erreur. La plupart des messages DNS non valides obtiennent un code d'erreur 200 avec FORMERR. L'erreur HTTP est renvoyée pour les messages illisibles sans section "Question", un indicateur QR indiquant une réponse ou d'autres combinaisons d'indicateurs absurdes avec des erreurs d'analyse DNS binaire.
413 Payload Too Large (Charge utile trop élevée)
Le corps d'une requête POST RFC 8484 dépassait la taille maximale d'un message de 512 octets.
414 URI Too Long (URI trop long)
L'en-tête de requête GET est trop volumineux, ou le paramètre dns comporte un message DNS encodé en Base64Url dépassant la taille maximale de message de 512 octets.
415 Type de contenu non accepté
Le corps POST ne comportait pas d'en-tête "Content-Type" application/dns-message.
429 Trop de requêtes
Le client a envoyé trop de requêtes sur un laps de temps donné. Les clients doivent cesser d'envoyer des requêtes jusqu'à l'heure spécifiée dans l'en-tête Réessayer-After (temps relatif en secondes).
500 Erreur interne au serveur
Erreurs DoH internes du DNS public de Google.
501 Non implémenté
Seules les méthodes GET et POST sont implémentées. Les autres méthodes reçoivent cette erreur.
502 Passerelle incorrecte
Le service DoH n'a pas pu contacter les résolveurs DNS publics Google.
Dans le cas d'une réponse 502, bien qu'une nouvelle tentative sur une autre adresse DNS publique Google puisse aider, une réponse de remplacement plus efficace consisterait à essayer un autre service DoH, ou à passer au DNS UDP ou TCP traditionnel à l'adresse 8.8.8.8.
Avantages de DoH
En plus du chiffrement TLS, l'utilisation du protocole HTTPS présente des avantages pratiques:
Les API HTTPS largement disponibles et bien prises en charge simplifient l'implémentation pour le DNS public de Google lui-même et pour les clients potentiels.
Un service HTTPS fournit aux applications Web un accès à tous les types d'enregistrements DNS, évitant ainsi les limites des API DNS de navigateur et d'OS existantes, qui ne prennent généralement en charge que les recherches hôte à adresse.
Les clients qui implémentent la compatibilité HTTPS basée sur le protocole QUIC UDP peuvent éviter des problèmes tels que le blocage en tête de ligne qui peut survenir lors de l'utilisation du transport TCP.
Bonnes pratiques concernant la confidentialité pour DoH
Les développeurs d'applications DoH doivent tenir compte des bonnes pratiques en matière de confidentialité décrites dans le document RFC 8484 et développées ci-dessous:
Limiter l'utilisation des en-têtes HTTP
Les en-têtes HTTP fournissent des informations sur l'implémentation DoH du client et peuvent être utilisés pour désanonymiser les clients. Des en-têtes tels que "Cookie", "User-Agent" et "Accept-Language" sont les pires contrevenants, mais même l'ensemble d'en-têtes envoyés peut être révélateur. Pour réduire ce risque, n'envoyez que les en-têtes HTTP requis pour DoH: Host, Content-Type (pour POST) et, si nécessaire, Accept.
Le user-agent doit être inclus dans toutes les versions de développement ou de test.
Utiliser les options de marge intérieure EDNS
Suivez les conseils de la RFC 8467 concernant l'utilisation des options de marge intérieure EDNS pour remplir les requêtes DoH sur quelques longueurs courantes afin de vous protéger contre l'analyse du trafic. L'utilisation du remplissage HTTP/2 est également possible, mais contrairement au remplissage EDNS, il n'entraîne pas de remplissage pour les réponses des serveurs DoH.
Utilisez la norme POST RFC 8484 uniquement pour les applications ou les modes de navigation sensibles à la confidentialité.
L'utilisation de la méthode POST pour les requêtes DoH réduit la mise en cache des réponses et peut augmenter la latence DNS. Elle n'est donc généralement pas recommandée. Toutefois, la réduction de la mise en cache est probablement souhaitable pour les applications sensibles à la confidentialité. Elle peut vous protéger contre les attaques temporelles des applications Web qui tentent de déterminer les domaines que l'utilisateur a consultés dernièrement.
Problèmes
Pour signaler un bug ou demander une nouvelle fonctionnalité, veuillez signaler un problème lié à DoH.
Sauf indication contraire, le contenu de cette page est régi par une licence Creative Commons Attribution 4.0, et les échantillons de code sont régis par une licence Apache 2.0. Pour en savoir plus, consultez les Règles du site Google Developers. Java est une marque déposée d'Oracle et/ou de ses sociétés affiliées.
Dernière mise à jour le 2025/07/25 (UTC).
[null,null,["Dernière mise à jour le 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)."]]
