community.crypto.openssl_pkcs12 模块 – 生成 OpenSSL PKCS#12 存档

注意

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

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

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

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

概要

• 此模块允许用户（重新）生成 PKCS#12。

• 该模块可以使用 cryptography Python 库或 pyOpenSSL Python 库。默认情况下，它会尝试检测哪个库可用，假设没有使用 iter_size 和 maciter_size 选项。可以使用 select_crypto_backend 选项来覆盖此行为。

要求

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

• PyOpenSSL >= 0.15, < 23.3.0 或 cryptography >= 3.0

参数

参数	注释
action 字符串	export 或 parse 一个 PKCS#12。 选项 "export" ←（默认） "parse"
attributes 别名：attr 字符串	结果文件系统对象应具有的属性。 要获取支持的标志，请查看目标系统上的 chattr 的手册页。 此字符串应包含与 lsattr 显示顺序相同的属性。 默认情况下假定 = 运算符，否则 + 或 - 运算符需要包含在字符串中。
backup 布尔值	创建一个包含时间戳的备份文件，以便在您不小心使用新文件覆盖原始输出文件时可以恢复它。 选项 false ←（默认） true
certificate_path 路径	从中读取证书和私钥的路径。 必须采用 PEM 格式。
encryption_level 字符串 在 community.crypto 2.8.0 中添加	确定使用的加密级别。 auto 使用所选后端的默认值。对于 cryptography，这是 cryptography 库的特定版本认为可用的最佳加密方式。 compatibility2022 使用 2022 年较旧软件的兼容性设置。只有在 cryptography >= 38.0.0 可用时，cryptography 后端才支持此设置。 请注意，此选项**不用于幂等性**。 选项 "auto" ←（默认） "compatibility2022"
force 布尔值	即使文件已经存在，是否应重新生成该文件。 选项 false ←（默认） true
friendly_name 别名：name 字符串	指定证书和私钥的友好名称。
group 字符串	应该拥有文件系统对象的用户组的名称，就像传递给 chown 一样。 如果未指定，则使用当前用户的当前用户组，除非您是 root 用户，在这种情况下，它可以保留先前的所有权。
iter_size 整数	重复加密步骤的次数。 这**不会在幂等性检查期间考虑**。 这仅由 pyopenssl 后端使用，或者当 encryption_level=compatibility2022 时使用。 当使用它时，pyopenssl 的默认值为 2048，cryptography 的默认值为 50000。
maciter_size 整数	重复 MAC 步骤的次数。 这**不会在幂等性检查期间考虑**。 这仅由 pyopenssl 后端使用。当使用它时，默认值为 1。
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。
other_certificates 别名: ca_certificates list / elements=path	要包含的其他证书的列表。在 Ansible 2.8 之前，此参数称为 ca_certificates。 假设每个文件有一个 PEM 编码的证书。如果一个文件包含多个 PEM 证书，请将 other_certificates_parse_all 设置为 true。
other_certificates_parse_all 布尔值 在 community.crypto 1.4.0 中添加	如果设置为 true，则假设 other_certificates 中提到的文件可以包含每个文件多个证书（甚至每个文件都不包含）。 选项 false ←（默认） true
owner 字符串	应该拥有文件系统对象的用户的名称，就像提供给 *chown* 一样。 如果未指定，它将使用当前用户，除非您是 root 用户，在这种情况下，它可以保留以前的所有权。 指定数字用户名将被假定为用户 ID，而不是用户名。避免使用数字用户名以避免这种混淆。
passphrase 字符串	PKCS#12 密码。 注意： PKCS12 加密是不安全的，不应将其用作安全机制。 如果您需要安全地存储或发送 PKCS12 文件，则还应使用其他方式对其进行加密。
路径 path / required	要将 PKCS#12 文件写入到的文件名。
privatekey_content 字符串 在 community.crypto 2.3.0 中添加	私钥文件的内容。 与 privatekey_path 互斥。
privatekey_passphrase 字符串	用于解密任何输入私钥的密码源。
privatekey_path 路径	从中读取私钥的文件。 与 privatekey_content 互斥。
return_content 布尔值 在 community.crypto 1.0.0 中添加	如果设置为 true，则会将（当前或生成的）PKCS#12 的内容作为 pkcs12 返回。 选项 false ←（默认） true
select_crypto_backend 字符串 在 community.crypto 1.7.0 中添加	确定要使用的加密后端。 默认选择是 auto，它会尝试使用 cryptography（如果可用），并回退到 pyopenssl。如果 iter_size 与 encryption_level 一起使用，且不是 compatibility2022，或者如果使用 maciter_size，则 auto 将始终导致选择 pyopenssl，以实现向后兼容。 如果设置为 pyopenssl，则将尝试使用 pyOpenSSL 库。 如果设置为 cryptography，则将尝试使用 cryptography 库。 选项 "auto" ←（默认） "cryptography" "pyopenssl"
selevel 字符串	SELinux 文件系统对象上下文的级别部分。 这是 MLS/MCS 属性，有时称为 range。 当设置为 _default 时，如果可用，它将使用策略的 level 部分。
serole 字符串	SELinux 文件系统对象上下文的角色部分。 当设置为 _default 时，如果可用，它将使用策略的 role 部分。
setype 字符串	SELinux 文件系统对象上下文的类型部分。 当设置为 _default 时，如果可用，它将使用策略的 type 部分。
seuser 字符串	SELinux 文件系统对象上下文的用户部分。 默认情况下，它使用 system 策略（如果适用）。 当设置为 _default 时，如果可用，它将使用策略的 user 部分。
src 路径	要解析的 PKCS#12 文件路径。
state 字符串	文件是否应该存在。 当 state 为 absent 时，将忽略除 path 之外的所有参数。 选项 "absent" "present" ← (默认)
unsafe_writes 布尔值	影响何时使用原子操作以防止数据损坏或从目标文件系统对象读取不一致的数据。 默认情况下，此模块使用原子操作来防止数据损坏或从目标文件系统对象读取不一致的数据，但有时系统的配置或损坏方式会阻止这种情况。一个例子是 docker 挂载的文件系统对象，它不能从容器内部以原子方式更新，并且只能以不安全的方式写入。 此选项允许 Ansible 在原子操作失败时回退到更新文件系统对象的不安全方法（但是，它不会强制 Ansible 执行不安全的写入）。 重要！不安全的写入会受到竞争条件的影响，并可能导致数据损坏。 选项 false ←（默认） true

