Модуль community.crypto.x509_certificate — создание и/или проверка сертификатов OpenSSL

Примечание

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

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

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

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

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

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

В модуле реализовано понятие провайдера (одного из selfsigned, ownca и acme) для сертификата.
Для взаимодействия с OpenSSL используется библиотека Python cryptography.
Обратите внимание: до версии 2.9 этот модуль назывался openssl_certificate, когда он входил непосредственно в состав Ansible. При переносе в коллекцию community.crypto его переименовали в community.crypto.x509_certificate. Начиная с Ansible 2.10 его по-прежнему можно использовать под старым кратким именем (или через ansible.builtin.openssl_certificate), которое перенаправляет на community.crypto.x509_certificate. При использовании FQCN или ключевого слова collections следует указывать новое имя community.crypto.x509_certificate, чтобы избежать предупреждения об устаревании.
Обратите внимание: модуль заново создаёт существующий сертификат, если он не соответствует параметрам модуля или выглядит повреждённым. Если вы опасаетесь, что это может привести к перезаписи существующего сертификата, рассмотрите возможность использования параметра backup.
Провайдер ownca предназначен для создания сертификата OpenSSL, подписанного вашим собственным сертификатом CA (центра сертификации) (самоподписанного сертификата).
Этот модуль позволяет создавать и повторно создавать сертификаты OpenSSL.

Требования

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

acme-tiny >= 4.0.0 (при использовании провайдера acme)
cryptography >= 3.3 (при использовании провайдера selfsigned или ownca)

Параметры

