Модуль community.crypto.acme_inspect — отправка прямых запросов серверу ACME

Примечание

Этот модуль входит в коллекцию community.crypto (версия 3.2.1).

Возможно, эта коллекция уже установлена, если вы используете пакет ansible. Она не входит в ansible-core. Чтобы проверить, установлена ли она, выполните ansible-galaxy collection list.

Чтобы установить её, используйте: ansible-galaxy collection install community.crypto. Для использования этого модуля требуются дополнительные зависимости; подробности см. в разделе Требования.

Чтобы использовать модуль в плейбуке, укажите: community.crypto.acme_inspect.

Краткое описание
Требования
Параметры
Атрибуты
Примечания
См. также
Примеры
Возвращаемые значения

Краткое описание

Позволяет отправлять прямые запросы серверу ACME с помощью протокола ACME, который поддерживается такими центрами сертификации, как Let’s Encrypt.
Этот модуль можно использовать для отладки неудачных попыток запросить сертификат, например, когда community.crypto.acme_certificate завершается с ошибкой или сталкивается с проблемой, которую необходимо исследовать.
Модуль также можно использовать для прямого доступа к функциям серверов ACME, которые пока не поддерживаются модулями ACME в Ansible.

Требования

На узле, выполняющем этот модуль, должны быть установлены перечисленные ниже компоненты.

либо openssl
либо cryptography >= 3.3

Параметры

Параметр	Комментарии
account_key_content строка	Содержимое ключа учётной записи ACME RSA или ключа на эллиптической кривой. Для ключей на эллиптических кривых поддерживаются только следующие кривые: `secp256r1`, `secp384r1` и `secp521r1`. Несовместим с `account_key_src`. Обязателен, если не используется `account_key_src`. Предупреждение: содержимое будет записано во временный файл, который Ansible удалит после завершения работы модуля. Это может быть неприемлемо, поскольку данный закрытый ключ очень важен: его можно использовать для смены ключа учётной записи или отзыва сертификатов без знания их закрытых ключей. Если используется `cryptography`, содержимое не записывается во временный файл. Однако Ansible всё ещё может записать его на диск в процессе передачи модуля с его аргументом на узел, где он выполняется.
account_key_passphrase строка добавлено в community.crypto 1.6.0	Парольная фраза для расшифровки ключа учётной записи. Примечание: эта возможность не поддерживается бэкендом `openssl`, она доступна только в бэкенде `cryptography`.
account_key_src псевдонимы: account_key путь	Путь к файлу, содержащему ключ учётной записи ACME RSA или ключ на эллиптической кривой. Для ключей на эллиптических кривых поддерживаются только следующие кривые: `secp256r1`, `secp384r1` и `secp521r1`. Закрытые ключи можно создать с помощью модулей community.crypto.openssl_privatekey или community.crypto.openssl_privatekey_pipe. Если необходимая зависимость (cryptography) недоступна, ключи можно также создать непосредственно с помощью инструмента командной строки `openssl`: ключи RSA можно создать командой `openssl genrsa ...`. Ключи на эллиптических кривых можно создать командой `openssl ecparam -genkey ...`. Также можно использовать любые другие инструменты для создания закрытых ключей в формате PEM. Несовместим с `account_key_content`. Обязателен, если не используется `account_key_content`.
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 должно быть задано значение `2`. Значение `1` больше не поддерживается начиная с community.crypto 3.0.0. Варианты: `2` ← (по умолчанию)
content строка	Закодированный объект JSON, который будет отправлен в качестве содержимого, если `method` имеет значение `post`. Обязателен, если `method` имеет значение `post`, и не допускается в остальных случаях.
fail_on_acme_error логическое значение	Если `method` имеет значение `post` или `get`, завершать работу модуля с ошибкой, если возвращена ошибка ACME. Варианты: `false` `true` ← (по умолчанию)
method строка	Метод доступа к указанному URL на сервере ACME. Значение `post` выполняет аутентифицированный запрос POST. Содержимое необходимо указать в параметре `content`. Значение `get` выполняет аутентифицированный запрос POST-as-GET для ACME v2 и обычный запрос GET для ACME v1. Значение `directory-only` только получает каталог, не отправляя запрос. Варианты: `"get"` ← (по умолчанию) `"post"` `"directory-only"`
request_timeout целое число добавлено в community.crypto 2.3.0	Время ожидания ответа от API ACME для Ansible. Этот тайм-аут применяется ко всем запросам HTTP(S) (HEAD, GET, POST). По умолчанию: `10`
select_crypto_backend строка	Определяет, какой криптографический бэкенд использовать. По умолчанию выбирается `auto`: сначала выполняется попытка использовать `cryptography`, если он доступен, а в противном случае — `openssl`. Если задано значение `openssl`, будет предпринята попытка использовать двоичный файл `openssl`. Если задано значение `cryptography`, будет предпринята попытка использовать библиотеку cryptography. Варианты: `"auto"` ← (по умолчанию) `"cryptography"` `"openssl"`
url строка	URL, на который нужно отправить запрос. Необходимо указать, если `method` не имеет значения `directory-only`.
validate_certs логическое значение	Проверять ли сертификаты TLS при обращении к каталогу ACME. Предупреждение: значение `false` следует задавать только для тестирования, например при проверке с локальным сервером Pebble. Варианты: `false` `true` ← (по умолчанию)

