用于 DNS over HTTPS (DoH) 的 JSON API

以前,基于网络的应用需要浏览器扩展程序才能使用 DANEDNS-SD 服务发现等高级 DNS 功能,甚至需要解析 IP 地址以外的任何内容(例如 MX 记录)。如需使用依赖于 DNSSEC 的功能(如 SSHFP 记录),任何此类扩展程序都必须自行验证 DNSSEC,因为浏览器或操作系统可能不会这样做。

自 2016 年以来,Google 公共 DNS 为 DoH 提供了适合 Web 的 API,可通过 DNSSEC 验证,而无需浏览器或操作系统配置或扩展程序。借助简单的 GET 查询参数和 JSON 响应,客户端可以使用通用 Web API 解析结果,并避免复杂的 DNS 消息格式细节,例如域名的指针压缩

请参阅常规 DoH 文档页面,大致了解 DoH,例如 HTTP 标头、重定向处理、隐私保护最佳实践和 HTTP 状态代码。

安全传输页面提供了 DoH 的 curl 命令行示例,以及 DoH 和 DNS over TLS (DoT) 的通用信息,例如 TLS 支持和 DNS 截断。

JSON API 规范

所有 API 调用都是 HTTP GET 请求。 如果参数重复,则仅使用第一个值。

支持的参数

name

字符串,必填

唯一的必需参数。接受 RFC 4343 反斜杠转义。

  • 长度(替换反斜杠转义后)必须介于 1 到 253 之间(如果存在可选的尾随点,则忽略)。
  • 所有标签(点之间的部分名称)的长度必须为 1 到 63 个字节。
  • 无效名称(如 .example.comexample..com)或空字符串 get 400 Bad Request。
  • 非 ASCII 字符应进行国际化域名编码xn--qxam,而不是 ελ)。
类型

字符串,默认值:1

RR 类型可以表示为 [1, 65535] 中的数字或规范字符串(不区分大小写,例如 Aaaaa)。您可以将 255 用于“任意”查询,但请注意,这不能替代同时发送针对 A 记录、AAAA 或 MX 记录的查询。权威域名服务器无需返回此类查询的所有记录;有些服务器不会响应,而其他域名服务器(例如 cloudflare.com)仅返回 HINFO。

cd

布尔值,默认值:false

CD(正在检查已停用)标志。 使用 cd=1cd=true 停用 DNSSEC 验证;使用 cd=0cd=false 或不使用 cd 参数来启用 DNSSEC 验证。

字符串,默认:空

所需内容类型选项。 使用 ct=application/dns-message 在响应 HTTP 正文中接收二进制 DNS 消息(而不是 JSON 文本)。使用 ct=application/x-javascript 明确请求 JSON 文本。其他内容类型值会被忽略,并返回默认 JSON 内容。

do

布尔值,默认值:false

DO (DNSSEC OK) 标志。 使用 do=1do=true 包含 DNSSEC 记录(RRSIG、NSEC、NSEC3);使用 do=0do=false 或不使用 do 参数可省略 DNSSEC 记录。

应用应始终处理(并在必要时忽略)JSON 响应中的任何 DNSSEC 记录,因为其他实现可能始终包含这些记录,并且我们以后可能会更改 JSON 响应的默认行为。(二进制 DNS 消息响应始终遵循 DO 标志的值。)

edns_client_subnet

字符串,默认:空

edns0-client-subnet 选项。格式为具有子网掩码的 IP 地址。 示例:1.2.3.4/242001:700:300::/48

如果您出于隐私方面的考虑而使用 DNS-over-HTTPS,并且不希望将 IP 地址的任何部分发送到权威域名服务器以确保地理位置的准确性,请使用 edns_client_subnet=0.0.0.0/0Google 公共 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 响应中的顶级字段。