JSON API für DNS über HTTPS (DoH)

Bisher waren für Webanwendungen Browsererweiterungen erforderlich, um erweiterte DNS-Funktionen wie DANE, DNS-SD-Diensterkennung und sogar zur Auflösung anderen Daten als IP-Adressen abrufen, z. B. MX-Einträge. Um DNSSEC-abhängige Funktionen wie SSHFP-Einträge zu verwenden, können solche Erweiterungen muss DNSSEC selbst validieren, da der Browser oder das Betriebssystem dies möglicherweise nicht tut.

Seit 2016 bietet Google Public DNS mit DNSSEC eine webfreundliche API für DoH an. Validierung, die keine Browser- oder Betriebssystemkonfiguration oder Erweiterungen erfordert. Mit einfachen GET-Abfrageparametern und JSON-Antworten können Clients die mithilfe gängiger Web-APIs Ergebnisse erzielen und komplexe DNS-Nachrichtenformatdetails wie Zeigerkomprimierung für Domainnamen

Informationen zum DoH finden Sie auf der allgemeinen DoH-Dokumentationsseite HTTP-Header, Weiterleitungshandhabung, Best Practices für den Datenschutz HTTP-Statuscodes.

Die Seite Sichere Übertragungen curl-Befehlszeilenbeispiele für DoH und allgemeine Informationen für DoH und DNS over TLS (DoT), z. B. TLS-Unterstützung und DNS-Kürzung.

JSON API-Spezifikation

Alle API-Aufrufe sind HTTP GET-Anfragen. Bei doppelten Parametern wird nur der erste Wert verwendet.

Unterstützte Parameter

Name

String, erforderlich

Der einzige erforderliche Parameter. Umgekehrte Schrägstriche gemäß RFC 4343 sind zulässig.

  • Die Länge (nach dem Ersetzen der umgekehrten Schrägstriche) muss zwischen 1 und 1 liegen. 253 (Ignoriert einen optionalen abschließenden Punkt, falls vorhanden).
  • Alle Labels (Teile des Namens zwischen den Punkten) müssen 1 bis 63 Byte lang sein.
  • Ungültige Namen wie „.example.com“, „example..com“ oder ein leerer String 400 Ungültige Anfrage.
  • Nicht-ASCII-Zeichen sollten punycodiert werden (xn--qxam, nicht ελ).
Typ

String, Standardwert: 1

Der RR-Typ kann als Zahl in [1, 65535] oder als kanonischer String dargestellt werden. (Groß-/Kleinschreibung wird nicht berücksichtigt, z. B. A oder aaaa). Du kannst 255 für ANY verwenden aber beachten Sie, dass dies kein Ersatz für das Senden von Abfragen für A- und AAAA- oder MX-Einträge. Autoritäre Nameserver müssen nicht alle Datensätze für solche Anfragen zurückgeben. einige antworten nicht und andere (wie cloudflare.com) geben nur HINFO zurück.

cd

Boolescher Wert, Standardwert: false

Die CD-Markierung (Checking Disabled). Verwenden Sie cd=1 oder cd=true, um die DNSSEC-Validierung zu deaktivieren. Verwenden Sie den Parameter cd=0, cd=false oder keinen cd-Parameter, um die DNSSEC-Validierung zu aktivieren.

Stück

String, Standard: leer

Gewünschte Option für den Inhaltstyp. Mit ct=application/dns-message können Sie eine binäre DNS-Nachricht im HTTP-Text der Antwort anstelle von JSON-Text. Verwenden Sie ct=application/x-javascript, um explizit JSON-Text anzufordern. Andere Werte für Inhaltstypen werden ignoriert und JSON-Standardinhalte werden zurückgegeben.

do

Boolescher Wert, Standardwert: false

Das Flag „DO (DNSSEC OK)“. Verwenden Sie do=1 oder do=true, um DNSSEC-Einträge (RRSIG, NSEC, NSEC3) einzuschließen. Verwenden Sie den Parameter do=0, do=false oder keinen do-Parameter, um DNSSEC-Einträge auszulassen.

Anwendungen sollten DNSSEC immer verarbeiten (und bei Bedarf ignorieren) Datensätze in JSON-Antworten enthalten, da andere Implementierungen sie und wir können das Standardverhalten für JSON-Antworten in Zukunft ändern. Antworten von binären DNS-Nachrichten berücksichtigen immer den Wert des DO-Flags.

edns_client_subnet

String, Standard: leer

Die Option „edns0-client-subnet“. Das Format ist eine IP-Adresse mit einer Subnetzmaske. Beispiele: 1.2.3.4/24, 2001:700:300::/48.

Wenn Sie DNS-over-HTTPS aus Datenschutzgründen verwenden und Beliebiger Teil Ihrer IP-Adresse, der an autoritative Nameserver gesendet wird Für die Genauigkeit des geografischen Standorts verwenden Sie edns_client_subnet=0.0.0.0/0. Google Public DNS sendet normalerweise ungefähre Netzwerkinformationen (normalerweise durch Nullen des letzten Teils der IPv4-Adresse).

random_padding

String, ignoriert

Der Wert dieses Parameters wird ignoriert. Beispiel: XmkMw~o_mgP2pf.gpw-Oi5dK.

API-Kunden, die Bedenken wegen möglicher Side-Channel-Datenschutzangriffe haben, nutzen die Funktion Paketgrößen von HTTPS-GET-Anfragen dieselbe Größe haben, indem Sie Anfragen mit zufälligen Daten auffüllen. Schränken Sie die Abstände ein, um eine Fehlinterpretation der URL zu vermeiden den nicht reservierten URL-Zeichen hinzu: Groß- und Kleinbuchstaben, Ziffern, Bindestrich, Punkt, Unterstrich und Tilde.

DNS-Antwort im JSON-Format

Eine erfolgreiche Antwort (hier hinzugefügte Kommentare sind in tatsächlichen Antworten nicht vorhanden):

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

Siehe RFC 7871 (EDNS-Client-Subnetz) für Details zu „Scope Prefix-length“ und ihren Auswirkungen auf das Caching.

Eine Fehlerantwort mit Diagnoseinformationen:

{
  "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- und TXT-Einträge mit eingebetteten Anführungszeichen und Nameserver-Zuordnung:

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

Alle TXT-Einträge sind als einzelner JSON-String codiert, wobei längere TXT-Einträge verwendet werden. Aufnahmeformate wie RFC 4408 (SPF) oder RFC 4871 (DKIM).

eDNS

Der allgemeine EDNS-Erweiterungsmechanismus wird nicht unterstützt. Die EDNS-Client-Subnetzoption (edns-client-subnet) ist ein Parameter im GET-Anfrage und ein Feld der obersten Ebene in der JSON-Antwort enthält.