Атрибуты

Атрибут	Поддержка	Описание
action_group	Группы действий: community.crypto.acme, acme	Используйте `group/acme` или `group/community.crypto.acme` в `module_defaults`, чтобы задать значения по умолчанию для этого модуля.
check_mode	Поддержка: нет	Может выполняться в режиме `check_mode` и возвращать прогноз изменения состояния без изменения целевого объекта.
diff_mode	Поддержка: нет	В режиме сравнения будет возвращена информация об изменениях (или о том, что, возможно, нужно изменить в `check_mode`).
idempotent	Поддержка: нет	При повторном запуске с теми же аргументами вне режима проверки модуль сообщает об отсутствии изменений. Предполагается, что система, которой управляет модуль или к которой он обращается, не изменилась существенным образом.

Примечания

Примечание

Для корректно аутентифицированных запросов ACME v2 необходимо указывать параметр account_uri (кроме запроса new-account).
С помощью инструмента ansible модуль community.crypto.acme_inspect можно использовать для непосредственного выполнения запросов ACME без необходимости писать плейбук. Например, следующая команда получает учётную запись ACME с ID 1 в Let’s Encrypt (при условии, что /path/to/key — это правильный закрытый ключ учётной записи): ansible localhost -m acme_inspect -a "account_key_src=/path/to/key acme_directory=https://acme-v02.api.letsencrypt.org/directory account_uri=https://acme-v02.api.letsencrypt.org/acme/acct/1 method=get url=https://acme-v02.api.letsencrypt.org/acme/acct/1".
Хотя значения по умолчанию выбраны так, чтобы модуль можно было использовать с центром сертификации Let’s Encrypt, в принципе он подходит для любого центра сертификации, предоставляющего конечную точку ACME.
На данный момент разработчики тестировали модули ACME только с Let’s Encrypt (тестовая и рабочая среды), ZeroSSL (рабочая среда) и тестовым сервером Pebble. Сообщество сообщало, что модули также работают с Sectigo ACME Service for InCommon и HARICA. Если у вас возникли проблемы с другим сервером ACME, создайте issue, чтобы помочь нам обеспечить его поддержку. Мы также будем благодарны за отзывы о том, что не упомянутый здесь сервер ACME работает.
Если доступна достаточно новая версия библиотеки cryptography (подробности см. в разделе «Требования»), она будет использоваться вместо двоичного файла openssl. Это можно явно отключить или включить с помощью параметра select_crypto_backend. Обратите внимание: использование двоичного файла openssl будет медленнее и менее безопасно, поскольку содержимое закрытого ключа всегда приходится хранить на диске (см. account_key_content).

См. также

Среда автоматического управления сертификатами (ACME): Спецификация протокола ACME (RFC 8555).
Расширение ACME TLS ALPN Challenge: Спецификация проверки tls-alpn-01 (RFC 8737).

Примеры

---
- name: Get directory
  community.crypto.acme_inspect:
    acme_directory: https://acme-staging-v02.api.letsencrypt.org/directory
    method: directory-only
  register: directory

- name: Create an account
  community.crypto.acme_inspect:
    acme_directory: https://acme-staging-v02.api.letsencrypt.org/directory
    account_key_src: /etc/pki/cert/private/account.key
    url: "{{ directory.newAccount}}"
    method: post
    content: '{"termsOfServiceAgreed":true}'
  register: account_creation
  # account_creation.headers.location contains the account URI
  # if creation was successful

- name: Get account information
  community.crypto.acme_inspect:
    acme_directory: https://acme-staging-v02.api.letsencrypt.org/directory
    account_key_src: /etc/pki/cert/private/account.key
    account_uri: "{{ account_creation.headers.location }}"
    url: "{{ account_creation.headers.location }}"
    method: get

- name: Update account contacts
  community.crypto.acme_inspect:
    acme_directory: https://acme-staging-v02.api.letsencrypt.org/directory
    account_key_src: /etc/pki/cert/private/account.key
    account_uri: "{{ account_creation.headers.location }}"
    url: "{{ account_creation.headers.location }}"
    method: post
    content: '{{ account_info | to_json }}'
  vars:
    account_info:
      # For valid values, see
      # https://tools.ietf.org/html/rfc8555#section-7.3
      contact:
        - mailto:me@example.com