Параметр	Комментарии
acme_accountkey_path path	Путь к ключу учетной записи для провайдера `acme`. Используется только провайдером `acme`.
acme_chain boolean	Добавлять промежуточный сертификат к созданному сертификату Используется только провайдером `acme`. Обратите внимание: этот параметр доступен только в старых версиях `acme-tiny`. Новые версии автоматически добавляют цепочку, поэтому установка `acme_chain` в `true` приводит к ошибке. Варианты: `false` ← (по умолчанию) `true`
acme_challenge_path path	Путь к каталогу проверки ACME, доступному по адресу http://<HOST>:80/.well-known/acme-challenge/ Используется только провайдером `acme`.
acme_directory string добавлено в community.crypto 1.0.0	Каталог ACME, который следует использовать. Можно использовать любой каталог, поддерживающий протокол ACME, например Let’s Encrypt. Let’s Encrypt рекомендует использовать тестовый сервер при разработке заданий. https://letsencrypt.org/docs/staging-environment/. По умолчанию: `"https://acme-v02.api.letsencrypt.org/directory"`
attributes псевдонимы: attr string	Атрибуты, которыми должен обладать результирующий объект файловой системы. Список поддерживаемых флагов см. на странице руководства для `chattr` в целевой системе. Эта строка должна содержать атрибуты в том же порядке, в котором они отображаются командой `lsattr`. По умолчанию предполагается оператор `=`; в противном случае строка должна содержать операторы `+` или `-`.
backup boolean	Создать резервную копию с временной меткой, чтобы можно было восстановить исходный сертификат, если он случайно был перезаписан новым. Варианты: `false` ← (по умолчанию) `true`
csr_content string добавлено в community.crypto 1.0.0	Содержимое запроса на подписание сертификата (CSR), использованного для создания этого сертификата. Несовместим с `csr_path`.
csr_path path	Путь к запросу на подписание сертификата (CSR), использованному для создания этого сертификата. Несовместим с `csr_content`.
force boolean	Создать сертификат, даже если он уже существует. Варианты: `false` ← (по умолчанию) `true`
group string	Имя группы, которой должен принадлежать объект файловой системы, передаваемое команде `chown`. Если значение не задано, используется текущая группа текущего пользователя. Если пользователь — root, можно сохранить прежнее владение.
ignore_timestamps boolean добавлено в community.crypto 2.0.0	Следует ли игнорировать временные метки «действителен с» и «действителен до» при проверке идемпотентности. При использовании относительных временных меток (например, `+0s` для текущего времени) рекомендуется оставить значение по умолчанию `true`. Варианты: `false` `true` ← (по умолчанию)
mode any	Права доступа, которыми должен обладать результирующий объект файловой системы. Если вы привыкли к `/usr/bin/chmod`, помните, что режимы на самом деле являются восьмеричными числами. Необходимо предоставить Ansible достаточно информации, чтобы он мог правильно их разобрать. Для предсказуемого результата заключайте восьмеричные числа в кавычки (например, `'644'` или `'1777'`), чтобы Ansible получил строку и преобразовал ее в число самостоятельно. Добавление начального нуля (например, `0755`) иногда работает, но может привести к сбоям в циклах и некоторых других ситуациях. Если передать Ansible число, не соблюдая ни одно из этих правил, оно будет воспринято как десятичное, что приведет к неожиданным результатам. Начиная с Ansible 1.8 режим можно задавать в символьном формате (например, `u+rwx` или `u=rw,g=r,o=r`). Если `mode` не задан, а целевой объект файловой системы не существует, при установке режима для создаваемого объекта будет использоваться системное значение `umask` по умолчанию. Если `mode` не задан, а целевой объект файловой системы существует, будет использоваться режим существующего объекта. Задание `mode` — лучший способ гарантировать, что объекты файловой системы будут созданы с правильными правами доступа. Дополнительные сведения см. в CVE-2020-1736.
ownca_content string добавлено в community.crypto 1.0.0	Содержимое сертификата ЦС (центра сертификации). Используется только провайдером `ownca`. Несовместим с `ownca_path`.
ownca_create_authority_key_identifier boolean	Создать идентификатор ключа центра сертификации на основе сертификата ЦС. Если в CSR указан идентификатор ключа центра сертификации, он игнорируется. Идентификатор ключа центра сертификации создается на основе идентификатора ключа субъекта сертификата ЦС, если он доступен. Если он недоступен, используется открытый ключ сертификата ЦС. Используется только провайдером `ownca`. Варианты: `false` `true` ← (по умолчанию)
ownca_create_subject_key_identifier string	Следует ли создавать идентификатор ключа субъекта (SKI) на основе открытого ключа. Значение `create_if_not_provided` (по умолчанию) создает SKI, только если CSR его не содержит. Значение `always_create` всегда создает SKI. Если CSR содержит SKI, он игнорируется. Значение `never_create` никогда не создает SKI. Если CSR содержит SKI, используется он. Используется только провайдером `ownca`. Варианты: `"create_if_not_provided"` ← (по умолчанию) `"always_create"` `"never_create"`
ownca_digest string	Алгоритм хеширования для сертификата `ownca`. Используется только провайдером `ownca`. По умолчанию: `"sha256"`
ownca_not_after string	Момент времени, после которого сертификат перестает быть действительным. Время можно указать как относительное значение или как абсолютную временную метку. Время всегда интерпретируется как UTC. Допустимый формат: `[+-]timespec \| ASN.1 TIME`, где timespec может быть целым числом + `[w \| d \| h \| m \| s]` (например, `+32w1d2h`). Если значение не указано, срок действия сертификата истечет через 10 лет. Обратите внимание: это значение не используется для определения необходимости повторного создания существующего сертификата. Это можно изменить, задав для параметра `ignore_timestamps` значение `false`. Учтите, что при задании `ignore_timestamps=false` следует избегать относительных временных меток. Используется только провайдером `ownca`. Начиная с macOS 10.15, срок действия сертификатов TLS-серверов не должен превышать 825 дней. Дополнительные сведения см. по адресу https://support.apple.com/en-us/HT210176. По умолчанию: `"+3650d"`
ownca_not_before string	Момент времени, с которого сертификат считается действительным. Время можно указать как относительное значение или как абсолютную временную метку. Время всегда интерпретируется как UTC. Допустимый формат: `[+-]timespec \| ASN.1 TIME`, где timespec может быть целым числом + `[w \| d \| h \| m \| s]` (например, `+32w1d2h`). Если значение не указано, срок действия сертификата начинается с текущего момента. Обратите внимание: это значение не используется для определения необходимости повторного создания существующего сертификата. Это можно изменить, задав для параметра `ignore_timestamps` значение `false`. Учтите, что при задании `ignore_timestamps=false` следует избегать относительных временных меток. Используется только провайдером `ownca`. По умолчанию: `"+0s"`
ownca_path path	Абсолютный удаленный путь к сертификату ЦС (центра сертификации). Используется только провайдером `ownca`. Несовместим с `ownca_content`.
ownca_privatekey_content string добавлено в community.crypto 1.0.0	Содержимое закрытого ключа ЦС (центра сертификации), используемого для подписания сертификата. Используется только провайдером `ownca`. Несовместим с `ownca_privatekey_path`.
ownca_privatekey_passphrase string	Парольная фраза для `ownca_privatekey_path` или `ownca_privatekey_content`. Используется только провайдером `ownca`.
ownca_privatekey_path path	Путь к закрытому ключу ЦС (центра сертификации), используемому для подписания сертификата. Используется только провайдером `ownca`. Несовместим с `ownca_privatekey_content`.
ownca_version integer	Версия сертификата `ownca`. В настоящее время почти всегда следует использовать `3`. Используется только провайдером `ownca`. Варианты: `3` ← (по умолчанию)
owner string	Имя пользователя, которому должен принадлежать объект файловой системы, передаваемое команде `chown`. Если значение не задано, используется текущий пользователь. Если пользователь — root, можно сохранить прежнее владение. Числовое имя пользователя будет интерпретировано как идентификатор пользователя, а не как имя. Во избежание неоднозначности не используйте числовые имена пользователей.
path path / обязательный	Абсолютный удаленный путь, по которому следует создать файл сертификата или где он уже находится.
privatekey_content string добавлено в community.crypto 1.0.0	Содержимое закрытого ключа, используемого для подписания сертификата. Несовместим с `privatekey_path`.
privatekey_passphrase string	Парольная фраза для `privatekey_path` или `privatekey_content`. Обязательна, если закрытый ключ защищен паролем.
privatekey_path path	Путь к закрытому ключу, используемому для подписания сертификата. Несовместим с `privatekey_content`.
provider string	Имя провайдера, используемого для создания или получения сертификата OpenSSL. Примеры эмуляции его работы см. в документации community.crypto.x509_certificate_info, community.crypto.openssl_csr_info, community.crypto.openssl_privatekey_info и ansible.builtin.assert. Обязателен, если `state` имеет значение `present`. Провайдер `entrust` удален из community.crypto 3.0.0 в связи с прекращением поддержки API ECS. Варианты: `"acme"` `"ownca"` `"selfsigned"`
return_content boolean добавлено в community.crypto 1.0.0	Если задано значение `true`, содержимое (текущего или созданного) сертификата будет возвращено как `certificate`. Варианты: `false` ← (по умолчанию) `true`
select_crypto_backend string	Определяет, какую криптографическую серверную часть использовать. По умолчанию выбрано `auto`; при наличии этот вариант пытается использовать `cryptography`. Если задано значение `cryptography`, будет предпринята попытка использовать библиотеку cryptography. Обратите внимание: в community.crypto 3.0.0 все значения работают одинаково. В более поздней версии этот параметр будет объявлен устаревшим. Рекомендуется не задавать его явно. Варианты: `"auto"` ← (по умолчанию) `"cryptography"`
selevel string	Уровневая часть контекста объекта файловой системы SELinux. Это атрибут MLS/MCS, иногда называемый `range`. При значении `_default` будет использоваться часть политики `level`, если она доступна.
selfsigned_create_subject_key_identifier string	Следует ли создавать идентификатор ключа субъекта (SKI) на основе открытого ключа. Значение `create_if_not_provided` (по умолчанию) создает SKI, только если CSR его не содержит. Значение `always_create` всегда создает SKI. Если CSR содержит SKI, он игнорируется. Значение `never_create` никогда не создает SKI. Если CSR содержит SKI, используется он. Используется только провайдером `selfsigned`. Варианты: `"create_if_not_provided"` ← (по умолчанию) `"always_create"` `"never_create"`
selfsigned_digest string	Алгоритм хеширования, используемый при самоподписании сертификата. Используется только провайдером `selfsigned`. По умолчанию: `"sha256"`
selfsigned_not_after псевдонимы: selfsigned_notAfter string	Момент времени, после которого сертификат перестает быть действительным. Время можно указать как относительное значение или как абсолютную временную метку. Время всегда интерпретируется как UTC. Допустимый формат: `[+-]timespec \| ASN.1 TIME`, где timespec может быть целым числом + `[w \| d \| h \| m \| s]` (например, `+32w1d2h`). Если значение не указано, срок действия сертификата истечет через 10 лет. Обратите внимание: это значение не используется для определения необходимости повторного создания существующего сертификата. Это можно изменить, задав для параметра `ignore_timestamps` значение `false`. Учтите, что при задании `ignore_timestamps=false` следует избегать относительных временных меток. Используется только провайдером `selfsigned`. Начиная с macOS 10.15, срок действия сертификатов TLS-серверов не должен превышать 825 дней. Дополнительные сведения см. по адресу https://support.apple.com/en-us/HT210176. По умолчанию: `"+3650d"`
selfsigned_not_before псевдонимы: selfsigned_notBefore string	Момент времени, с которого сертификат считается действительным. Время можно указать как относительное значение или как абсолютную временную метку. Время всегда интерпретируется как UTC. Допустимый формат: `[+-]timespec \| ASN.1 TIME`, где timespec может быть целым числом + `[w \| d \| h \| m \| s]` (например, `+32w1d2h`). Если значение не указано, срок действия сертификата начинается с текущего момента. Обратите внимание: это значение не используется для определения необходимости повторного создания существующего сертификата. Это можно изменить, задав для параметра `ignore_timestamps` значение `false`. Учтите, что при задании `ignore_timestamps=false` следует избегать относительных временных меток. Используется только провайдером `selfsigned`. По умолчанию: `"+0s"`

