community.crypto.x509_certificate_pipe 模块 – 生成和/或检查 OpenSSL 证书

注意

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

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

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

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

community.crypto 1.3.0 中的新功能

概要

• 它为您的证书实现了一种提供程序概念（selfsigned、ownca、entrust 之一）。

• 它使用 cryptography Python 库与 OpenSSL 交互。

• ownca 提供程序用于生成使用您自己的 CA（证书颁发机构）证书（自签名证书）签名的 OpenSSL 证书。

• 此模块允许重新生成 OpenSSL 证书。

要求

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

• cryptography >= 1.6（如果使用 selfsigned 或 ownca 提供程序）

参数

参数	注释
content 字符串	现有证书。
csr_content 字符串	用于生成此证书的证书签名请求 (CSR) 的内容。 它与 csr_path 互斥。
csr_path 路径	用于生成此证书的证书签名请求 (CSR) 的路径。 它与 csr_content 互斥。
entrust_api_client_cert_key_path 路径	用于向 Entrust Certificate Services (ECS) API 进行身份验证的客户端证书私钥的路径。 这仅供 entrust 提供程序使用。 如果提供程序为 entrust，则这是必需的。
entrust_api_client_cert_path 路径	用于向 Entrust Certificate Services (ECS) API 进行身份验证的客户端证书的路径。 这仅供 entrust 提供程序使用。 如果提供程序为 entrust，则这是必需的。
entrust_api_key 字符串	用于向 Entrust Certificate Services (ECS) API 进行身份验证的密钥（密码）。 这仅供 entrust 提供程序使用。 如果提供程序为 entrust，则这是必需的。
entrust_api_specification_path 路径	定义 Entrust Certificate Services (ECS) API 配置的规范文件的路径。 您可以使用此选项来保留规范的本地副本，以避免每次使用该模块时都下载它。 这仅供 entrust 提供程序使用。 默认值： "https://cloud.entrust.net/EntrustCloud/documentation/cms-api-2.1.0.yaml"
entrust_api_user 字符串	用于向 Entrust Certificate Services (ECS) API 进行身份验证的用户名。 这仅供 entrust 提供程序使用。 如果提供程序为 entrust，则这是必需的。
entrust_cert_type 字符串	指定请求的证书类型。 这仅供 entrust 提供程序使用。 选项 "STANDARD_SSL" ← (默认) "ADVANTAGE_SSL" "UC_SSL" "EV_SSL" "WILDCARD_SSL" "PRIVATE_SSL" "PD_SSL" "CDS_ENT_LITE" "CDS_ENT_PRO" "SMIME_ENT"
entrust_not_after 字符串	证书停止有效的时间点。 时间可以指定为相对时间或绝对时间戳。 有效的绝对时间格式是 ASN.1 TIME，例如 2019-06-18。 有效的相对时间格式是 [+-]timespec，其中 timespec 可以是整数 + [w | d | h | m | s]，例如 +365d 或 +32w1d2h)。 时间将始终解释为 UTC。 请注意，仅支持日期（日、月、年）来指定颁发证书的到期日期。 完整的日期时间在颁发之前会调整为 EST (GMT -5:00)，如果使用相对时间，这可能会导致证书的到期日期比预期的提前一天。 证书的最短有效期为 90 天，最长有效期为三年。 如果未指定此值，则证书将在颁发日期后 365 天失效。 这仅供 entrust 提供程序使用。 请注意，此值不包含在 ignore_timestamps 选项中。 默认值： "+365d"
entrust_requester_email 字符串	证书请求者的电子邮件（用于跟踪目的）。 这仅供 entrust 提供程序使用。 如果提供程序为 entrust，则这是必需的。
entrust_requester_name 字符串	证书请求者的姓名（用于跟踪目的）。 这仅供 entrust 提供程序使用。 如果提供程序为 entrust，则这是必需的。
entrust_requester_phone 字符串	证书请求者的电话号码（用于跟踪目的）。 这仅供 entrust 提供程序使用。 如果提供程序为 entrust，则这是必需的。
强制 布尔值	生成证书，即使它已存在。 选项 false ←（默认） true
ignore_timestamps 布尔值 在 community.crypto 2.0.0 中添加	是否应忽略“生效日期”和“失效日期”时间戳以进行幂等性检查。 当使用相对时间戳（例如 +0s 表示现在）时，最好保持默认值 true。 选项 false true ←（默认）
ownca_content 字符串	CA（证书颁发机构）证书的内容。 这仅供 ownca 提供程序使用。 这与 ownca_path 互斥。
ownca_create_authority_key_identifier 布尔值	从 CA 的证书创建一个授权密钥标识符。如果 CSR 提供了授权密钥标识符，则将其忽略。 授权密钥标识符从 CA 证书的主题密钥标识符（如果可用）生成。如果不可用，将使用 CA 证书的公钥。 这仅供 ownca 提供程序使用。 请注意，仅当使用 cryptography 后端时才支持此功能！ 选项 false true ←（默认）
ownca_create_subject_key_identifier 字符串	是否从公钥创建主题密钥标识符（SKI）。 create_if_not_provided（默认）的值仅在 CSR 未提供 SKI 时创建 SKI。 always_create 的值始终创建 SKI。如果 CSR 提供了 SKI，则该 SKI 将被忽略。 never_create 的值从不创建 SKI。如果 CSR 提供了 SKI，则使用该 SKI。 这仅供 ownca 提供程序使用。 请注意，仅当使用 cryptography 后端时才支持此功能！ 选项 "create_if_not_provided" ←（默认） "always_create" "never_create"
ownca_digest 字符串	用于 ownca 证书的摘要算法。 这仅供 ownca 提供程序使用。 默认值： "sha256"
ownca_not_after 字符串	证书停止有效的时间点。 时间可以指定为相对时间或绝对时间戳。 时间将始终解释为 UTC。 有效格式为 [+-]timespec | ASN.1 TIME，其中 timespec 可以是整数 + [w | d | h | m | s]（例如 +32w1d2h）。 如果未指定此值，则证书将在 10 年后失效。 请注意，此值不用于确定是否应重新生成现有证书。可以通过将 ignore_timestamps 选项设置为 false 来更改此行为。请注意，当设置 ignore_timestamps=false 时，应避免使用相对时间戳。 这仅供 ownca 提供程序使用。 在 macOS 10.15 及更高版本中，TLS 服务器证书的有效期必须为 825 天或更短。有关更多详细信息，请参见 https://support.apple.com/en-us/HT210176。 默认值： "+3650d"
ownca_not_before 字符串	证书生效的时间点。 时间可以指定为相对时间或绝对时间戳。 时间将始终解释为 UTC。 有效格式为 [+-]timespec | ASN.1 TIME，其中 timespec 可以是整数 + [w | d | h | m | s]（例如 +32w1d2h）。 如果未指定此值，则证书将从现在开始生效。 请注意，此值不用于确定是否应重新生成现有证书。可以通过将 ignore_timestamps 选项设置为 false 来更改此行为。请注意，当设置 ignore_timestamps=false 时，应避免使用相对时间戳。 这仅供 ownca 提供程序使用。 默认值： "+0s"
ownca_path 路径	CA（证书颁发机构）证书的远程绝对路径。 这仅供 ownca 提供程序使用。 这与 ownca_content 互斥。
ownca_privatekey_content 字符串	用于签署证书的 CA（证书颁发机构）私钥的内容。 这仅供 ownca 提供程序使用。 这与 ownca_privatekey_path 互斥。
ownca_privatekey_passphrase 字符串	ownca_privatekey_path 或 ownca_privatekey_content 的密码。 这仅供 ownca 提供程序使用。
ownca_privatekey_path 路径	用于签署证书的 CA（证书颁发机构）私钥的路径。 这仅供 ownca 提供程序使用。 这与 ownca_privatekey_content 互斥。
ownca_version 整数	ownca 证书的版本。 如今，它几乎总是 3。 这仅供 ownca 提供程序使用。 默认值： 3
privatekey_content 字符串	用于签署证书的私钥的内容。 这与 privatekey_path 互斥。
privatekey_passphrase 字符串	privatekey_path 或 privatekey_content 的密码。 如果私钥受密码保护，则这是必需的。
privatekey_path 路径	用于签署证书的私钥的路径。 这与 privatekey_content 互斥。
provider 字符串 / 必需	用于生成/检索 OpenSSL 证书的提供程序的名称。 entrust 提供程序需要 Entrust Certificate Services (ECS) API 的凭据。 选项 "entrust" "ownca" "selfsigned"
select_crypto_backend 字符串	确定要使用的加密后端。 默认选择是 auto，它会尝试使用 cryptography（如果可用）。 如果设置为 cryptography，将尝试使用 cryptography 库。 选项 "auto" ←（默认） "cryptography"
selfsigned_create_subject_key_identifier 字符串	是否从公钥创建主题密钥标识符（SKI）。 create_if_not_provided（默认）的值仅在 CSR 未提供 SKI 时创建 SKI。 always_create 的值始终创建 SKI。如果 CSR 提供了 SKI，则该 SKI 将被忽略。 never_create 的值从不创建 SKI。如果 CSR 提供了 SKI，则使用该 SKI。 这仅供 selfsigned 提供程序使用。 请注意，仅当使用 cryptography 后端时才支持此功能！ 选项 "create_if_not_provided" ←（默认） "always_create" "never_create"
selfsigned_digest 字符串	自签名证书时要使用的摘要算法。 这仅供 selfsigned 提供程序使用。 默认值： "sha256"
selfsigned_not_after 别名：selfsigned_notAfter 字符串	证书停止有效的时间点。 时间可以指定为相对时间或绝对时间戳。 时间将始终解释为 UTC。 有效格式为 [+-]timespec | ASN.1 TIME，其中 timespec 可以是整数 + [w | d | h | m | s]（例如 +32w1d2h）。 如果未指定此值，则证书将在 10 年后失效。 请注意，此值不用于确定是否应重新生成现有证书。可以通过将 ignore_timestamps 选项设置为 false 来更改此行为。请注意，当设置 ignore_timestamps=false 时，应避免使用相对时间戳。 这仅供 selfsigned 提供程序使用。 在 macOS 10.15 及更高版本中，TLS 服务器证书的有效期必须为 825 天或更短。有关更多详细信息，请参见 https://support.apple.com/en-us/HT210176。 默认值： "+3650d"
selfsigned_not_before 别名：selfsigned_notBefore 字符串	证书生效的时间点。 时间可以指定为相对时间或绝对时间戳。 时间将始终解释为 UTC。 有效格式为 [+-]timespec | ASN.1 TIME，其中 timespec 可以是整数 + [w | d | h | m | s]（例如 +32w1d2h）。 如果未指定此值，则证书将从现在开始生效。 请注意，此值不用于确定是否应重新生成现有证书。可以通过将 ignore_timestamps 选项设置为 false 来更改此行为。请注意，当设置 ignore_timestamps=false 时，应避免使用相对时间戳。 这仅供 selfsigned 提供程序使用。 默认值： "+0s"
selfsigned_version 整数	selfsigned 证书的版本。 如今，它几乎总是 3。 这仅供 selfsigned 提供程序使用。 默认值： 3

