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 DNS avancées telles que DANE, la détection de services DNS-SD, ou même pour résoudre tout autre problème que les adresses IP, comme les enregistrements MX. Pour utiliser des fonctionnalités qui dépendent de DNSSEC, telles que les enregistrements SSHFP, ces extensions doivent valider DNSSEC elles-mêmes, car le navigateur ou le système d'exploitation peut ne pas le faire.

Depuis 2016, Google Public DNS propose une API adaptée au Web pour DoH avec validation DNSSEC qui ne nécessite aucune configuration ni extension de navigateur ou de système d'exploitation. Les paramètres de requête GET simples et les réponses JSON permettent aux clients d'analyser les résultats à l'aide d'API Web courantes et d'éviter les détails complexes du format des messages DNS, tels que la compression de pointeur pour les noms de domaine.

Consultez la page de documentation générale de DoH pour en savoir plus sur DoH en général, y compris les en-têtes HTTP, la gestion des redirections, les bonnes pratiques de confidentialité et les codes d'état HTTP.

La page Transports sécurisés contient des exemples de ligne de commande curl pour DoH, ainsi que des informations communes à DoH et à DNS sur TLS (DoT), telles que la prise en charge de 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

name

chaîne, obligatoire

Il s'agit du seul paramètre obligatoire. Les barres obliques inverses RFC 4343 sont acceptées.

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

type

chaîne, valeur par défaut: 1

Le type RR peut être représenté par un nombre dans [1, 65535] ou par une chaîne canonique (non sensible à la casse, comme A ou aaaa). Vous pouvez utiliser 255 pour les requêtes "TOUTE", mais sachez qu'il ne s'agit pas d'un remplacement pour envoyer des requêtes à la fois pour les enregistrements A, AAAA ou MX. Les serveurs de noms faisant autorité n'ont pas besoin de renvoyer tous les enregistrements de ces requêtes. Certains ne répondent pas, tandis que d'autres (tels que cloudflare.com) ne renvoient que le code HINFO.

cd

Booléen. Valeur par défaut: false

L'indicateur CD (vérification désactivée). 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 du type de contenu souhaité. Utilisez ct=application/dns-message pour recevoir un message DNS binaire dans le corps HTTP de la réponse au lieu du 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é.

do

Booléen. Valeur par défaut: false

L'indicateur DO (DNSSEC OK) Utilisez do=1 ou do=true pour inclure des 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) tous les enregistrements DNSSEC dans les 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 de message 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. Le format correspond à 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 questions de confidentialité et que vous ne souhaitez pas que aucune partie de votre adresse IP soit envoyée à des serveurs de noms primaires pour garantir la précision de l'emplacement 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 s'inquiètent des potentielles attaques de la confidentialité par canal auxiliaire utilisant les tailles de paquets des requêtes GET HTTPS peuvent l'utiliser pour effectuer toutes les requêtes exactement de la même taille en les remplissant avec des données aléatoires. Pour éviter une mauvaise interprétation de l'URL, limitez les caractères de marge intérieure aux caractères d'URL non réservés : lettres majuscules et minuscules, chiffres, trait d'union, point, trait de soulignement et tilde.

Réponse DNS au format 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 client EDNS) pour en savoir plus sur la "longueur du préfixe de champ d'application" et son impact sur la mise en cache.

Réponse d'échec accompagnée d'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 dans une seule chaîne JSON, y compris en utilisant des formats d'enregistrement TXT plus longs tels que RFC 4408 (SPF) ou RFC 4871 (DKIM).

EDNS

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