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

注意

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

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

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

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

概要

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

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

• 请注意，此模块在 Ansible 2.9 版本之前直接包含时被称为 openssl_certificate。当移至 community.crypto 集合时，它被重命名为 community.crypto.x509_certificate。从 Ansible 2.10 开始，仍然可以使用旧的短名称（或 ansible.builtin.openssl_certificate），它会重定向到 community.crypto.x509_certificate。当使用 FQCN 或使用 集合 关键字时，应使用新名称 community.crypto.x509_certificate 以避免弃用警告。

• 请注意，如果现有证书与模块的选项不匹配，或者看起来已损坏，则模块会重新生成现有证书。如果您担心这可能会覆盖您现有的证书，请考虑使用 backup 选项。

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

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

要求

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

• acme-tiny >= 4.0.0（如果使用 acme 提供程序）

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

参数

参数	注释
acme_accountkey_path 路径	acme 提供程序的 accountkey 路径。 仅 acme 提供程序使用。
acme_chain 布尔值	将中间证书包含到生成的证书中 仅 acme 提供程序使用。 请注意，这仅适用于旧版本的 acme-tiny。新版本会自动包含链，并将 acme_chain 设置为 true 会导致错误。 选项 false ← (默认) true
acme_challenge_path 路径	在 http://<HOST>:80/.well-known/acme-challenge/ 上服务的 ACME challenge 目录的路径 仅 acme 提供程序使用。
acme_directory 字符串 在 community.crypto 1.0.0 中添加	要使用的 ACME 目录。您可以使用任何支持 ACME 协议的目录，例如 Buypass 或 Let’s Encrypt。 Let’s Encrypt 建议在开发作业时使用其暂存服务器。https://letsencrypt.openssl.ac.cn/docs/staging-environment/. 默认值： "https://acme-v02.api.letsencrypt.org/directory"
attributes 别名：attr 字符串	目标文件系统对象应具有的属性。 要获取支持的标志，请查看目标系统上chattr的手册页。 此字符串应包含与lsattr显示的顺序相同的属性。 默认情况下假定使用=运算符，否则需要在字符串中包含+或-运算符。
backup 布尔值	创建一个包含时间戳的备份文件，以便您可以意外地用新证书覆盖原始证书后找回它。 选项 false ← (默认) true
csr_content 字符串 在 community.crypto 1.0.0 中添加	用于生成此证书的证书签名请求 (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
group 字符串	应拥有文件系统对象的组的名称，如同提供给chown一样。 如果未指定，除非您是 root 用户，否则它将使用当前用户的当前组，在这种情况下，它可以保留之前的拥有权。
ignore_timestamps 布尔值 在 community.crypto 2.0.0 中添加	是否应忽略“not before”和“not after”时间戳以进行幂等性检查。 使用相对时间戳（例如，现在使用+0s）时，最好保留默认值true。 选项 false true ← (默认)
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。
ownca_content 字符串 在 community.crypto 1.0.0 中添加	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 提供了一个，则忽略该一个。 never_create值从不创建 SKI。如果 CSR 提供了一个，则使用该一个。 这仅由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 字符串 在 community.crypto 1.0.0 中添加	签名证书时使用的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
owner 字符串	应该拥有文件系统对象的用户的名称，就像传递给chown一样。 如果未指定，则使用当前用户，除非您是root用户，在这种情况下，它可以保留之前的拥有者。 指定数字用户名将被认为是用户ID而不是用户名。避免使用数字用户名以避免此混淆。
路径 路径 / 必需	应创建生成的证书文件或已存在生成的证书文件的远程绝对路径。
privatekey_content 字符串 在 community.crypto 1.0.0 中添加	签名证书时使用的私钥内容。 这与privatekey_path互斥。
privatekey_passphrase 字符串	privatekey_path或privatekey_content的密码。 如果私钥受密码保护，则需要此项。
privatekey_path 路径	签名证书时使用的私钥的路径。 这与privatekey_content互斥。
provider 字符串	用于生成/检索OpenSSL证书的提供程序名称。请参阅有关如何使用community.crypto.x509_certificate_info、community.crypto.openssl_csr_info、community.crypto.openssl_privatekey_info和ansible.builtin.assert模拟它的示例。 为Ansible 2.9添加了entrust提供程序，它需要Entrust证书服务(ECS) API的凭据。 如果state为present，则需要此项。 选项 "acme" "entrust" "ownca" "selfsigned"
return_content 布尔值 在 community.crypto 1.0.0 中添加	如果设置为true，则会将（当前或生成的）证书的内容作为certificate返回。 选项 false ← (默认) true
select_crypto_backend 字符串	确定要使用的加密后端。 默认选择是auto，如果可用，它会尝试使用cryptography。 如果设置为cryptography，将尝试使用cryptography库。 选项 "auto" ← (默认) "cryptography"
selevel 字符串	SELinux文件系统对象上下文的级别部分。 这是MLS/MCS属性，有时称为range。 如果设置为_default，它将使用策略的level部分（如果可用）。
selfsigned_create_subject_key_identifier 字符串	是否从公钥创建主题密钥标识符 (SKI)。 create_if_not_provided（默认）值仅在 CSR 未提供 SKI 时才创建 SKI。 always_create值始终创建 SKI。如果 CSR 提供了一个，则忽略该一个。 never_create值从不创建 SKI。如果 CSR 提供了一个，则使用该一个。 仅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
serole 字符串	SELinux文件系统对象上下文的角色部分。 如果设置为_default，它将使用策略的role部分（如果可用）。
setype 字符串	SELinux文件系统对象上下文的类型部分。 如果设置为_default，它将使用策略的type部分（如果可用）。
seuser 字符串	SELinux文件系统对象上下文的用户部分。 默认情况下，它使用system策略（如果适用）。 如果设置为_default，它将使用策略的user部分（如果可用）。
state 字符串	证书是否应该存在，如果状态与声明的状态不同，则采取措施。 选项 "absent" "present" ← (默认)
unsafe_writes 布尔值	影响何时使用原子操作来防止目标文件系统对象的数据损坏或不一致读取。 默认情况下，此模块使用原子操作来防止目标文件系统对象的数据损坏或不一致读取，但有时系统配置或损坏的方式会阻止此操作。一个例子是docker挂载的文件系统对象，不能从容器内部以原子方式更新，只能以不安全的方式写入。 此选项允许Ansible在原子操作失败时回退到不安全的文件系统对象更新方法（但是，它不会强制Ansible执行不安全的写入）。 重要！不安全的写入容易发生竞争条件，并可能导致数据损坏。 选项 false ← (默认) true

属性

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

备注

注意

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

• 指定的日期应为UTC。分钟和秒是必需的。

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

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

另请参阅

另请参阅

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_privatekey

生成 OpenSSL 私钥。

community.crypto.openssl_privatekey_pipe

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

community.crypto.openssl_publickey

根据私钥生成 OpenSSL 公钥。

示例

- name: Generate a Self Signed OpenSSL certificate
  community.crypto.x509_certificate:
    path: /etc/ssl/crt/ansible.com.crt
    privatekey_path: /etc/ssl/private/ansible.com.pem
    csr_path: /etc/ssl/csr/ansible.com.csr
    provider: selfsigned

- name: Generate an OpenSSL certificate signed with your own CA certificate
  community.crypto.x509_certificate:
    path: /etc/ssl/crt/ansible.com.crt
    csr_path: /etc/ssl/csr/ansible.com.csr
    ownca_path: /etc/ssl/crt/ansible_CA.crt
    ownca_privatekey_path: /etc/ssl/private/ansible_CA.pem
    provider: ownca

- name: Generate a Let's Encrypt Certificate
  community.crypto.x509_certificate:
    path: /etc/ssl/crt/ansible.com.crt
    csr_path: /etc/ssl/csr/ansible.com.csr
    provider: acme
    acme_accountkey_path: /etc/ssl/private/ansible.com.pem
    acme_challenge_path: /etc/ssl/challenges/ansible.com/

- name: Force (re-)generate a new Let's Encrypt Certificate
  community.crypto.x509_certificate:
    path: /etc/ssl/crt/ansible.com.crt
    csr_path: /etc/ssl/csr/ansible.com.csr
    provider: acme
    acme_accountkey_path: /etc/ssl/private/ansible.com.pem
    acme_challenge_path: /etc/ssl/challenges/ansible.com/
    force: true

- name: Generate an Entrust certificate via the Entrust Certificate Services (ECS) API
  community.crypto.x509_certificate:
    path: /etc/ssl/crt/ansible.com.crt
    csr_path: /etc/ssl/csr/ansible.com.csr
    provider: entrust
    entrust_requester_name: Jo Doe
    entrust_requester_email: [email protected]
    entrust_requester_phone: 555-555-5555
    entrust_cert_type: STANDARD_SSL
    entrust_api_user: apiusername
    entrust_api_key: a^lv*32!cd9LnT
    entrust_api_client_cert_path: /etc/ssl/entrust/ecs-client.crt
    entrust_api_client_cert_key_path: /etc/ssl/entrust/ecs-key.crt
    entrust_api_specification_path: /etc/ssl/entrust/api-docs/cms-api-2.1.0.yaml

# The following example shows how to emulate the behavior of the removed
# "assertonly" provider with the x509_certificate_info, openssl_csr_info,
# openssl_privatekey_info and assert modules:

- name: Get certificate information
  community.crypto.x509_certificate_info:
    path: /etc/ssl/crt/ansible.com.crt
    # for valid_at, invalid_at and valid_in
    valid_at:
      one_day_ten_hours: "+1d10h"
      fixed_timestamp: 20200331202428Z
      ten_seconds: "+10"
  register: result

- name: Get CSR information
  community.crypto.openssl_csr_info:
    # Verifies that the CSR signature is valid; module will fail if not
    path: /etc/ssl/csr/ansible.com.csr
  register: result_csr

- name: Get private key information
  community.crypto.openssl_privatekey_info:
    path: /etc/ssl/csr/ansible.com.key
  register: result_privatekey

- name: Check conditions on certificate, CSR, and private key
  ansible.builtin.assert:
    that:
      # When private key was specified for assertonly, this was checked:
      - result.public_key == result_privatekey.public_key
      # When CSR was specified for assertonly, this was checked:
      - result.public_key == result_csr.public_key
      - result.subject_ordered == result_csr.subject_ordered
      - result.extensions_by_oid == result_csr.extensions_by_oid
      # signature_algorithms check
      - "result.signature_algorithm == 'sha256WithRSAEncryption' or result.signature_algorithm == 'sha512WithRSAEncryption'"
      # subject and subject_strict
      - "result.subject.commonName == 'ansible.com'"
      - "result.subject | length == 1"  # the number must be the number of entries you check for
      # issuer and issuer_strict
      - "result.issuer.commonName == 'ansible.com'"
      - "result.issuer | length == 1"  # the number must be the number of entries you check for
      # has_expired
      - not result.expired
      # version
      - result.version == 3
      # key_usage and key_usage_strict
      - "'Data Encipherment' in result.key_usage"
      - "result.key_usage | length == 1"  # the number must be the number of entries you check for
      # extended_key_usage and extended_key_usage_strict
      - "'DVCS' in result.extended_key_usage"
      - "result.extended_key_usage | length == 1"  # the number must be the number of entries you check for
      # subject_alt_name and subject_alt_name_strict
      - "'dns:ansible.com' in result.subject_alt_name"
      - "result.subject_alt_name | length == 1"  # the number must be the number of entries you check for
      # not_before and not_after
      - "result.not_before == '20190331202428Z'"
      - "result.not_after == '20190413202428Z'"
      # valid_at, invalid_at and valid_in
      - "result.valid_at.one_day_ten_hours"  # for valid_at
      - "not result.valid_at.fixed_timestamp"  # for invalid_at
      - "result.valid_at.ten_seconds"  # for valid_in

返回值

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

键	描述
backup_file 字符串	创建的备份文件名称。 返回：changed 以及如果 backup 为 true 示例： "/path/to/www.ansible.com.crt.2019-03-09@11:22~"
certificate 字符串 在 community.crypto 1.0.0 中添加	证书的（当前或生成的）内容。 返回：如果 state 为 present 且 return_content 为 true
filename 字符串	生成的证书的路径。 返回：changed 或 success 示例： "/etc/ssl/crt/www.ansible.com.crt"

作者

• Yanis Guenane (@Spredzy)

• Markus Teufelberger (@MarkusTeufelberger)

集合链接

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