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.

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

מפרט JSON API

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

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

name

מחרוזת, חובה

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

• האורך (אחרי שמחליפים תווי בריחה בקו נטוי הפוך) צריך להיות בין 1 ל-253 (אם יש נקודה בסוף, המערכת מתעלמת מהנקודה הזו).
• כל התוויות (חלקים מהשם בין הנקודות) חייבות להיות באורך של 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=1 או ב-cd=true כדי להשבית את האימות של DNSSEC. כדי להפעיל אימות של DNSSEC, צריך להשתמש בפרמטר cd=0 או cd=false, או ללא cd.

כמות

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

האפשרות הרצויה של סוג התוכן. באמצעות 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 שלכם).

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

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

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