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 私钥。

要求

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

参数

参数

注释

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

path / required

包含公钥和私钥的文件的名称。包含公钥的文件将具有扩展名 .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

integer

指定要创建的私钥中的位数。对于 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

返回值

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

密钥

描述

comment

字符串

生成的密钥的注释。

返回： changed 或 success

示例： "test@comment"

文件名

字符串

生成的 SSH 私钥文件的路径。

返回： changed 或 success

示例： "/tmp/id_ssh_rsa"

指纹

字符串

密钥的指纹。

返回： changed 或 success

示例： "SHA256:r4YCZxihVjedH2OlfjVGI6Y5xAYtdCwk8VxKyzVyYfM"

public_key

字符串

生成的 SSH 私钥的公钥。

返回： changed 或 success

示例： "ssh-rsa AAAAB3Nza(...省略...)veL4E3Xcw=="

size

integer

SSH 私钥的大小（以位为单位）。

返回： changed 或 success

示例： 4096

type

字符串

用于生成 SSH 私钥的算法。

返回： changed 或 success

示例： "rsa"

作者

  • David Kainz (@lolcube)