Эта страница переведена с помощью Cloud Translation API.

JSON API для DNS через HTTPS (DoH)

Раньше веб-приложениям требовались расширения браузера для использования расширенных функций DNS, таких как DANE , обнаружение службы DNS-SD , или даже для разрешения чего-либо, кроме IP-адресов, например записей MX. Чтобы использовать функции, зависящие от DNSSEC, такие как записи SSHFP , любые такие расширения должны будут сами проверять DNSSEC, поскольку браузер или ОС могут этого не делать.

С 2016 года Google Public DNS предлагает удобный для Интернета API для DoH с проверкой DNSSEC, который не требует настройки или расширений браузера или ОС. Простые параметры запроса GET и ответы JSON позволяют клиентам анализировать результаты с помощью общих веб-API и избегать сложных деталей формата сообщений DNS, таких как сжатие указателей для доменных имен .

См. страницу общей документации DoH для получения общей информации о DoH, такой как заголовки HTTP, обработка перенаправления, рекомендации по обеспечению конфиденциальности и коды состояния HTTP.

На странице Secure Transports приведены примеры командной строки curl для DoH, а также информация, общая для DoH и DNS через TLS (DoT), например поддержка TLS и усечение DNS.

Спецификация API JSON

Все вызовы API представляют собой HTTP-запросы GET. В случае дублирования параметров используется только первое значение.

Поддерживаемые параметры

имя

строка, обязательна

Единственный обязательный параметр. Допускаются символы обратной косой черты RFC 4343.

Длина (после замены обратной косой черты) должна находиться в диапазоне от 1 до 253 (игнорируя необязательную конечную точку, если она присутствует).
Все метки (части имени между точками) должны иметь длину от 1 до 63 байт.
Недопустимые имена, такие как .example.com , example..com или пустая строка, получают 400 неверных запросов.
Символы, не входящие в ASCII, должны иметь точечный код ( xn--qxam , а не ελ ).

тип

строка, по умолчанию: 1

Тип RR может быть представлен как число в формате [1, 65535] или каноническая строка (без учета регистра, например A или aaaa ). Вы можете использовать 255 для запросов «ЛЮБЫЕ», но имейте в виду, что это не замена отправке запросов как для записей A, так и для записей AAAA или MX. Авторитетным серверам имен не обязательно возвращать все записи для таких запросов; некоторые не отвечают, а другие (например, Cloudflare.com) возвращают только HINFO.

компакт-диск

логическое значение, по умолчанию: false

Флаг CD (проверка отключена). Используйте cd=1 или cd=true , чтобы отключить проверку DNSSEC; используйте cd=0 , cd=false или не используйте параметр cd , чтобы включить проверку DNSSEC.

КТ

строка, по умолчанию: пустая

Желаемый вариант типа контента. Используйте ct=application/dns-message чтобы получить двоичное DNS-сообщение в теле ответа HTTP вместо текста JSON. Используйте ct=application/x-javascript для явного запроса текста JSON. Другие значения типов контента игнорируются, и возвращается содержимое JSON по умолчанию.

делать

логическое значение, по умолчанию: false

Флаг DO (DNSSEC OK). Используйте do=1 или do=true чтобы включить записи DNSSEC (RRSIG, NSEC, NSEC3); используйте параметр do=0 , do=false или no do , чтобы пропустить записи DNSSEC.

Приложения должны всегда обрабатывать (и игнорировать, если необходимо) любые записи DNSSEC в ответах JSON, поскольку другие реализации всегда могут включать их, и в будущем мы можем изменить поведение по умолчанию для ответов JSON. (Ответы на двоичные сообщения DNS всегда учитывают значение флага DO.)

edns_client_subnet

строка, по умолчанию: пустая

Опция edns0-client-subnet. Формат — IP-адрес с маской подсети. Примеры: 1.2.3.4/24 , 2001:700:300::/48 .

Если вы используете DNS-over-HTTPS из соображений конфиденциальности и не хотите, чтобы какая-либо часть вашего IP-адреса отправлялась на авторитетные серверы имен для обеспечения точности географического местоположения, используйте edns_client_subnet=0.0.0.0/0 . Google Public DNS обычно отправляет приблизительную информацию о сети (обычно обнуляет последнюю часть вашего IPv4-адреса).

Random_padding

строка, игнорируется

Значение этого параметра игнорируется. Пример: XmkMw~o_mgP2pf.gpw-Oi5dK .

Клиенты API, обеспокоенные возможными атаками на конфиденциальность по побочным каналам с использованием размеров пакетов HTTPS-запросов GET, могут использовать это, чтобы сделать все запросы одинакового размера, дополняя запросы случайными данными. Чтобы предотвратить неправильное толкование URL-адреса, ограничьте символы заполнения незарезервированными символами URL-адреса : буквами верхнего и нижнего регистра, цифрами, дефисом, точкой, подчеркиванием и тильдой.

Ответ DNS в формате JSON

Успешный ответ (добавленные здесь комментарии не присутствуют в реальных ответах):

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

См. RFC 7871 (клиентская подсеть EDNS) для получения подробной информации о «длине префикса области» и о том, как она влияет на кэширование.

Реакция на ошибку с диагностической информацией:

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

Записи SPF и TXT со встроенными кавычками и указанием сервера имен:

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

DNS-строки

Все записи TXT кодируются как одна строка JSON, включая использование более длинных форматов записей TXT, таких как RFC 4408 (SPF) или RFC 4871 (DKIM) .

ЭДНС

Общий механизм расширения EDNS не поддерживается. Параметр «Подсеть клиента EDNS» (edns-client-subnet) — это параметр запроса GET и поле верхнего уровня в ответе JSON.