Spec-Zone.ru › Ansible

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

Примечание

Этот модуль входит в коллекцию community.crypto (версия 2.22.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, которые пока не поддерживаются модулями Ansible ACME.

Требования

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

  • либо openssl, либо cryptography >= 1.5
  • ipaddress

Параметры

Параметр

Комментарии

account_key_content

string

Содержимое ключа ACME RSA или ключа эллиптической кривой.

Взаимоисключающий с account_key_src.

Обязателен, если account_key_src не используется.

Предупреждение: содержимое будет записано во временный файл, который будет удален Ansible по завершении работы модуля. Поскольку это важный закрытый ключ — его можно использовать для изменения ключа учетной записи или для отзыва ваших сертификатов без знания их закрытых ключей —, это может быть неприемлемо.

В случае использования cryptography, содержимое не записывается во временный файл. Тем не менее, Ansible все еще может записать его на диск в процессе перемещения модуля с его аргументом на узел, где он выполняется.

account_key_passphrase

string

добавлено в community.crypto 1.6.0

Пароль для декодирования ключа учетной записи.

Примечание: это не поддерживается бэкендом openssl, только бэкендом cryptography.

account_key_src

aliases: account_key

path

Путь к файлу, содержащему ключ учетной записи ACME RSA или ключ эллиптической кривой.

Закрытые ключи можно создавать с помощью модулей 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

string

Если указано, предполагается, что URI учетной записи задан. Если ключ учетной записи не соответствует этой учетной записи или учетная запись с этим URI не существует, модуль завершается с ошибкой.

acme_directory

string / required

Каталог ACME для использования. Это URL-адрес точки входа для доступа к API-сервера центра сертификации ACME.

В целях безопасности значение по умолчанию установлено на тестовый сервер Let’s Encrypt (для протокола ACME v1). Это создаст технически корректные, но недоверенные сертификаты.

Для Let’s Encrypt все тестовые конечные точки можно найти здесь: https://letsencrypt.org/docs/staging-environment/. Для Buypass все конечные точки можно найти здесь: https://community.buypass.com/t/63d4ay/buypass-go-ssl-endpoints

Для Let’s Encrypt, URL-адрес производственного каталога для ACME v2 — https://acme-v02.api.letsencrypt.org/directory.

Для Buypass, URL-адрес производственного каталога для ACME v2 и v1 — https://api.buypass.com/acme/directory.

Для ZeroSSL, URL-адрес производственного каталога для ACME v2 — https://acme.zerossl.com/v2/DV90.

Для Sectigo, URL-адрес производственного каталога для ACME v2 — https://acme-qa.secure.trust-provider.com/v2/DV.

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

acme_version

integer / required

Версия ACME конечной точки.

Должно быть 1 для классических конечных точек Let’s Encrypt и Buypass ACME или 2 для стандартизированных конечных точек ACME v2.

Значение 1 устарело начиная с community.crypto 2.0.0 и будет удалено из community.crypto 3.0.0.

Варианты:

  • 1
  • 2

content

string

Закодированный объект JSON, который будет отправлен в качестве содержимого, если method равно post.

Обязательно, когда method равно post, и недопустимо в противном случае.

fail_on_acme_error

boolean

Если method равно post или get, заставить модуль завершиться с ошибкой в случае возврата ошибки ACME.

Варианты:

  • false
  • true ← (по умолчанию)

method

string

Метод доступа к заданному URL-адресу на сервере ACME.

Значение post выполняет аутентифицированный запрос POST. Содержимое должно быть указано в параметре content.

Значение get выполняет аутентифицированный запрос POST-as-GET для ACME v2 и обычный запрос GET для ACME v1.

Значение directory-only только извлекает каталог, не выполняя запрос.

Варианты:

  • "get" ← (по умолчанию)
  • "post"
  • "directory-only"

request_timeout

integer

добавлено в community.crypto 2.3.0

Время ожидания Ansible ответа от API ACME.

Это время ожидания применяется ко всем запросам HTTP(S) (HEAD, GET, POST).

По умолчанию: 10

select_crypto_backend

string

Определяет, какой криптографический бэкенд использовать.

Выбор по умолчанию — auto, который пытается использовать cryptography, если доступен, и возвращается к openssl.

Если установлено в openssl, будет пытаться использовать бинарный файл openssl.

Если установлено в cryptography, будет пытаться использовать библиотеку cryptography.

Варианты:

  • "auto" ← (по умолчанию)
  • "cryptography"
  • "openssl"

url

string

URL-адрес для отправки запроса.

Должен быть указан, если method не directory-only.

validate_certs

boolean

Включает проверку 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), при использовании режима сравнения.

Примечания

Примечание

  • Параметр account_uri должен быть указан для правильной аутентификации запросов ACME v2 (кроме запроса new-account).
  • С помощью инструмента ansible, модуль community.crypto.acme_inspect может быть использован для непосредственного выполнения запросов ACME без необходимости написания плейбука. Например, следующая команда извлекает учётную запись ACME с идентификатором 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 acme_version=2 account_uri=https://acme-v02.api.letsencrypt.org/acme/acct/1 method=get url=https://acme-v02.api.letsencrypt.org/acme/acct/1"
  • Хотя значения по умолчанию выбраны таким образом, чтобы модуль мог использоваться с CA Let’s Encrypt, модуль в принципе может быть использован с любой CA, предоставляющей конечную точку ACME, например, Buypass Go SSL.
  • На данный момент модули ACME были протестированы разработчиками только с Let’s Encrypt (этап и производство), Buypass (этап и производство), ZeroSSL (производство) и Pebble testing server. Мы получили обратную связь от сообщества, что они также работают с Sectigo ACME Service for InCommon. Если у вас возникнут проблемы с другим сервером ACME, пожалуйста, создайте вопрос, чтобы помочь нам в его поддержке. Обратная связь о том, что не упомянутый сервер 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
    acme_version: 2
    method: directory-only
  register: directory

- name: Create an account
  community.crypto.acme_inspect:
    acme_directory: https://acme-staging-v02.api.letsencrypt.org/directory
    acme_version: 2
    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
    acme_version: 2
    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
    acme_version: 2
    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
    acme_version: 2
    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
  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
    acme_version: 2
    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
    acme_version: 2
    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
    acme_version: 2
    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
    acme_version: 2
    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 ..."

Авторы

  • Фёликс Фонтейн (@felixfontein)

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

  • Система отслеживания ошибок
  • Репозиторий (исходный код)
  • Задайте вопрос (crypto)
  • Задайте вопрос (ACME)
  • Отправить отчет об ошибке
  • Запросить функцию
  • Связь

© 2012–2018 Michael DeHaan
© 2018–2024 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/collections/community/crypto/acme_inspect_module.html

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API