過去,網頁應用程式需要瀏覽器擴充功能才能使用進階 DNS 功能,例如 DANE、DNS-SD 服務探索,甚至是解析 IP 位址以外的任何內容,例如 MX 記錄。如要使用 DNSSEC 依附功能 (例如 SSHFP 記錄),這類擴充功能都必須自行驗證 DNSSEC,因為瀏覽器或 OS 可能無法執行。
自 2016 年起,Google 公用 DNS 便提供適用於 DoH 且具備 DNSSEC 驗證的 DoH 網路,且不需要瀏覽器或作業系統設定或擴充功能。簡單的 GET 查詢參數和 JSON 回應可讓用戶端使用常見的網路 API 剖析結果,並避免使用網域名稱指標壓縮等複雜的 DNS 訊息格式詳細資料。
請參閱一般 DoH 說明文件頁面,瞭解 DoH 的一般資訊,例如 HTTP 標頭、重新導向處理、隱私權最佳做法以及 HTTP 狀態碼。
「安全傳輸」頁面提供 DoH 的 curl
指令列範例,以及 DoH 和 DNS over TLS (DoT) 通用的資訊,例如 TLS 支援和 DNS 截斷。
JSON API 規格
所有 API 呼叫都是 HTTP GET 要求。如果有重複的參數,系統只會使用第一個值。
支援的參數
- 名稱
字串,必要
唯一的必要參數。系統接受 RFC 4343 反斜線逸出。
- 長度 (取代反斜線逸出後) 必須介於 1 到 253 之間 (如有選用的結尾點,系統會忽略這個結尾點)。
- 所有標籤 (點之間的名稱部分) 長度必須介於 1 到 63 位元組之間。
.example.com
、example..com
等無效名稱,或是空字串 get 400 Bad Request。- 非 ASCII 字元應採用 Puny 編碼 (
xn--qxam
,而非ελ
)。
- 類型
字串,預設值:
1
RR 類型可以使用 [1, 65535] 的數字,或標準字串 (不區分大小寫,例如
A
或aaaa
) 表示。您可以在「ANY」查詢中使用255
,但請注意,這「不是」取代 A 和 AAAA 或 MX 記錄的查詢。權威名稱伺服器不需要傳回這類查詢的所有記錄;有些伺服器不會回應,而其他伺服器 (例如 cloudflare.com) 只會傳回 HINFO。- cd
布林值,預設值:
false
CD (勾選已停用) 標記。請使用
cd=1
或cd=true
停用 DNSSEC 驗證;使用cd=0
、cd=false
或不使用cd
參數來啟用 DNSSEC 驗證。- 個
字串,預設值:空白
所需的內容類型選項。使用
ct=application/dns-message
在回應 HTTP 主體中接收二進位 DNS 訊息,而非 JSON 文字。使用ct=application/x-javascript
明確要求 JSON 文字。系統會忽略其他內容類型值,並傳回預設的 JSON 內容。- do
布林值,預設值:
false
DO (DNSSEC OK) 標記。使用
do=1
或do=true
以納入 DNSSEC 記錄 (RRSIG、NSEC、NSEC3);使用do=0
、do=false
或不使用do
參數來省略 DNSSEC 記錄。應用程式應一律處理 (並在必要時忽略) JSON 回應中的任何 DNSSEC 記錄,因為其他實作項目可能會包含這些記錄,而我們日後可能會變更 JSON 回應的預設行為。(二進位 DNS 訊息回應一律會遵循 DO 旗標的值)。
- edns_client_subnet
字串,預設值:空白
edns0-client-subnet 選項。格式為具有子網路遮罩的 IP 位址。範例:
1.2.3.4/24
、2001:700:300::/48
。假如您因為隱私權疑慮而使用 DNS-over-HTTPS,而且您不希望 IP 位址的任何部分傳送至權威名稱伺服器,藉此取得地理位置準確度,請使用
edns_client_subnet=0.0.0.0/0
。Google 公用 DNS 通常會傳送近似網路資訊 (通常會將 IPv4 位址的最後一部分去除)。- random_padding
字串,已忽略
系統會忽略這項參數的值。範例:
XmkMw~o_mgP2pf.gpw-Oi5dK
。當 API 用戶端擔心使用 HTTPS GET 要求的封包大小時,可能會遭受旁路隱私權攻擊的問題,可以在為要求加上隨機資料填補要求,使所有要求的大小都相同。為避免網址被誤解,請將邊框間距字元限制在未保留的網址字元中:大寫和小寫英文字母、數字、連字號、句號、底線和波浪號。
JSON 格式的 DNS 回應
成功的回應 (在這裡新增的留言不會顯示在實際回應中):
{
"Status": 0, // NOERROR - Standard DNS response code (32 bit integer).
"TC": false, // Whether the response is truncated
"RD": true, // Always true for Google Public DNS
"RA": true, // Always true for Google Public DNS
"AD": false, // Whether all response data was validated with DNSSEC
"CD": false, // Whether the client asked to disable DNSSEC
"Question":
[
{
"name": "apple.com.", // FQDN with trailing dot
"type": 1 // A - Standard DNS RR type
}
],
"Answer":
[
{
"name": "apple.com.", // Always matches name in the Question section
"type": 1, // A - Standard DNS RR type
"TTL": 3599, // Record's time-to-live in seconds
"data": "17.178.96.59" // Data for A - IP address as text
},
{
"name": "apple.com.",
"type": 1,
"TTL": 3599,
"data": "17.172.224.47"
},
{
"name": "apple.com.",
"type": 1,
"TTL": 3599,
"data": "17.142.160.59"
}
],
"edns_client_subnet": "12.34.56.78/0" // IP address / scope prefix-length
}
如要進一步瞭解「範圍前置字串長度」以及其對快取的影響,請參閱 RFC 7871 (EDNS 用戶端子網路)。
包含診斷資訊的失敗回應:
{
"Status": 2, // SERVFAIL - Standard DNS response code (32 bit integer).
"TC": false, // Whether the response is truncated
"RD": true, // Always true for Google Public DNS
"RA": true, // Always true for Google Public DNS
"AD": false, // Whether all response data was validated with DNSSEC
"CD": false, // Whether the client asked to disable DNSSEC
"Question":
[
{
"name": "dnssec-failed.org.", // FQDN with trailing dot
"type": 1 // A - Standard DNS RR type
}
],
"Comment": "DNSSEC validation failure. Please check http://dnsviz.net/d/dnssec-failed.org/dnssec/."
}
含有內嵌引號和名稱伺服器歸因的 SPF 和 TXT 記錄:
{
"Status": 0, // NOERROR - Standard DNS response code (32 bit integer).
"TC": false, // Whether the response is truncated
"RD": true, // Always true for Google Public DNS
"RA": true, // Always true for Google Public DNS
"AD": false, // Whether all response data was validated with DNSSEC
"CD": false, // Whether the client asked to disable DNSSEC
"Question": [
{
"name": "*.dns-example.info.", // FQDN with trailing dot
"type": 99 // SPF - Standard DNS RR type
}
],
"Answer": [
{
"name": "*.dns-example.info.", // Always matches name in Question
"type": 99, // SPF - Standard DNS RR type
"TTL": 21599, // Record's time-to-live in seconds
"data": "\"v=spf1 -all\"" // Data for SPF - quoted string
}
],
"Comment": "Response from 216.239.38.110"
// Uncached responses are attributed to the authoritative name server
}
{
"Status": 0, // NOERROR - Standard DNS response code (32 bit integer).
"TC": false, // Whether the response is truncated
"RD": true, // Always true for Google Public DNS
"RA": true, // Always true for Google Public DNS
"AD": false, // Whether all response data was validated with DNSSEC
"CD": false, // Whether the client asked to disable DNSSEC
"Question": [
{
"name": "s1024._domainkey.yahoo.com.", // FQDN with trailing dot
"type": 16 // TXT - Standard DNS RR type
}
],
"Answer": [
{
"name": "s1024._domainkey.yahoo.com.", // Always matches Question name
"type": 16, // TXT - Standard DNS RR type
"data": "\"k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDrEee0Ri4Juz+QfiWYui/E9UGSXau/2P8LjnTD8V4Unn+2FAZVGE3kL23bzeoULYv4PeleB3gfm\"\"JiDJOKU3Ns5L4KJAUUHjFwDebt0NP+sBK0VKeTATL2Yr/S3bT/xhy+1xtj4RkdV7fVxTn56Lb4udUnwuxK4V5b5PdOKj/+XcwIDAQAB; n=A 1024 bit key;\""
// Data for TXT - multiple quoted strings
}
],
}
DNS 字串
所有 TXT 記錄都會編碼為單一 JSON 字串,包括使用較長的 TXT 記錄格式,例如 RFC 4408 (SPF) 或 RFC 4871 (DKIM)。
EDNS
系統不支援一般的 EDNS 擴充功能機制。EDNS 用戶端子網路選項 (edns-client-subnet) 是 GET 要求中的參數,以及 JSON 回應中的頂層欄位。