community.crypto.openssl_privatekey 模块 – 生成 OpenSSL 私钥

注意

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

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

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

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

概要 

密钥以 PEM 格式生成。
可以生成 RSA、DSA、ECC 或 EdDSA 私钥。
请注意，如果私钥与模块的选项不匹配，则模块会重新生成私钥。特别是，如果您提供另一个密码（或指定无密码），更改密钥大小等，则私钥将被重新生成。如果您担心这可能会 **覆盖您的私钥**，请考虑使用 backup 选项。
如果未显式设置 mode，则私钥文件的默认模式将为 0600。
此模块允许（重新）生成 OpenSSL 私钥。

要求 

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

cryptography >= 1.2.3 （较旧的版本也可能有效）

参数 

参数	注释
attributes 别名：attr 字符串	生成的filesystem对象应具有的属性。要获取支持的标志，请查看目标系统上 chattr 的手册页。此字符串应按 lsattr 显示的相同顺序包含属性。 `=` 运算符默认为假定，否则需要在字符串中包含 `+` 或 `-` 运算符。
backup 布尔值	创建一个包含时间戳的备份文件，以便您可以意外地用新文件覆盖原始私钥后找回它。选项 `false` ← (默认) `true`
cipher 字符串	用于加密私钥的密码。仅当提供 `passphrase` 时才使用。必须为 `auto`。默认值： `"auto"`
curve 字符串	请注意，并非所有曲线都受所有版本的 `cryptography` 支持。为了最大限度地提高互操作性，应使用 `secp384r1` 或 `secp256r1`。我们使用在 IANA TLS 注册表中定义的曲线名称。请注意，除了 `secp224r1`、`secp256k1`、`secp256r1`、`secp384r1` 和 `secp521r1` 之外的所有曲线都不建议用于新的私钥。选项 `"secp224r1"` `"secp256k1"` `"secp256r1"` `"secp384r1"` `"secp521r1"` `"secp192r1"` `"brainpoolP256r1"` `"brainpoolP384r1"` `"brainpoolP512r1"` `"sect163k1"` `"sect163r2"` `"sect233k1"` `"sect233r1"` `"sect283k1"` `"sect283r1"` `"sect409k1"` `"sect409r1"` `"sect571k1"` `"sect571r1"`
force 布尔值	即使密钥已存在，是否也应重新生成密钥。选项 `false` ← (默认) `true`
格式字符串社区crypto 1.0.0版本中添加	确定私钥的写入格式。默认情况下，所有支持的密钥都使用PKCS1（传统的OpenSSL格式）。请注意，并非所有密钥都可以在任何格式下导出。值`auto`根据密钥格式选择格式。值`auto_ignore`执行相同的操作，但对于现有的私钥文件，如果其格式不是自动选择的生成格式，则不会强制重新生成。请注意，如果现有私钥的格式不匹配，则默认情况下会重新生成密钥。要更改此行为，请使用`format_mismatch`选项。选项 `"pkcs1"` `"pkcs8"` `"raw"` `"auto"` `"auto_ignore"` ← (默认)
format_mismatch 字符串社区crypto 1.0.0版本中添加	确定如果私钥的格式与预期格式不匹配，但所有其他参数都符合预期时，模块的行为。如果设置为`regenerate`（默认），则会生成一个新的私钥。如果设置为`convert`，则密钥将转换为新的格式。仅受`cryptography`后端支持。选项 `"regenerate"` ← (默认) `"convert"`
组字符串	应拥有文件系统对象的组的名称，如同提供给chown一样。如果未指定，则使用当前用户的当前组，除非您是root用户，在这种情况下，它可以保留之前的拥有权。
模式任意	生成的最终文件系统对象应具有的权限。对于习惯使用/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。
所有者字符串	应拥有文件系统对象的用户的名称，如同提供给chown一样。如果未指定，则使用当前用户，除非您是root用户，在这种情况下，它可以保留之前的拥有权。指定数字用户名将被认为是用户ID而不是用户名。避免使用数字用户名以避免此混淆。
密码字符串	私钥的密码。
路径路径 / 必需	将生成的TLS/SSL私钥写入的文件名。如果未显式设置`mode`，则其模式为`0600`。
重新生成字符串社区crypto 1.0.0版本中添加	允许配置模块在哪些情况下可以重新生成私钥。如果目标文件不存在，模块将始终生成一个新密钥。默认情况下，当密钥与模块的选项不匹配时，密钥将被重新生成，除非密钥无法读取或密码不匹配。请注意，这在Ansible 2.10中已更改。对于Ansible 2.9，行为如同指定了`full_idempotence`。如果设置为`never`，则如果密钥无法读取或密码不匹配，模块将失败，并且永远不会重新生成现有密钥。如果设置为`fail`，则如果密钥与模块的选项不对应，模块将失败。如果设置为`partial_idempotence`，如果密钥不符合模块的选项，则将重新生成密钥。如果密钥无法读取（损坏的文件）、密钥受未知密码保护，或者密钥未受密码保护但指定了密码，则不会重新生成密钥。如果设置为`full_idempotence`，如果密钥不符合模块的选项，则将重新生成密钥。如果密钥无法读取（损坏的文件）、密钥受未知密码保护，或者密钥未受密码保护但指定了密码，情况也是如此。使用此选项时，请确保您有备份！如果设置为`always`，模块将始终重新生成密钥。这等效于将`force`设置为`true`。请注意，如果`format_mismatch`设置为`convert`并且除了格式之外的所有内容都匹配，则始终会转换密钥，除非`regenerate`设置为`always`。选项 `"never"` `"fail"` `"partial_idempotence"` `"full_idempotence"` ← (默认) `"always"`
返回内容布尔值社区crypto 1.0.0版本中添加	如果设置为`true`，将返回（当前或生成的）私钥的内容作为`privatekey`。请注意，特别是如果私钥未加密，您必须确保返回值得到适当处理，并且不会意外写入日志等！谨慎使用！使用Ansible的`no_log`任务选项来避免显示输出。另请参阅https://docs.ansible.org.cn/ansible/latest/reference_appendices/faq.html#how-do-i-keep-secret-data-in-my-playbook。选项 `false` ← (默认) `true`
选择加密后端字符串	确定要使用的加密后端。默认选择是`auto`，如果可用，它会尝试使用`cryptography`。如果设置为`cryptography`，将尝试使用cryptography库。选项 `"auto"` ← (默认) `"cryptography"`
安全级别字符串	SELinux文件系统对象上下文的级别部分。这是MLS/MCS属性，有时称为`range`。如果设置为`_default`，则将使用策略中可用的`level`部分。
安全角色字符串	SELinux文件系统对象上下文的role部分。如果设置为`_default`，则将使用策略中可用的`role`部分。
安全类型字符串	SELinux 文件系统对象上下文中的类型部分。设置为 `_default` 时，如果可用，它将使用策略的 `type` 部分。
seuser 字符串	SELinux 文件系统对象上下文中的用户部分。默认情况下，它使用 `system` 策略（如果适用）。设置为 `_default` 时，如果可用，它将使用策略的 `user` 部分。
size 整数	要生成的 TLS/SSL 密钥的大小（以位为单位）。默认值： `4096`
state 字符串	私钥是否应该存在，如果状态与声明的不同则采取行动。选项 `"absent"` `"present"` ← (默认)
type 字符串	用于生成 TLS/SSL 私钥的算法。请注意，`ECC`、`X25519`、`X448`、`Ed25519` 和 `Ed448` 需要 `cryptography` 后端。`X25519` 需要 cryptography 2.5 或更高版本，而 `X448`、`Ed25519` 和 `Ed448` 需要 cryptography 2.6 或更高版本。对于 `ECC`，所需的最小 cryptography 版本取决于 `curve` 选项。选项 `"DSA"` `"ECC"` `"Ed25519"` `"Ed448"` `"RSA"` ← (默认) `"X25519"` `"X448"`
unsafe_writes 布尔值	影响何时使用原子操作来防止目标文件系统对象的数据损坏或不一致读取。默认情况下，此模块使用原子操作来防止目标文件系统对象的数据损坏或不一致读取，但有时系统配置错误或损坏，从而阻止此操作。一个例子是 docker 挂载的文件系统对象，无法在容器内部以原子方式更新，只能以不安全的方式写入。此选项允许 Ansible 在原子操作失败时回退到不安全的文件系统对象更新方法（但是，它不会强制 Ansible 执行不安全写入）。重要！不安全写入容易出现竞争条件，并可能导致数据损坏。选项 `false` ← (默认) `true`

