Questa pagina è stata tradotta dall'API Cloud Translation.

API JSON per DNS su HTTPS (DoH)

In precedenza, le applicazioni basate sul web richiedevano le estensioni del browser per usare come DANE, DNS-SD Service Discovery o persino per la risoluzione qualsiasi cosa diversa dagli indirizzi IP, come i record MX. Per usare funzionalità che dipendono da DNSSEC come i record SSHFP, qualsiasi estensione devono convalidare le DNSSEC perché il browser o il sistema operativo potrebbero non farlo.

Dal 2016, Google Public DNS offre un'API ottimizzata per il web per DoH con DNSSEC una convalida che non richiede la configurazione o le estensioni del browser o del sistema operativo. I parametri di query GET semplici e le risposte JSON consentono ai client di analizzare utilizzando le comuni API web ed evitare dettagli complessi per il formato dei messaggi DNS, come compressione dei pointer per i nomi di dominio.

Per informazioni su DoH, consulta la pagina generale della documentazione del DoH. in generale, come intestazioni HTTP, gestione dei reindirizzamenti, best practice per la privacy e Codici di stato HTTP.

La pagina Trasporti sicuri ha Esempi di riga di comando curl per DoH e informazioni comuni a DoH e DNS su TLS (DoT), ad esempio supporto TLS e troncamento del DNS.

Specifica API JSON

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

Parametri supportati

nome

stringa, obbligatorio

L'unico parametro obbligatorio. Sono accettati i caratteri di escape RFC 4343.

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

tipo

stringa, valore predefinito: 1

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

cd

booleano, valore predefinito: false

Il flag CD (Checking Disabled). Usa cd=1 o cd=true per disabilitare la convalida DNSSEC. usa il parametro cd=0, cd=false o nessun parametro cd per abilitare la convalida delle DNSSEC.

num.

stringa, valore predefinito: vuoto

Opzione per il tipo di contenuti desiderato. Utilizza ct=application/dns-message per ricevere un messaggio DNS binario nell' corpo HTTP della risposta al posto del testo JSON. Utilizza ct=application/x-javascript per richiedere esplicitamente testo JSON. Altri valori per il tipo di contenuto vengono ignorati e vengono restituiti i 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); usa il parametro do=0, do=false o nessun parametro do per omettere i record DNSSEC.

Le applicazioni devono sempre gestire (e ignorare, se necessario) eventuali DNSSEC i record nelle risposte JSON, che potrebbero essere inclusi in altre implementazioni, e potremmo modificare il comportamento predefinito delle risposte JSON in futuro. Le risposte dei messaggi DNS binari rispettano sempre il valore del flag DO.

edns_client_subnet

stringa, valore predefinito: vuoto

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

Se utilizzi DNS over HTTPS per problemi di privacy e non vuoi qualsiasi parte del tuo indirizzo IP da inviare a server dei nomi autorevoli per la precisione della posizione geografica, utilizza edns_client_subnet=0.0.0.0/0. Il DNS pubblico di Google di solito invia informazioni di rete approssimative (di solito azzerando l'ultima parte dell'indirizzo IPv4).

random_padding

stringa, ignorato

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

Client API preoccupati per i possibili attacchi alla privacy side-channel che utilizzano delle dimensioni di pacchetti delle richieste GET HTTPS può usare questa soluzione delle stesse dimensioni inserendo dati casuali per le richieste. Per evitare un'interpretazione errata dell'URL, limita i caratteri di spaziatura interna ai caratteri URL non prenotati: lettere maiuscole e minuscole, cifre, trattini, punti, trattini bassi e tilde.

Risposta DNS in JSON

Una risposta positiva (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
}

Fai riferimento a RFC 7871 (subnet client EDNS) per dettagli su "scopePrefix-length" (lunghezza del prefisso dell'ambito) e su come influisce sulla memorizzazione nella cache.

Una risposta all'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 dei 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 un'unica stringa JSON, inclusi gli utilizzi di file TXT più lunghi formati di registrazione come RFC 4408 (SPF) oppure RFC 4871 (DKIM).

EDNS

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