JSON API ל-DNS ב-HTTPS (DoH)

בעבר, אפליקציות מבוססות-אינטרנט חייבו להשתמש בתוספי דפדפן כדי להשתמש בתכונות מתקדמות תכונות DNS כמו DANE, גילוי שירות DNS-SD או אפילו כדי לפתור את הבעיה כל דבר מלבד כתובות IP – כמו רשומות MX. כדי להשתמש בתכונות שמתבססות על DNSSEC, כמו רשומות SSHFP, צריך להשתמש בתוספים כאלה יצטרכו לאמת את DNSSEC בעצמם, כי הדפדפן או מערכת ההפעלה לא יוכלו לעשות זאת.

מאז 2016, שירות ה-DNS הציבורי של Google מציע API ידידותי לאינטרנט ל-DoH באמצעות DNSSEC אימות שלא מחייב הגדרות או תוספים של הדפדפן או מערכת ההפעלה. פרמטרים פשוטים של שאילתות GET ותגובות JSON מאפשרים ללקוחות לנתח באמצעות ממשקי API נפוצים באינטרנט ונמנעים מפרטים מורכבים של פורמטים של הודעות DNS, כמו דחיסת נתונים לגבי שמות דומיינים.

מידע נוסף על DoH זמין בדף התיעוד הכללי של DoH. באופן כללי, כמו כותרות HTTP, טיפול בהפניות אוטומטיות, שיטות מומלצות לשמירה על פרטיות קודי מצב של HTTP.

הדף Secure Transports כולל דוגמאות לשורת הפקודה curl ל-DoH, ומידע משותף ל-DoH ול-DNS TLS (DoT), כמו תמיכה ב-TLS וקטיעת DNS.

מפרט API בפורמט JSON

כל הקריאות ל-API הן בקשות HTTP GET. במקרה של פרמטרים כפולים, משתמשים רק בערך הראשון.

פרמטרים נתמכים

שם

מחרוזת, חובה

הפרמטר היחיד שנדרש. ניתן להשתמש בתו בריחה של לוכסן הפוך ב-RFC 4343.

• האורך (אחרי החלפת תווי בריחה של לוכסן הפוך) חייב להיות בין 1 ל- 212 (התעלמות מנקודה אופציונלית בסוף, אם קיימת).
• כל התוויות (חלקים מהשם בין הנקודות) צריכות להיות באורך של 1 עד 63 בייטים.
• שמות לא חוקיים כמו .example.com, example..com או מחרוזת ריקה 400 Bad Request.
• תווים שאינם ASCII צריכים להיות punycoded (xn--qxam ולא ελ).

סוג

מחרוזת, ברירת המחדל: 1

אפשר לייצג סוג RR כמספר ב-[1, 65535] או במחרוזת קנונית (לא תלוי-רישיות, למשל 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 שמוגדר כברירת מחדל.

אפשר

בוליאני, ברירת מחדל: false

הדגל DO (DNSSEC OK). צריך להשתמש ב-do=1 או ב-do=true כדי לכלול רשומות DNSSEC (RRSIG, NSEC, NSEC3). כדי להשמיט רשומות DNSSEC, צריך להשתמש בפרמטר do=0, do=false או לא להשתמש בפרמטר do.

אפליקציות צריכות תמיד לטפל ב-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).

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 Client Subnet) פרטים על 'היקף prefix-length' ועל האופן שבו הוא משפיע על השמירה במטמון.

תגובה על כשל עם פרטי אבחון:

{
  "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 Client Subnet (edns-client-subnet) היא פרמטר בקשת GET ושדה ברמה העליונה בתשובת JSON.