属性 

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

另请参阅 

另请参阅

community.crypto.openssl_privatekey_pipe: 无需磁盘访问即可生成 OpenSSL 私钥。
community.crypto.openssl_privatekey_info: 提供 OpenSSL 私钥的信息。
community.crypto.x509_certificate: 生成和/或检查 OpenSSL 证书。
community.crypto.x509_certificate_pipe: 生成和/或检查 OpenSSL 证书。
community.crypto.openssl_csr: 生成 OpenSSL 证书签名请求 (CSR)。
community.crypto.openssl_csr_pipe: 生成 OpenSSL 证书签名请求 (CSR)。
community.crypto.openssl_dhparam: 生成 OpenSSL Diffie-Hellman 参数。
community.crypto.openssl_pkcs12: 生成 OpenSSL PKCS#12 归档文件。
community.crypto.openssl_publickey: 根据其私钥生成 OpenSSL 公钥。

示例 

- name: Generate an OpenSSL private key with the default values (4096 bits, RSA)
  community.crypto.openssl_privatekey:
    path: /etc/ssl/private/ansible.com.pem

- name: Generate an OpenSSL private key with the default values (4096 bits, RSA) and a passphrase
  community.crypto.openssl_privatekey:
    path: /etc/ssl/private/ansible.com.pem
    passphrase: ansible
    cipher: auto