selfsigned_version integer	Версия сертификата `selfsigned`. В настоящее время почти всегда следует использовать `3`. Используется только провайдером `selfsigned`. Варианты: `3` ← (по умолчанию)
serole string	Часть роли в контексте объекта файловой системы SELinux. Если задано значение `_default`, будет использоваться часть политики `role`, если она доступна.
setype string	Часть типа в контексте объекта файловой системы SELinux. Если задано значение `_default`, будет использоваться часть политики `type`, если она доступна.
seuser string	Часть пользователя в контексте объекта файловой системы SELinux. По умолчанию используется политика `system`, если применимо. Если задано значение `_default`, будет использоваться часть политики `user`, если она доступна.
state string	Должен ли сертификат существовать; при несовпадении текущего состояния с указанным выполняется соответствующее действие. Варианты: `"absent"` `"present"` ← (по умолчанию)
unsafe_writes boolean	Определяет, когда использовать атомарную операцию, чтобы предотвратить повреждение данных или несогласованное чтение целевого объекта файловой системы. По умолчанию этот модуль использует атомарные операции для предотвращения повреждения данных или несогласованного чтения целевых объектов файловой системы, но иногда конфигурация систем или их неисправности этому препятствуют. Например, объекты файловой системы, смонтированные Docker, невозможно атомарно обновить из контейнера — их можно записать только небезопасным способом. Этот параметр позволяет Ansible в случае сбоя атомарных операций использовать небезопасные методы обновления объектов файловой системы (однако он не заставляет Ansible выполнять небезопасную запись). ВАЖНО! При небезопасной записи возможны состояния гонки и повреждение данных. Варианты: `false` ← (по умолчанию) `true`

