Модуль community.crypto.openssh_cert — создание сертификатов узла или пользователя OpenSSH

Примечание

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

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

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

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

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

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

Создание и повторное создание сертификатов узла или пользователя OpenSSH.

Требования

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

ssh-keygen

Параметры

Параметр	Комментарии
attributes псевдонимы: attr строка	Атрибуты, которыми должен обладать результирующий объект файловой системы. Список поддерживаемых флагов можно найти на странице руководства для `chattr` в целевой системе. Эта строка должна содержать атрибуты в том же порядке, в каком они отображаются командой `lsattr`. По умолчанию предполагается оператор `=`, в противном случае в строку необходимо включить операторы `+` или `-`.
force логическое значение	Следует ли повторно создать сертификат, даже если он уже существует и является действительным. Эквивалентно `regenerate=always`. Варианты: `false` ← (по умолчанию) `true`
group строка	Имя группы, которой должен принадлежать объект файловой системы; оно передавалось бы команде `chown`. Если значение не указано, используется текущая группа текущего пользователя, кроме случая, когда пользователь — root: тогда может быть сохранён прежний владелец.
identifier строка	Указывает идентификатор ключа при подписании открытого ключа. Идентификатор регистрируется сервером при использовании сертификата для аутентификации.
ignore_timestamps логическое значение добавлено в community.crypto 2.2.0	Следует ли игнорировать временные метки `valid_from` и `valid_to` при проверках идемпотентности. Однако эти значения всё равно будут применены к новому сертификату, если выполняются другие необходимые условия для его создания или повторного создания. Варианты: `false` ← (по умолчанию) `true`
mode любое значение	Права доступа, которыми должен обладать результирующий объект файловой системы. Если вы привыкли к `/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.
options список / элементы=строка	Указывает параметры сертификата при подписании ключа. Для сертификатов пользователей допустимы следующие параметры: `clear`: очистить все включённые разрешения. Это полезно для сброса набора разрешений по умолчанию, чтобы добавлять разрешения по отдельности. `force-command=command`: принудительно выполнять указанную команду вместо любой оболочки или команды, заданной пользователем, при использовании сертификата для аутентификации. `no-agent-forwarding`: отключить перенаправление ssh-agent (разрешено по умолчанию). `no-port-forwarding`: отключить перенаправление портов (разрешено по умолчанию). `no-pty`: отключить выделение PTY (разрешено по умолчанию). `no-user-rc`: отключить выполнение `~/.ssh/rc` программой sshd (разрешено по умолчанию). `no-x11-forwarding`: отключить перенаправление X11 (разрешено по умолчанию). `permit-agent-forwarding`: разрешить перенаправление ssh-agent. `permit-port-forwarding`: разрешить перенаправление портов. `permit-pty`: разрешить выделение PTY. `permit-user-rc`: разрешить выполнение `~/.ssh/rc` программой sshd. `permit-x11-forwarding`: разрешить перенаправление X11. `source-address=address_list`: ограничить адреса источников, с которых сертификат считается действительным. `address_list` — это список из одной или нескольких пар адрес/маска, разделённых запятыми и записанных в формате CIDR. На данный момент для ключей узлов параметры не предусмотрены.
owner строка	Имя пользователя, которому должен принадлежать объект файловой системы; оно передавалось бы команде `chown`. Если значение не указано, используется текущий пользователь, кроме случая, когда пользователь — root: тогда может быть сохранён прежний владелец. Числовое имя пользователя будет считаться идентификатором пользователя, а не именем пользователя. Во избежание неоднозначности не используйте числовые имена пользователей.
path путь / обязательно	Путь к файлу, содержащему сертификат.
pkcs11_provider строка добавлено в community.crypto 1.1.0	Чтобы использовать ключ подписи, хранящийся на токене PKCS#11, укажите здесь имя (или полный путь) общей библиотеки, используемой с токеном. Обычно это `libpkcs11.so`. Если этот параметр задан, `signing_key` должен указывать на файл, содержащий открытый ключ CA.
principals список / элементы=строка	Можно ограничить действие сертификатов набором допустимых имён принципалов (пользователей/узлов). По умолчанию созданные сертификаты действительны для всех пользователей или узлов.
public_key путь	Путь к открытому ключу, который будет подписан ключом подписи для создания сертификата. Обязательно, если `state` имеет значение `present`.
regenerate строка добавлено в community.crypto 1.8.0	Если задано значение `never`, задача завершится ошибкой, если сертификат уже существует по пути `path` и не может быть прочитан; в противном случае новый сертификат будет создан только при отсутствии существующего. Если задано значение `fail`, задача завершится ошибкой, если сертификат уже существует по пути `path` и не соответствует параметрам модуля. Если задано значение `partial_idempotence`, существующий сертификат будет создан заново с учётом `serial_number`, `signature_algorithm`, `type`, `valid_from`, `valid_to`, `valid_at` и `principals`. `valid_from` и `valid_to` можно исключить с помощью `ignore_timestamps=true`. Если задано значение `full_idempotence`, при сравнении с существующим сертификатом также учитываются `identifier`, `options`, `public_key` и `signing_key`. `always` эквивалентно `force=true`. Варианты: `"never"` `"fail"` `"partial_idempotence"` ← (по умолчанию) `"full_idempotence"` `"always"`
selevel строка	Уровневая часть контекста объекта файловой системы SELinux. Это атрибут MLS/MCS, иногда называемый `range`. Если задано значение `_default`, будет использоваться часть политики `level`, если она доступна.
serial_number целое число	Указывает серийный номер сертификата. Сервер регистрирует серийный номер при использовании сертификата для аутентификации. Серийный номер сертификата можно использовать в списке отзыва ключей (KeyRevocationList). Для проверок серийный номер можно не указывать, но для нового сертификата его необходимо указать повторно. Примечание: значение по умолчанию, устанавливаемое ssh-keygen, равно 0. Этот параметр принимает целое число. Если необходимо указать серийный номер в виде разделённой двоеточиями шестнадцатеричной строки, например `11:22:33`, преобразуйте его в целое число с помощью фильтра community.crypto.parse_serial.
serole строка	Ролевая часть контекста объекта файловой системы SELinux. Если задано значение `_default`, будет использоваться часть политики `role`, если она доступна.
setype строка	Типовая часть контекста объекта файловой системы SELinux. Если задано значение `_default`, будет использоваться часть политики `type`, если она доступна.
seuser строка	Пользовательская часть контекста объекта файловой системы SELinux. По умолчанию используется политика `system`, если применимо. Если задано значение `_default`, будет использоваться часть политики `user`, если она доступна.
signature_algorithm строка добавлено в community.crypto 1.10.0	Начиная с OpenSSH 8.2 алгоритм подписи SHA-1 для ключей RSA отключён, а `ssh` отклоняет сертификаты узлов, подписанные алгоритмом SHA-1. В OpenSSH 8.1 алгоритм `rsa-sha2-512` стал алгоритмом по умолчанию при работе в качестве CA и подписании сертификатов ключом RSA. Однако в версиях OpenSSH ниже 8.1 алгоритмы подписания SHA-2 — `rsa-sha2-256` или `rsa-sha2-512` — необходимо указывать с помощью этого параметра, если требуется совместимость с более новыми клиентами `ssh`. И наоборот, если узлы с OpenSSH версии 8.2 или выше должны оставаться совместимыми с клиентами `ssh`, использующими OpenSSH ниже 7.2, при создании сертификатов узлов можно использовать `ssh-rsa` (также потребуется соответствующим образом изменить sshd_config, добавив `ssh-rsa` в директиву `CASignatureAlgorithms`). Использование любого значения этого параметра с ключом `signing_key`, не являющимся RSA, приведёт к ошибке модуля. Примечание: версии OpenSSH до 7.2 не поддерживают алгоритмы подписи SHA-2 для ключей RSA, а версии OpenSSH до 7.3 не поддерживают алгоритмы подписи SHA-2 для сертификатов. Дополнительные сведения см. на странице https://www.openssh.com/txt/release-8.2. Варианты: `"ssh-rsa"` `"rsa-sha2-256"` `"rsa-sha2-512"`
signing_key путь	Путь к закрытому ключу OpenSSH, используемому для подписания открытого ключа и создания сертификата. Если закрытый ключ находится на токене PKCS#11 (`pkcs11_provider`), укажите здесь путь к открытому ключу. Обязательно, если `state` имеет значение `present`.
state строка	Указывает, должен ли сертификат узла или пользователя существовать; если текущее состояние отличается от указанного, выполняется соответствующее действие. Варианты: `"present"` ← (по умолчанию) `"absent"`
type строка	Указывает, должен ли модуль создать сертификат узла или пользователя. Обязательно, если `state` имеет значение `present`. Варианты: `"host"` `"user"`
unsafe_writes логическое значение	Определяет, когда использовать атомарные операции для предотвращения повреждения данных и несогласованного чтения из целевого объекта файловой системы. По умолчанию этот модуль использует атомарные операции для предотвращения повреждения данных и несогласованного чтения из целевых объектов файловой системы, но иногда конфигурация систем или их неисправности не позволяют этого. Например, смонтированные в Docker объекты файловой системы нельзя атомарно обновить из контейнера — их можно записать только небезопасным способом. Этот параметр позволяет Ansible перейти к небезопасным способам обновления объектов файловой системы, если атомарные операции завершаются неудачей (однако он не заставляет Ansible выполнять небезопасную запись). ВАЖНО! Небезопасная запись подвержена состояниям гонки и может привести к повреждению данных. Варианты: `false` ← (по умолчанию) `true`
use_agent логическое значение добавлено в community.crypto 1.3.0	Следует ли ssh-keygen использовать ключ CA, хранящийся в ssh-agent. Варианты: `false` ← (по умолчанию) `true`
valid_at строка	Проверяет, действителен ли сертификат в определённый момент времени. Если нет, сертификат будет создан заново. Время всегда интерпретируется как UTC. В основном используется с относительным указанием времени для `valid_from` и/или `valid_to`. Обратите внимание: при использовании относительного времени этот модуль НЕ является идемпотентным.
valid_from строка	Момент времени, начиная с которого сертификат действителен. Время можно задать как относительное значение или как абсолютную временную метку. Время всегда интерпретируется как UTC. Допустимые форматы: `[+-]timespec \| YYYY-MM-DD \| YYYY-MM-DDTHH:MM:SS \| YYYY-MM-DD HH:MM:SS \| always`, где timespec — целое число + `[w \| d \| h \| m \| s]` (например, `+32w1d2h`). Обратите внимание: при использовании относительного времени этот модуль НЕ является идемпотентным. Значение `always` поддерживается только в OpenSSH 7.7 и выше; однако в более ранних версиях можно использовать эквивалентное выражение `1970-01-01T00:00:01`. Чтобы игнорировать это значение при сравнении с существующим сертификатом, задайте `ignore_timestamps=true`. Обязательно, если `state` имеет значение `present`.
valid_to строка	Момент времени, до которого сертификат действителен. Время можно задать как относительное значение или как абсолютную временную метку. Время всегда интерпретируется как UTC. Допустимые форматы: `[+-]timespec \| YYYY-MM-DD \| YYYY-MM-DDTHH:MM:SS \| YYYY-MM-DD HH:MM:SS \| forever`, где timespec — целое число + `[w \| d \| h \| m \| s]` (например, `+32w1d2h`). Обратите внимание: при использовании относительного времени этот модуль НЕ является идемпотентным. Чтобы игнорировать это значение при сравнении с существующим сертификатом, задайте `ignore_timestamps=true`. Обязательно, если `state` имеет значение `present`.

Атрибуты

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

См. также

community.crypto.parse_serial — плагин фильтра: Преобразует серийный номер в виде разделённого двоеточиями списка шестнадцатеричных чисел в целое число.

Примеры

---
- name: Generate an OpenSSH user certificate that is valid forever and for all users
  community.crypto.openssh_cert:
    type: user
    signing_key: /path/to/private_key
    public_key: /path/to/public_key.pub
    path: /path/to/certificate
    valid_from: always
    valid_to: forever

# Generate an OpenSSH host certificate that is valid for 32 weeks from now and will be regenerated
# if it is valid for less than 2 weeks from the time the module is being run
- name: Generate an OpenSSH host certificate with valid_from, valid_to and valid_at parameters
  community.crypto.openssh_cert:
    type: host
    signing_key: /path/to/private_key
    public_key: /path/to/public_key.pub
    path: /path/to/certificate
    valid_from: +0s
    valid_to: +32w
    valid_at: +2w
    ignore_timestamps: true

- name: Generate an OpenSSH host certificate that is valid forever and only for example.com and examplehost
  community.crypto.openssh_cert:
    type: host
    signing_key: /path/to/private_key
    public_key: /path/to/public_key.pub
    path: /path/to/certificate
    valid_from: always
    valid_to: forever
    principals:
      - example.com
      - examplehost

- name: Generate an OpenSSH host Certificate that is valid from 21.1.2001 to 21.1.2019
  community.crypto.openssh_cert:
    type: host
    signing_key: /path/to/private_key
    public_key: /path/to/public_key.pub
    path: /path/to/certificate
    valid_from: "2001-01-21"
    valid_to: "2019-01-21"

- name: Generate an OpenSSH user Certificate with clear and force-command option
  community.crypto.openssh_cert:
    type: user
    signing_key: /path/to/private_key
    public_key: /path/to/public_key.pub
    path: /path/to/certificate
    valid_from: always
    valid_to: forever
    options:
      - "clear"
      - "force-command=/tmp/bla/foo"

- name: Generate an OpenSSH user certificate using a PKCS#11 token
  community.crypto.openssh_cert:
    type: user
    signing_key: /path/to/ca_public_key.pub
    pkcs11_provider: libpkcs11.so
    public_key: /path/to/public_key.pub
    path: /path/to/certificate
    valid_from: always
    valid_to: forever

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

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

Ключ	Описание
filename строка	Путь к сертификату. Возвращается: при изменении или успехе Пример: `"/tmp/certificate-cert.pub"`
info список / элементы=строка	Информация о сертификате. Вывод `ssh-keygen -L -f`. Возвращается: при изменении или успехе
type строка	Тип сертификата (хост или пользователь). Возвращается: при изменении или успехе Пример: `"host"`

Авторы

David Kainz (@lolcube)

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

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