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 文件系统对象上下文的 level 部分。 这是 MLS/MCS 属性，有时称为 range。 如果设置为 _default，它将使用策略的 level 部分（如果可用）。
serole 字符串	SELinux 文件系统对象上下文的 role 部分。 如果设置为 _default，它将使用策略的 role 部分（如果可用）。
setype 字符串	SELinux 文件系统对象上下文的 type 部分。 如果设置为 _default，它将使用策略的 type 部分（如果可用）。
seuser 字符串	SELinux 文件系统对象上下文的 user 部分。 默认情况下，它使用 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，则返回 changed。 示例: "/path/to/ansible.com.pem.2019-03-09@11:22~"
filename 字符串	生成 PKCS#12 文件的路径。 返回值: changed 或 success 示例: "/opt/certs/ansible.p12"
pkcs12 字符串 在 community.crypto 1.0.0 中添加	（当前或生成的）PKCS#12 的内容，以 Base64 编码。 返回值: 如果 state 为 present 并且 return_content 为 true，则返回该值。
privatekey 字符串	从中生成公钥的 TLS/SSL 私钥的路径。 返回值: changed 或 success 示例: "/etc/ssl/private/ansible.com.pem"

作者

• Guillaume Delpierre (@gdelpierre)

集合链接

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