Questa pagina è stata tradotta dall'API Cloud Translation.

API JSON per DNS su HTTPS (DoH)

In precedenza, le applicazioni basate sul web richiedevano estensioni del browser per utilizzare funzionalità DNS avanzate come DANE, rilevamento dei servizi DNS-SD o anche per risolvere elementi diversi dagli indirizzi IP, come i record MX. Per utilizzare le funzionalità dipendenti dalle DNSSEC, come i record SSHFP, eventuali estensioni di questo tipo dovrebbero convalidare le DNSSEC autonomamente, perché il browser o il sistema operativo potrebbero non farlo.

Dal 2016, Google Public DNS offre un'API web-friendly per DoH con convalida DNSSEC che non richiede estensioni o estensioni del browser o del sistema operativo. I semplici parametri di query GET e le risposte JSON consentono ai client di analizzare i risultati utilizzando le comuni API web ed evitano dettagli complessi nei formati dei messaggi DNS come la compressione del puntatore per i nomi di dominio.

Consulta la pagina generale della documentazione DoH per informazioni generali su DoH, ad esempio intestazioni HTTP, gestione del reindirizzamento, best practice per la privacy e codici di stato HTTP.

La pagina Trasporti sicuri contiene curl esempi di riga di comando per DoH e informazioni comuni a DoH e DNS tramite TLS (DoT), come il supporto TLS e il troncamento del DNS.

Specifiche API JSON

Tutte le chiamate API sono richieste HTTP GET. In caso di parametri duplicati, viene utilizzato solo il primo valore.

Parametri supportati

nome

stringa, obbligatoria

L'unico parametro obbligatorio. Sono accettati gli escape RFC 4343 con barra rovesciata.

La lunghezza (dopo la sostituzione delle escape della barra rovesciata) deve essere compresa tra 1 e 253 (ignorando un punto finale facoltativo, se presente).
Tutte le etichette (parti del nome tra punti) devono avere una lunghezza compresa tra 1 e 63 byte.
Nomi non validi come .example.com, example..com o stringa vuota ricevono 400 Richiesta non valida.
I caratteri non ASCII devono essere punycoded (xn--qxam, non ελ).

digita

stringa, valore predefinito: 1

Il tipo RR può essere rappresentato come un numero in [1, 65535] o come una stringa canonica (senza distinzione tra maiuscole e minuscole, ad esempio A o aaaa). Puoi utilizzare 255 per le query "ANY", ma tieni presente che non sostituisce l'invio di query per entrambi i record A e AAAA o MX. I server dei nomi autorevoli non devono restituire tutti i record per queste query; alcuni non rispondono e altri (come cloudflare.com) restituiscono solo HINFO.

cd

booleano; valore predefinito: false

Il flag CD (Checking Disabled). Utilizza cd=1 o cd=true per disabilitare la convalida delle DNSSEC; utilizza cd=0, cd=false o nessun parametro cd per abilitare la convalida di DNSSEC.

num.

stringa, valore predefinito: vuoto

l'opzione per il tipo di contenuti desiderata. Utilizza ct=application/dns-message per ricevere un messaggio DNS binario nel corpo HTTP della risposta anziché nel testo JSON. Usa ct=application/x-javascript per richiedere esplicitamente testo JSON. Gli altri valori per i tipi di contenuti vengono ignorati e vengono restituiti contenuti JSON predefiniti.

do

booleano; valore predefinito: false

Il flag DO (DNSSEC OK). Usa do=1 o do=true per includere i record DNSSEC (RRSIG, NSEC, NSEC3); utilizza do=0, do=false o nessun parametro do per omettere i record DNSSEC.

Le applicazioni devono sempre gestire (e ignorare, se necessario) tutti i record DNSSEC nelle risposte JSON, poiché altre implementazioni potrebbero sempre includerli e potremmo modificare il comportamento predefinito per le risposte JSON in futuro. Le risposte ai messaggi DNS binari rispettano sempre il valore del flag DO.

edns_client_subnet

stringa, valore predefinito: vuoto

L'opzione edns0-client-subnet. Il formato è un indirizzo IP con una subnet mask. Esempi: 1.2.3.4/24, 2001:700:300::/48.

Se utilizzi DNS over HTTPS per motivi di privacy e non vuoi che qualsiasi parte del tuo indirizzo IP venga inviata a server dei nomi autorevoli per garantire la precisione della posizione geografica, utilizza edns_client_subnet=0.0.0.0/0. Google Public DNS solitamente invia informazioni di rete approssimative (in genere azzerando l'ultima parte dell'indirizzo IPv4).

random_padding

stringa, ignorato

Il valore di questo parametro viene ignorato. Esempio: XmkMw~o_mgP2pf.gpw-Oi5dK.

I client API preoccupati per possibili attacchi alla privacy del canale laterale che utilizzano le dimensioni del pacchetto delle richieste GET HTTPS possono utilizzarlo per rendere tutte le richieste esattamente delle stesse dimensioni, riempiendo le richieste con dati casuali. Per evitare interpretazioni errate dell'URL, limita i caratteri di spaziatura interna ai caratteri dell'URL non riservati: lettere maiuscole e minuscole, numeri, trattini, punti, trattini bassi e tilde.

Risposta DNS in JSON

Una risposta corretta (i commenti aggiunti qui non sono presenti nelle risposte effettive):

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

Consulta RFC 7871 (EDNS Client Subnet) per maggiori dettagli sulla "lunghezza del prefisso dell'ambito" e su come influisce sulla memorizzazione nella cache.

Una risposta di errore con informazioni diagnostiche:

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

Record SPF e TXT con virgolette incorporate e attribuzione del server dei nomi:

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

Stringhe DNS

Tutti i record TXT sono codificati come singola stringa JSON, inclusi l'utilizzo di formati di record TXT più lunghi come RFC 4408 (SPF) o RFC 4871 (DKIM).

EDNS

Il meccanismo dell'estensione EDNS generale non è supportato. L'opzione Subnet client EDNS (edns-client-subnet) è un parametro nella richiesta GET e un campo di primo livello nella risposta JSON.