Модуль community.crypto.acme_certificate_order_create — создание заказа ACME v2
Примечание
Этот модуль является частью коллекции community.crypto (версия 3.2.1).
Возможно, эта коллекция уже установлена, если вы используете пакет ansible. Она не входит в состав ansible-core. Чтобы проверить, установлена ли она, выполните ansible-galaxy collection list.
Чтобы установить её, используйте: ansible-galaxy collection install community.crypto. Для использования этого модуля требуются дополнительные компоненты; подробности см. в разделе Требования.
Чтобы использовать его в плейбуке, укажите: community.crypto.acme_certificate_order_create.
Добавлено в community.crypto 2.24.0
Краткое описание
- Создаёт заказ ACME v2. Это первый этап получения нового сертификата с помощью протокола ACME от центра сертификации, например Let’s Encrypt. Этот модуль не поддерживает ACME v1 — исходную версию протокола ACME до его стандартизации.
- Текущая реализация поддерживает задачи
http-01,dns-01,dns-account-01,dns-persist-01иtls-alpn-01. - Этот модуль необходимо использовать вместе с модулями community.crypto.acme_certificate_order_validate и community.crypto.acme_certificate_order_finalize. Заказ можно фактически деактивировать с помощью модуля community.crypto.acme_certificate_deactivate_authz. Обратите внимание, что обоим модулям требуется вывод
order_uriэтого модуля. - Для создания или изменения учётных записей ACME используйте модуль community.crypto.acme_account. Этот модуль не создаёт и не обновляет учётные записи ACME.
- Между вызовом этого модуля и вызовом community.crypto.acme_certificate_order_finalize необходимо любыми необходимыми средствами выполнить требуемые действия для выбранной задачи. Для
http-01это означает создание необходимого файла задачи на целевом веб-сервере. Дляdns-01,dns-account-01иdns-persist-01необходимо создать соответствующие записи DNS. Дляtls-alpn-01необходимо создать и предоставить соответствующий сертификат. Выполнение этих действий не входит в обязанности этого модуля. - Чтобы узнать, как выполнять эти задачи, возможно, потребуется ознакомиться с основной спецификацией ACME и спецификацией TLS-ALPN-01. Также ознакомьтесь с примерами для этого модуля.
- Модуль поддерживает IP-идентификаторы согласно расширению ACME RFC 8738.
- Модуль экспериментально поддерживает тип задачи
dns-account-01согласно черновику 02 acme-dns-account-label. Обратите внимание: поддерживаемая версия черновика может измениться в любой момент; изменения будут считаться нарушающими совместимость только после того, как черновик получит статус RFC. - Модуль экспериментально поддерживает тип задачи
dns-persist-01согласно черновику 01 acme-dns-persist. Обратите внимание: поддерживаемая версия черновика может измениться в любой момент; изменения будут считаться нарушающими совместимость только после того, как черновик получит статус RFC.
Требования
На хосте, выполняющем этот модуль, должны быть установлены следующие компоненты.
- либо
openssl - либо cryptography >= 3.3
Параметры
Параметр | Комментарии |
|---|---|
account_key_content строка | Содержимое ключа учётной записи ACME RSA или ключа на эллиптических кривых. Для ключей на эллиптических кривых поддерживаются только следующие кривые: Несовместим с Обязателен, если не используется Предупреждение: содержимое будет записано во временный файл, который Ansible удалит после завершения модуля. Поскольку это важный закрытый ключ — его можно использовать для смены ключа учётной записи или отзыва ваших сертификатов без знания их закрытых ключей, — такой способ может быть неприемлем. Если используется |
account_key_passphrase строка добавлено в community.crypto 1.6.0 | Парольная фраза для расшифровки ключа учётной записи. Примечание: эта возможность не поддерживается механизмом |
account_key_src псевдонимы: account_key путь | Путь к файлу, содержащему ключ учётной записи ACME RSA или ключ на эллиптических кривых. Для ключей на эллиптических кривых поддерживаются только следующие кривые: Закрытые ключи можно создать с помощью модулей community.crypto.openssl_privatekey или community.crypto.openssl_privatekey_pipe. Если необходимый компонент (cryptography) недоступен, ключи также можно создать непосредственно с помощью инструмента командной строки Несовместим с Обязателен, если не используется |
account_uri строка | Если указано, предполагается, что URI учётной записи соответствует заданному значению. Если ключ учётной записи не соответствует этой учётной записи или учётная запись с таким URI не существует, модуль завершится с ошибкой. |
acme_directory строка / обязательный | Используемый каталог ACME. Это URL-адрес точки входа для доступа к API сервера центра сертификации ACME. В целях безопасности по умолчанию используется промежуточный сервер Let’s Encrypt (для протокола ACME v1). Он выдаёт технически корректные, но недоверенные сертификаты. Все промежуточные конечные точки Let’s Encrypt перечислены здесь: https://letsencrypt.org/docs/staging-environment/. Для Let’s Encrypt URL производственного каталога ACME v2: https://acme-v02.api.letsencrypt.org/directory. Для ZeroSSL URL производственного каталога ACME v2: https://acme.zerossl.com/v2/DV90. Для Sectigo URL производственного каталога ACME v2: https://acme-qa.secure.trust-provider.com/v2/DV. Для HARICA URL производственного каталога ACME v2: https://acme.harica.gr/XXX/directory, где XXX — значение, уникальное для вашей учётной записи. В примечаниях к этому модулю приведён список служб ACME, с которыми он проходил тестирование. |
acme_version целое число | Версия ACME конечной точки. Для стандартизированных конечных точек ACME v2 должно быть указано Значение Варианты:
|
csr путь | Файл с запросом на подпись сертификата (CSR) для нового сертификата. Его можно создать с помощью community.crypto.openssl_csr. CSR может содержать несколько альтернативных имён субъектов (Subject Alternate Names), но каждое из них создаёт отдельную задачу, которую необходимо выполнить, чтобы подписать CSR. Примечание: закрытый ключ, использованный для создания CSR, не должен быть ключом учётной записи. С точки зрения безопасности это плохая идея, и центр сертификации не должен принимать такой CSR. В этом случае сервер ACME должен вернуть ошибку. Необходимо указать ровно один из параметров: |
csr_content строка | Содержимое запроса на подпись сертификата (CSR) для нового сертификата. Его можно создать с помощью community.crypto.openssl_csr_pipe. CSR может содержать несколько альтернативных имён субъектов (Subject Alternate Names), но каждое из них создаёт отдельную задачу, которую необходимо выполнить, чтобы подписать CSR. Примечание: закрытый ключ, использованный для создания CSR, не должен быть ключом учётной записи. С точки зрения безопасности это плохая идея, и центр сертификации не должен принимать такой CSR. В этом случае сервер ACME должен вернуть ошибку. Необходимо указать ровно один из параметров: |
deactivate_authzs логическое значение | Деактивировать объекты аутентификации (authz), если при выдаче сертификата произошла ошибка. Объекты аутентификации привязаны к ключу учётной записи, остаются действительными в течение определённого времени и могут использоваться для выдачи сертификатов без повторной аутентификации домена. Это может представлять угрозу безопасности. Варианты:
|
order_creation_error_strategy строка | Выбирает стратегию обработки ошибок протокола ACME в случае сбоя при создании нового заказа ACME. Варианты:
|
order_creation_max_retries целое число | В зависимости от стратегии, выбранной в По умолчанию: |
profile строка | Выберите определённый профиль для выбора сертификата. Доступные профили зависят от центра сертификации. Дополнительные сведения см. в публикации в блоге Let’s Encrypt и черновике draft-aaron-acme-profiles-01. |
replaces_cert_id строка | Если указано, модуль запросит создание заказа на замену сертификата с этим идентификатором согласно разделу 5 RFC 9773. Идентификатор сертификата необходимо вычислить согласно разделу 4.1 RFC 9773. Он возвращается в качестве возвращаемого значения Серверы ACME могут отказаться создавать новые заказы на замену сертификата, для которого уже существует активный заказ на замену. Это может произойти, если с помощью этого модуля создаётся заказ, а затем выполнение плейбука или роли завершается с ошибкой, поскольку не удалось настроить задачи. Если плейбук или роль не сохраняет данные заказа для продолжения работы с существующим заказом, а при следующем запуске пытается создать новый, создание нового заказа может завершиться ошибкой. Если используется Если задан параметр |
request_timeout целое число добавлено в community.crypto 2.3.0 | Время ожидания ответа от API ACME для Ansible. Это ограничение времени применяется ко всем HTTP(S)-запросам (HEAD, GET, POST). По умолчанию: |
select_crypto_backend строка | Определяет, какой криптографический механизм использовать. По умолчанию выбирается Если задано значение Если задано значение Варианты:
|
validate_certs логическое значение | Проверять ли TLS-сертификаты при обращении к каталогу ACME. Предупреждение: значение Варианты:
|
Атрибуты
Атрибут | Поддержка | Описание |
|---|---|---|
action_group | Группы действий: community.crypto.acme, acme | Используйте |
check_mode | Поддержка: отсутствует | Модуль может работать в режиме |
diff_mode | Поддержка: отсутствует | В режиме различий модуль возвращает подробные сведения о внесённых изменениях (или о том, какие изменения могут потребоваться в |
idempotent | Поддержка: отсутствует | При двух последовательных запусках вне режима проверки с одинаковыми аргументами второй вызов сообщает об отсутствии изменений. Предполагается, что система, состояние которой контролирует или запрашивает модуль, не изменилась существенным образом. |
Примечания
Примечание
- Хотя значения по умолчанию подобраны так, чтобы модуль можно было использовать с центром сертификации Let’s Encrypt, в принципе он подходит для любого центра сертификации, предоставляющего конечную точку ACME.
- На данный момент разработчики тестировали модули ACME только с Let’s Encrypt (промежуточная и рабочая среды), ZeroSSL (рабочая среда) и тестовым сервером Pebble. Сообщество сообщало, что модули также работают с Sectigo ACME Service for InCommon и HARICA. Если у вас возникли проблемы с другим сервером ACME, создайте задачу, чтобы помочь нам обеспечить его поддержку. Мы также будем рады узнать, что сервер ACME, не упомянутый здесь, работает.
- Если доступна достаточно новая версия библиотеки
cryptography(подробности см. в разделе «Требования»), вместо двоичного файлаopensslбудет использоваться она. Это поведение можно явно отключить или включить с помощью параметраselect_crypto_backend. Обратите внимание: использование двоичного файлаopensslбудет медленнее и менее безопасно, поскольку закрытые ключи всегда необходимо хранить на диске (см.account_key_content).
См. также
См. также
- community.crypto.acme_certificate_order_validate
-
Проверяет ожидающие подтверждения авторизации заказа ACME.
- community.crypto.acme_certificate_order_finalize
-
Завершает заказ ACME после выполнения проверок.
- community.crypto.acme_certificate_order_info
-
Получает сведения о заказе ACME.
- community.crypto.acme_certificate_deactivate_authz
-
Деактивирует все авторизации (authz) заказа ACME, фактически деактивируя сам заказ.
- community.crypto.acme_certificate_renewal_info
-
Определяет, следует ли обновить сертификат.
- Документация Let’s Encrypt
-
Документация центра сертификации Let’s Encrypt. Содержит полезную информацию, например о лимитах запросов.
- Среда автоматического управления сертификатами (ACME)
-
Спецификация протокола ACME (RFC 8555).
- Расширение ACME TLS ALPN Challenge
-
Спецификация проверки
tls-alpn-01(RFC 8737). - community.crypto.acme_challenge_cert_helper
-
Помогает подготовить проверки
tls-alpn-01. - community.crypto.openssl_privatekey
-
Можно использовать для создания закрытых ключей (как для сертификатов, так и для учетных записей).
- community.crypto.openssl_privatekey_pipe
-
Можно использовать для создания закрытых ключей без записи на диск (как для сертификатов, так и для учетных записей).
- community.crypto.openssl_csr
-
Можно использовать для создания запроса на подпись сертификата (CSR).
- community.crypto.openssl_csr_pipe
-
Можно использовать для создания запроса на подпись сертификата (CSR) без записи на диск.
- community.crypto.acme_account
-
Позволяет создать, изменить или удалить учетную запись ACME.
- community.crypto.acme_inspect
-
Позволяет отлаживать проблемы.
Примеры
---
### Example with HTTP-01 challenge ###
- name: Create a challenge for sample.com using a account key from a variable
community.crypto.acme_certificate_order_create:
account_key_content: "{{ account_private_key }}"
csr: /etc/pki/cert/csr/sample.com.csr
register: sample_com_challenge
# Alternative first step:
- name: Create a challenge for sample.com using a account key from Hashi Vault
community.crypto.acme_certificate_order_create:
account_key_content: >-
{{ lookup('community.hashi_vault.hashi_vault', 'secret=secret/account_private_key:value') }}
csr: /etc/pki/cert/csr/sample.com.csr
register: sample_com_challenge
# Alternative first step:
- name: Create a challenge for sample.com using a account key file
community.crypto.acme_certificate_order_create:
account_key_src: /etc/pki/cert/private/account.key
csr_content: "{{ lookup('file', '/etc/pki/cert/csr/sample.com.csr') }}"
register: sample_com_challenge
# Perform the necessary steps to fulfill the challenge. For example:
#
# - name: Copy http-01 challenges
# ansible.builtin.copy:
# dest: /var/www/{{ item.identifier }}/{{ item.challenges['http-01'].resource }}
# content: "{{ item.challenges['http-01'].resource_value }}"
# loop: "{{ sample_com_challenge.challenge_data }}"
# when: "'http-01' in item.challenges"
- name: Let the challenge be validated
community.crypto.acme_certificate_order_validate:
account_key_src: /etc/pki/cert/private/account.key
order_uri: "{{ sample_com_challenge.order_uri }}"
challenge: http-01
- name: Retrieve the cert and intermediate certificate
community.crypto.acme_certificate_order_finalize:
account_key_src: /etc/pki/cert/private/account.key
csr: /etc/pki/cert/csr/sample.com.csr
order_uri: "{{ sample_com_challenge.order_uri }}"
cert_dest: /etc/httpd/ssl/sample.com.crt
fullchain_dest: /etc/httpd/ssl/sample.com-fullchain.crt
chain_dest: /etc/httpd/ssl/sample.com-intermediate.crt
---
### Example with DNS challenge against production ACME server ###
- name: Create a challenge for sample.com using a account key file.
community.crypto.acme_certificate_order_create:
acme_directory: https://acme-v01.api.letsencrypt.org/directory
account_key_src: /etc/pki/cert/private/account.key
csr: /etc/pki/cert/csr/sample.com.csr
register: sample_com_challenge
# Perform the necessary steps to fulfill the challenge. For example:
#
# - name: Create DNS records for dns-01 challenges
# community.aws.route53:
# zone: sample.com
# record: "{{ item.key }}"
# type: TXT
# ttl: 60
# state: present
# wait: true
# # Note: item.value is a list of TXT entries, and route53
# # requires every entry to be enclosed in quotes
# value: "{{ item.value | map('community.dns.quote_txt', always_quote=true) | list }}"
# loop: "{{ sample_com_challenge.challenge_data_dns | dict2items }}"
- name: Let the challenge be validated
community.crypto.acme_certificate_order_validate:
acme_directory: https://acme-v01.api.letsencrypt.org/directory
account_key_src: /etc/pki/cert/private/account.key
order_uri: "{{ sample_com_challenge.order_uri }}"
challenge: dns-01
- name: Retrieve the cert and intermediate certificate
community.crypto.acme_certificate_order_finalize:
acme_directory: https://acme-v01.api.letsencrypt.org/directory
account_key_src: /etc/pki/cert/private/account.key
csr: /etc/pki/cert/csr/sample.com.csr
order_uri: "{{ sample_com_challenge.order_uri }}"
cert_dest: /etc/httpd/ssl/sample.com.crt
fullchain_dest: /etc/httpd/ssl/sample.com-fullchain.crt
chain_dest: /etc/httpd/ssl/sample.com-intermediate.crt
Возвращаемые значения
Общие возвращаемые значения описаны здесь; ниже приведены поля, уникальные для этого модуля:
Ключ | Описание |
|---|---|
account_uri строка | URI учетной записи ACME. Возвращается: при успехе |
challenge_data список / элементы=словарь | Предоставляет информацию о проверке для каждого идентификатора. Возвращаются только проверки, которые еще не завершены. Возвращается: при изменении |
|
challenges словарь |
Информация о различных типах проверок, поддерживаемых для этого идентификатора. Обратите внимание, что ключи не являются допустимыми идентификаторами Jinja2. Возвращается: при успехе |
|
dns-01 словарь |
Информация об авторизации Необходимо создать запись DNS TXT с именем Возвращается: если идентификатор поддерживает авторизацию |
|
record строка |
Полное имя записи DNS для проверки. Возвращается: при успехе Пример: |
|
resource строка |
Всегда содержит строку Возвращается: при успехе Пример: |
|
resource_value строка |
Значение, которое ресурс должен предоставить для проверки. Возвращается: при успехе Пример: |
|
dns-account-01 словарь добавлено в community.crypto 3.2.0 |
Информация об авторизации Необходимо создать запись DNS TXT с именем Примечание: это возвращаемое значение является экспериментальным и может быть несовместимо изменено даже в минорных выпусках, пока черновик acme-dns-account-label не станет более стабильным. Возвращается: если идентификатор поддерживает авторизацию |
|
record строка |
Полное имя записи DNS для проверки. Возвращается: при успехе Пример: |
|
resource строка |
Всегда заканчивается строкой Возвращается: при успехе Пример: |
|
resource_value строка |
Значение, которое ресурс должен предоставить для проверки. Возвращается: при успехе Пример: |
|
dns-persist-01 словарь добавлено в community.crypto 3.2.0 |
Информация об авторизации Необходимо создать запись DNS TXT с именем Примечание: это возвращаемое значение является экспериментальным и может быть несовместимо изменено даже в минорных выпусках, пока черновик acme-dns-persist не станет более стабильным. Возвращается: если идентификатор поддерживает авторизацию |
|
account_uri строка |
URI учетной записи, который необходимо указать в записи DNS TXT. Примечание: тип этого возвращаемого значения может быть несовместимо изменен даже в минорных выпусках, пока черновик acme-dns-persist не станет более стабильным. Это поле проверки в настоящее время обсуждается в рабочей группе ACME. Возвращается: при успехе Пример: |
|
issuer_domain_names список / элементы=строка |
Одно из доменных имен издателя необходимо указать в записи DNS TXT. Возвращается: при успехе Пример: |
|
http-01 словарь |
Информация об авторизации Сервер должен предоставить доступ к пути Возвращается: если идентификатор поддерживает авторизацию |
|
resource строка |
Путь, по которому необходимо предоставить значение. Возвращается: при успехе Пример: |
|
resource_value строка |
Значение, которое ресурс должен предоставить для проверки. Возвращается: при успехе Пример: |
|
tls-alpn-01 словарь |
Информация об авторизации Для имени DNS Подробности см. в разделе https://www.rfc-editor.org/rfc/rfc8737.html#section-3. Возвращается: если идентификатор поддерживает авторизацию |
|
resource строка |
Имя DNS для DNS-идентификаторов и обратное отображение DNS (RFC1034, RFC3596) для IP-адресов. Возвращается: при успехе Пример: |
|
resource_original строка |
Исходный идентификатор, включая идентификатор типа. Возвращается: при успехе Пример: |
|
resource_value строка |
Значение, которое ресурс должен предоставить для проверки. Примечание: это возвращаемое значение содержит версию правильного двоичного блока, закодированную в Base64; ее необходимо поместить в расширение X.509 acmeValidation. Подробности см. в разделе https://www.rfc-editor.org/rfc/rfc8737.html#section-3. Для извлечения двоичного блока из этого возвращаемого значения может потребоваться фильтр Jinja ansible.builtin.b64decode. Возвращается: при успехе Пример: |
|
identifier строка |
Идентификатор этой проверки. Возвращается: при успехе Пример: |
|
identifier_type строка |
Тип идентификатора.
Возвращается: при успехе Возможные значения:
Пример: |
challenge_data_dns словарь | Список значений TXT для каждой записи DNS для проверок Возвращаются только проверки, которые еще не завершены. Возвращается: при успехе |
challenge_data_dns_account словарь добавлено в community.crypto 3.2.0 | Список значений TXT для каждой записи DNS для проверок Возвращаются только проверки, которые еще не завершены. Возвращается: при успехе |
order_uri строка | URI заказа ACME. Возвращается: при успехе |
Ссылки на коллекцию
© 2012–2018 Michael DeHaan
© 2018–2025 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/projects/ansible/latest/collections/community/crypto/acme_certificate_order_create_module.html