community.crypto.acme_certificate_revoke 模块 – 使用 ACME 协议撤销证书

注意

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

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

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

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

概要 

允许撤销由支持 ACME 协议的 CA（证书颁发机构）颁发的证书，例如 Let’s Encrypt。

要求 

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

openssl 或 cryptography >= 1.5
ipaddress

参数 

参数	注释
account_key_content 字符串	ACME 帐户 RSA 或椭圆曲线密钥的内容。请注意，必须指定以下各项中的恰好一项：`account_key_src`、`account_key_content`、`private_key_src` 或 `private_key_content`。警告：内容将写入临时文件，该文件将在模块完成时由 Ansible 删除。由于这是一个重要的私钥——它可以用于更改帐户密钥，或在不知道其私钥的情况下撤销您的证书——这可能是不可接受的。如果使用 `cryptography`，则内容不会写入临时文件。Ansible 在将模块及其参数移动到执行它的节点的过程中，仍然可能将其写入磁盘。
account_key_passphrase 字符串在 community.crypto 1.6.0 中添加	用于解码帐户密钥的密码。注意：`openssl` 后端不支持此功能，仅 `cryptography` 后端支持。
account_key_src 别名：account_key 路径	包含 ACME 帐户 RSA 或椭圆曲线密钥的文件的路径。可以使用 `openssl rsa ...` 创建 RSA 密钥。可以使用 `openssl ecparam -genkey ...` 创建椭圆曲线密钥。任何其他创建 PEM 格式私钥的工具都可以使用。与 `account_key_content` 互斥。如果未使用 `account_key_content`，则为必需。
account_uri 字符串	如果指定，则假定帐户 URI 如所提供的那样。如果帐户密钥与该帐户不匹配，或者不存在具有此 URI 的帐户，则模块将失败。
acme_directory 字符串 / 必需	要使用的 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_version 整数 / 必需	端点的 ACME 版本。对于经典的 Let’s Encrypt 和 Buypass ACME 端点，必须为 `1`；对于标准化的 ACME v2 端点，必须为 `2`。自 community.crypto 2.0.0 起，值 `1` 已弃用，并将从 community.crypto 3.0.0 中删除。选项 `1` `2`
certificate 路径 / 必需	要撤销的证书的路径。
private_key_content 字符串	证书私钥的内容。请注意，必须指定以下各项中的恰好一项：`account_key_src`、`account_key_content`、`private_key_src` 或 `private_key_content`。警告：内容将写入临时文件，该文件将在模块完成时由 Ansible 删除。由于这是一个重要的私钥——它可以用于更改帐户密钥，或在不知道其私钥的情况下撤销您的证书——这可能是不可接受的。如果使用 `cryptography`，则内容不会写入临时文件。Ansible 在将模块及其参数移动到执行它的节点的过程中，仍然可能将其写入磁盘。
private_key_passphrase 字符串在 community.crypto 1.6.0 中添加	用于解码证书私钥的密码。注意：`openssl` 后端不支持此功能，仅 `cryptography` 后端支持。
private_key_src 路径	证书私钥的路径。请注意，必须指定以下各项中的恰好一项：`account_key_src`、`account_key_content`、`private_key_src` 或 `private_key_content`。
request_timeout 整数在 community.crypto 2.3.0 中添加	Ansible 等待 ACME API 响应的时间。此超时适用于所有 HTTP(S) 请求 (HEAD、GET、POST)。默认值： `10`
撤销原因整数	RFC5280 5.3.1 节中定义的撤销 reasonCodes 之一。可能的值为 `0`（未指定）、`1`（keyCompromise）、`2`（cACompromise）、`3`（affiliationChanged）、`4`（superseded）、`5`（cessationOfOperation）、`6`（certificateHold）、`8`（removeFromCRL）、`9`（privilegeWithdrawn）、`10`（aACompromise）。
选择加密后端字符串	确定要使用的加密后端。默认选择是 `auto`，如果可用，它会尝试使用 `cryptography`，然后回退到 `openssl`。如果设置为 `openssl`，将尝试使用 `openssl` 二进制文件。如果设置为 `cryptography`，将尝试使用 cryptography 库。选项 `"auto"` ← (默认) `"cryptography"` `"openssl"`
验证证书布尔值	是否对 ACME 目录的调用验证 TLS 证书。警告：仅应出于测试目的将其设置为 `false`，例如针对本地 Pebble 服务器进行测试时。选项 `false` `true` ← (默认)

属性 

属性	支持	描述
action_group	操作组： community.crypto.acme、acme	在 `module_defaults` 中使用 `group/acme` 或 `group/community.crypto.acme` 为此模块设置默认值。
check_mode	支持：不支持	可以在 `check_mode` 下运行并返回更改状态预测，而无需修改目标。
diff_mode	支持：不支持	在差异模式下，将返回有关已更改内容（或在 `check_mode` 中可能需要更改的内容）的详细信息。

备注 

注意

必须指定以下选项中的一个：account_key_src、account_key_content、private_key_src 或 private-key-content。
尝试撤销已撤销的证书应导致状态不变，即使撤销原因与此处指定的不同。此外，根据服务器的不同，如果证书已被撤销，则可能会返回其他错误。
尽管默认值的选择使得该模块可以与 Let’s Encrypt CA 一起使用，但原则上该模块可以与任何提供 ACME 端点的 CA 一起使用，例如 Buypass Go SSL。
到目前为止，ACME 模块仅由开发人员针对 Let’s Encrypt（暂存和生产）、Buypass（暂存和生产）、ZeroSSL（生产）和 Pebble 测试服务器进行了测试。我们收到了社区的反馈，表明它们也可以与 Sectigo ACME Service for InCommon 一起使用。如果您在其他 ACME 服务器上遇到问题，请创建问题以帮助我们支持它。我们也感谢您反馈未提及的 ACME 服务器是否正常工作。
如果可以使用足够新的 cryptography 库版本（有关详细信息，请参阅要求），它将代替 openssl 二进制文件使用。可以使用 select_crypto_backend 选项显式禁用或启用此功能。请注意，使用 openssl 二进制文件会更慢且安全性更低，因为私钥内容始终必须存储在磁盘上（请参阅 account_key_content）。

另请参阅 

另请参阅

Let’s Encrypt 文档: Let’s Encrypt 认证机构的文档。例如，提供有关速率限制的有用信息。
自动证书管理环境 (ACME): ACME 协议规范 (RFC 8555)。
community.crypto.acme_inspect: 允许调试问题。

示例 

- name: Revoke certificate with account key
  community.crypto.acme_certificate_revoke:
    account_key_src: /etc/pki/cert/private/account.key
    certificate: /etc/httpd/ssl/sample.com.crt

- name: Revoke certificate with certificate's private key
  community.crypto.acme_certificate_revoke:
    private_key_src: /etc/httpd/ssl/sample.com.key
    certificate: /etc/httpd/ssl/sample.com.crt

作者

Felix Fontein (@felixfontein)