- name: Generate an OpenSSL private key with a different size (2048 bits)
  community.crypto.openssl_privatekey:
    path: /etc/ssl/private/ansible.com.pem
    size: 2048

- name: Force regenerate an OpenSSL private key if it already exists
  community.crypto.openssl_privatekey:
    path: /etc/ssl/private/ansible.com.pem
    force: true

- name: Generate an OpenSSL private key with a different algorithm (DSA)
  community.crypto.openssl_privatekey:
    path: /etc/ssl/private/ansible.com.pem
    type: DSA

- name: Generate an OpenSSL private key with elliptic curve cryptography (ECC)
  community.crypto.openssl_privatekey:
    path: /etc/ssl/private/ansible.com.pem
    type: ECC
    curve: secp256r1

返回值 

常见的返回值已记录在此处，以下是此模块独有的字段

键	描述
backup_file 字符串	创建的备份文件的名称。返回：已更改，如果 `backup` 为 `true` 示例： `"/path/to/privatekey.pem.2019-03-09@11:22~"`
curve 字符串	用于生成 TLS/SSL 私钥的椭圆曲线。返回：已更改或成功，并且 `type` 为 `ECC` 示例： `"secp256r1"`
filename 字符串	生成的 TLS/SSL 私钥文件的路径。返回：已更改或成功示例： `"/etc/ssl/private/ansible.com.pem"`
fingerprint 字典	公钥的指纹。将为每个可用的 `hashlib.algorithms` 生成指纹。返回：已更改或成功示例： {"md5": "84:75:71:72:8d:04:b5:6c:4d:37:6d:66:83:f5:4c:29", "sha1": "51:cc:7c:68:5d:eb:41:43:88:7e:1a:ae:c7:f8:24:72:ee:71:f6:10", "sha224": "b1:19:a6:6c:14:ac:33:1d:ed:18:50:d3:06:5c:b2:32:91:f1:f1:52:8c:cb:d5:75:e9:f5:9b:46", "sha256": "41:ab:c7:cb:d5:5f:30:60:46:99:ac:d4:00:70:cf:a1:76:4f:24:5d:10:24:57:5d:51:6e:09:97:df:2f:de:c7", "sha384": "85:39:50:4e:de:d9:19:33:40:70:ae:10:ab:59:24:19:51:c3:a2:e4:0b:1c:b1:6e:dd:b3:0c:d9:9e:6a:46:af:da:18:f8:ef:ae:2e:c0:9a:75:2c:9b:b3:0f:3a:5f:3d", "sha512": "fd:ed:5e:39:48:5f:9f:fe:7f:25:06:3f:79:08:cd:ee:a5:e7:b3:3d:13:82:87:1f:84:e1:f5:c7:28:77:53:94:86:56:38:69:f0:d9:35:22:01:1e:a6:60:...:0f:9b"}
privatekey 字符串社区crypto 1.0.0版本中添加	（当前或生成的）私钥的内容。如果密钥为原始格式，则将进行 Base64 编码。返回：如果 `state` 为 `present` 并且 `return_content` 为 `true`
size 整数	TLS/SSL 私钥的大小（以位为单位）。返回：已更改或成功示例： `4096`
type 字符串	用于生成 TLS/SSL 私钥的算法。返回：已更改或成功示例： `"RSA"`

