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 字符串	结果文件系统对象应具有的属性。 要获取支持的标志，请查看目标系统上 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 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。
选项 list / elements=string	指定签名密钥时使用的证书选项。用户证书的有效选项包括： 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 / required	包含证书的文件路径。
pkcs11_provider 字符串 在 community.crypto 1.1.0 中添加	要使用驻留在 PKCS#11 令牌上的签名密钥，请将其设置为与令牌一起使用的共享库的名称（或完整路径）。通常是 libpkcs11.so。 如果设置了此项，则 signing_key 需要指向一个包含 CA 公钥的文件。
principals list / elements=string	证书可能仅限于对一组主体（用户/主机）名称有效。默认情况下，生成的证书对所有用户或主机有效。
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 重新生成现有证书。可以通过 ignore_timestamps=true 排除 valid_from 和 valid_to。 当 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 开始，已禁用 RSA 密钥的 SHA-1 签名算法，并且 ssh 将拒绝使用 SHA-1 算法签名的主机证书。OpenSSH 8.1 将 rsa-sha2-512 作为用 RSA 密钥签署证书时充当 CA 的默认算法。但是，对于低于 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)。请注意，如果使用相对时间，则此模块不是幂等的。 仅 OpenSSH 7.7 及更高版本支持值 always，但是，值 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	支持: 完整	在 diff 模式下运行时，将返回已更改（或可能需要在 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 字符串	证书的路径 返回: 已更改或成功 示例: "/tmp/certificate-cert.pub"
info list / elements=string	有关证书的信息。ssh-keygen -L -f 的输出。 返回: 已更改或成功
type 字符串	证书的类型（主机或用户） 返回: 已更改或成功 示例: "host"

作者

• David Kainz (@lolcube)

集合链接

• 问题跟踪器
• 存储库（源代码）
• 寻求帮助（crypto）
• 寻求帮助（ACME）
• 提交错误报告
• 请求功能
• 沟通