属性

属性	支持	描述
check_mode	支持：完全 当前在检查模式下，不会（重新）生成私钥，只会设置更改状态。这将在 community.crypto 3.0.0 中更改。 从 community.crypto 3.0.0 开始，该模块将忽略检查模式，并且始终表现得好像检查模式未激活。如果您认为这会破坏您对此模块的使用案例，请在 community.crypto 存储库中创建一个问题。	可以在 check_mode 中运行，并在不修改目标的情况下返回已更改状态的预测。
diff_mode	支持：完全	当处于差异模式时，将返回有关已更改内容（或可能需要在 check_mode 中更改的内容）的详细信息。

备注

注意

• 所有 ASN.1 TIME 值都应按照 YYYYMMDDHHMMSSZ 模式指定。

• 指定的日期应为 UTC。分钟和秒是强制性的。

• 出于安全原因，当您使用 ownca 提供程序时，您不应在目标计算机上运行 community.crypto.x509_certificate，而应在专用的 CA 计算机上运行。建议不要将 CA 私钥存储在目标计算机上。签名后，可以将证书移动到目标计算机。

• 对于 selfsigned 提供程序，csr_path 和 csr_content 是可选的。如果未提供，则会创建一个不包含任何信息（主题、主题备用名称、密钥用法等）的证书。

