Esta página foi traduzida pela API Cloud Translation.

API JSON para DNS por HTTPS (DoH)

Antes, os aplicativos baseados na Web exigiam extensões de navegador para usar recursos de DNS, como DANE, descoberta de serviço DNS-SD ou até mesmo para resolver qualquer coisa que não seja endereços IP, como registros MX. Para usar recursos dependentes de DNSSEC, como registros SSHFP, essas extensões teriam que validar as DNSSEC, já que o navegador ou o SO podem não fazê-lo.

Desde 2016, o DNS público do Google oferece uma API compatível com a Web para DoH com DNSSEC validação que não requer configurações ou extensões de navegador ou sistema operacional. Parâmetros de consulta GET simples e respostas JSON permitem que os clientes analisem usando APIs da Web comuns e evite detalhes complexos sobre formatos de mensagens DNS, como compactação de ponteiro para nomes de domínio.

Consulte a página de documentação geral do DoH para informações sobre o DoH. em geral, como cabeçalhos HTTP, tratamento de redirecionamentos, práticas recomendadas de privacidade e Códigos de status HTTP.

A página Transportes seguros tem Exemplos de linha de comando curl para DoH e informações comuns para DoH e DNS por TLS (DoT), como suporte a TLS e truncamento de DNS.

Especificação da API JSON

Todas as chamadas de API são solicitações HTTP GET. No caso de parâmetros duplicados, somente o primeiro valor será usado.

Parâmetros aceitos

nome

string, obrigatório

O único parâmetro obrigatório. Escapes de barra invertida RFC 4343 são aceitos.

O comprimento (após a substituição dos escapes de barra invertida) deve estar entre 1 e 253 (ignorando um ponto final opcional, se houver).
Todos os rótulos (partes do nome entre pontos) precisam ter de 1 a 63 bytes.
Nomes inválidos como .example.com, example..com ou string vazia são recebidos 400 Solicitação inválida.
Caracteres não ASCII precisam ser codificados (xn--qxam, e não ελ).

tipo

string. Padrão: 1

O tipo de RR pode ser representado como um número em [1, 65535] ou uma string canônica (não diferencia maiúsculas de minúsculas, como A ou aaaa). Você pode usar 255 para "QUALQUER" consultas, mas saiba que isso não é um substituto para o envio de consultas para os registros A e AAAA ou MX. Servidores de nomes autoritativos não precisam retornar todos os registros para essas consultas; algumas não respondem, e outras (como cloudflare.com) retornam apenas HINFO.

cd

booleano, padrão: false

O flag CD (verificação desativada). Use cd=1 ou cd=true para desativar a validação das DNSSEC. use cd=0, cd=false ou nenhum parâmetro cd para ativar a validação das DNSSEC.

unid.

string, padrão: vazia

Opção de tipo de conteúdo desejada. Use ct=application/dns-message para receber uma mensagem DNS binária no ao corpo HTTP de resposta do Google em vez do texto JSON. Use ct=application/x-javascript para solicitar explicitamente o texto JSON. Outros valores de tipo de conteúdo são ignorados e o conteúdo JSON padrão é retornado.

fazer

booleano, padrão: false

A sinalização DO (DNSSEC OK). Use do=1 ou do=true para incluir registros DNSSEC (RRSIG, NSEC, NSEC3). use do=0, do=false ou nenhum parâmetro do para omitir os registros das DNSSEC.

Os aplicativos devem sempre processar (e ignorar, se necessário) qualquer DNSSEC registros em respostas JSON, pois outras implementações podem sempre incluí-los, e podemos mudar o comportamento padrão das respostas JSON no futuro. As respostas de mensagens DNS binárias sempre respeitam o valor da sinalização DO.

edns_client_subnet

string, padrão: vazia

A opção edns0-client-subnet. O formato é um endereço IP com uma máscara de sub-rede. Exemplos: 1.2.3.4/24, 2001:700:300::/48.

Se estiver usando DNS sobre HTTPS por questões de privacidade e não quiser qualquer parte do seu endereço IP a ser enviada para servidores de nomes autoritativos Para precisão de localização geográfica, use edns_client_subnet=0.0.0.0/0. O DNS público do Google normalmente envia informações aproximadas da rede (geralmente zerando a última parte do endereço IPv4).

random_padding

string, ignorado

O valor desse parâmetro é ignorado. Exemplo: XmkMw~o_mgP2pf.gpw-Oi5dK.

Os clientes de API preocupados com possíveis ataques à privacidade de canal lateral usando a tamanhos de pacote de solicitações GET HTTPS podem usar isso para fazer com que todas as solicitações do mesmo tamanho preenchendo solicitações de preenchimento com dados aleatórios. Para evitar que o URL seja interpretado incorretamente, restrinja os caracteres de padding aos caracteres de URL não reservados: letras maiúsculas e minúsculas, dígitos, hífen, ponto, sublinhado e til.

Resposta DNS em JSON

Uma resposta bem-sucedida (os comentários adicionados aqui não estão presentes nas respostas reais):

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

Consulte RFC 7871 (sub-rede do cliente EDNS) para detalhes sobre o "tamanho do prefixo do escopo" e como isso afeta o armazenamento em cache.

Uma resposta de falha com informações de diagnóstico:

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

Registros SPF e TXT com aspas incorporadas e atribuição de servidor de nomes:

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

Strings de DNS

Todos os registros TXT são codificados como uma única string JSON, incluindo usos de TXT mais longos formatos de registro como RFC 4408 (SPF) ou RFC 4871 (DKIM).

EDNS

O mecanismo geral de extensão de EDNS não é compatível. A opção Sub-rede do cliente EDNS (edns-client-subnet) é um parâmetro na GET e um campo de nível superior na resposta JSON.