JSON API for HTTPS over HTTPS (DoH)

以前， Web 应用需要浏览器扩展程序才能使用高级 DNS 功能，例如 DANE、DNS-SD 服务发现，甚至用于解析除 IP 地址以外的其他内容（如 MX 记录）。若要使用依赖 DNSSEC 的功能（如 SSHFP 记录），任何此类扩展程序都必须自行验证 DNSSEC，因为浏览器或操作系统可能不会进行验证。

自 2016 年以来，Google 公共 DNS 为 DoH 提供了一种支持 DNSSEC 验证的 Web 友好型 API，无需浏览器或操作系统配置或扩展程序即可实现。简单的 GET 查询参数和 JSON 响应允许客户端使用常用 Web API 解析结果，并避免复杂的 DNS 消息格式详细信息，例如域名的指针压缩。

如需大致了解 DoH（例如 HTTP 标头、重定向处理、隐私权最佳做法和 HTTP 状态代码），请参阅常规 DoH 文档页面。

安全传输页面包含 DoH 的 curl 命令行示例，以及 DoH 和基于传输层安全协议 (TLS) 的 DNS 常见信息，例如 TLS 支持和 DNS 截断。

JSON API 规范

所有 API 调用都是 HTTP GET 请求。如果参数重复，系统只会使用第一个值。

支持的参数

name

字符串，必需

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

• 长度（替换反斜杠转义后）必须介于 1 到 253 之间（忽略可选结尾的点（如果存在）。
• 所有标签（英文句点之间的部分）长度必须为 1 到 63 个字节。
• .example.com、example..com 等空名称或空字符串导致收到 400 Bad Request。
• 非 ASCII 字符应采用 Punycode 编码（xn--qxam，而不是 ελ）。

类型

字符串，默认值：1

RR 类型可以用 [1, 65535] 中的一个数字或规范字符串（不区分大小写，例如 A 或 aaaa）表示。您可以对“任意”查询使用 255，但请注意，这不A是为 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 正文（而非 JSON 文本）中的二进制 DNS 消息。使用 ct=application/x-javascript 明确请求 JSON 文本。系统会忽略其他内容类型值并返回默认 JSON 内容。

do

布尔值，默认值：false

DO（DNSSEC 正常）标志。使用 do=1 或 do=true 添加 DNSSEC 记录（RRSIG、NSEC、NSEC3）；使用 do=0、do=false 或不使用 do 参数以省略 DNSSEC 记录。

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

edns_client_子网

字符串，默认值：空

edns0-client-子网选项。格式是一个具有子网掩码的 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 地址的最后一部分设置为零）。

随机填充

字符串，已忽略

此参数的值将被忽略。示例：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-子网) 是 GET 请求中的参数，也是 JSON 响应中的顶级字段。