另请参阅

另请参阅

community.crypto.x509_certificate

生成和/或检查 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_privatekey

生成 OpenSSL 私钥。

community.crypto.openssl_privatekey_pipe

无需访问磁盘即可生成 OpenSSL 私钥。

community.crypto.openssl_publickey

从 OpenSSL 私钥生成公钥。

示例

- name: Generate a Self Signed OpenSSL certificate
  community.crypto.x509_certificate_pipe:
    provider: selfsigned
    privatekey_path: /etc/ssl/private/ansible.com.pem
    csr_path: /etc/ssl/csr/ansible.com.csr
  register: result
- name: Print the certificate
  ansible.builtin.debug:
    var: result.certificate

# In the following example, both CSR and certificate file are stored on the
# machine where ansible-playbook is executed, while the OwnCA data (certificate,
# private key) are stored on the remote machine.

- name: (1/2) Generate an OpenSSL Certificate with the CSR provided inline
  community.crypto.x509_certificate_pipe:
    provider: ownca
    content: "{{ lookup('ansible.builtin.file', '/etc/ssl/csr/www.ansible.com.crt') }}"
    csr_content: "{{ lookup('ansible.builtin.file', '/etc/ssl/csr/www.ansible.com.csr') }}"
    ownca_cert: /path/to/ca_cert.crt
    ownca_privatekey: /path/to/ca_cert.key
    ownca_privatekey_passphrase: hunter2
  register: result