Атрибуты

Атрибут	Поддержка	Описание
check_mode	Поддержка: полная	Может работать в режиме `check_mode` и возвращать прогноз изменения состояния, не изменяя целевой объект.
diff_mode	Поддержка: полная	В режиме diff возвращает сведения об изменениях (или возможных изменениях в `check_mode`).
idempotent	Поддержка: частичная При использовании относительных временных меток и `ignore_timestamps=false` модуль не является идемпотентным. Параметр `force=true` обычно отключает идемпотентность.	При повторном запуске с теми же аргументами вне режима check второй вызов указывает на отсутствие изменений. Предполагается, что система, которой управляет модуль или к которой он обращается, не изменилась существенным образом.
safe_file_operations	Поддержка: полная	Используются строгие функции Ansible для работы с файлами, обеспечивающие правильные разрешения и предотвращающие повреждение данных.

Примечания

Примечание

Все значения времени ASN.1 TIME следует задавать в формате YYYYMMDDHHMMSSZ.
Указанная дата должна быть в часовом поясе UTC. Минуты и секунды обязательны.
В целях безопасности при использовании провайдера ownca НЕ следует запускать community.crypto.x509_certificate на целевой машине; запустите его на выделенной машине центра сертификации (CA). Рекомендуется не хранить закрытый ключ CA на целевой машине. После подписания сертификат можно перенести на целевую машину.
Для провайдера selfsigned параметры csr_path и csr_content необязательны. Если их не указать, будет создан сертификат без какой-либо информации (субъекта, альтернативных имен субъекта, использования ключа и т. д.).

