Halaman Secure Transports Overview
memiliki contoh command line curl untuk menggunakan API serta detail
TLS dan fitur lain yang umum digunakan untuk DNS melalui TLS (DoT) dan DoH.
Google Public DNS tidak mendukung URL http: yang tidak aman untuk panggilan API.
Metode HTTP
GET
Menggunakan metode GET dapat mengurangi latensi, karena metode tersebut di-cache secara lebih efektif.
Permintaan GET RFC 8484 harus memiliki parameter kueri ?dns= dengan pesan DNS berenkode Base64Url.
Metode GET adalah satu-satunya metode yang didukung untuk JSON API.
POST
Metode POST hanya didukung untuk RFC 8484 API dan menggunakan pesan DNS biner
dengan aplikasi/dns-message Content-Type dalam isi permintaan dan dalam
respons HTTP DoH.
HEAD
HEAD saat ini tidak didukung dan menampilkan error 400 Bad Request.
Metode lain menampilkan error 501 Not Implemented.
Kode status HTTP
Google Public DNS DoH menampilkan kode status HTTP berikut:
Berhasil
200 OK
Penguraian HTTP dan komunikasi dengan resolver DNS berhasil, dan konten isi respons adalah respons DNS dalam encoding biner atau JSON, bergantung pada endpoint kuerinya, serta parameter GET dan header Accept.
Pengalihan
301 Dipindahkan Secara Permanen
Klien harus mencoba lagi di URL yang diberikan di header Location:. Jika kueri asli adalah permintaan POST, klien hanya boleh mencoba lagi dengan GET jika URL baru menentukan argumen parameter GET dns; jika tidak, klien harus mencoba lagi dengan POST.
Kode lain seperti 302 Found, 307 Temporary Redirect, atau Pengalihan Permanen 308 dapat digunakan di masa mendatang, dan klien DoH harus menangani keempat kode tersebut.
Respons dengan kode 301 dan 308 permanen harus di-cache tanpa batas waktu, dan jika memungkinkan, pengguna mungkin diminta untuk memperbarui konfigurasi awal mereka menggunakan URL baru.
Permintaan POST yang mendapatkan respons 307 atau 308 harus selalu dicoba lagi dengan POST.
Error
Respons error akan memiliki penjelasan tentang status HTTP di bagian isi, menggunakan HTML atau teks biasa.
400 Permintaan Buruk
Masalah saat menguraikan parameter GET, atau pesan permintaan DNS yang tidak valid.
Untuk parameter GET yang buruk, isi HTTP harus menjelaskan error. Sebagian besar pesan DNS yang tidak valid mendapatkan 200 OK dengan FORMERR; error HTTP ditampilkan untuk pesan yang kacau balau tanpa bagian Pertanyaan, flag QR yang menunjukkan balasan, atau kombinasi flag tidak masuk akal lainnya dengan error penguraian DNS biner.
Payload 413 Terlalu Besar
Isi permintaan POST RFC 8484 melampaui ukuran pesan maksimum 512 byte.
URI 414 Terlalu Panjang
Header kueri GET terlalu besar atau parameter dns memiliki pesan DNS yang dienkode Base64Url
yang melebihi ukuran pesan maksimum 512 byte.
Jenis Media 415 Tidak Didukung
Isi POST tidak memiliki header Content-Type application/dns-message.
429 Terlalu Banyak Permintaan
Klien telah mengirim terlalu banyak permintaan dalam jangka waktu tertentu. Klien harus berhenti mengirim permintaan hingga waktu yang ditentukan di header Retry-After (waktu relatif dalam detik).
500 Error Server Internal
Error DoH internal Google Public DNS.
501 Tidak Diterapkan
Hanya metode GET dan POST yang diterapkan, metode lain mendapatkan error ini.
502 Gateway Buruk
Layanan DoH tidak dapat menghubungi resolver Google Public DNS.
Dalam kasus respons 502, meskipun mencoba ulang alamat DNS Publik
Google alternatif mungkin dapat membantu, respons penggantian yang lebih efektif adalah mencoba
layanan DoH lain, atau beralih ke DNS UDP atau TCP tradisional di 8.8.8.8.
Manfaat DoH
Menggunakan HTTPS, bukan hanya enkripsi TLS, memiliki beberapa manfaat praktis:
API HTTPS yang tersedia secara luas dan didukung dengan baik akan menyederhanakan implementasi untuk
Google Public DNS itu sendiri dan calon klien.
Layanan HTTPS memberi aplikasi web akses ke semua jenis data DNS,
sehingga menghindari batasan API DNS OS dan browser yang ada, yang
umumnya hanya mendukung pencarian host-ke-alamat.
Klien yang menerapkan dukungan HTTPS berbasis QUIC UDP dapat menghindari masalah seperti
pemblokiran head-of-line yang dapat terjadi saat menggunakan transpor TCP.
Praktik Terbaik Privasi untuk Departemen Kesehatan
Developer aplikasi DoH harus mempertimbangkan praktik terbaik privasi
yang diuraikan dalam RFC 8484 dan
diperluas di bawah:
Membatasi penggunaan Header HTTP
Header HTTP mengungkapkan informasi tentang implementasi DoH klien dan dapat digunakan untuk mendeanonimisasi klien. Header seperti Cookie, Agen Pengguna, dan
Accept-Language adalah pelanggar terburuk, tetapi bahkan kumpulan header yang dikirim
dapat terungkap. Untuk meminimalkan risiko ini, hanya kirim header HTTP yang diperlukan
untuk DoH: Host, Content-Type (untuk POST), dan jika perlu, Accept.
Agen Pengguna harus disertakan dalam setiap versi pengembangan atau pengujian.
Menggunakan opsi padding EDNS
Ikuti panduan di RFC 8467 untuk
penggunaan opsi padding EDNS guna menambahkan kueri DoH ke beberapa panjang umum untuk
melindungi dari analisis traffic. Penggunaan padding HTTP/2 juga dapat dilakukan, tetapi
tidak seperti padding EDNS, tidak akan menimbulkan padding pada respons dari server DoH.
Gunakan RFC 8484 POST hanya untuk aplikasi atau mode browser yang sensitif terhadap privasi
Menggunakan kueri POST untuk DoH akan mengurangi kemampuan cache respons dan dapat meningkatkan latensi DNS, sehingga umumnya tidak direkomendasikan. Namun, mengurangi
cache mungkin diinginkan untuk aplikasi yang sensitif terhadap privasi, dan dapat
melindungi dari serangan waktu dari aplikasi web yang mencoba menentukan
domain yang telah dikunjungi pengguna akhir-akhir ini.
Masalah
Untuk melaporkan bug atau meminta fitur baru, buka masalah untuk DoH.
[null,null,["Terakhir diperbarui pada 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)."]]