作者

Yanis Guenane (@Spredzy)
Felix Fontein (@felixfontein)

参数	注释
attributes 别名：attr 字符串	生成的filesystem对象应具有的属性。要获取支持的标志，请查看目标系统上 chattr 的手册页。此字符串应按 lsattr 显示的相同顺序包含属性。 `=` 运算符默认为假定，否则需要在字符串中包含 `+` 或 `-` 运算符。
backup 布尔值	创建一个包含时间戳的备份文件，以便您可以意外地用新文件覆盖原始私钥后找回它。选项 `false` ← (默认) `true`
cipher 字符串	用于加密私钥的密码。仅当提供 `passphrase` 时才使用。必须为 `auto`。默认值： `"auto"`
curve 字符串	请注意，并非所有曲线都受所有版本的 `cryptography` 支持。为了最大限度地提高互操作性，应使用 `secp384r1` 或 `secp256r1`。我们使用在 IANA TLS 注册表中定义的曲线名称。请注意，除了 `secp224r1`、`secp256k1`、`secp256r1`、`secp384r1` 和 `secp521r1` 之外的所有曲线都不建议用于新的私钥。选项 `"secp224r1"` `"secp256k1"` `"secp256r1"` `"secp384r1"` `"secp521r1"` `"secp192r1"` `"brainpoolP256r1"` `"brainpoolP384r1"` `"brainpoolP512r1"` `"sect163k1"` `"sect163r2"` `"sect233k1"` `"sect233r1"` `"sect283k1"` `"sect283r1"` `"sect409k1"` `"sect409r1"` `"sect571k1"` `"sect571r1"`
force 布尔值	即使密钥已存在，是否也应重新生成密钥。选项 `false` ← (默认) `true`
格式字符串社区crypto 1.0.0版本中添加	确定私钥的写入格式。默认情况下，所有支持的密钥都使用PKCS1（传统的OpenSSL格式）。请注意，并非所有密钥都可以在任何格式下导出。值`auto`根据密钥格式选择格式。值`auto_ignore`执行相同的操作，但对于现有的私钥文件，如果其格式不是自动选择的生成格式，则不会强制重新生成。请注意，如果现有私钥的格式不匹配，则默认情况下会重新生成密钥。要更改此行为，请使用`format_mismatch`选项。选项 `"pkcs1"` `"pkcs8"` `"raw"` `"auto"` `"auto_ignore"` ← (默认)
format_mismatch 字符串社区crypto 1.0.0版本中添加	确定如果私钥的格式与预期格式不匹配，但所有其他参数都符合预期时，模块的行为。如果设置为`regenerate`（默认），则会生成一个新的私钥。如果设置为`convert`，则密钥将转换为新的格式。仅受`cryptography`后端支持。选项 `"regenerate"` ← (默认) `"convert"`
组字符串	应拥有文件系统对象的组的名称，如同提供给chown一样。如果未指定，则使用当前用户的当前组，除非您是root用户，在这种情况下，它可以保留之前的拥有权。
模式任意	生成的最终文件系统对象应具有的权限。对于习惯使用/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。
所有者字符串	应拥有文件系统对象的用户的名称，如同提供给chown一样。如果未指定，则使用当前用户，除非您是root用户，在这种情况下，它可以保留之前的拥有权。指定数字用户名将被认为是用户ID而不是用户名。避免使用数字用户名以避免此混淆。
密码字符串	私钥的密码。
路径路径 / 必需	将生成的TLS/SSL私钥写入的文件名。如果未显式设置`mode`，则其模式为`0600`。
重新生成字符串社区crypto 1.0.0版本中添加	允许配置模块在哪些情况下可以重新生成私钥。如果目标文件不存在，模块将始终生成一个新密钥。默认情况下，当密钥与模块的选项不匹配时，密钥将被重新生成，除非密钥无法读取或密码不匹配。请注意，这在Ansible 2.10中已更改。对于Ansible 2.9，行为如同指定了`full_idempotence`。如果设置为`never`，则如果密钥无法读取或密码不匹配，模块将失败，并且永远不会重新生成现有密钥。如果设置为`fail`，则如果密钥与模块的选项不对应，模块将失败。如果设置为`partial_idempotence`，如果密钥不符合模块的选项，则将重新生成密钥。如果密钥无法读取（损坏的文件）、密钥受未知密码保护，或者密钥未受密码保护但指定了密码，则不会重新生成密钥。如果设置为`full_idempotence`，如果密钥不符合模块的选项，则将重新生成密钥。如果密钥无法读取（损坏的文件）、密钥受未知密码保护，或者密钥未受密码保护但指定了密码，情况也是如此。使用此选项时，请确保您有备份！如果设置为`always`，模块将始终重新生成密钥。这等效于将`force`设置为`true`。请注意，如果`format_mismatch`设置为`convert`并且除了格式之外的所有内容都匹配，则始终会转换密钥，除非`regenerate`设置为`always`。选项 `"never"` `"fail"` `"partial_idempotence"` `"full_idempotence"` ← (默认) `"always"`
返回内容布尔值社区crypto 1.0.0版本中添加	如果设置为`true`，将返回（当前或生成的）私钥的内容作为`privatekey`。请注意，特别是如果私钥未加密，您必须确保返回值得到适当处理，并且不会意外写入日志等！谨慎使用！使用Ansible的`no_log`任务选项来避免显示输出。另请参阅https://docs.ansible.org.cn/ansible/latest/reference_appendices/faq.html#how-do-i-keep-secret-data-in-my-playbook。选项 `false` ← (默认) `true`
选择加密后端字符串	确定要使用的加密后端。默认选择是`auto`，如果可用，它会尝试使用`cryptography`。如果设置为`cryptography`，将尝试使用cryptography库。选项 `"auto"` ← (默认) `"cryptography"`
安全级别字符串	SELinux文件系统对象上下文的级别部分。这是MLS/MCS属性，有时称为`range`。如果设置为`_default`，则将使用策略中可用的`level`部分。
安全角色字符串	SELinux文件系统对象上下文的role部分。如果设置为`_default`，则将使用策略中可用的`role`部分。
安全类型字符串	SELinux 文件系统对象上下文中的类型部分。设置为 `_default` 时，如果可用，它将使用策略的 `type` 部分。
seuser 字符串	SELinux 文件系统对象上下文中的用户部分。默认情况下，它使用 `system` 策略（如果适用）。设置为 `_default` 时，如果可用，它将使用策略的 `user` 部分。
size 整数	要生成的 TLS/SSL 密钥的大小（以位为单位）。默认值： `4096`
state 字符串	私钥是否应该存在，如果状态与声明的不同则采取行动。选项 `"absent"` `"present"` ← (默认)
type 字符串	用于生成 TLS/SSL 私钥的算法。请注意，`ECC`、`X25519`、`X448`、`Ed25519` 和 `Ed448` 需要 `cryptography` 后端。`X25519` 需要 cryptography 2.5 或更高版本，而 `X448`、`Ed25519` 和 `Ed448` 需要 cryptography 2.6 或更高版本。对于 `ECC`，所需的最小 cryptography 版本取决于 `curve` 选项。选项 `"DSA"` `"ECC"` `"Ed25519"` `"Ed448"` `"RSA"` ← (默认) `"X25519"` `"X448"`
unsafe_writes 布尔值	影响何时使用原子操作来防止目标文件系统对象的数据损坏或不一致读取。默认情况下，此模块使用原子操作来防止目标文件系统对象的数据损坏或不一致读取，但有时系统配置错误或损坏，从而阻止此操作。一个例子是 docker 挂载的文件系统对象，无法在容器内部以原子方式更新，只能以不安全的方式写入。此选项允许 Ansible 在原子操作失败时回退到不安全的文件系统对象更新方法（但是，它不会强制 Ansible 执行不安全写入）。重要！不安全写入容易出现竞争条件，并可能导致数据损坏。选项 `false` ← (默认) `true`