См. также

community.crypto.x509_certificate_pipe: Создание и/или проверка сертификатов OpenSSL.
community.crypto.openssl_csr: Создание запроса на подписание сертификата (CSR) OpenSSL.
community.crypto.openssl_csr_pipe: Создание запроса на подписание сертификата (CSR) OpenSSL.
community.crypto.openssl_dhparam: Создание параметров Диффи — Хеллмана OpenSSL.
community.crypto.openssl_pkcs12: Создание архива PKCS#12 OpenSSL.
community.crypto.openssl_privatekey: Создание закрытых ключей OpenSSL.
community.crypto.openssl_privatekey_pipe: Создание закрытых ключей OpenSSL без доступа к диску.
community.crypto.openssl_publickey: Создание открытого ключа OpenSSL на основе закрытого ключа.

Примеры

---
- name: Generate a Self Signed OpenSSL certificate
  community.crypto.x509_certificate:
    path: /etc/ssl/crt/ansible.com.crt
    privatekey_path: /etc/ssl/private/ansible.com.pem
    csr_path: /etc/ssl/csr/ansible.com.csr
    provider: selfsigned

- name: Generate an OpenSSL certificate signed with your own CA certificate
  community.crypto.x509_certificate:
    path: /etc/ssl/crt/ansible.com.crt
    csr_path: /etc/ssl/csr/ansible.com.csr
    ownca_path: /etc/ssl/crt/ansible_CA.crt
    ownca_privatekey_path: /etc/ssl/private/ansible_CA.pem
    provider: ownca

- name: Generate a Let's Encrypt Certificate
  community.crypto.x509_certificate:
    path: /etc/ssl/crt/ansible.com.crt
    csr_path: /etc/ssl/csr/ansible.com.csr
    provider: acme
    acme_accountkey_path: /etc/ssl/private/ansible.com.pem
    acme_challenge_path: /etc/ssl/challenges/ansible.com/

