https://ietf-wg-acme.github.io/acme/draft-ietf-acme-acme.html
Рабочая группа ACME Р. Барнс
Интернет-проект Cisco
Предполагаемый статус: Стандарт Track Дж. Хоффман-Эндрюс
Истекает: 21 мая 2018 г. EFF
J. Kasten
университет Мичигана
17 ноября 2017 г.
Автоматическая среда управления сертификатами (ACME)
draft-ietf-acme-acme-latest
Абстрактные
Сертификаты в PKI с использованием X.509 (PKIX) используются для ряда целей, наиболее значимым из которых является аутентификация доменных имен. Таким образом, органам сертификатов в веб-PKI доверяют, чтобы убедиться, что заявитель для сертификата на законных основаниях представляет доменное имя (имена) в сертификате. Сегодня эта проверка проводится с помощью набора специальных механизмов. В этом документе описывается протокол, который может использоваться центром сертификации (CA) и заявителем для автоматизации процесса проверки и выдачи сертификатов. Протокол также предоставляет возможности для других функций управления сертификатами, таких как аннулирование сертификата.
ОТКАЗ ОТ ОТВЕТСТВЕННОСТИ: Это подготовленный проектом ACME проект и еще не провел тщательного анализа безопасности.
РЕДАКТОР RFC: ПОЖАЛУЙСТА, УДАЛИТЕ СЛЕДУЮЩИЙ ПАРАГРАФ: Источник этого проекта поддерживается в GitHub. Предложенные изменения должны быть представлены в виде запросов на загрузку по адресу https://github.com/ietf-wg-acme/acme. Инструкции также находятся на этой странице. Редакционные изменения могут управляться в GitHub, но любые существенные изменения должны обсуждаться в списке рассылки ACME (acme@ietf.org).
Статус этой заметки
Настоящий Интернет-проект представляется в полном соответствии с положениями BCP 78 и BCP 79.
Интернет-проекты - это рабочие документы Целевой группы Internet Engineering Task Force (IETF). Обратите внимание, что другие группы могут также распространять рабочие документы в виде интернет-черновиков. Список текущих интернет-проектов находится по адресу https://datatracker.ietf.org/drafts/current/.
Интернет-проекты - это проекты документов, действительные в течение максимум шести месяцев и могут быть обновлены, заменены или устарели другими документами в любое время. Нецелесообразно использовать Internet-Drafts в качестве справочного материала или ссылаться на них, кроме как «работа в процессе».
Этот интернет-проект истекает 21 мая 2018 года.
Уведомление об авторских правах
Copyright (c) 2017 Trust IETF и лица, идентифицированные как авторы документа. Все права защищены.
Этот документ подлежит BCP 78 и правовым положениям IETF Trust, относящимся к документам IETF (https://trustee.ietf.org/license-info), действующим на дату публикации этого документа. Пожалуйста, внимательно ознакомьтесь с этими документами, поскольку они описывают ваши права и ограничения в отношении этого документа. Компоненты кода, извлеченные из этого документа, должны включать в себя упрощенный текст лицензии BSD, как описано в разделе 4.e Доверенных правовых положений, и предоставляются без гарантии, как описано в упрощенной лицензии BSD.
Содержание
1. Введение
2. Модель развертывания и опыт работы оператора
3. Терминология
4. Обзор протокола
5. Кодировка символов
6. Транспорт сообщений
6.1. Запросы HTTPS
6.2. Аутентификация запроса
6.3. Целостность URL-адреса запроса
6.3.1. Параметр заголовка JWS "URL-адрес" (URL)
6.4. Защита воспроизведения
6.4.1. Replay-Нонс
6.4.2. Параметр заголовка «nonce» (Nonce) JWS
6,5. Пределы ставок
6.6. ошибки
7. Управление сертификатами
7.1. Ресурсы
7.1.1. каталог
7.1.2. Объекты аккаунта
7.1.3. Объекты заказа
7.1.4. Объекты авторизации
7.2. Получение Nonce
7.3. Создание аккаунта
7.3.1. Поиск URL-адреса учетной записи с учетом ключа
7.3.2. Обновление учетной записи
7.3.3. Информация об аккаунте
7.3.4. Изменения Условий обслуживания
7.3.5. Внешняя привязка учетной записи
7.3.6. Переключение учетной записи
7.3.7. Деактивация учетной записи
7.4. Подача заявки на выдачу сертификата
7.4.1. Pre-Authorization
7.4.2. Загрузка сертификата
7,5. Авторизация идентификатора
7.5.1. Реагирование на вызовы
7.5.2. Деактивация авторизации
7,6. Отмена сертификата
8. Задачи проверки идентификатора
8.1. Основные полномочия
8.2. Повторные вызовы
8.3. HTTP-вызов
8.4. TLS с индикацией имени сервера (TLS SNI)
8,5. DNS-вызов
8.6. Внеполосный вызов
9. Соображения IANA
9.1. MIME Тип: application / pem-certificate-chain
9.2. Хорошо известный URI для HTTP-теста
9.3. Заголовок заголовка Replay-Nonce HTTP
9.4. Параметр заголовка JWS "url"
9.5. Параметр заголовка JWS "nonce"
9.6. URN Подпространство имен для ACME (urn: ietf: params: acme)
9,7. Новые реестры
9.7.1. Поля в объектах учетной записи
9.7.2. Поля в объектах заказа
9.7.3. Типы ошибок
9.7.4. Типы ресурсов
9.7.5. Типы идентификаторов
9.7.6. Методы валидации
10. Вопросы безопасности
10.1. Модель угрозы
10,2. Целостность полномочий
10.3. Отказ в обслуживании
10.4. Подделка запроса на стороне сервера
10.5. Вопросы политики CA
11. Оперативные соображения
11.1. Безопасность DNS
11.2. Виртуальные хосты по умолчанию
11.3. Энциклопедия токенов
11,4. Отверженные цепочки сертификатов
12. Благодарности
13. Ссылки
13,1. Нормативные ссылки
13,2. Информационные ссылки
Адреса авторов
1. Введение
Сертификаты [RFC5280] в веб-PKI чаще всего используются для аутентификации доменных имен. Таким образом, органам сертификатов в веб-PKI доверяют, чтобы убедиться, что заявитель для сертификата на законных основаниях представляет доменное имя (имена) в сертификате.
Различные типы сертификатов отражают различные виды CA-проверки информации о предмете сертификата. Сертификаты «Проверка домена» (DV) являются наиболее распространенным типом. Для проверки DV CA просто проверяет, что запросчик имеет эффективный контроль над веб-сервером и / или DNS-сервером для домена, но явно не пытается проверить их реальную идентичность. (Это, в отличие от сертификатов «Организация валидации» (OV) и «Расширенная проверка» (EV), где этот процесс предназначен также для проверки подлинности подлинника реквестера.)
Существующие органы сертификации веб-PKI, как правило, работают по набору специальных протоколов для выдачи сертификатов и проверки подлинности. В случае сертификатов DV типичный пользовательский интерфейс выглядит примерно так:
Сгенерируйте запрос на подписание сертификата PKCS # 10 [RFC2986] (CSR).
Вырезать и вставить CSR на веб-страницу CA.
Докажите владение доменом одним из следующих способов:
Поместите предоставленную CA задачу в определенное место на веб-сервере.
Поместите вызов, предоставленный CA, в местоположение DNS, соответствующее целевому домену.
Получите запрос CA на (надеюсь) управляемый администратором адрес электронной почты, соответствующий домену, а затем ответьте на него на веб-странице CA.
Загрузите выпущенный сертификат и установите его на свой веб-сервер.
За исключением самой CSR и выданных сертификатов, все они являются полностью ad hoc-процедурами и выполняются путем предоставления пользователю-пользователю возможности следовать интерактивным инструкциям на естественном языке из CA, а не по опубликованным машинным протоколам. Во многих случаях инструкции трудно следовать и вызывать значительную путаницу. Неофициальные тесты на удобство использования авторами показывают, что веб-мастерам часто требуется 1-3 часа для получения и установки сертификата для домена. Даже в лучшем случае отсутствие опубликованных стандартизированных механизмов представляет собой препятствие для широкого развертывания HTTPS и других PKIX-зависимых систем, поскольку оно препятствует механизации задач, связанных с выдачей, развертыванием и отзывом сертификатов.
В этом документе описывается расширяемая структура для автоматизации процедуры выдачи и проверки домена, что позволяет серверам и инфраструктурному программному обеспечению получать сертификаты без взаимодействия с пользователем. Использование этого протокола должно радикально упростить развертывание HTTPS и практичность проверки подлинности PKIX для других протоколов на основе безопасности транспортного уровня (TLS) [RFC5246].
Следует отметить, что, хотя основное внимание в этом документе уделяется проверке доменных имен для целей выдачи сертификатов в веб-PKI, ACME поддерживает расширения для использования с другими идентификаторами в других контекстах PKI. Например, на момент написания этой статьи продолжается работа по использованию ACME для выдачи сертификатов WebPKI, подтверждающих IP-адреса [ID.ietf-acme-ip] и сертификаты STIR, подтверждающие номера телефонов [ID.ietf-acme-phone].
ACME также может использоваться для автоматизации некоторых аспектов управления сертификатами даже там, где по-прежнему необходимы неавтоматические процессы. Например, функция привязки внешней учетной записи (см. Раздел 7.3.5) может использоваться для связывания полномочий с учетной записью, которая не была проверена с помощью процесса авторизации ACME. Это позволяет ACME решать сценарии выпуска, которые еще не могут быть полностью автоматизированы, например, выдача сертификатов расширенной проверки.
2. Модель развертывания и опыт работы оператора
Руководящим вариантом использования ACME является получение сертификатов для веб-сайтов (HTTPS [RFC2818]). В этом случае веб-сервер пользователя должен выступать за один или несколько доменов, а процесс выдачи сертификата предназначен для проверки того, что этот веб-сервер действительно говорит для домена (ов).
Проверка сертификата DV обычно проверяет утверждения о свойствах, связанных с управлением доменным именем, - свойствами, которые могут быть обнаружены эмитентом сертификата в интерактивном процессе, который может быть проведен исключительно в Интернете. Это означает, что при типичных обстоятельствах все этапы процесса запроса, проверки и выдачи могут быть представлены и выполняться с помощью интернет-протоколов без вмешательства человека вне диапазона.
До ACME при развертывании HTTPS-сервера оператор обычно получает запрос на создание самозаверяющего сертификата. Если бы оператор вместо этого использовал сервер HTTPS с использованием ACME, опыт был бы примерно таким:
Клиент ACME запрашивает у оператора предполагаемые имена (имена) доменов, на которые должен стоять веб-сервер.
Клиент ACME представляет оператору список CA, из которого он может получить сертификат. (Этот список со временем изменится на основе возможностей ЦС и обновлений конфигурации ACME.) Клиент ACME может запросить у оператора информацию о платежах в этот момент.
Оператор выбирает CA.
В фоновом режиме клиент ACME связывается с ЦС и запрашивает выдачу сертификата для предполагаемых доменных имен.
CA проверяет, что клиент управляет запрошенным доменным именем (именами).
Как только CA будет удовлетворен, сертификат выдается, и клиент ACME автоматически загружает и устанавливает его, потенциально уведомляя оператора по электронной почте, SMS и т. Д.
Клиент ACME периодически связывается с ЦС для получения обновленных сертификатов, сшитых ответов OCSP или любого другого, что потребуется, чтобы поддерживать функциональность веб-сервера и его учетные данные в актуальном состоянии.
Таким образом, было бы так же легко развернуть с сертификатом CA, как с самозаверяющим сертификатом. Кроме того, для обслуживания этого сертификата, выданного CA, потребуется минимальное ручное вмешательство. Такая тесная интеграция ACME с серверами HTTPS позволяет немедленное и автоматическое развертывание сертификатов по мере их выпуска, избавляя администратора от большей части трудоемкой работы, описанной в предыдущем разделе.
3. Терминология
Ключевыми словами «ДОЛЖЕН», «НЕ ДОЛЖЕН», «ТРЕБУЕТСЯ», «ДОЛЖЕН», «НЕ ДОЛЖЕН», «СЛЕДУЕТ», «НЕ ДОЛЖЕН», «РЕКОМЕНДУЕТСЯ», «МОЖЕТ» и «ДОПОЛНИТЕЛЬНО» в этом документе для интерпретации, как описано в RFC 2119 [RFC2119].
Две основные роли в ACME - «клиент» и «сервер». Клиент ACME использует протокол для запроса действий управления сертификатами, таких как выдача или аннулирование. Клиент ACME может работать на веб-сервере, почтовом сервере или какой-либо другой серверной системе, которая требует действительных сертификатов TLS. Или он может работать на отдельном сервере, который не использует сертификат, но имеет право отвечать на вызов, предоставленный CA. Сервер ACME запускается в центре сертификации и отвечает на запросы клиентов, выполняя запрошенные действия, если клиент авторизовался.
Клиент ACME представлен «парой ключей учетной записи». Клиент использует закрытый ключ этой пары ключей для подписывания всех сообщений, отправленных на сервер. Сервер использует открытый ключ для проверки подлинности и целостности сообщений от клиента.
4. Обзор протокола
ACME позволяет клиенту запрашивать действия по управлению сертификатами, используя набор сообщений JavaScript Object Notation (JSON), переносимых через HTTPS. Во многих отношениях ACME функционирует так же, как традиционный ЦС, в котором пользователь создает учетную запись, запрашивает сертификат и проверяет контроль над доменами в этом сертификате, чтобы ЦС подписал запрошенный сертификат.
Первый этап ACME заключается в том, что клиент запрашивает учетную запись на сервере ACME. Клиент генерирует асимметричную пару ключей и запрашивает новую учетную запись, опционально предоставляя контактную информацию, соглашаясь с условиями обслуживания и / или связывая учетную запись с существующей учетной записью в другой системе. Запрос создания подписан с помощью сгенерированного закрытого ключа, чтобы доказать, что клиент контролирует его.
Клиентский сервер
Контактная информация
Соглашение о предоставлении услуг
Дополнительная информация
Подпись ------->
<------- Учетная запись
Как только учетная запись зарегистрирована, для получения сертификата необходимо выполнить три основных шага:
Оформить заказ на выдачу сертификата
Докажите контроль над любыми идентификаторами, запрошенными в сертификате
Ожидайте выпуск и загрузку выданного сертификата
Заказ клиента для сертификата описывает желаемый сертификат с использованием запроса подписки на сертификат PKCS № 10 (CSR) плюс несколько дополнительных полей, которые захватывают семантику, которые не поддерживаются в формате CSR. Если сервер желает рассмотреть вопрос о выдаче такого сертификата, он отвечает списком требований, которые клиент должен удовлетворить до выдачи сертификата.
Например, в большинстве случаев серверу требуется, чтобы клиент продемонстрировал, что он контролирует идентификаторы в запрошенном сертификате. Поскольку существует много разных способов проверки владения различными типами идентификаторов, сервер будет выбирать из расширяемого набора проблем, которые подходят для заявленного идентификатора. Клиент отвечает набором ответов, которые сообщают серверу, который вызывает проблемы с клиентом. Затем сервер проверяет проблемы, чтобы проверить, что клиент выполнил их.
Как только процесс проверки завершен, и сервер удовлетворен тем, что клиент выполнил свои требования, сервер выдаст запрошенный сертификат и сделает его доступным для клиента.
порядок
Подпись ------->
необходимые
<------- Авторизация
Ответы
Подпись ------->
<~~~~~~~~ Validation ~~~~~~~~>
<------- Сертификат
Чтобы отозвать сертификат, клиент отправляет подписанный аннулированный запрос, указывающий, что сертификат должен быть отозван:
Клиентский сервер
Запрос отзыва
Подпись -------->
<-------- Результат
Обратите внимание, что в то время как ACME определяется с достаточной гибкостью для обработки различных типов идентификаторов в принципе, основной случай использования, адресованный этим документом, - это случай, когда имена доменов используются в качестве идентификаторов. Например, все проблемы проверки идентификатора, описанные в разделе 8 ниже, проверяют проверку имен доменов. Использование ACME для других идентификаторов потребует дополнительных спецификаций, чтобы описать, как эти идентификаторы закодированы в протоколе, и какие типы проблем проверки, которые могут потребоваться серверу.
5. Кодировка символов
Все запросы и ответы, отправленные через HTTP клиентами ACME, серверами ACME и серверами проверки, а также любые входы для вычислений дайджеста ДОЛЖНЫбыть закодированы с использованием набора символов UTF-8 [RFC3629].
6. Транспорт сообщений
Связь между клиентом ACME и сервером ACME выполняется через HTTPS с использованием JSON Web Signature (JWS) [RFC7515], чтобы предоставить некоторые дополнительные свойства безопасности для сообщений, отправленных клиентом на сервер. HTTPS обеспечивает аутентификацию и конфиденциальность сервера. С некоторыми расширениями, поддерживающими ACME, JWS обеспечивает аутентификацию полезных запросов клиента, защиту от повторного воспроизведения и целостность URL-адреса запроса HTTPS.
6.1. Запросы HTTPS
Каждая функция ACME выполняется клиентом, отправляющим на сервер последовательность запросов HTTPS, несущих сообщения JSON [RFC2818] [RFC7159]. ТРЕБУЕТСЯ использование HTTPS. В каждом подразделе раздела 7 ниже описаны форматы сообщений, используемые функцией и порядок отправки сообщений.
В большинстве транзакций HTTPS, используемых ACME, клиент ACME является клиентом HTTPS, а сервером ACME является сервер HTTPS. Сервер ACME выступает в качестве клиента HTTP и HTTPS при проверке проблем через HTTP.
Серверы ACME ДОЛЖНЫследовать рекомендациям [RFC7525] при настройке своих TLS-реализаций. Серверы ACME, поддерживающие TLS 1.3, могут разрешать клиентам отправлять ранние данные (0xRTT). Это безопасно, поскольку сам протокол ACME включает защиту от повторного воспроизведения (см. Раздел 6.4).
Клиенты ACME ДОЛЖНЫотправлять заголовок User-Agent в соответствии с [RFC7231], включая имя и версию программного обеспечения ACME в дополнение к имени и версии базового программного обеспечения HTTP-клиента.
Клиенты ACME ДОЛЖНЫотправлять заголовок Accept-Language в соответствии с [RFC7231], чтобы включить локализацию сообщений об ошибках.
Для доступа к серверам ACME, которые обычно доступны для доступа, необходимо использовать совместное использование ресурсов Cross-Origin (CORS) для доступа к браузерам [W3C.CR-cors-20130129]. Такие серверы СЛЕДУЕТ установить поле заголовка Access-Control-Allow-Origin значением «*».
Двоичные поля в объектах JSON, используемые ACME, кодируются с использованием кодировки base64url, описанной в разделе [RFC4648] в соответствии с профилем, указанным в разделе JSON Web Signature [RFC7515]. 2. В этой кодировке используется безопасный набор символов URL. Трейлинг символов '=' ДОЛЖЕН быть разделен.
6.2. Аутентификация запроса
Все запросы ACME с непустым телом ДОЛЖНЫинкапсулировать свою полезную нагрузку в объект JSON Web Signature (JWS) [RFC7515], подписанный с использованием закрытого ключа учетной записи, если не указано иное. Сервер ДОЛЖЕН проверять JWS перед обработкой запроса. Инкапсулирующие органы запроса в JWS обеспечивают аутентификацию запросов.
Объекты JWS, отправленные в запросах ACME, ДОЛЖНЫсоответствовать следующим дополнительным критериям:
JWS НЕ ДОЛЖЕН иметь значение «none» в своем поле «alg»
JWS НЕ ДОЛЖЕН иметь алгоритм на основе кода аутентификации сообщения (MAC) в своем поле «alg»
Защищенный заголовок JWS ДОЛЖЕН включать следующие поля:
"Alg" (Алгоритм)
«Jwk» (JSON Web Key, только для запросов к ресурсам новой учетной записи и отзыва)
«Kid» (идентификатор ключа, для всех других запросов)
«Nonce» (определяется в разделе 6.4 ниже)
«Url» (определенный в разделе 6.3 ниже)
Поля «jwk» и «kid» являются взаимоисключающими. Серверы ДОЛЖНЫотклонять запросы, содержащие оба.
Для запросов новой учетной записи и для запросов отзыва-cert, заверенных ключом сертификата, ДОЛЖНО быть поле «jwk».
Для всех других запросов ДОЛЖНО быть полем «ребенок». Это поле должно содержать URL-адрес учетной записи, полученный POSTing, на ресурс новой учетной записи.
Обратите внимание, что аутентификация через подписанные службы запросов JWS подразумевает, что запросы GET не аутентифицированы. Серверы НЕ ДОЛЖНЫотвечать на запросы GET для ресурсов, которые могут считаться чувствительными. Ресурсы учетной записи являются единственными чувствительными ресурсами, определенными в этой спецификации.
Если клиент отправляет JWS, подписанный с алгоритмом, который сервер не поддерживает, сервер ДОЛЖЕН возвращать ошибку с кодом состояния 400 (Bad Request) и набирать «urn: ietf: params: acme: error: badSignatureAlgorithm». Документ проблемы, возвращаемый с ошибкой, ДОЛЖЕН включать в себя поле «алгоритмы» с массивом поддерживаемых значений «alg».
В приведенных ниже примерах объекты JWS показаны в JSON или сплющенной JSON-сериализации с защищенным заголовком и полезной нагрузкой, выраженными как base64url (контент), а не фактическим значением, закодированным base64, чтобы содержимое было читаемым.
6.3. Целостность URL-адреса запроса
Обычно в развертывании для объекта, заканчивающего TLS для HTTPS, отличается от объекта, работающего на логическом сервере HTTPS, с уровнем «маршрутизации запроса» посередине. Например, CA ACME может иметь сеть доставки контента, которая завершает соединения TLS от клиентов, чтобы она могла проверять клиентские запросы на защиту от отказа в обслуживании.
Эти посредники также могут изменять значения в запросе, который не подписан в запросе HTTPS, например URL-адрес запроса и заголовки. ACME использует JWS для обеспечения механизма целостности, который защищает от посредника, изменяющего URL-адрес запроса, на другой URL-адрес ACME.
Как отмечено в разделе 6.2 выше, все объекты запроса ACME несут параметр заголовка «url» в защищенном заголовке. Этот параметр заголовка кодирует URL-адрес, на который клиент направляет запрос. При получении такого объекта в HTTP-запросе сервер ДОЛЖЕН сравнить параметр заголовка «url» с URL-адресом запроса. Если эти два не совпадают, тогда сервер ДОЛЖЕН отклонить запрос как неавторизованный.
За исключением ресурса каталога, все ресурсы ACME адресуются URL-адресами, предоставленными клиенту сервером. Для этих ресурсов клиент ДОЛЖЕН установить параметр заголовка «url» в точную строку, предоставленную сервером (вместо выполнения какого-либо повторного кодирования по URL-адресу). Сервер ДОЛЖЕН выполнить соответствующую проверку равенства строк, настроив каждый ресурс на строку URL, предоставленную клиентам, и проверит проверку ресурсов, что запросы имеют одну и ту же строку в своем параметре заголовка «url».
6.3.1. Параметр заголовка JWS "URL-адрес" (URL)
Параметр заголовка «url» указывает URL [RFC3986], которому направлен этот объект JWS. Параметр заголовка «url» ДОЛЖЕН быть перенесен в защищенный заголовок JWS. Значение параметра заголовка «url» ДОЛЖНО быть строкой, представляющей URL-адрес.
6.4. Защита воспроизведения
Чтобы защитить ресурсы ACME от любых возможных повторных атак, запросы ACME имеют обязательный механизм против повтора. Этот механизм основан на сервере, поддерживающем список несетов, который он выдал клиентам, и требует, чтобы какой-либо подписанный запрос от клиента выполнял такое nonce.
Сервер ACME предоставляет клиентам nonce, используя поле заголовка Replay-Nonce, как указано в разделе 6.4.1 ниже. Сервер ДОЛЖЕН включать поле заголовка Replay-Nonce в каждом успешном ответе на запрос POST и СЛЕДУЕТ предоставлять его также в ответах об ошибках.
Каждый JWS, отправленный клиентом ACME, ДОЛЖЕН включать в свой защищенный заголовок параметр «nonce» с содержимым, как определено в разделе 6.4.2 ниже. В рамках проверки JWS сервер ACME ДОЛЖЕН проверить, что значение заголовка «nonce» является значением, которое ранее было предоставлено сервером в поле заголовка Replay-Nonce. Как только значение nonce появилось в запросе ACME, сервер ДОЛЖЕН считать его недействительным, так же как значение, которое оно никогда не выдавало.
Когда сервер отклоняет запрос, потому что его значение nonce было неприемлемым (или не присутствовало), оно ДОЛЖНО предоставлять код состояния HTTP 400 (Bad Request) и указывать тип ошибки ACME «urn: ietf: params: acme: error: badNonce». Ответ об ошибке с типом ошибки «badNonce» ДОЛЖЕН включать заголовок Replay-Nonce со свежим носом. При получении такого ответа клиент ДОЛЖЕН повторить запрос с использованием нового nonce.
Точный метод, используемый для генерации и отслеживания nonces, зависит от сервера. Например, сервер может генерировать случайное 128-битное значение для каждого ответа, сохранять список выпущенных нот и удалять ноты из этого списка по мере их использования.
6.4.1. Replay-Нонс
Поле заголовка «Replay-Nonce» содержит генерируемое сервером значение, которое сервер может использовать для обнаружения несанкционированного воспроизведения в будущих клиентских запросах. Сервер ДОЛЖЕН генерировать значение, предоставленное в Replay-Nonce, таким образом, что они уникальны для каждого сообщения с высокой вероятностью. Например, допустимо генерировать Replay-Nonces случайным образом.
Значение поля Replay-Nonce ДОЛЖНО быть строкой октета, закодированной в соответствии с кодировкой base64url, описанной в разделе 2 документа [RFC7515]. Клиенты ДОЛЖНЫигнорировать недопустимые значения Replay-Nonce.
base64url = [AZ] / [az] / [0-9] / "-" / "_"
Replay-Nonce = * base64url
Поле заголовка Replay-Nonce НЕ ДОЛЖНО быть включено в сообщения HTTP-запроса.
6.4.2. Параметр заголовка «nonce» (Nonce) JWS
Параметр заголовка «nonce» предоставляет уникальное значение, которое позволяет верификатору JWS распознавать, когда произошло повторное воспроизведение. Параметр заголовка «nonce» ДОЛЖЕН быть перенесен в защищенный заголовок JWS.
Значение параметра заголовка «nonce» ДОЛЖНО быть октетной строкой, закодированной в соответствии с кодировкой base64url, описанной в разделе 2 документа [RFC7515]. Если значение параметра «nonce» недействительно в соответствии с этой кодировкой, то верификатор ДОЛЖЕН отклонить JWS как некорректный.
6,5. Пределы ставок
Создание ресурсов может быть ограничено курсом для обеспечения справедливого использования и предотвращения злоупотреблений. Как только предел скорости превышен, сервер ДОЛЖЕН ответить на ошибку с типом «urn: ietf: params: acme: error: rateLimited». Кроме того, сервер СЛЕДУЕТ отправить заголовок «Повторить-После», указывающий, когда текущий запрос может снова завершиться. Если установлены несколько ограничений скорости, это время, когда все ограничения скорости позволяют снова получить доступ к текущему запросу с точно такими же параметрами.
В дополнение к понятному пользователю «подробному» полю ответа об ошибке сервер МОЖЕТ отправить один или несколько токенов в заголовок «Ссылка», указывающий на документацию о конкретных предельных значениях скорости, используя параметр «urn: ietf: params: acme: документация ".
6.6. ошибки
Ошибки могут быть сообщены в ACME как на уровне HTTP, так и в объектах-запросах, как определено в разделе 8. Серверы ACME могут возвращать ответы с кодом ответа HTTP-кода (4XX или 5XX). Например: если клиент отправляет запрос с использованием метода, не разрешенного в этом документе, тогда сервер МОЖЕТ возвращать код состояния 405 (метод не разрешен).
Когда сервер отвечает со статусом ошибки, ему ДОЛЖЕН предоставлять дополнительную информацию, используя проблемный документ [RFC7807]. Чтобы облегчить автоматический ответ на ошибки, этот документ определяет следующие стандартные токены для использования в поле «тип» (в пространстве имен «urn: ietf: params: acme: error:»):
Тип Описание
badCSR CSR неприемлем (например, из-за короткого ключа)
badNonce Клиент отправил неприемлемый анти-повтор
badSignatureAlgorithm JWS был подписан с алгоритмом, который сервер не поддерживает
invalidContact Недопустимый URL-адрес контакта для учетной записи.
unsupportedContact URL-адрес контакта для учетной записи, используемой неподдерживаемой схемой протокола
Аккаунт не существует В запросе указана учетная запись, которая не существует
бесформенный Сообщение запроса искажено
rateLimited Запрос превышает лимит скорости
rejectedIdentifier Сервер не будет выдавать идентификатор
serverInternal На сервере произошла внутренняя ошибка
неразрешенный Клиенту не хватает достаточного разрешения
unsupportedIdentifier Идентификатор не поддерживается, но может быть в будущем
userActionRequired Посетите URL-адрес экземпляра и выполните действия, указанные там
badRevocationReason Предоставленная причина отзыва не разрешена сервером
CAA Записи авторизационного центра (CAA) запрещают CA выдавать
DNS Возникла проблема с DNS-запросом
соединение Сервер не смог подключиться к цели проверки
TLS Сервер получил ошибку TLS во время проверки
incorrectResponse Полученный ответ не соответствовал требованиям задачи
Этот список не является исчерпывающим. Сервер МОЖЕТ возвращать ошибки, для которых в поле «type» установлено значение URI, отличное от указанного выше. Серверы НЕ ДОЛЖНЫиспользовать пространство имен ACME URN [RFC3553] для ошибок, отличных от стандартных типов. Клиентам СЛЕДУЕТ отображать поле «подробно» всех ошибок.
7. Управление сертификатами
В этом разделе мы описываем функции управления сертификатами, которые ACME позволяет:
Создание аккаунта
Заказ сертификата
Авторизация идентификатора
Выдача сертификата
Отмена сертификата
7.1. Ресурсы
ACME структурирован как приложение REST со следующими типами ресурсов:
Ресурсы учетной записи, представляющие информацию об учетной записи (раздел 7.1.2, раздел 7.3)
Заказывать ресурсы, представляя запросы учетной записи для выдачи сертификатов (раздел 7.1.3)
Ресурсы авторизации, представляющие авторизацию учетной записи для действия для идентификатора (раздел 7.1.4)
Ресурсы вызова, представляющие проблему для проверки контроля идентификатора (раздел 7.5, раздел 8)
Ресурсы сертификатов, представляющие выпущенные сертификаты (раздел 7.4.2)
Ресурс «каталога» (раздел 7.1.1)
Ресурс «new-nonce» (раздел 7.2)
Ресурс «новая учетная запись» (раздел 7.3)
Ресурс «нового порядка» (раздел 7.4)
Ресурс «revoke-cert» (раздел 7.6)
Ресурс «смены ключа» (раздел 7.3.6)
Сервер ДОЛЖЕН предоставлять ресурсы «directory» и «new-nonce».
ACME использует разные URL-адреса для различных функций управления. Каждая функция указана в каталоге вместе с соответствующим URL-адресом, поэтому клиентам нужно настроить только URL-адрес каталога. Эти URL-адреса связаны несколькими отношениями ссылок [RFC5988].
Связь «вверх» используется с ресурсами вызова, чтобы указать ресурс авторизации, которому принадлежит вызов. Он также используется из ресурсов сертификатов для указания ресурса, из которого клиент может получить цепочку сертификатов ЦС, которые могут использоваться для проверки сертификата в исходном ресурсе.
Отношение ссылки «индекс» присутствует на всех ресурсах, отличных от каталога, и указывает URL-адрес каталога.
Следующая диаграмма иллюстрирует отношения между ресурсами на сервере ACME. По большей части эти отношения выражаются URL-адресами, представленными в виде строк в представлениях JSON ресурсов. Строки с метками в кавычках указывают отношения HTTP-ссылок.
каталог
|
| --Новости
|
---------------------------------- +
| | | |
| | | |
VVVV
new-account new-authz new-order revoke-cert
| | |
| | |
V | В
счет | заказать -----> cert
| |
| |
| В
+ ------> authz
| ^
| | «Вверх»
V |
вызов
Следующая таблица иллюстрирует типичную последовательность запросов, необходимых для создания новой учетной записи на сервере, проверки контроля идентификатора, выдачи сертификата и получения обновленного сертификата через некоторое время после выпуска. «->» - мнемоника для заголовка Location, указывающего на созданный ресурс.
действие Запрос отклик
Получите nonce HEAD new-nonce 204
Регистрация POST new-account 201 -> счет
Отправить заявку POST новый порядок 201 -> заказать
Выбор задач GET authz 200
Ответьте на вызов Задача POST 200
Опрос по статусу GET authz 200
Проверить наличие нового сертификата GET cert 200
В оставшейся части этого раздела дается подробная информация о том, как эти ресурсы структурированы и как используется протокол ACME.
7.1.1. каталог
Чтобы помочь клиентам настроить правильные URL-адреса для каждой операции ACME, серверы ACME предоставляют объект каталога. Это должен быть единственный URL, необходимый для настройки клиентов. Это объект JSON, имена полей которого взяты из следующей таблицы и значениями которых являются соответствующие URL-адреса.
поле URL в значении
новое временное значение Новый нонс
новый аккаунт Новый аккаунт
новый заказ Новый заказ
новый AuthZ Новая авторизация
отзывать-CERT Отменить сертификат
Ключ-изменения Изменение ключа
Не существует ограничений на фактический URL-адрес каталога, за исключением того, что он должен отличаться от других URL-адресов ресурсов сервера ACME и что он не должен конфликтовать с другими службами. Например:
хост, который функционирует как ACME, так и веб-сервер, может захотеть сохранить корневой путь «/» для «главной страницы» HTML и поместить каталог ACME под путь «/ acme».
хост, который функционирует только как сервер ACME, может поместить каталог под путь «/».
Объект MAY дополнительно содержит поле «meta». Если он присутствует, он ДОЛЖЕН быть объектом JSON; каждое поле объекта представляет собой элемент метаданных, относящихся к службе, предоставляемой сервером ACME.
Определены следующие элементы метаданных, все из которых являются ДОПОЛНИТЕЛЬНЫМИ:
«Условия обслуживания» (необязательно, строка):
URL, определяющий текущие условия обслуживания.
«Веб-сайт» (необязательно, строка):
URL-адрес HTTP или HTTPS, на котором размещается веб-сайт, содержащий дополнительную информацию об ACME-сервере.
«Caa-identity» (необязательно, массив строк):
Каждая строка ДОЛЖНА быть строчным именем хоста, которое сервер ACME распознает как относящийся к себе для проверки достоверности CAA, как определено в [RFC6844]. Это позволяет клиентам определять правильное имя домена эмитента для использования при настройке записей CAA.
Клиенты получают доступ к каталогу, отправляя запрос GET в URL-адрес каталога.
HTTP / 1.1 200 OK
Content-Type: application / json
{
«new-nonce»: «https://example.com/acme/new-nonce»,
«new-account»: «https://example.com/acme/new-account»,
«новый порядок»: «https://example.com/acme/new-order»,
«new-authz»: «https://example.com/acme/new-authz»,
«revoke-cert»: «https://example.com/acme/revoke-cert»,
«key-change»: «https://example.com/acme/key-change»,
"meta": {
«Условия обслуживания»: «https://example.com/acme/terms/2017-5-30»,
«веб-сайт»: «https://www.example.com/»,
"caa-identity": ["example.com"]
}
}
7.1.2. Объекты аккаунта
Ресурс учетной записи ACME представляет собой набор метаданных, связанных с учетной записью. Ресурсы учетной записи имеют следующую структуру:
статус (обязательно, строка):
Статус этого аккаунта. Возможные значения: «действительный», «деактивированный» и «аннулированный». Значение «деактивировано» должно использоваться для указания дезактивации, инициированной клиентом, тогда как «отменено» следует использовать для указания дезактивации, инициированной сервером.
contact (необязательно, массив строк):
Массив URL-адресов, которые сервер может использовать для связи с клиентом по вопросам, связанным с этой учетной записью. Например, сервер может пожелать уведомить клиента об аннулировании сервера или истечении срока действия сертификата.
Условия обслуживания (необязательные, логические):
Включение этого поля в запрос новой учетной записи со значением true указывает на согласие клиента с условиями обслуживания. Это поле не обновляется клиентом.
заказы (обязательные, строка):
URL-адрес, из которого список заказов, представленных этой учетной записью, можно получить с помощью запроса GET, как описано в разделе 7.1.2.1.
{
«status»: «valid»,
«контакт»: [
"Электронная почта: cert-admin@example.com",
"Электронная почта: admin@example.com"
],
«условия обслуживания»: true,
«заказы»: «https://example.com/acme/acct/1/orders»
}
7.1.2.1. Список заказов
Каждый объект учетной записи включает URL-адрес «заказы», из которого список заказов, созданных учетной записью, может быть пол<