JSON API สำหรับ DNS ผ่าน HTTPS (DoH)

ก่อนหน้านี้ แอปพลิเคชันบนเว็บจำเป็นต้องมีส่วนขยายเบราว์เซอร์เพื่อใช้ขั้นสูง ฟีเจอร์ DNS เช่น DANE, การค้นหาบริการ DNS-SD หรือแม้แต่เพื่อแก้ไข อื่นๆ นอกเหนือจากที่อยู่ IP เช่น ระเบียน MX หากต้องการใช้ฟีเจอร์ที่ขึ้นอยู่กับ DNSSEC เช่น ระเบียน SSHFP ส่วนขยายดังกล่าว จะต้องตรวจสอบ DNSSEC ด้วยตนเอง เนื่องจากเบราว์เซอร์หรือระบบปฏิบัติการอาจไม่ทำเช่นนั้น

ตั้งแต่ปี 2016 Google Public DNS ได้นำเสนอ API ที่เหมาะสำหรับเว็บสำหรับ DoH ที่มี DNSSEC การตรวจสอบความถูกต้องที่ไม่ต้องมีการกำหนดค่าหรือส่วนขยายของเบราว์เซอร์หรือระบบปฏิบัติการ พารามิเตอร์การค้นหา GET อย่างง่าย และการตอบกลับ JSON จะช่วยให้ไคลเอ็นต์สามารถแยกวิเคราะห์พารามิเตอร์ โดยใช้ Web API ทั่วไปและหลีกเลี่ยงรายละเอียดรูปแบบข้อความ DNS ที่ซับซ้อน เช่น การบีบอัดตัวชี้สำหรับชื่อโดเมน

ดูข้อมูลเกี่ยวกับ DoH ได้ที่หน้าเอกสารประกอบทั่วไปเกี่ยวกับ DoH เช่น ส่วนหัว HTTP, การจัดการการเปลี่ยนเส้นทาง, แนวทางปฏิบัติแนะนำด้านความเป็นส่วนตัว และ รหัสสถานะ HTTP

หน้าการส่งที่ปลอดภัยมี ตัวอย่างบรรทัดคำสั่ง curl สำหรับ DoH และข้อมูลทั่วไปสำหรับ DoH และ DNS ผ่าน TLS (DoT) เช่น การรองรับ TLS และการตัด DNS

ข้อกำหนดของ JSON API

การเรียก API ทั้งหมดเป็นคำขอ HTTP GET ในกรณีที่มีพารามิเตอร์ซ้ำกัน ระบบจะใช้เฉพาะค่าแรกเท่านั้น

พารามิเตอร์ที่รองรับ

ชื่อ

สตริง ต้องระบุ

พารามิเตอร์เดียวที่จำเป็น ยอมรับอักขระหลีกแบ็กสแลช RFC 4343

• ความยาว (หลังจากแทนที่แบ็กสแลช Escape) ต้องอยู่ระหว่าง 1 และ 3,530 (ละเว้นจุดต่อท้ายที่ไม่บังคับ หากมี)
• ป้ายกำกับทั้งหมด (ส่วนของชื่อระหว่างจุด) ต้องมีความยาว 1 ถึง 63 ไบต์
• ชื่อที่ไม่ถูกต้อง เช่น .example.com, example..com หรือสตริงว่าง 400 คำขอไม่ถูกต้อง
• อักขระที่ไม่ใช่ ASCII ควรเป็น punyหัวข้อ (xn--qxam ไม่ใช่ ελ)

ประเภท

สตริง, ค่าเริ่มต้น: 1

ประเภท RR สามารถแสดงเป็นตัวเลขใน [1, 65535] หรือสตริง Canonical (ไม่คำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่ เช่น A หรือ aaaa) คุณใช้ 255 สำหรับ "ANY" ได้ คำค้นหาของคุณ แต่โปรดทราบว่านี่ไม่ใช่ แทนการส่งคำค้นหาสำหรับทั้งระเบียน A และ AAAA หรือ MX เนมเซิร์ฟเวอร์ที่ได้รับอนุญาตไม่จำเป็นต้องแสดงผลระเบียนทั้งหมดสำหรับคำค้นหาดังกล่าว บางรายไม่ตอบสนอง ขณะที่บางโปรแกรม (เช่น cloudflare.com) ส่งคืนเฉพาะ HINFO

cd

บูลีน ค่าเริ่มต้น: false

ธง CD (กำลังตรวจสอบปิดอยู่) ใช้ cd=1 หรือ cd=true เพื่อปิดใช้การตรวจสอบ DNSSEC ใช้ cd=0, cd=false หรือไม่ใช้พารามิเตอร์ cd เพื่อเปิดใช้การตรวจสอบ DNSSEC

หน่วย

สตริง, ค่าเริ่มต้น: ว่าง

ตัวเลือกประเภทเนื้อหาที่ต้องการ ใช้ ct=application/dns-message เพื่อรับข้อความ DNS แบบไบนารีใน เนื้อหา HTTP ของการตอบกลับแทนข้อความ 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

แอปพลิเคชันควรจัดการ (และละเว้น หากจำเป็น) กับ DNSSEC เสมอ ในการตอบสนอง JSON เนื่องจากการใช้งานอื่นๆ อาจรวมเข้าไว้เสมอ และเราอาจเปลี่ยนลักษณะการทำงานเริ่มต้นของการตอบกลับ 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 โดยปกติแล้ว DNS สาธารณะของ Google จะส่งข้อมูลเครือข่ายโดยประมาณ (โดยปกติจะทำให้ส่วนสุดท้ายของที่อยู่ IPv4 เป็น 0)

random_padding

สตริง ละเว้น

ระบบจะไม่สนใจค่าของพารามิเตอร์นี้ ตัวอย่าง: XmkMw~o_mgP2pf.gpw-Oi5dK

ไคลเอ็นต์ API ที่กังวลว่าอาจมีการโจมตีความเป็นส่วนตัวแบบ Side-channel โดยใช้ ขนาดแพ็กเก็ตของคำขอ HTTPS GET สามารถใช้สิ่งนี้เพื่อทำให้คำขอทั้งหมดตรงตาม ขนาดเดียวกันโดยคำขอระยะห่างจากขอบที่มีข้อมูลแบบสุ่ม ป้องกันไม่ให้ URL ตีความผิด ให้จำกัดอักขระ Padding เป็นอักขระของ URL ที่ไม่ได้สำรองไว้ ดังนี้ ตัวอักษรพิมพ์ใหญ่และพิมพ์เล็ก ตัวเลข ขีดกลางสั้น จุด ขีดล่าง และตัวหนอน

การตอบสนองของ DNS ใน JSON

การตอบกลับที่สำเร็จ (ความคิดเห็นที่เพิ่มไว้ที่นี่ไม่ได้แสดงในคำตอบจริง):

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