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 证书服务 (ECS) API 进行身份验证的客户端证书的私钥路径。 仅 entrust 提供程序使用。 如果提供程序为 entrust，则这是必需的。
entrust_api_client_cert_path 路径	用于向 Entrust 证书服务 (ECS) API 进行身份验证的客户端证书的路径。 仅 entrust 提供程序使用。 如果提供程序为 entrust，则这是必需的。
entrust_api_key 字符串	用于向 Entrust 证书服务 (ECS) API 进行身份验证的密钥（密码）。 仅 entrust 提供程序使用。 如果提供程序为 entrust，则这是必需的。
entrust_api_specification_path 路径	定义 Entrust 证书服务 (ECS) API 配置的规范文件的路径。 您可以使用此方法保留规范的本地副本，以避免每次使用模块时都下载它。 仅 entrust 提供程序使用。 默认值： "https://cloud.entrust.net/EntrustCloud/documentation/cms-api-2.1.0.yaml"
entrust_api_user 字符串	用于向 Entrust 证书服务 (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，则这是必需的。
force 布尔值	即使证书已存在，也生成证书。 选项 false ← (默认) true
ignore_timestamps 布尔值 在community.crypto 2.0.0中添加	是否应忽略“not before”和“not after”时间戳以进行幂等性检查。 使用相对时间戳（例如，目前使用+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，则会忽略它。 值为never_create从不创建SKI。如果CSR提供了一个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）。 如果未指定此值，则证书将在十年后停止有效。 请注意，此值**不用于确定是否应重新生成现有证书**。可以通过将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，则会忽略它。 值为never_create从不创建SKI。如果CSR提供了一个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）。 如果未指定此值，则证书将在十年后停止有效。 请注意，此值**不用于确定是否应重新生成现有证书**。可以通过将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

返回值

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

键	描述
certificate 字符串	证书（当前或生成的）内容。 返回：已更改或成功

作者

• Yanis Guenane (@Spredzy)

• Markus Teufelberger (@MarkusTeufelberger)

• Felix Fontein (@felixfontein)

集合链接

• 问题追踪器
• 代码库（源代码）
• 寻求帮助（加密）
• 寻求帮助（ACME）
• 提交错误报告
• 请求功能
• 沟通