community.crypto.acme_certificate 模块 – 使用 ACME 协议创建 SSL/TLS 证书
注意
此模块是 community.crypto 集合 (版本 2.22.3) 的一部分。
如果您使用的是 ansible 包，则可能已经安装了此集合。它不包含在 ansible-core 中。要检查它是否已安装，请运行 ansible-galaxy collection list。
要安装它，请使用：ansible-galaxy collection install community.crypto。您需要其他要求才能使用此模块，有关详细信息，请参阅 要求。
要在 playbook 中使用它，请指定：community.crypto.acme_certificate。
概要
使用支持 ACME 协议 的 CA（例如 Let’s Encrypt 或 Buypass）创建和续订 SSL/TLS 证书。当前实现支持
http-01、dns-01和tls-alpn-01挑战。要使用此模块，必须执行两次。要么在同一运行中作为两个不同的任务，要么在两次运行中。请注意，第一次运行的输出需要被记录下来，并作为模块参数
data传递给第二次运行。在这两个任务之间，您必须通过任何必要的方式完成所选挑战的必要步骤。对于
http-01，这意味着在目标 Web 服务器上创建必要的挑战文件。对于dns-01，必须创建必要的 DNS 记录。对于tls-alpn-01，必须创建和提供必要的证书。此模块 _不_ 负责执行这些步骤。有关如何完成这些挑战的详细信息，您可能需要阅读 主要的 ACME 规范 和 TLS-ALPN-01 规范。此外，请考虑为此模块提供的示例。
该模块包含对根据 RFC 8738 的 IP 标识符的实验性支持。
要求
以下要求是在执行此模块的主机上所需的。
openssl 或 cryptography >= 1.5
ipaddress
参数
参数 |
注释 |
|---|---|
与该帐户关联的电子邮件地址。 它将用于证书到期警告。 请注意，当 |
|
ACME 帐户 RSA 或椭圆曲线密钥的内容。 与 如果未使用 警告：内容将被写入临时文件，该文件将在模块完成时由 Ansible 删除。由于这是一个重要的私钥——它可以用来更改帐户密钥，或者在不知道其私钥的情况下撤销您的证书——这可能不可接受。 如果使用 |
|
用于解码帐户密钥的密码。 注意：这不受 |
|
包含 ACME 账户 RSA 或椭圆曲线密钥的文件路径。 可以使用 community.crypto.openssl_privatekey 或 community.crypto.openssl_privatekey_pipe 模块创建私钥。如果所需的 (cryptography) 库不可用，也可以使用 与 如果未使用 |
|
如果指定，则假定帐户 URI 与所提供的一致。如果帐户密钥与该帐户不匹配，或者不存在具有此 URI 的帐户，则模块将失败。 |
|
要使用的 ACME 目录。这是访问 ACME CA 服务器 API 的入口点 URL。 出于安全原因，默认设置为 Let's Encrypt 暂存服务器（适用于 ACME v1 协议）。这将创建技术上正确的证书，但这些证书不受信任。 对于 Let's Encrypt，所有暂存端点都可以在此处找到：https://letsencrypt.openssl.ac.cn/docs/staging-environment/。对于 Buypass，所有端点都可以在此处找到：https://community.buypass.com/t/63d4ay/buypass-go-ssl-endpoints 对于 **Let's Encrypt**，ACME v2 的生产目录 URL 为 https://acme-v02.api.letsencrypt.org/directory。 对于 **Buypass**，ACME v2 和 v1 的生产目录 URL 为 https://api.buypass.com/acme/directory。 对于 **ZeroSSL**，ACME v2 的生产目录 URL 为 https://acme.zerossl.com/v2/DV90。 对于 **Sectigo**，ACME v2 的生产目录 URL 为 https://acme-qa.secure.trust-provider.com/v2/DV。 此模块的说明包含已针对其测试过此模块的 ACME 服务列表。 |
|
端点的 ACME 版本。 对于经典的 Let's Encrypt 和 Buypass ACME 端点，必须为 自 community.crypto 2.0.0 版本起， 选项
|
|
使用 默认为从 仅当 |
|
如果指定，则中间证书将写入此文件。 |
|
要执行的挑战。 如果设置为 选项
|
|
包含新证书 CSR 的文件。 可以使用 community.crypto.openssl_csr 创建。 CSR 可以包含多个主题备用名称，但每个名称都会导致必须满足的单独挑战才能签署 CSR。 注意：用于创建 CSR 的私钥 **不能** 是帐户密钥。从安全的角度来看，这是一个坏主意，CA 不应接受 CSR。ACME 服务器在这种情况下应返回错误。 必须精确指定 |
|
新证书的 CSR 内容。 可以使用 community.crypto.openssl_csr_pipe 创建。 CSR 可以包含多个主题备用名称，但每个名称都会导致必须满足的单独挑战才能签署 CSR。 注意：用于创建 CSR 的私钥 **不能** 是帐户密钥。从安全的角度来看，这是一个坏主意，CA 不应接受 CSR。ACME 服务器在这种情况下应返回错误。 必须精确指定 |
|
在颁发证书后或颁发证书失败时停用身份验证对象 (authz)。 身份验证对象绑定到帐户密钥并在一段时间内保持有效，并且可用于颁发证书，而无需重新验证域。这可能是一个安全隐患。 选项
|
|
证书的目标文件。 如果未指定 |
|
完整链的目标文件（即，证书后跟中间证书链）。 如果未指定 |
|
确定是否根据 ACME ARI 草案 3 请求续订现有证书。 仅当
如果您知道 ACME 服务支持 ARI 扩展的兼容草案（或最终版本，一旦发布），通常应使用 ACME 服务器可能会拒绝为已经存在订单的证书创建新的订单，其中包含 选项
|
|
布尔值，指示模块是否需要时创建帐户并更新其联系数据。 如果您想使用 community.crypto.acme_account 模块来管理您的帐户，并避免在您使用 community.crypto.acme_account 更改帐户密钥后意外使用旧密钥创建新帐户，则将其设置为 如果设置为 选项
|
|
证书必须剩余的有效天数。如果 为了确保在任何情况下都续期证书，可以使用 默认值： |
|
Ansible 应等待 ACME API 响应的时间。 此超时适用于所有 HTTP(S) 请求 (HEAD、GET、POST)。 默认值： |
|
设置为 选项
|
|
允许指定选择（备用）信任链的标准。 将逐一处理标准列表，直到找到与标准匹配的链。如果找到这样的链，模块将使用它而不是默认链。 如果一个标准匹配多个链，则返回第一个匹配的链。顺序由 ACME 服务器返回的 每个标准可以包含多个不同的条件，例如 此选项只能与 |
|
检查 AuthorityKeyIdentifier 扩展。这是基于中间证书颁发者私钥的标识符。 标识符必须采用 |
|
允许指定链中证书的颁发者必须具有的部分。 如果 示例值为 |
|
允许指定链中证书的主题必须具有的部分。 如果 示例值为 |
|
检查 SubjectKeyIdentifier 扩展。这是基于中间证书私钥的标识符。 标识符必须采用 |
|
确定将测试链中的哪些证书。
选项
|
|
确定要使用的加密后端。 默认选择是 如果设置为 如果设置为 选项
|
|
对 ACME 目录的调用是否验证 TLS 证书。 警告： 仅应在测试目的时（例如，针对本地 Pebble 服务器进行测试）将其设置为 选项
|
属性
属性 |
支持 |
描述 |
|---|---|---|
动作组： community.crypto.acme，acme |
在 |
|
支持：完全支持 |
可以在 |
|
支持：不支持 |
处于 diff 模式时，将返回关于已更改内容（或可能需要在 |
|
支持：完全支持 |
使用 Ansible 的严格文件操作函数来确保正确的权限并避免数据损坏。 |
注释
注意
必须指定至少一个
dest和fullchain_dest。此模块包含基本帐户管理功能。如果您想更详细地控制您的 ACME 帐户，请使用 community.crypto.acme_account 模块，并使用
modify_account选项为此模块禁用帐户管理。在 Ansible 2.6 之前，此模块被称为
letsencrypt。使用方法没有改变。尽管默认值的选择使得该模块可以与 Let’s Encrypt CA 一起使用，但原则上该模块可以与任何提供 ACME 端点的 CA 一起使用，例如 Buypass Go SSL。
到目前为止，ACME 模块仅由开发人员针对 Let’s Encrypt（暂存和生产）、Buypass（暂存和生产）、ZeroSSL（生产）和 Pebble 测试服务器 进行过测试。我们收到了社区的反馈，这些模块也可以与用于 InCommon 的 Sectigo ACME 服务一起使用。如果您在使用其他 ACME 服务器时遇到问题，请 创建一个问题 来帮助我们支持它。我们也欢迎您反馈未提及的 ACME 服务器是否可以正常工作。
如果可以使用足够新版本的
cryptography库（详情请参阅“需求”），它将代替openssl二进制文件使用。这可以通过select_crypto_backend选项显式禁用或启用。请注意，使用openssl二进制文件将更慢且安全性较低，因为私钥内容始终必须存储在磁盘上（请参阅account_key_content）。
另请参阅
另请参阅
- Let’s Encrypt 文档
Let’s Encrypt 证书颁发机构的文档。例如，提供有关速率限制的有用信息。
- Buypass Go SSL
Buypass 证书颁发机构的文档。例如，提供有关速率限制的有用信息。
- 自动证书管理环境 (ACME)
ACME 协议的规范 (RFC 8555)。
- ACME TLS ALPN 挑战扩展
tls-alpn-01挑战的规范 (RFC 8737)。- community.crypto.acme_challenge_cert_helper
帮助准备
tls-alpn-01挑战。- community.crypto.openssl_privatekey
可用于创建私钥（证书和帐户）。
- community.crypto.openssl_privatekey_pipe
可用于创建私钥而无需将其写入磁盘（证书和帐户）。
- community.crypto.openssl_csr
可用于创建证书签名请求 (CSR)。
- community.crypto.openssl_csr_pipe
可用于创建证书签名请求 (CSR) 而无需将其写入磁盘。
- community.crypto.certificate_complete_chain
允许查找返回的 fullchain 的根证书。
- community.crypto.acme_certificate_revoke
允许吊销证书。
- community.crypto.acme_account
允许创建、修改或删除 ACME 帐户。
- community.crypto.acme_inspect
允许调试问题。
- community.crypto.acme_certificate_deactivate_authz
允许停用（使无效）ACME v2 订单。
示例
### Example with HTTP challenge ###
- name: Create a challenge for sample.com using a account key from a variable.
community.crypto.acme_certificate:
account_key_content: "{{ account_private_key }}"
csr: /etc/pki/cert/csr/sample.com.csr
dest: /etc/httpd/ssl/sample.com.crt
register: sample_com_challenge
# Alternative first step:
- name: Create a challenge for sample.com using a account key from Hashi Vault.
community.crypto.acme_certificate:
account_key_content: >-
{{ lookup('community.hashi_vault.hashi_vault', 'secret=secret/account_private_key:value') }}
csr: /etc/pki/cert/csr/sample.com.csr
fullchain_dest: /etc/httpd/ssl/sample.com-fullchain.crt
register: sample_com_challenge
# Alternative first step:
- name: Create a challenge for sample.com using a account key file.
community.crypto.acme_certificate:
account_key_src: /etc/pki/cert/private/account.key
csr_content: "{{ lookup('file', '/etc/pki/cert/csr/sample.com.csr') }}"
dest: /etc/httpd/ssl/sample.com.crt
fullchain_dest: /etc/httpd/ssl/sample.com-fullchain.crt
register: sample_com_challenge
# perform the necessary steps to fulfill the challenge
# for example:
#
# - name: Copy http-01 challenge for sample.com
# ansible.builtin.copy:
# dest: /var/www/html/{{ sample_com_challenge['challenge_data']['sample.com']['http-01']['resource'] }}
# content: "{{ sample_com_challenge['challenge_data']['sample.com']['http-01']['resource_value'] }}"
# when: sample_com_challenge is changed and 'sample.com' in sample_com_challenge['challenge_data']
#
# Alternative way:
#
# - name: Copy http-01 challenges
# ansible.builtin.copy:
# dest: /var/www/{{ item.key }}/{{ item.value['http-01']['resource'] }}
# content: "{{ item.value['http-01']['resource_value'] }}"
# loop: "{{ sample_com_challenge.challenge_data | dict2items }}"
# when: sample_com_challenge is changed
- name: Let the challenge be validated and retrieve the cert and intermediate certificate
community.crypto.acme_certificate:
account_key_src: /etc/pki/cert/private/account.key
csr: /etc/pki/cert/csr/sample.com.csr
dest: /etc/httpd/ssl/sample.com.crt
fullchain_dest: /etc/httpd/ssl/sample.com-fullchain.crt
chain_dest: /etc/httpd/ssl/sample.com-intermediate.crt
data: "{{ sample_com_challenge }}"
### Example with DNS challenge against production ACME server ###
- name: Create a challenge for sample.com using a account key file.
community.crypto.acme_certificate:
account_key_src: /etc/pki/cert/private/account.key
account_email: [email protected]
src: /etc/pki/cert/csr/sample.com.csr
cert: /etc/httpd/ssl/sample.com.crt
challenge: dns-01
acme_directory: https://acme-v01.api.letsencrypt.org/directory
# Renew if the certificate is at least 30 days old
remaining_days: 60
register: sample_com_challenge
# perform the necessary steps to fulfill the challenge
# for example:
#
# - name: Create DNS record for sample.com dns-01 challenge
# community.aws.route53:
# zone: sample.com
# record: "{{ sample_com_challenge.challenge_data['sample.com']['dns-01'].record }}"
# type: TXT
# ttl: 60
# state: present
# wait: true
# # Note: route53 requires TXT entries to be enclosed in quotes
# value: "{{ sample_com_challenge.challenge_data['sample.com']['dns-01'].resource_value | community.dns.quote_txt(always_quote=true) }}"
# when: sample_com_challenge is changed and 'sample.com' in sample_com_challenge.challenge_data
#
# Alternative way:
#
# - name: Create DNS records for dns-01 challenges
# community.aws.route53:
# zone: sample.com
# record: "{{ item.key }}"
# type: TXT
# ttl: 60
# state: present
# wait: true
# # Note: item.value is a list of TXT entries, and route53
# # requires every entry to be enclosed in quotes
# value: "{{ item.value | map('community.dns.quote_txt', always_quote=true) | list }}"
# loop: "{{ sample_com_challenge.challenge_data_dns | dict2items }}"
# when: sample_com_challenge is changed
- name: Let the challenge be validated and retrieve the cert and intermediate certificate
community.crypto.acme_certificate:
account_key_src: /etc/pki/cert/private/account.key
account_email: [email protected]
src: /etc/pki/cert/csr/sample.com.csr
cert: /etc/httpd/ssl/sample.com.crt
fullchain: /etc/httpd/ssl/sample.com-fullchain.crt
chain: /etc/httpd/ssl/sample.com-intermediate.crt
challenge: dns-01
acme_directory: https://acme-v01.api.letsencrypt.org/directory
remaining_days: 60
data: "{{ sample_com_challenge }}"
when: sample_com_challenge is changed
# Alternative second step:
- name: Let the challenge be validated and retrieve the cert and intermediate certificate
community.crypto.acme_certificate:
account_key_src: /etc/pki/cert/private/account.key
account_email: [email protected]
src: /etc/pki/cert/csr/sample.com.csr
cert: /etc/httpd/ssl/sample.com.crt
fullchain: /etc/httpd/ssl/sample.com-fullchain.crt
chain: /etc/httpd/ssl/sample.com-intermediate.crt
challenge: tls-alpn-01
remaining_days: 60
data: "{{ sample_com_challenge }}"
# We use Let's Encrypt's ACME v2 endpoint
acme_directory: https://acme-v02.api.letsencrypt.org/directory
acme_version: 2
# The following makes sure that if a chain with /CN=DST Root CA X3 in its issuer is provided
# as an alternative, it will be selected. These are the roots cross-signed by IdenTrust.
# As long as Let's Encrypt provides alternate chains with the cross-signed root(s) when
# switching to their own ISRG Root X1 root, this will use the chain ending with a cross-signed
# root. This chain is more compatible with older TLS clients.
select_chain:
- test_certificates: last
issuer:
CN: DST Root CA X3
O: Digital Signature Trust Co.
when: sample_com_challenge is changed
返回值
常用的返回值已在 此处 记录，以下是此模块特有的字段
密钥 |
描述 |
|---|---|
ACME 帐户 URI。 返回：已更改 |
|
当 详情请参阅 RFC8555 的 7.4.2 节。 返回：当检索证书且 |
|
叶证书本身，采用 PEM 格式。 返回：始终 |
|
证书链，不包括根证书，作为连接的 PEM 证书。 返回：始终 |
|
证书链，不包括根证书，但包括叶证书，作为连接的 PEM 证书。 返回：始终 |
|
ACME 授权数据。 将标识符映射到 ACME 授权对象。请参阅 https://tools.ietf.org/html/rfc8555#section-7.1.4。 返回：已更改 示例： |
|
证书有效期天数。 返回：成功 |
|
每个标识符/挑战类型的挑战数据。 自 Ansible 2.8.5 起，仅返回尚未有效的挑战。 返回：已更改 |
|
对于每个标识符，提供一个挑战类型映射到挑战数据的字典。 此字典中的键是标识符。 请注意，这些键不是有效的 Jinja2 标识符。 返回：已更改 |
|
每种挑战类型的的数据。 此字典中的键是挑战类型。 请注意，这些键不是有效的 Jinja2 标识符。 返回：已更改 |
|
挑战的完整 DNS 记录名称。 返回：已更改且挑战为 示例： |
|
必须创建以进行验证的挑战资源。 返回：已更改 示例： |
|
资源必须为验证生成的值。 对于 对于 返回：已更改 示例： |
|
如果挑战是 自 Ansible 2.8.5 起，仅返回尚未有效的挑战。 返回：已更改 |
|
ACME 完成 URI。 返回：已更改 |
|
ACME 订单 URI。 返回：已更改 |