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

Früher waren für webbasierte Anwendungen Browsererweiterungen erforderlich, um erweiterte DNS-Funktionen wie DANE und DNS-SD-Diensterkennung zu nutzen oder sogar alles andere als IP-Adressen aufzulösen, z. B. MX-Einträge. Zur Verwendung von DNSSEC-abhängigen Features wie SSHFP-Einträgen müssen solche Erweiterungen DNSSEC selbst validieren, da der Browser oder das Betriebssystem dies möglicherweise nicht tut.

Seit 2016 bietet Google Public DNS eine webfreundliche API für DoH mit DNSSEC-Validierung an, für die keine Browser- oder Betriebssystemkonfiguration oder ‐erweiterungen erforderlich sind. Einfache GET-Abfrageparameter und JSON-Antworten ermöglichen es Clients, die Ergebnisse mithilfe gängiger Web-APIs zu parsen und komplexe Details zum DNS-Nachrichtenformat wie Pointer-Komprimierung für Domainnamen zu vermeiden.

Informationen zu DoH im Allgemeinen finden Sie auf der allgemeinen Dokumentationsseite von DoH, z. B. HTTP-Header, Weiterleitungsverarbeitung, Best Practices zum Datenschutz und HTTP-Statuscodes.

Auf der Seite Sichere Übertragungen finden Sie curl-Befehlszeilenbeispiele für DoH sowie allgemeine Informationen für DoH und DNS over TLS (DoT), z. B. TLS-Unterstützung und DNS-Kürzel.

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 253 liegen (ohne einen optionalen abschließenden Punkt, falls vorhanden).
  • Alle Labels (Teile des Namens zwischen Punkten) müssen 1 bis 63 Byte lang sein.
  • Bei ungültigen Namen wie .example.com, example..com oder einem leeren String wird der Code 400 ungültig.
  • Nicht-ASCII-Zeichen sollten punycodiert werden (xn--qxam, nicht ελ).
eingeben

String, Standard: 1

Der RR-Typ kann als Zahl in [1, 65535] oder als kanonischer String dargestellt werden, wobei die Groß- und Kleinschreibung nicht berücksichtigt wird, z. B. A oder aaaa. Sie können 255 für ANY-Abfragen verwenden. Beachten Sie jedoch, dass dies kein Ersatz für das Senden von Abfragen sowohl für A- als auch für AAAA- oder MX-Einträge ist. Autoritative Nameserver müssen nicht alle Datensätze für solche Abfragen zurückgeben. Einige antworten nicht und andere (z. B. cloudflare.com) geben nur HINFO zurück.

cd

Boolescher Wert, Standard: false

Die CD-Markierung (Überprüfung deaktiviert). Verwenden Sie cd=1 oder cd=true, um die DNSSEC-Validierung zu deaktivieren. Verwenden Sie 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. Verwenden Sie ct=application/dns-message, um eine binäre DNS-Nachricht im HTTP-Antworttext anstelle von JSON-Text zu erhalten. Verwenden Sie ct=application/x-javascript, um explizit JSON-Text anzufordern. Andere Inhaltstypen werden ignoriert und der JSON-Standardinhalt wird zurückgegeben.

do

Boolescher Wert, Standard: false

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

Anwendungen sollten DNSSEC-Einträge in JSON-Antworten immer verarbeiten und bei Bedarf ignorieren, da andere Implementierungen sie möglicherweise immer enthalten. Außerdem kann das Standardverhalten für JSON-Antworten in Zukunft geändert werden. Antworten auf binäre 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 aus Datenschutzgründen DNS-over-HTTPS verwenden und nicht möchten, dassein Teil Ihrer IP-Adresse an autoritative Nameserver gesendet wird, um die Genauigkeit des geografischen Standorts zu gewährleisten, verwenden Sie edns_client_subnet=0.0.0.0/0. Google Public DNS sendet normalerweise ungefähre Netzwerkinformationen (in der Regel wird der letzte Teil der IPv4-Adresse auf eine Null gesetzt).

random_padding

String, ignoriert

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

API-Clients, die besorgt über mögliche Side-Channel-Datenschutzangriffe sind, die Paketgrößen von HTTPS-GET-Anfragen verwenden, können damit alle Anfragen durch Auffüllen von Anfragen mit zufälligen Daten genau auf dieselbe Größe bringen. Damit die URL nicht falsch interpretiert wird, sollten Sie die Abstände auf die nicht reservierten URL-Zeichen beschränken: Groß- und Kleinbuchstaben, Ziffern, Bindestriche, Punkte, Unterstriche und Tilde.

DNS-Antwort im JSON-Format

Erfolgreiche Antwort (hier hinzugefügte Kommentare sind in den 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
}

Weitere Informationen zur „Bereichspräfixlänge“ und ihren Auswirkungen auf das Caching finden Sie unter RFC 7871 (EDNS-Client-Subnetz).

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 werden als einzelner JSON-String codiert. Dazu zählen auch längere TXT-Eintragsformate wie RFC 4408 (SPF) oder RFC 4871 (DKIM).

EDNS

Der allgemeine Mechanismus der EDNS-Erweiterung wird nicht unterstützt. Die Option für das EDNS-Client-Subnetz (edns-client-subnet) ist ein Parameter in der GET-Anfrage und ein Feld der obersten Ebene in der JSON-Antwort.