community.crypto.openssh_cert 模块 – 生成 OpenSSH 主机或用户证书。

注意

此模块是 community.crypto 集合 (版本 2.22.3) 的一部分。

如果您使用的是 ansible 包，则可能已安装此集合。它不包含在 ansible-core 中。要检查它是否已安装，请运行 ansible-galaxy collection list。

要安装它，请使用：ansible-galaxy collection install community.crypto。您需要其他要求才能使用此模块，请参阅 要求 以了解详细信息。

要在 playbook 中使用它，请指定：community.crypto.openssh_cert。

概要

• 生成和重新生成 OpenSSH 主机或用户证书。

要求

在执行此模块的主机上需要以下要求。

• ssh-keygen

参数

参数	注释
attributes 别名：attr 字符串	生成的 filesystem 对象应具有的属性。 要获取支持的标志，请查看目标系统上 chattr 的手册页。 此字符串应按 lsattr 显示的顺序包含属性。 假定 = 运算符为默认值，否则需要在字符串中包含 + 或 - 运算符。
force 布尔值	即使证书已存在且有效，是否也应重新生成证书。 相当于 regenerate=always。 选项 false ← (默认) true
group 字符串	应拥有 filesystem 对象的组的名称，就像提供给 chown 一样。 如果未指定，则它使用当前用户的当前组，除非您是 root 用户，在这种情况下，它可以保留以前的拥有权。
identifier 字符串	签名公钥时指定密钥标识。服务器在使用证书进行身份验证时记录的标识符。
ignore_timestamps 布尔值 在 community.crypto 2.2.0 中添加	对于幂等性检查，是否应忽略 valid_from 和 valid_to 时间戳。 但是，如果满足生成/重新生成的任何其他必要条件，这些值仍将应用于新证书。 选项 false ← (默认) true
mode 任意	生成的 filesystem 对象应具有的权限。 对于习惯使用 /usr/bin/chmod 的用户，请记住模式实际上是八进制数。您必须向 Ansible 提供足够的信息才能正确解析它们。为了获得一致的结果，请引用八进制数（例如，'644' 或 '1777'），以便 Ansible 接收一个字符串并可以自行将字符串转换为数字。添加前导零（例如，0755）有时有效，但在循环和其他情况下可能会失败。 向 Ansible 提供不遵循上述任何规则的数字将导致十进制数，这将产生意外的结果。 从 Ansible 1.8 开始，模式可以指定为符号模式（例如，u+rwx 或 u=rw,g=r,o=r）。 如果未指定 mode 且目标 filesystem 对象**不存在**，则在设置新创建的 filesystem 对象的模式时，将使用系统上的默认 umask。 如果未指定 mode 且目标 filesystem 对象**存在**，则将使用现有 filesystem 对象的模式。 指定 mode 是确保以正确的权限创建 filesystem 对象的最佳方法。有关更多详细信息，请参阅 CVE-2020-1736。
options 列表 / 元素=字符串	签名密钥时指定证书选项。对用户证书有效的选项是 clear：清除所有已启用权限。这对于清除默认权限集以便可以单独添加权限很有用。 force-command=command：强制执行命令command，而不是在使用证书进行身份验证时用户指定的任何 shell 或命令。 no-agent-forwarding：禁用 ssh-agent 转发（默认允许）。 no-port-forwarding：禁用端口转发（默认允许）。 no-pty：禁用 PTY 分配（默认允许）。 no-user-rc：禁用 sshd 执行 ~/.ssh/rc（默认允许）。 no-x11-forwarding：禁用 X11 转发（默认允许）。 permit-agent-forwarding：允许 ssh-agent 转发。 permit-port-forwarding：允许端口转发。 permit-pty：允许 PTY 分配。 permit-user-rc：允许 sshd 执行 ~/.ssh/rc。 permit-x11-forwarding：允许 X11 转发。 source-address=address_list：限制证书被认为有效的源地址。 address_list 是一个用逗号分隔的一个或多个 CIDR 格式的地址/网络掩码对列表。 目前，主机密钥不接受任何选项。
owner 字符串	应该拥有文件系统对象的用户名称，如同传递给 chown 命令一样。 如果未指定，则使用当前用户，除非您是 root 用户，在这种情况下，它可以保留之前的拥有者。 指定数字用户名将被认为是用户 ID 而不是用户名。避免使用数字用户名以避免此混淆。
path path / 必填	包含证书的文件路径。
pkcs11_provider 字符串 community.crypto 1.1.0 版本中新增	要使用驻留在 PKCS#11 令牌上的签名密钥，请将其设置为与令牌一起使用的共享库的名称（或完整路径）。通常为 libpkcs11.so。 如果设置了此选项，则需要 signing_key 指向包含 CA 公钥的文件。
principals 列表 / 元素=字符串	证书可以限制为对一组主体（用户/主机）名称有效。默认情况下，生成的证书对所有用户或主机有效。
public_key path	将使用签名密钥签名的公钥路径，用于生成证书。 如果 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 整数	指定证书序列号。证书用于身份验证时，服务器会记录序列号。证书序列号可用于密钥吊销列表。可以省略序列号进行检查，但必须为新证书再次指定。注意：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 开始，RSA 密钥的 SHA-1 签名算法已被禁用，ssh 将拒绝使用 SHA-1 算法签名的主机证书。OpenSSH 8.1 在充当 CA 并使用 RSA 密钥签署证书时，将 rsa-sha2-512 设为默认算法。但是，对于低于 8.1 的 OpenSSH 版本，如果需要与较新的 ssh 客户端兼容，则必须使用此选项指定 SHA-2 签名算法 rsa-sha2-256 或 rsa-sha2-512。相反，如果必须使使用 OpenSSH 8.2 或更高版本的服务器与使用低于 7.2 的 OpenSSH 版本的 ssh 客户端保持兼容，则在生成主机证书时可以使用 ssh-rsa（还需要相应地更改 sshd_config，以便将 ssh-rsa 添加到 CASignatureAlgorithms 关键字）。 对于非 RSA signing_key，使用此选项的任何值都会导致此模块失败。 注意：7.2 之前的 OpenSSH 版本不支持 RSA 密钥的 SHA-2 签名算法，7.3 之前的 OpenSSH 版本不支持证书的 SHA-2 签名算法。 更多信息请参见 https://www.openssh.com/txt/release-8.2。 选项 "ssh-rsa" "rsa-sha2-256" "rsa-sha2-512"
signing_key path	用于签署公钥以生成证书的私有 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 是否应使用驻留在 ssh-agent 中的 CA 密钥。 选项 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 中更改）的详细信息。
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 字符串	证书路径 返回：changed 或 success 示例："/tmp/certificate-cert.pub"
info 列表 / 元素=字符串	有关证书的信息。ssh-keygen -L -f 的输出。 返回：change 或 success
type 字符串	证书的类型（主机或用户） 返回：changed 或 success 示例："host"

作者

• David Kainz (@lolcube)

收藏链接

• 问题追踪器
• 代码库（源代码）
• 寻求帮助（加密）
• 寻求帮助（ACME）
• 提交错误报告
• 请求功能
• 沟通