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 do navegador para usar recursos avançados de DNS, como DANE, descoberta de serviço DNS-SD (em inglês) ou até mesmo para resolver algo que não fosse endereços IP, como registros MX. Para usar recursos dependentes de DNSSEC, como registros SSHFP, essas extensões precisam validar as DNSSEC por conta própria, já que o navegador ou o SO talvez não façam isso.

Desde 2016, o DNS público do Google oferece uma API otimizada para a Web para DoH com validação DNSSEC que não requer extensões ou configurações do navegador ou do SO. Os parâmetros de consulta GET e respostas JSON simples permitem que os clientes analisem os resultados usando APIs da Web comuns e evitem detalhes complexos sobre o formato de mensagem do DNS, como a compactação de ponteiro para nomes de domínio.

Consulte a página de documentação do DoH para mais informações sobre o DoH, como cabeçalhos HTTP, processamento de redirecionamento, 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 via 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, apenas o primeiro valor é usado.

Parâmetros suportados

name

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) precisa 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 recebem 400 Solicitação inválida.
Caracteres não ASCII precisam ser punyencoded (xn--qxam, não ελ).

digitar

string, padrão: 1

O tipo RR pode ser representado como um número em [1, 65535] ou uma string canônica (sem diferenciação de maiúsculas e minúsculas, como A ou aaaa). É possível usar 255 para consultas "QUALQUER", mas esteja ciente de que isso não é um substituto para enviar consultas para registros A e AAAA ou MX. Servidores de nomes autoritativos não precisam retornar todos os registros para essas consultas. Alguns não respondem e outros (como cloudflare.com) retornam somente HINFO.

cd

booleano, padrão: false

A sinalização de CD (Verificação desativada). Use cd=1 ou cd=true para desativar a validação de DNSSEC. Use cd=0, cd=false ou nenhum parâmetro cd para ativar a validação de DNSSEC.

unid.

string, padrão: vazio

Opção de tipo de conteúdo desejada. Use ct=application/dns-message para receber uma mensagem de DNS binária no corpo HTTP de resposta em vez de 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 DNSSEC.

Os aplicativos precisam sempre processar (e ignorar, se necessário) registros de DNSSEC nas respostas JSON, porque outras implementações sempre podem incluí-los. É possível que o comportamento padrão das respostas JSON seja alterado no futuro. As respostas de mensagens de DNS binárias sempre respeitam o valor da sinalização DO.

edns_client_subnet

string, padrão: vazio

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 você estiver usando DNS sobre HTTPS por questões de privacidade e não quiser que nenhuma parte do seu endereço IP seja enviada a servidores de nomes autoritativos para precisão da 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 da API preocupados com possíveis ataques de privacidade de canal lateral usando os tamanhos de pacote de solicitações GET HTTPS podem usar isso para fazer todas as solicitações exatamente do mesmo tamanho, preenchendo solicitações com dados aleatórios. Para evitar a interpretação incorreta do URL, 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 (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 a RFC 7871 (sub-rede do cliente EDNS) para saber mais sobre o "comprimento 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 DNS

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

EDNS

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