La pagina Panoramica sui trasporti sicuri contiene curl esempi di riga di comando per l'utilizzo di entrambe le API e dettagli di TLS e di altre funzionalità comuni a DNS tramite TLS (DoT) e DoH.
Il DNS pubblico di Google non supporta URL http: non sicuri per le chiamate API.
Metodi HTTP
GET
L'utilizzo del metodo GET può ridurre la latenza poiché viene memorizzato nella cache in modo più efficace.
Le richieste GET RFC 8484 devono avere un parametro di query ?dns= con un messaggio DNS con codifica Base64Url.
Il metodo Get è l'unico supportato per l'API JSON.
POST
Il metodo POST è supportato solo per l'API RFC 8484 e utilizza un messaggio DNS binario con applicazione Content-Type/dns-message nel corpo della richiesta e nella risposta HTTP DoH.
HEAD
HEAD non è attualmente supportato e restituisce un errore 400 Bad Request (Richiesta errata).
Gli altri metodi restituiscono errori 501 Not Implemented (Non implementato).
Codici di stato HTTP
Google Public DNS DoH restituisce i seguenti codici di stato HTTP:
Operazione riuscita
200 OK
L'analisi HTTP e la comunicazione con il resolver DNS sono riuscite e il contenuto del corpo della risposta è una risposta DNS con codifica binaria o JSON, a seconda dell'endpoint di query, dell'intestazione Accept e dei parametri GET.
Reindirizzamenti
301 Spostato in modo permanente
I clienti dovrebbero riprovare all'URL fornito nell'intestazione Location:. Se la query originale era una richiesta POST, i client devono riprovare con GET solo se il nuovo URL specifica un argomento del parametro GET dns; in caso contrario, i client devono riprovare con POST.
In futuro potrebbero essere utilizzati altri codici come 302 Found, 307 Temporary Redirect o 308 Permanent Redirect e i client DoH dovrebbero gestire tutti e quattro i codici.
Le risposte con i codici 301 e 308 permanenti devono essere memorizzate nella cache a tempo indeterminato e, se possibile, agli utenti potrebbe essere richiesto di aggiornare la configurazione originale utilizzando il nuovo URL.
Le richieste POST che ricevono risposte 307 o 308 devono sempre essere ritentate con POST.
Errori
Le risposte di errore forniscono una spiegazione dello stato HTTP nel corpo,
utilizzando HTML o testo normale.
richiesta non valida (400)
Problemi di analisi dei parametri GET o un messaggio di richiesta DNS non valido.
Per i parametri GET non validi, il corpo HTTP deve spiegare l'errore. Alla maggior parte dei messaggi DNS non validi viene assegnato un valore di 200 OK con FORMERR; l'errore HTTP viene restituito per i messaggi incomprensibili senza la sezione di domande, un flag QR che indica una risposta o altre combinazioni di flag senza senso con errori di analisi DNS binaria.
413 Payload troppo grande
Il corpo di una richiesta POST RFC 8484 ha superato la dimensione massima del messaggio di 512 byte.
URI 414 troppo lungo
L'intestazione della query GET era troppo grande oppure il parametro dns aveva un messaggio DNS codificato in Base64Url che superava la dimensione massima del messaggio di 512 byte.
415 Tipo di supporto non supportato
Il corpo del POST non aveva un'intestazione Content-Type application/dns-message.
429 Troppe richieste
Il client ha inviato troppe richieste in un determinato periodo di tempo. I client
devono interrompere l'invio delle richieste fino al momento specificato nell'intestazione Riprova-Dopo (un tempo relativo in secondi).
Errore interno del server (500)
Errori DoH interni del DNS pubblico di Google.
501 Non implementato
Solo i metodi GET e POST sono implementati, altri metodi ricevono questo errore.
gateway non valido (502)
Il servizio DoH non è riuscito a contattare i resolver DNS pubblici di Google.
Nel caso di una risposta 502, anche se un nuovo tentativo con un indirizzo Google Public DNS alternativo potrebbe essere utile, una risposta di fallback più efficace potrebbe essere provare un altro servizio DoH o passare al DNS tradizionale UDP o TCP all'indirizzo 8.8.8.8.
Vantaggi di DoH
L'utilizzo di HTTPS, non solo della crittografia TLS, presenta alcuni vantaggi pratici:
Le API HTTPS ampiamente disponibili e ben supportate semplificano l'implementazione sia per Google Public DNS stesso sia per i potenziali clienti.
Un servizio HTTPS fornisce alle app web l'accesso a tutti i tipi di record DNS, evitando le limitazioni delle API DNS esistenti del browser e del sistema operativo, che in genere supportano solo le ricerche host-to-address.
I client che implementano il supporto HTTPS basato su QUIC UDP possono evitare problemi come il blocco head-of-line che può verificarsi quando si utilizza il trasporto TCP.
Best practice sulla privacy per DoH
Gli sviluppatori di applicazioni DoH devono prendere in considerazione le best practice sulla privacy descritte in RFC 8484 ed ampliate di seguito:
Limita l'utilizzo delle intestazioni HTTP
Le intestazioni HTTP rivelano informazioni sull'implementazione DoH del client e possono essere utilizzate per anonimizzare i client. Intestazioni come Cookie, User-Agent e
Accetta-Language sono le violazioni peggiori, ma anche l'insieme di intestazioni inviate
può essere rivelatore. Per ridurre al minimo questo rischio, invia solo le intestazioni HTTP richieste per DoH: Host, Content-Type (per POST) e, se necessario, Accept.
Lo user agent deve essere incluso in qualsiasi versione di sviluppo o test.
Utilizzare le opzioni di spaziatura interna EDNS
Segui le indicazioni riportate in RFC 8467 per l'utilizzo delle opzioni di spaziatura interna EDNS per comprimere le query DoH di poche lunghezze comuni per evitare l'analisi del traffico. È anche possibile l'utilizzo della spaziatura interna HTTP/2 ma, a differenza di quella EDNS, non causerà un spaziatura interna nelle risposte dai server DoH.
Utilizza RFC 8484 POST solo per applicazioni sensibili alla privacy o modalità del browser
L'utilizzo di POST per le query DoH riduce la memorizzazione nella cache delle risposte e può aumentare la latenza DNS, pertanto non è consigliato in genere. Tuttavia, la riduzione della memorizzazione nella cache è probabilmente auspicabile per le applicazioni sensibili alla privacy e potrebbe proteggere dalla tempestività degli attacchi da parte delle app web che cercano di determinare quali domini l'utente ha visitato di recente.
Problemi
Per segnalare un bug o richiedere una nuova funzionalità, apri un problema per DoH.
[null,null,["Ultimo aggiornamento 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)."]]