- name: Force (re-)generate a new Let's Encrypt Certificate
  community.crypto.x509_certificate:
    path: /etc/ssl/crt/ansible.com.crt
    csr_path: /etc/ssl/csr/ansible.com.csr
    provider: acme
    acme_accountkey_path: /etc/ssl/private/ansible.com.pem
    acme_challenge_path: /etc/ssl/challenges/ansible.com/
    force: true

# The following example shows how to emulate the behavior of the removed
# "assertonly" provider with the x509_certificate_info, openssl_csr_info,
# openssl_privatekey_info and assert modules:

- name: Get certificate information
  community.crypto.x509_certificate_info:
    path: /etc/ssl/crt/ansible.com.crt
    # for valid_at, invalid_at and valid_in
    valid_at:
      one_day_ten_hours: "+1d10h"
      fixed_timestamp: 20200331202428Z
      ten_seconds: "+10"
  register: result

- name: Get CSR information
  community.crypto.openssl_csr_info:
    # Verifies that the CSR signature is valid; module will fail if not
    path: /etc/ssl/csr/ansible.com.csr
  register: result_csr

- name: Get private key information
  community.crypto.openssl_privatekey_info:
    path: /etc/ssl/csr/ansible.com.key
  register: result_privatekey

- name: Check conditions on certificate, CSR, and private key
  ansible.builtin.assert:
    that:
      # When private key was specified for assertonly, this was checked:
      - result.public_key == result_privatekey.public_key
      # When CSR was specified for assertonly, this was checked:
      - result.public_key == result_csr.public_key
      - result.subject_ordered == result_csr.subject_ordered
      - result.extensions_by_oid == result_csr.extensions_by_oid
      # signature_algorithms check
      - "result.signature_algorithm == 'sha256WithRSAEncryption' or result.signature_algorithm == 'sha512WithRSAEncryption'"
      # subject and subject_strict
      - "result.subject.commonName == 'ansible.com'"
      - "result.subject | length == 1" # the number must be the number of entries you check for
      # issuer and issuer_strict
      - "result.issuer.commonName == 'ansible.com'"
      - "result.issuer | length == 1" # the number must be the number of entries you check for
      # has_expired
      - not result.expired
      # version
      - result.version == 3
      # key_usage and key_usage_strict
      - "'Data Encipherment' in result.key_usage"
      - "result.key_usage | length == 1" # the number must be the number of entries you check for
      # extended_key_usage and extended_key_usage_strict
      - "'DVCS' in result.extended_key_usage"
      - "result.extended_key_usage | length == 1" # the number must be the number of entries you check for
      # subject_alt_name and subject_alt_name_strict
      - "'dns:ansible.com' in result.subject_alt_name"
      - "result.subject_alt_name | length == 1" # the number must be the number of entries you check for
      # not_before and not_after
      - "result.not_before == '20190331202428Z'"
      - "result.not_after == '20190413202428Z'"
      # valid_at, invalid_at and valid_in
      - "result.valid_at.one_day_ten_hours" # for valid_at
      - "not result.valid_at.fixed_timestamp" # for invalid_at
      - "result.valid_at.ten_seconds" # for valid_in

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

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

Ключ	Описание
backup_file string	Имя созданного файла резервной копии. Возвращается: если состояние изменилось и `backup` равно `true` Пример: `"/path/to/www.ansible.com.crt.2019-03-09@11:22~"`
certificate string добавлено в community.crypto 1.0.0	Содержимое (текущего или сгенерированного) сертификата. Возвращается: если `state` равно `present`, а `return_content` равно `true`
filename string	Путь к сгенерированному сертификату. Возвращается: при изменении состояния или успешном выполнении Пример: `"/etc/ssl/crt/www.ansible.com.crt"`

Авторы

Yanis Guenane (@Spredzy)
Markus Teufelberger (@MarkusTeufelberger)

Ссылки коллекции

© 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/x509_certificate_module.html