community.crypto.openssh_keypair 模块 – 生成 OpenSSH 私钥和公钥

注意

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

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

要安装它，请使用： ansible-galaxy collection install community.crypto。您需要进一步的要求才能使用此模块，有关详细信息，请参阅要求。

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

概要

• 此模块允许（重新）生成 OpenSSH 私钥和公钥。它使用 ssh-keygen 生成密钥。可以生成 rsa、 dsa、 rsa1、 ed25519 或 ecdsa 私钥。

要求

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

• ssh-keygen (如果 backend=openssh)

• cryptography >= 2.6 (如果 backend=cryptography 并且安装了 OpenSSH < 7.8)

• cryptography >= 3.0 (如果 backend=cryptography 并且安装了 OpenSSH >= 7.8)

参数

参数	注释
attributes 别名: attr 字符串	结果文件系统对象应具有的属性。 要获取支持的标志，请查看目标系统上 chattr 的手册页。 此字符串应包含与 lsattr 显示的顺序相同的属性。 默认情况下假定 = 运算符，否则需要在字符串中包含 + 或 - 运算符。
backend 字符串 在 community.crypto 1.7.0 中添加	在 cryptography 库或 OpenSSH 二进制文件 opensshbin 之间进行选择。 auto 将默认为 opensshbin，除非未安装 OpenSSH 二进制文件或使用 passphrase 时。 选项 "auto" ←（默认） "cryptography" "opensshbin"
comment 字符串	为公钥提供新注释。
force 布尔值	即使密钥已存在，是否应重新生成密钥 选项 false ←（默认） true
group 字符串	应该拥有文件系统对象的所有者的组的名称，就像提供给 chown 的一样。 如果未指定，它将使用当前用户的当前组，除非您是 root 用户，在这种情况下它可以保留之前的属主关系。
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。
owner 字符串	应拥有文件系统对象的用户的名称，与传递给 *chown* 的名称相同。 如果未指定，则使用当前用户，除非您是 root 用户，在这种情况下，它可以保留以前的所有权。 指定数字用户名将被假定为用户 ID，而不是用户名。避免使用数字用户名，以避免这种混淆。
passphrase 字符串 在 community.crypto 1.7.0 中添加	用于解密现有私钥或加密新生成的私钥的密码。 不支持 type=rsa1 的密码。 仅当 backend=cryptography 时，或当 backend=auto 且安装了必需的 cryptography 版本时，才可以使用。
path 路径 / 必需	包含公钥和私钥的文件的名称。包含公钥的文件将具有扩展名 .pub。
private_key_format 字符串 在 community.crypto 1.7.0 中添加	当 backend=cryptography 时使用，用于为提供的 path 选择私钥的格式。 当设置为 auto 时，此模块将匹配已安装的 OpenSSH 版本的密钥格式。 对于 OpenSSH < 7.8，私钥将采用 PKCS1 格式，但 ed25519 密钥将采用 OpenSSH 格式。 对于 OpenSSH >= 7.8，所有私钥类型都将采用 OpenSSH 格式。 当 regenerate=partial_idempotence 或 regenerate=full_idempotence 时使用此选项，如果私钥的格式与 private_key_format 的值不匹配，将导致生成新的密钥对。但是，此模块不会在格式之间转换现有私钥。 选项 "auto" ←（默认） "pkcs1" "pkcs8" "ssh"
regenerate 字符串 在 community.crypto 1.0.0 中添加	允许配置在哪些情况下允许模块重新生成私钥。如果目标文件不存在，模块将始终生成新密钥。 默认情况下，当密钥与模块的选项不匹配时，将重新生成密钥，除非密钥无法读取或密码不匹配。请注意，Ansible 2.10 的此行为已发生更改。对于 Ansible 2.9，其行为如同指定了 full_idempotence。 如果设置为 never，则如果密钥无法读取或密码不匹配，模块将失败，并且永远不会重新生成现有密钥。 如果设置为 fail，则如果密钥与模块的选项不符，模块将失败。 如果设置为 partial_idempotence，则如果密钥不符合模块的选项，将重新生成密钥。如果密钥无法读取（文件损坏）、密钥受到未知密码保护，或者当密钥未受密码保护但指定了密码时，则不会重新生成密钥。 如果设置为 full_idempotence，则如果密钥不符合模块的选项，将重新生成密钥。如果密钥无法读取（文件损坏）、密钥受到未知密码保护，或者当密钥未受密码保护但指定了密码时，也会重新生成密钥。使用此选项时，请确保您有备份！ 如果设置为 always，则模块将始终重新生成密钥。这等效于将 force 设置为 true。 请注意，调整注释和权限可以进行更改，而无需重新生成。因此，即使对于 never，任务也可能导致更改。 选项 "never" "fail" "partial_idempotence" ←（默认） "full_idempotence" "always"
selevel 字符串	SELinux 文件系统对象上下文的级别部分。 这是 MLS/MCS 属性，有时称为 range。 当设置为 _default 时，如果可用，它将使用策略的 level 部分。
serole 字符串	SELinux 文件系统对象上下文的角色部分。 当设置为 _default 时，如果可用，它将使用策略的 role 部分。
setype 字符串	SELinux 文件系统对象上下文的类型部分。 当设置为 _default 时，如果可用，它将使用策略的 type 部分。
seuser 字符串	SELinux 文件系统对象上下文的用户部分。 默认情况下，它使用 system 策略（如果适用）。 当设置为 _default 时，如果可用，它将使用策略的 user 部分。
size 整数	指定要创建的私钥中的位数。对于 RSA 密钥，最小大小为 1024 位，默认大小为 4096 位。通常，2048 位被认为是足够的。DSA 密钥必须按照 FIPS 186-2 的规定精确地为 1024 位。对于 ECDSA 密钥，大小通过从以下三种椭圆曲线大小中选择一种来确定密钥长度：256、384 或 521 位。尝试对 ECDSA 密钥使用这三个值之外的位长度将导致此模块失败。Ed25519 密钥具有固定长度，并且将忽略大小。
state 字符串	私钥和公钥是否应该存在，如果状态与所声明的不同，则采取操作。 选项 "present" ←（默认） "absent"
type 字符串	用于生成 SSH 私钥的算法。rsa1 用于协议版本 1。rsa1 已弃用，并且可能不受 ssh-keygen 的每个版本支持。 选项 "rsa" ←（默认） "dsa" "rsa1" "ecdsa" "ed25519"
unsafe_writes 布尔值	影响何时使用原子操作以防止数据损坏或从目标文件系统对象读取不一致的数据。 默认情况下，此模块使用原子操作来防止数据损坏或从目标文件系统对象读取不一致的数据，但有时系统的配置或损坏方式会阻止这种情况。一个例子是 docker 挂载的文件系统对象，这些对象无法从容器内部以原子方式更新，并且只能以不安全的方式写入。 当原子操作失败时，此选项允许 Ansible 回退到更新文件系统对象的不安全方法（但是，它不会强制 Ansible 执行不安全写入）。 重要提示！不安全的写入会受到竞争条件的影响，并可能导致数据损坏。 选项 false ←（默认） true

