API JSON cho DNS qua HTTPS (DoH)

Trước đây, các ứng dụng dựa trên web yêu cầu tiện ích của trình duyệt để sử dụng Các tính năng DNS như DANE, Phát hiện dịch vụ DNS-SD hoặc thậm chí là để phân giải bất kỳ thông tin nào khác ngoài địa chỉ IP – chẳng hạn như bản ghi MX. Để sử dụng các tính năng phụ thuộc vào DNSSEC như bản ghi SSHFP, bất kỳ tiện ích nào như vậy sẽ phải tự xác thực DNSSEC, vì trình duyệt hoặc hệ điều hành có thể không làm được việc này.

Từ năm 2016, Google Public DNS đã cung cấp một API thân thiện với web cho DoH sử dụng DNSSEC không yêu cầu cấu hình trình duyệt hoặc hệ điều hành hoặc tiện ích. Tham số truy vấn GET và phản hồi JSON đơn giản cho phép ứng dụng phân tích cú pháp kết quả bằng cách sử dụng các API web phổ biến và tránh các chi tiết định dạng thông báo DNS phức tạp như nén con trỏ cho tên miền.

Xem trang tài liệu chung của Bộ Tài chính và Nhà nước để biết thông tin về DoH chẳng hạn như tiêu đề HTTP, xử lý lệnh chuyển hướng, các phương pháp hay nhất về quyền riêng tư và Mã trạng thái HTTP.

Trang Vận chuyển an toàn có Ví dụ về dòng lệnh curl cho DoH và thông tin chung với DoH và DNS qua TLS (DoT), chẳng hạn như hỗ trợ TLS và cắt bớt DNS.

Thông số kỹ thuật của API JSON

Tất cả lệnh gọi API đều là yêu cầu HTTP GET. Trong trường hợp tham số trùng lặp, chỉ giá trị đầu tiên được sử dụng.

Các tham số được hỗ trợ

tên

chuỗi, bắt buộc

Tham số bắt buộc duy nhất. Chấp nhận ký tự thoát dấu gạch chéo ngược RFC 4343.

• Độ dài (sau khi thay thế các ký tự thoát dấu gạch chéo ngược) phải nằm trong khoảng từ 1 đến 253 (bỏ qua dấu chấm kèm theo không bắt buộc nếu có).
• Tất cả các nhãn (một phần của tên giữa các dấu chấm) phải dài từ 1 đến 63 byte.
• Các tên không hợp lệ như .example.com, example..com hoặc chuỗi trống get 400 Yêu cầu không hợp lệ.
• Các ký tự không phải ASCII phải là punycoded (xn--qxam, chứ không phải ελ).

loại

chuỗi, mặc định: 1

Loại RR có thể được biểu thị dưới dạng một số trong [1, 65535] hoặc một chuỗi chuẩn (không phân biệt chữ hoa chữ thường, chẳng hạn như A hoặc aaaa). Bạn có thể sử dụng 255 cho "BẤT KỲ" nhưng xin lưu ý rằng đây không phải là một thay thế để gửi truy vấn cho cả bản ghi A và AAAA hoặc MX. Các máy chủ định danh có thẩm quyền không cần trả về tất cả bản ghi cho những truy vấn như vậy; một số không phản hồi và một số khác (chẳng hạn như Cloudflare.com) chỉ trả về HINFO.

cd

boolean, mặc định: false

Cờ CD (Checking Disabled (Kiểm tra đã tắt)). Dùng cd=1 hoặc cd=true để tắt tính năng xác thực DNSSEC; sử dụng cd=0, cd=false hoặc không dùng tham số cd để bật tính năng xác thực DNSSEC.

đơn vị

chuỗi, mặc định: trống

Lựa chọn loại nội dung mong muốn. Sử dụng ct=application/dns-message để nhận thông báo DNS nhị phân trong phản hồi nội dung HTTP thay vì văn bản JSON. Sử dụng ct=application/x-javascript để yêu cầu văn bản JSON một cách rõ ràng. Các giá trị loại nội dung khác sẽ bị bỏ qua và nội dung JSON mặc định sẽ được trả về.

làm

boolean, mặc định: false

Cờ DO (DNSSEC OK). Sử dụng do=1 hoặc do=true để thêm các bản ghi DNSSEC (RRSIG, NSEC, NSEC3); sử dụng do=0, do=false hoặc không dùng tham số do để bỏ qua các bản ghi DNSSEC.

Ứng dụng phải luôn xử lý (và bỏ qua, nếu cần) mọi DNSSEC các bản ghi trong phản hồi JSON vì những cách triển khai khác luôn có thể bao gồm các bản ghi này, và chúng tôi có thể thay đổi hành vi mặc định đối với phản hồi JSON trong tương lai. (Phản hồi của thông báo DNS nhị phân luôn tuân theo giá trị của cờ DO.)

edns_client_subnet

chuỗi, mặc định: trống

Tuỳ chọn edns0-client-subnet. Định dạng là địa chỉ IP có mặt nạ mạng con. Ví dụ: 1.2.3.4/24, 2001:700:300::/48.

Nếu bạn đang sử dụng giao thức DNS-over-HTTPS do lo ngại về quyền riêng tư và không muốn bất kỳ phần địa chỉ IP nào được gửi đến các máy chủ định danh có thẩm quyền để biết độ chính xác của vị trí địa lý, hãy sử dụng edns_client_subnet=0.0.0.0/0. DNS Google Public thường gửi thông tin mạng gần đúng (thường bỏ trống phần cuối cùng của địa chỉ IPv4).

random_padding

chuỗi, bị bỏ qua

Giá trị của thông số này sẽ bị bỏ qua. Ví dụ: XmkMw~o_mgP2pf.gpw-Oi5dK

Những ứng dụng API lo ngại về những cuộc tấn công quyền riêng tư kênh bên có thể có bằng cách sử dụng kích thước gói của các yêu cầu GET HTTPS có thể dùng tính năng này để thực hiện chính xác tất cả các yêu cầu có cùng kích thước theo các yêu cầu khoảng đệm với dữ liệu ngẫu nhiên. Để tránh bị hiểu sai URL, hãy hạn chế các ký tự khoảng đệm vào các ký tự URL không được dành riêng: chữ hoa và chữ thường, chữ số, dấu gạch nối, dấu chấm, dấu gạch dưới và dấu ngã.

Phản hồi DNS trong JSON

Phản hồi thành công (những bình luận được thêm ở đây không có trong câu trả lời thực tế):

{
  "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
}

Hãy xem bài viết RFC 7871 (Mạng con máy khách EDNS) để thông tin chi tiết về "độ dài tiền tố phạm vi" và cách nó ảnh hưởng đến việc lưu vào bộ nhớ đệm.

Phản hồi lỗi kèm theo thông tin chẩn đoán:

{
  "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/."
}

Các bản ghi SPF và TXT có dấu ngoặc kép được nhúng và thuộc tính máy chủ định danh:

{
  "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
    }
  ],
}

Chuỗi DNS

Tất cả bản ghi TXT đều được mã hoá dưới dạng một chuỗi JSON duy nhất, bao gồm cả việc sử dụng TXT dài hơn ghi lại các định dạng như RFC 4408 (SPF) hoặc RFC 4871 (DKIM).

EDNS

Cơ chế mở rộng EDNS chung không được hỗ trợ. Tuỳ chọn Mạng con máy khách EDNS (edns-client-subnet) là một thông số trong Yêu cầu GET và trường cấp cao nhất trong phản hồi JSON.