Cette page a été traduite par l'API Cloud Translation.

API JSON pour DNS sur HTTPS (DoH)

Auparavant, les applications Web nécessitaient des extensions de navigateur pour utiliser les fonctionnalités avancées des fonctionnalités DNS comme DANE, la détection de services DNS-SD, ou même pour résoudre autre chose que les adresses IP, comme les enregistrements MX. Pour utiliser des fonctionnalités dépendantes de DNSSEC telles que les enregistrements SSHFP, ces extensions devraient valider DNSSEC eux-mêmes, car le navigateur ou le système d'exploitation pourrait ne pas le faire.

Depuis 2016, Google Public DNS propose une API Web pour DoH avec DNSSEC. qui ne nécessite pas de configuration ni d'extensions pour le navigateur ou le système d'exploitation. Des paramètres de requête GET simples et des réponses JSON permettent aux clients d'analyser le des résultats à l'aide d'API Web courantes et d'éviter les détails de format de message DNS complexes tels que compression de pointeurs pour les noms de domaine.

Pour en savoir plus sur DoH, consultez la page de documentation générale de DoH. en général, comme les en-têtes HTTP, la gestion des redirections, les bonnes pratiques de confidentialité Codes d'état HTTP

La page Transports sécurisés contient des exemples de ligne de commande curl pour DoH et des informations communes à DoH et DNS via TLS (DoT), comme la compatibilité avec TLS et la troncation DNS.

Spécification de l'API JSON

Tous les appels d'API sont des requêtes HTTP GET. Dans le cas de paramètres en double, seule la première valeur est utilisée.

Paramètres possibles

nom

chaîne (obligatoire)

Le seul paramètre obligatoire. Les caractères d'échappement dans la barre oblique inverse RFC 4343 sont acceptés.

La longueur (après le remplacement des caractères d'échappement des barres obliques inverses) doit être comprise entre 1 et 253 (en ignorant un point facultatif à la fin, le cas échéant).
Toutes les étiquettes (parties du nom entre les points) doivent comprendre entre 1 et 63 octets.
Les noms non valides tels que .example.com, example..com ou une chaîne vide 400 Requête incorrecte.
Les caractères non-ASCII doivent être codés en punais (xn--qxam, et non ελ).

type

chaîne, valeur par défaut: 1

Le type RR peut être représenté sous la forme d'un nombre dans [1, 65535] ou d'une chaîne canonique (non sensible à la casse, comme A ou aaaa). Vous pouvez utiliser 255 pour "N'IMPORTE LEQUEL des éléments suivants". requêtes, mais sachez qu'il ne s'agit pas remplacer l’envoi de requêtes pour les enregistrements A et AAAA ou MX. Les serveurs de noms faisant autorité n'ont pas besoin de renvoyer tous les enregistrements pour ces requêtes. certains ne répondent pas, tandis que d'autres (comme cloudflare.com) renvoient uniquement HINFO.

cd

Booléen, valeur par défaut: false

Indicateur CD (Checking Disabled) Utilisez cd=1 ou cd=true pour désactiver la validation DNSSEC. utilisez cd=0, cd=false ou aucun paramètre cd pour activer la validation DNSSEC.

nb

chaîne, valeur par défaut: vide

Option de type de contenu souhaitée. Utilisez ct=application/dns-message pour recevoir un message DNS binaire dans le corps HTTP de la réponse au lieu d'un texte JSON. Utilisez ct=application/x-javascript pour demander explicitement du texte JSON. Les autres valeurs de type de contenu sont ignorées et le contenu JSON par défaut est renvoyé.

Ne

Booléen, valeur par défaut: false

L’indicateur DO (DNSSEC OK). Utilisez do=1 ou do=true pour inclure les enregistrements DNSSEC (RRSIG, NSEC, NSEC3). utilisez do=0, do=false ou aucun paramètre do pour omettre les enregistrements DNSSEC.

Les applications doivent toujours gérer (et ignorer, si nécessaire) les enregistrements DNSSEC dans des réponses JSON, car d'autres implémentations peuvent toujours les inclure, et il se peut que nous modifiions le comportement par défaut des réponses JSON à l'avenir. (Les réponses aux messages DNS binaires respectent toujours la valeur de l'indicateur DO.)

edns_client_subnet

chaîne, valeur par défaut: vide

L'option "edns0-client-subnet". Cette valeur doit correspondre à une adresse IP avec un masque de sous-réseau. Exemples: 1.2.3.4/24, 2001:700:300::/48.

Si vous utilisez DNS-over-HTTPS pour des raisons de confidentialité et si vous ne souhaitez pas n'importe quelle partie de votre adresse IP à envoyer aux serveurs de noms primaires pour garantir la précision de la position géographique, utilisez edns_client_subnet=0.0.0.0/0. Le DNS public de Google envoie normalement des informations réseau approximatives (généralement en mettant à zéro la dernière partie de votre adresse IPv4).

random_padding

chaîne, ignorée

La valeur de ce paramètre est ignorée. Exemple : XmkMw~o_mgP2pf.gpw-Oi5dK

Les clients API préoccupés par d'éventuelles attaques visant la confidentialité des versions secondaires à l'aide du les tailles de paquets des requêtes GET HTTPS peuvent l'utiliser pour effectuer des requêtes exactes de la même taille en complétant les requêtes avec des données aléatoires. Pour éviter une mauvaise interprétation de l'URL, limitez les caractères de marge intérieure. caractères non réservés de l'URL: des lettres majuscules et minuscules, des chiffres, des traits d'union, des points, des traits de soulignement et des tildes.

Réponse DNS en JSON

Réponse positive (les commentaires ajoutés ici ne sont pas présents dans les réponses réelles):

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

Consultez le document RFC 7871 (sous-réseau de client EDNS) pour en savoir plus des détails sur la "longueur du préfixe du champ d'application" et son impact sur la mise en cache.

Une réponse d'échec avec des informations de diagnostic:

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

Enregistrements SPF et TXT avec guillemets intégrés et attribution au serveur de noms:

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

Chaînes DNS

Tous les enregistrements TXT sont encodés sous la forme d'une chaîne JSON unique, y compris lorsque des enregistrements TXT plus longs sont utilisés. des formats d'enregistrement tels que RFC 4408 (SPF) ou RFC 4871 (DKIM).

EDNS

Le mécanisme d'extension EDNS général n'est pas compatible. L'option de sous-réseau du client EDNS (edns-client-subnet) est un paramètre du sous-réseau GET et un champ de niveau supérieur dans la réponse JSON.