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

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

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

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

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

ข้อกำหนด JSON API

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

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

ชื่อ

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

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

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

ประเภท

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

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

cd

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

แฟล็ก CD (Checking Disabled) ใช้ 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 ตามปกติแล้ว Google Public DNS จะส่งข้อมูลเครือข่ายโดยประมาณ (โดยมากจะลบส่วนสุดท้ายของที่อยู่ IPv4 ออก)

random_padding

สตริง, ละเว้น

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

ไคลเอ็นต์ API ที่กังวลเรื่องการโจมตีความเป็นส่วนตัวของช่องทางด้านข้างที่อาจเกิดขึ้นโดยใช้ขนาดแพ็กเก็ตของคำขอ HTTPS GET นี้สามารถใช้ขนาดดังกล่าวเพื่อทำให้คำขอทั้งหมดมีขนาดเท่ากันได้โดยขยายคำขอด้วยข้อมูลแบบสุ่ม เพื่อป้องกันการตีความ URL ผิด ให้จำกัดอักขระช่องว่างตามอักขระใน 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