API de JSON para DNS por HTTPS (DoH)

Antes, las aplicaciones basadas en la Web requerían extensiones del navegador para usar funciones de DNS avanzadas como DANE y detección de servicios DNS-SD, o incluso para resolver cualquier otro elemento que no fueran las direcciones IP, como los registros MX. Para usar funciones que dependen de DNSSEC, como los registros SSHFP, esas extensiones deberían validar DNSSEC por sí mismas, ya que es posible que el navegador o el SO no lo hagan.

Desde 2016, el DNS público de Google ofrece una API optimizada para la Web para DoH con validación de DNSSEC que no requiere extensiones ni configuración del navegador o del SO. Los parámetros de consulta GET simples y las respuestas JSON permiten a los clientes analizar los resultados con las APIs web comunes y evitar detalles complejos del formato de mensajes DNS, como la compresión de puntero para nombres de dominio.

Consulta la página general de la documentación de DoH para obtener información general sobre este, como los encabezados HTTP, el manejo de redireccionamientos, las prácticas recomendadas de privacidad y los códigos de estado HTTP.

La página Transportes seguros tiene ejemplos de la línea de comandos de curl para DoH, además de información común al DoH y DNS mediante TLS (DoT), como la compatibilidad con TLS y el truncamiento de DNS.

Especificación de la API de JSON

Todas las llamadas a la API son solicitudes HTTP GET. En el caso de parámetros duplicados, solo se utiliza el primer valor.

Parámetros admitidos

name

cadena, obligatoria

Es el único parámetro obligatorio. Se aceptan los caracteres de escape de barra inversa RFC 4343.

  • La longitud (después de reemplazar los escapes de barra inversa) debe ser de entre 1 y 253 (si se ignora un punto final opcional, si está presente).
  • Todas las etiquetas (partes del nombre entre puntos) deben tener entre 1 y 63 bytes de longitud.
  • Los nombres no válidos, como .example.com, example..com o una string vacía, reciben el error 400 Bad Request.
  • Los caracteres que no son ASCII deben estar codificados con puntia (xn--qxam, no ελ).
tipo

string, valor predeterminado: 1

El tipo de RR se puede representar como un número en [1, 65535] o una cadena canónica (no distingue mayúsculas de minúsculas, como A o aaaa). Puedes usar 255 para las consultas "ANY", pero ten en cuenta que no es un reemplazo para enviar consultas de registros A y AAAA o MX. Los servidores de nombres autorizados no necesitan mostrar todos los registros para esas consultas. Algunas no responden y otros (como cloudflare.com) solo muestran HINFO.

cd

booleano, valor predeterminado: false

La marca de CD (verificación inhabilitada). Usa cd=1 o cd=true para inhabilitar la validación de DNSSEC; usa cd=0, cd=false, o ningún parámetro cd para habilitar la validación de DNSSEC.

cant.

string, valor predeterminado: vacío

Es la opción de tipo de contenido que deseas. Usa ct=application/dns-message para recibir un mensaje de DNS binario en el cuerpo HTTP de la respuesta, en lugar de texto JSON. Usa ct=application/x-javascript para solicitar texto JSON de manera explícita. Se ignoran otros valores de tipo de contenido y se muestra el contenido JSON predeterminado.

do

booleano, valor predeterminado: false

La marca DO (DNSSEC OK). Usa do=1 o do=true para incluir registros DNSSEC (RRSIG, NSEC, NSEC3); usa do=0, do=false o ningún parámetro do para omitir los registros DNSSEC.

Las aplicaciones siempre deben manejar (e ignorar, de ser necesario) cualquier registro de DNSSEC en las respuestas JSON, ya que otras implementaciones siempre pueden incluirlos. Además, es posible que cambiemos el comportamiento predeterminado de las respuestas de JSON en el futuro. (Las respuestas a los mensajes DNS binarios siempre respetan el valor de la marca DO).

edns_client_subnet

string, valor predeterminado: vacío

La opción edns0-client-subnet. El formato es una dirección IP con una máscara de subred. Ejemplos: 1.2.3.4/24 y 2001:700:300::/48.

Si usas DNS-over-HTTPS por cuestiones de privacidad y no quieres que ninguna parte de tu dirección IP se envíe a servidores de nombres autorizados para garantizar la precisión de la ubicación geográfica, utiliza edns_client_subnet=0.0.0.0/0. Por lo general, el DNS público de Google envía información de red aproximada (por lo general, coloca a cero la última parte de la dirección IPv4).

random_padding

cadena, ignorada

Se ignora el valor de este parámetro. Ejemplo: XmkMw~o_mgP2pf.gpw-Oi5dK.

Los clientes de API a los que les preocupan los posibles ataques a la privacidad del canal lateral que usan los tamaños de paquete de las solicitudes GET HTTPS pueden usar esto para hacer que todas las solicitudes tengan exactamente el mismo tamaño mediante el relleno de solicitudes con datos aleatorios. Para evitar que se malinterprete la URL, restringe los caracteres de padding a los caracteres de URL sin reservar: letras mayúsculas y minúsculas, dígitos, guiones, puntos, guiones bajos y virgulillas.

Respuesta de DNS en JSON

Una respuesta exitosa (los comentarios agregados aquí no aparecen en las respuestas reales):

{
  "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 (subred de cliente de EDNS) para obtener detalles sobre la “longitud del prefijo de alcance” y cómo afecta el almacenamiento en caché.

Una respuesta de falla con información 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 y TXT con comillas incorporadas y atribución del servidor de nombres:

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

Cadenas de DNS

Todos los registros TXT están codificados como una sola string JSON, incluidos los usos de formatos de registro TXT más largos, como RFC 4408 (SPF) o RFC 4871 (DKIM).

EDNS

No se admite el mecanismo de extensión de EDNS general. La opción de subred de cliente de EDNS (edns-client-subnet) es un parámetro en la solicitud GET y un campo de nivel superior en la respuesta JSON.