属性

属性	支持	描述
check_mode	支持：完全	可以在 check_mode 中运行并返回更改状态预测，而无需修改目标。
diff_mode	支持：完全	当处于 diff 模式时，将返回有关已更改的内容（或可能需要在 check_mode 中更改的内容）的详细信息。
safe_file_operations	支持：完全	使用 Ansible 的严格文件操作函数来确保正确的权限并避免数据损坏。

备注

注意

• 如果 ssh 密钥损坏或受密码保护，模块将失败。如果要重新生成密钥对，请将 force 选项设置为 true。

• 如果提供了自定义的 mode、group、owner 或其他文件属性，它将应用于两个密钥文件。

示例

- name: Generate an OpenSSH keypair with the default values (4096 bits, rsa)
  community.crypto.openssh_keypair:
    path: /tmp/id_ssh_rsa

- name: Generate an OpenSSH keypair with the default values (4096 bits, rsa) and encrypted private key
  community.crypto.openssh_keypair:
    path: /tmp/id_ssh_rsa
    passphrase: super_secret_password

- name: Generate an OpenSSH rsa keypair with a different size (2048 bits)
  community.crypto.openssh_keypair:
    path: /tmp/id_ssh_rsa
    size: 2048

- name: Force regenerate an OpenSSH keypair if it already exists
  community.crypto.openssh_keypair:
    path: /tmp/id_ssh_rsa
    force: true

- name: Generate an OpenSSH keypair with a different algorithm (dsa)
  community.crypto.openssh_keypair:
    path: /tmp/id_ssh_dsa
    type: dsa

返回值

通用返回值记录在这里，以下是此模块特有的字段

Key	描述
comment 字符串	生成的密钥的注释。 返回: changed 或 success 示例: "test@comment"
filename 字符串	生成的 SSH 私钥文件的路径。 返回: changed 或 success 示例: "/tmp/id_ssh_rsa"
fingerprint 字符串	密钥的指纹。 返回: changed 或 success 示例: "SHA256:r4YCZxihVjedH2OlfjVGI6Y5xAYtdCwk8VxKyzVyYfM"
public_key 字符串	生成的 SSH 私钥的公钥。 返回: changed 或 success 示例: "ssh-rsa AAAAB3Nza(...omitted...)veL4E3Xcw=="
size 整数	SSH 私钥的大小（以位为单位）。 返回: changed 或 success 示例: 4096
type 字符串	用于生成 SSH 私钥的算法。 返回: changed 或 success 示例: "rsa"

作者

• David Kainz (@lolcube)

集合链接

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