- name: (2/2) Store certificate
  ansible.builtin.copy:
    dest: /etc/ssl/csr/www.ansible.com.crt
    content: "{{ result.certificate }}"
  delegate_to: localhost
  when: result is changed

# In the following example, the certificate from another machine is signed by
# our OwnCA whose private key and certificate are only available on this
# machine (where ansible-playbook is executed), without having to write
# the certificate file to disk on localhost. The CSR could have been
# provided by community.crypto.openssl_csr_pipe earlier, or also have been
# read from the remote machine.

- name: (1/3) Read certificate's contents from remote machine
  ansible.builtin.slurp:
    src: /etc/ssl/csr/www.ansible.com.crt
  register: certificate_content

- name: (2/3) Generate an OpenSSL Certificate with the CSR provided inline
  community.crypto.x509_certificate_pipe:
    provider: ownca
    content: "{{ certificate_content.content | b64decode }}"
    csr_content: "{{ the_csr }}"
    ownca_cert: /path/to/ca_cert.crt
    ownca_privatekey: /path/to/ca_cert.key
    ownca_privatekey_passphrase: hunter2
  delegate_to: localhost
  register: result

- name: (3/3) Store certificate
  ansible.builtin.copy:
    dest: /etc/ssl/csr/www.ansible.com.crt
    content: "{{ result.certificate }}"
  when: result is changed

返回值

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

密钥	描述
证书 字符串	（当前或生成的）证书的内容。 返回: changed 或 success

作者

• Yanis Guenane (@Spredzy)

• Markus Teufelberger (@MarkusTeufelberger)

• Felix Fontein (@felixfontein)

集合链接

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