属性

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

另请参阅

另请参阅

community.crypto.x509_certificate

生成和/或检查 OpenSSL 证书。

community.crypto.openssl_csr

生成 OpenSSL 证书签名请求 (CSR)。

community.crypto.openssl_dhparam

生成 OpenSSL Diffie-Hellman 参数。

community.crypto.openssl_privatekey

生成 OpenSSL 私钥。

community.crypto.openssl_publickey

从私钥生成 OpenSSL 公钥。

示例

- name: Generate PKCS#12 file
  community.crypto.openssl_pkcs12:
    action: export
    path: /opt/certs/ansible.p12
    friendly_name: raclette
    privatekey_path: /opt/certs/keys/key.pem
    certificate_path: /opt/certs/cert.pem
    other_certificates: /opt/certs/ca.pem
    # Note that if /opt/certs/ca.pem contains multiple certificates,
    # only the first one will be used. See the other_certificates_parse_all
    # option for changing this behavior.
    state: present

- name: Generate PKCS#12 file
  community.crypto.openssl_pkcs12:
    action: export
    path: /opt/certs/ansible.p12
    friendly_name: raclette
    privatekey_content: '{{ private_key_contents }}'
    certificate_path: /opt/certs/cert.pem
    other_certificates_parse_all: true
    other_certificates:
      - /opt/certs/ca_bundle.pem
        # Since we set other_certificates_parse_all to true, all
        # certificates in the CA bundle are included and not just
        # the first one.
      - /opt/certs/intermediate.pem
        # In case this file has multiple certificates in it,
        # all will be included as well.
    state: present

- name: Change PKCS#12 file permission
  community.crypto.openssl_pkcs12:
    action: export
    path: /opt/certs/ansible.p12
    friendly_name: raclette
    privatekey_path: /opt/certs/keys/key.pem
    certificate_path: /opt/certs/cert.pem
    other_certificates: /opt/certs/ca.pem
    state: present
    mode: '0600'

- name: Regen PKCS#12 file
  community.crypto.openssl_pkcs12:
    action: export
    src: /opt/certs/ansible.p12
    path: /opt/certs/ansible.p12
    friendly_name: raclette
    privatekey_path: /opt/certs/keys/key.pem
    certificate_path: /opt/certs/cert.pem
    other_certificates: /opt/certs/ca.pem
    state: present
    mode: '0600'
    force: true

- name: Dump/Parse PKCS#12 file
  community.crypto.openssl_pkcs12:
    action: parse
    src: /opt/certs/ansible.p12
    path: /opt/certs/ansible.pem
    state: present

- name: Remove PKCS#12 file
  community.crypto.openssl_pkcs12:
    path: /opt/certs/ansible.p12
    state: absent

返回值

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

键	描述
backup_file 字符串	创建的备份文件的名称。 返回: 如果 backup 为 true，则已更改 示例: "/path/to/ansible.com.pem.2019-03-09@11:22~"
filename 字符串	生成的 PKCS#12 文件的路径。 返回: 已更改或成功 示例: "/opt/certs/ansible.p12"
pkcs12 字符串 在 community.crypto 1.0.0 中添加	（当前或生成的）PKCS#12 的内容，Base64 编码。 返回: 如果 state 为 present 且 return_content 为 true
privatekey 字符串	从中生成公钥的 TLS/SSL 私钥的路径。 返回: 已更改或成功 示例: "/etc/ssl/private/ansible.com.pem"

作者

• Guillaume Delpierre (@gdelpierre)

集合链接

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