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提供程序）
参数
参数 |
注释 |
|---|---|
仅 |
|
将中间证书包含到生成的证书中 仅 请注意，这仅适用于旧版本的 选项
|
|
在 http://<HOST>:80/.well-known/acme-challenge/ 上提供的 ACME 挑战目录的路径 仅 |
|
要使用的 ACME 目录。您可以使用任何支持 ACME 协议的目录，例如 Buypass 或 Let’s Encrypt。 Let’s Encrypt 建议在开发作业时使用其暂存服务器。https://letsencrypt.openssl.ac.cn/docs/staging-environment/。 默认值： |
|
生成的 文件系统对象应具有的属性。 要获取支持的标志，请查看目标系统上chattr的手册页。 此字符串应按lsattr显示的相同顺序包含属性。 默认情况下假定使用 |
|
创建一个包含时间戳的备份文件，以便在您意外地用新证书覆盖原始证书时可以恢复原始证书。 选项
|
|
用于生成此证书的证书签名请求 (CSR) 的内容。 这与 |
|
用于生成此证书的证书签名请求 (CSR) 的路径。 这与 |
|
用于向 Entrust 证书服务 (ECS) API 进行身份验证的客户端证书的私钥路径。 仅 如果提供程序为 |
|
用于向 Entrust 证书服务 (ECS) API 进行身份验证的客户端证书的路径。 仅 如果提供程序为 |
|
用于向 Entrust 证书服务 (ECS) API 进行身份验证的密钥（密码）。 仅 如果提供程序为 |
|
定义 Entrust 证书服务 (ECS) API 配置的规范文件的路径。 您可以使用此功能保留规范的本地副本，以避免每次使用模块时都下载它。 仅 默认值： |
|
用于向 Entrust 证书服务 (ECS) API 进行身份验证的用户名。 仅 如果提供程序为 |
|
指定请求的证书类型。 仅 选项
|
|
证书停止有效的时刻。 时间可以指定为相对时间或绝对时间戳。 有效的绝对时间格式为 有效的相对时间格式为 时间将始终解释为 UTC。 请注意，仅支持日期（日、月、年）来指定已颁发证书的到期日期。 在颁发之前，完整日期时间将调整为 EST (GMT -5:00)，如果使用相对时间，则可能导致证书的到期日期比预期早一天。 证书最短有效期为 90 天，最长有效期为三年。 如果未指定此值，则证书将在签发日期后 365 天停止有效。 仅 请注意，此值不受 默认值： |
|
证书请求者的电子邮件（用于跟踪目的）。 仅 如果提供程序为 |
|
证书请求者的姓名（用于跟踪目的）。 仅 如果提供程序为 |
|
证书请求者的电话号码（用于跟踪目的）。 仅 如果提供程序为 |
|
即使证书已存在，也生成证书。 选项
|
|
应拥有文件系统对象的组的名称，如同传递给chown一样。 如果未指定，则除非您是 root 用户，否则它使用当前用户的当前组，在这种情况下，它可以保留以前的拥有者。 |
|
是否应忽略“生效前”和“生效后”时间戳以进行幂等性检查。 使用相对时间戳（例如，目前为 选项
|
|
生成的 文件系统对象应具有的权限。 对于习惯使用/usr/bin/chmod的用户，请记住模式实际上是八进制数。您必须向 Ansible 提供足够的信息才能正确解析它们。为了获得一致的结果，请引用八进制数（例如， 不遵循这些规则中的任何一个而向 Ansible 提供数字，最终将得到一个十进制数，这将产生意外的结果。 从 Ansible 1.8 开始，模式可以指定为符号模式（例如， 如果未指定 如果未指定 指定 |
|
从 CA 的证书创建授权密钥标识符。如果提供的 CSR 包含授权密钥标识符，则会忽略它。 授权密钥标识符是从 CA 证书的主题密钥标识符（如果可用）生成的。如果不可用，则将使用 CA 证书的公钥。 仅 请注意，这仅在使用 选项
|
|
是否根据公钥创建主题密钥标识符 (SKI)。
仅 请注意，这仅在使用 选项
|
|
要用于 仅 默认值： |
|
证书停止有效的时刻。 时间可以指定为相对时间或绝对时间戳。 时间将始终解释为 UTC。 有效格式为 如果未指定此值，则证书将在 10 年后停止有效。 请注意，此值不用于确定是否应重新生成现有证书。这可以通过将 仅 在 macOS 10.15 及更高版本上，TLS 服务器证书的有效期必须为 825 天或更短。有关更多详细信息，请参阅https://support.apple.com/en-us/HT210176。 默认值： |
|
证书生效时间点。 时间可以指定为相对时间或绝对时间戳。 时间将始终解释为 UTC。 有效格式为 如果未指定此值，则证书将从现在开始生效。 请注意，此值不用于确定是否应重新生成现有证书。这可以通过将 仅 默认值： |
|
仅 |
|
现在几乎总是应该为 仅 默认值： |
|
应该拥有文件系统对象的用户名，如同传递给chown命令一样。 如果未指定，则使用当前用户，除非您是 root 用户，在这种情况下，它可以保留之前的拥有者。 指定数字用户名将被视为用户 ID，而不是用户名。避免使用数字用户名以避免此混淆。 |
|
生成证书文件应创建或已存在的远程绝对路径。 |
|
签署证书时使用的私钥内容。 此选项与 |
|
如果私钥受密码保护，则此选项为必需。 |
|
签署证书时使用的私钥路径。 此选项与 |
|
用于生成/检索OpenSSL证书的提供程序名称。请参阅示例，了解如何使用community.crypto.x509_certificate_info、community.crypto.openssl_csr_info、community.crypto.openssl_privatekey_info和ansible.builtin.assert模拟它。
如果 选项
|
|
确定使用哪个加密后端。 默认选择是 如果设置为 选项
|
|
SELinux 文件系统对象上下文中的级别部分。 这是 MLS/MCS 属性，有时称为 设置为 |
|
是否根据公钥创建主题密钥标识符 (SKI)。
此选项仅由 请注意，这仅在使用 选项
|
|
自签名证书时使用的摘要算法。 此选项仅由 默认值： |
|
证书停止有效的时刻。 时间可以指定为相对时间或绝对时间戳。 时间将始终解释为 UTC。 有效格式为 如果未指定此值，则证书将在 10 年后停止有效。 请注意，此值不用于确定是否应重新生成现有证书。这可以通过将 此选项仅由 在 macOS 10.15 及更高版本上，TLS 服务器证书的有效期必须为 825 天或更短。有关更多详细信息，请参阅https://support.apple.com/en-us/HT210176。 默认值： |
|
证书生效时间点。 时间可以指定为相对时间或绝对时间戳。 时间将始终解释为 UTC。 有效格式为 如果未指定此值，则证书将从现在开始生效。 请注意，此值不用于确定是否应重新生成现有证书。这可以通过将 此选项仅由 默认值： |
|
现在几乎总是应该为 此选项仅由 默认值： |
|
SELinux 文件系统对象上下文中的角色部分。 设置为 |
|
SELinux 文件系统对象上下文中的类型部分。 设置为 |
|
SELinux 文件系统对象上下文中的用户部分。 默认情况下，它使用 设置为 |
|
证书是否应该存在，如果状态与声明的状态不同，则采取行动。 选项
|
|
影响何时使用原子操作来防止数据损坏或目标文件系统对象的不一致读取。 默认情况下，此模块使用原子操作来防止数据损坏或目标文件系统对象的不一致读取，但有时系统配置或损坏的方式会阻止此操作。一个例子是 docker 挂载的文件系统对象，不能从容器内部以原子方式更新，只能以不安全的方式写入。 此选项允许 Ansible 在原子操作失败时回退到不安全的文件系统对象更新方法（但是，它不会强制 Ansible 执行不安全的写入）。 重要！不安全的写入容易出现竞争条件，并可能导致数据损坏。 选项
|
属性
属性 |
支持 |
描述 |
|---|---|---|
支持：完全支持 |
可以在 |
|
支持：完全支持 |
处于差异模式时，将返回有关已更改内容（或可能需要在 |
|
支持：完全支持 |
使用 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
返回值
常见返回值已在此处记录，以下是此模块特有的字段
键 |
描述 |
|---|---|
(当前或生成的)证书内容。 返回：如果 |
|
生成的证书路径。 返回：changed 或 success 示例： |