- name: Create certificate order
  community.crypto.acme_certificate:
    acme_directory: https://acme-staging-v02.api.letsencrypt.org/directory
    account_key_src: /etc/pki/cert/private/account.key
    account_uri: "{{ account_creation.headers.location }}"
    csr: /etc/pki/cert/csr/sample.com.csr
    fullchain_dest: /etc/httpd/ssl/sample.com-fullchain.crt
    challenge: http-01
    modify_account: false
  register: certificate_request

# Assume something went wrong. certificate_request.order_uri contains
# the order URI.

- name: Get order information
  community.crypto.acme_inspect:
    acme_directory: https://acme-staging-v02.api.letsencrypt.org/directory
    account_key_src: /etc/pki/cert/private/account.key
    account_uri: "{{ account_creation.headers.location }}"
    url: "{{ certificate_request.order_uri }}"
    method: get
  register: order

- name: Get first authz for order
  community.crypto.acme_inspect:
    acme_directory: https://acme-staging-v02.api.letsencrypt.org/directory
    account_key_src: /etc/pki/cert/private/account.key
    account_uri: "{{ account_creation.headers.location }}"
    url: "{{ order.output_json.authorizations[0] }}"
    method: get
  register: authz

- name: Get HTTP-01 challenge for authz
  community.crypto.acme_inspect:
    acme_directory: https://acme-staging-v02.api.letsencrypt.org/directory
    account_key_src: /etc/pki/cert/private/account.key
    account_uri: "{{ account_creation.headers.location }}"
    url: "{{ authz.output_json.challenges | selectattr('type', 'equalto', 'http-01') }}"
    method: get
  register: http01challenge

- name: Activate HTTP-01 challenge manually
  community.crypto.acme_inspect:
    acme_directory: https://acme-staging-v02.api.letsencrypt.org/directory
    account_key_src: /etc/pki/cert/private/account.key
    account_uri: "{{ account_creation.headers.location }}"
    url: "{{ http01challenge.url }}"
    method: post
    content: '{}'

Возвращаемые значения

Общие возвращаемые значения описаны здесь; ниже перечислены поля, уникальные для этого модуля:

Ключ	Описание
directory словарь	Содержимое каталога ACME. Возвращается: всегда Пример: {"a85k3x9f91A4": "https://community.letsencrypt.org/t/adding-random-entries-to-the-directory/33417", "keyChange": "https://acme-v02.api.letsencrypt.org/acme/key-change", "meta": {"caaIdentities": ["letsencrypt.org"], "termsOfService": "https://letsencrypt.org/documents/LE-SA-v1.2-November-15-2017.pdf", "website": "https://letsencrypt.org"}, "newAccount": "https://acme-v02.api.letsencrypt.org/acme/new-acct", "newNonce": "https://acme-v02.api.letsencrypt.org/acme/new-nonce", "newOrder": "https://acme-v02.api.letsencrypt.org/acme/new-order", "revokeCert": "https://acme-v02.api.letsencrypt.org/acme/revoke-cert"}
headers словарь	HTTP-заголовки запроса (ключи в нижнем регистре). Возвращается: всегда Пример: {"boulder-requester": "12345", "cache-control": "max-age=0, no-cache, no-store", "connection": "close", "content-length": "904", "content-type": "application/json", "cookies": {}, "cookies_string": "", "date": "Wed, 07 Nov 2018 12:34:56 GMT", "expires": "Wed, 07 Nov 2018 12:44:56 GMT", "link": "<https://letsencrypt.org/documents/LE-SA-v1.2-November-15-2017.pdf>;rel=\"terms-of-service\"", "msg": "OK (904 bytes)", "pragma": "no-cache", "replay-nonce": "1234567890abcdefghijklmnopqrstuvwxyzABCDEFGH", "server": "nginx", "status": 200, "strict-transport-security": "max-age=604800", "url": "https://acme-v02.api.letsencrypt.org/acme/acct/46161", "x-frame-options": "DENY"}
output_json словарь	Вывод, разобранный как JSON. Возвращается: если вывод можно разобрать как JSON Пример: `[{"id": 12345}, {"key": [{"kty": "RSA"}, "..."]}]`
output_text строка	Исходный текстовый вывод. Возвращается: всегда Пример: `"{\\n \\\"id\\\": 12345,\\n \\\"key\\\": {\\n \\\"kty\\\": \\\"RSA\\\",\\n ..."`

Авторы

Felix Fontein (@felixfontein)

Ссылки на коллекцию

© 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_inspect_module.html