community.crypto.acme_inspect 模块 – 向 ACME 服务器发送直接请求

注意

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

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

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

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

概要

• 允许使用 ACME 协议 向 ACME 服务器发送直接请求，ACME 协议受 Let's Encrypt 等 CA 支持。

• 此模块可用于调试证书请求尝试失败的情况，例如，当 community.crypto.acme_certificate 失败或遇到您希望调查的问题时。

• 此模块还可用于直接访问 Ansible ACME 模块尚不支持的 ACME 服务器功能。

要求

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

• openssl 或 cryptography >= 1.5

• ipaddress

参数

参数	注释
account_key_content 字符串	ACME 账户 RSA 或椭圆曲线密钥的内容。 与 account_key_src 互斥。 如果未使用 account_key_src，则需要此参数。 **警告：**内容将写入临时文件，模块完成后 Ansible 将删除该文件。由于这是一个重要的私钥——它可以用来更改帐户密钥，或者在不知道其私钥的情况下吊销您的证书——这可能不可接受。 如果使用 cryptography，则内容不会写入临时文件。Ansible 在将模块及其参数移动到执行它的节点的过程中，仍然可能将其写入磁盘。
account_key_passphrase 字符串 在 community.crypto 1.6.0 中添加	用于解码帐户密钥的密码。 **注意：**openssl 后端不支持此功能，仅 cryptography 后端支持。
account_key_src 别名：account_key 路径	包含 ACME 账户 RSA 或椭圆曲线密钥的文件路径。 可以使用 community.crypto.openssl_privatekey 或 community.crypto.openssl_privatekey_pipe 模块创建私钥。如果所需的 (cryptography) 库不可用，也可以使用 openssl 命令行工具直接创建密钥：可以使用 openssl genrsa ... 创建 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
content 字符串	如果 method 为 post，则此参数为一个将作为内容发送的编码 JSON 对象。 当 method 为 post 时，此参数为必填项；其他情况下不允许。
fail_on_acme_error 布尔值	如果 method 为 post 或 get，则在返回 ACME 错误时，使模块失败。 选项 false true ← (默认值)
method 字符串	用于访问 ACME 服务器上指定 URL 的方法。 post 值将执行经过身份验证的 POST 请求。内容必须在 content 选项中指定。 get 值将对 ACME v2 执行经过身份验证的 POST-as-GET 请求，对 ACME v1 执行常规 GET 请求。 directory-only 值仅检索目录，不执行请求。 选项 "get" ← (默认值) "post" "directory-only"
request_timeout 整数 在 community.crypto 2.3.0 中添加	Ansible 应等待 ACME API 响应的时间。 此超时适用于所有 HTTP(S) 请求 (HEAD、GET、POST)。 默认值： 10
select_crypto_backend 字符串	确定要使用的加密后端。 默认选项为 auto，如果可用，则尝试使用 cryptography，否则回退到 openssl。 如果设置为 openssl，将尝试使用 openssl 二进制文件。 如果设置为 cryptography，将尝试使用 cryptography 库。 选项 "auto" ← (默认值) "cryptography" "openssl"
url 字符串	要发送请求的 URL。 如果 method 不是 directory-only，则必须指定此参数。
validate_certs 布尔值	是否验证对 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 中更改的内容）的详细信息。

备注

注意

• 对于正确验证的 ACME v2 请求（new-account 请求除外），必须指定 account_uri 选项。

• 使用 ansible 工具，community.crypto.acme_inspect 可用于直接执行 ACME 请求，无需编写剧本。例如，以下命令从 Let’s Encrypt 检索 ID 为 1 的 ACME 帐户（假设 /path/to/key 是正确的私有帐户密钥）：ansible localhost -m acme_inspect -a "account_key_src=/path/to/key acme_directory=https://acme-v02.api.letsencrypt.org/directory acme_version=2 account_uri=https://acme-v02.api.letsencrypt.org/acme/acct/1 method=get url=https://acme-v02.api.letsencrypt.org/acme/acct/1"

• 尽管默认值的选择使得该模块可以与 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）。

另请参阅

另请参阅

自动证书管理环境 (ACME)

ACME 协议规范 (RFC 8555)。

ACME TLS ALPN 质询扩展

tls-alpn-01 质询的规范 (RFC 8737)。

示例

- name: Get directory
  community.crypto.acme_inspect:
    acme_directory: https://acme-staging-v02.api.letsencrypt.org/directory
    acme_version: 2
    method: directory-only
  register: directory

- name: Create an account
  community.crypto.acme_inspect:
    acme_directory: https://acme-staging-v02.api.letsencrypt.org/directory
    acme_version: 2
    account_key_src: /etc/pki/cert/private/account.key
    url: "{{ directory.newAccount}}"
    method: post
    content: '{"termsOfServiceAgreed":true}'
  register: account_creation
  # account_creation.headers.location contains the account URI
  # if creation was successful

- name: Get account information
  community.crypto.acme_inspect:
    acme_directory: https://acme-staging-v02.api.letsencrypt.org/directory
    acme_version: 2
    account_key_src: /etc/pki/cert/private/account.key
    account_uri: "{{ account_creation.headers.location }}"
    url: "{{ account_creation.headers.location }}"
    method: get

- name: Update account contacts
  community.crypto.acme_inspect:
    acme_directory: https://acme-staging-v02.api.letsencrypt.org/directory
    acme_version: 2
    account_key_src: /etc/pki/cert/private/account.key
    account_uri: "{{ account_creation.headers.location }}"
    url: "{{ account_creation.headers.location }}"
    method: post
    content: '{{ account_info | to_json }}'
  vars:
    account_info:
      # For valid values, see
      # https://tools.ietf.org/html/rfc8555#section-7.3
      contact:
      - mailto:[email protected]

- name: Create certificate order
  community.crypto.acme_certificate:
    acme_directory: https://acme-staging-v02.api.letsencrypt.org/directory
    acme_version: 2
    account_key_src: /etc/pki/cert/private/account.key
    account_uri: "{{ account_creation.headers.location }}"
    csr: /etc/pki/cert/csr/sample.com.csr
    fullchain_dest: /etc/httpd/ssl/sample.com-fullchain.crt
    challenge: http-01
  register: certificate_request

# Assume something went wrong. certificate_request.order_uri contains
# the order URI.

- name: Get order information
  community.crypto.acme_inspect:
    acme_directory: https://acme-staging-v02.api.letsencrypt.org/directory
    acme_version: 2
    account_key_src: /etc/pki/cert/private/account.key
    account_uri: "{{ account_creation.headers.location }}"
    url: "{{ certificate_request.order_uri }}"
    method: get
  register: order

- name: Get first authz for order
  community.crypto.acme_inspect:
    acme_directory: https://acme-staging-v02.api.letsencrypt.org/directory
    acme_version: 2
    account_key_src: /etc/pki/cert/private/account.key
    account_uri: "{{ account_creation.headers.location }}"
    url: "{{ order.output_json.authorizations[0] }}"
    method: get
  register: authz

- name: Get HTTP-01 challenge for authz
  community.crypto.acme_inspect:
    acme_directory: https://acme-staging-v02.api.letsencrypt.org/directory
    acme_version: 2
    account_key_src: /etc/pki/cert/private/account.key
    account_uri: "{{ account_creation.headers.location }}"
    url: "{{ authz.output_json.challenges | selectattr('type', 'equalto', 'http-01') }}"
    method: get
  register: http01challenge

- name: Activate HTTP-01 challenge manually
  community.crypto.acme_inspect:
    acme_directory: https://acme-staging-v02.api.letsencrypt.org/directory
    acme_version: 2
    account_key_src: /etc/pki/cert/private/account.key
    account_uri: "{{ account_creation.headers.location }}"
    url: "{{ http01challenge.url }}"
    method: post
    content: '{}'

返回值

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

键	描述
directory 字典	ACME 目录的内容 返回：始终返回 示例： {"a85k3x9f91A4": "https://community.letsencrypt.org/t/adding-random-entries-to-the-directory/33417", "keyChange": "https://acme-v02.api.letsencrypt.org/acme/key-change", "meta": {"caaIdentities": ["letsencrypt.org"], "termsOfService": "https://letsencrypt.openssl.ac.cn/documents/LE-SA-v1.2-November-15-2017.pdf", "website": "https://letsencrypt.openssl.ac.cn"}, "newAccount": "https://acme-v02.api.letsencrypt.org/acme/new-acct", "newNonce": "https://acme-v02.api.letsencrypt.org/acme/new-nonce", "newOrder": "https://acme-v02.api.letsencrypt.org/acme/new-order", "revokeCert": "https://acme-v02.api.letsencrypt.org/acme/revoke-cert"}
headers 字典	请求的 HTTP 头 (使用小写键) 返回：始终返回 示例： {"boulder-requester": "12345", "cache-control": "max-age=0, no-cache, no-store", "connection": "close", "content-length": "904", "content-type": "application/json", "cookies": {}, "cookies_string": "", "date": "Wed, 07 Nov 2018 12:34:56 GMT", "expires": "Wed, 07 Nov 2018 12:44:56 GMT", "link": "<https://letsencrypt.openssl.ac.cn/documents/LE-SA-v1.2-November-15-2017.pdf>;rel=\"terms-of-service\"", "msg": "OK (904 bytes)", "pragma": "no-cache", "replay-nonce": "1234567890abcdefghijklmnopqrstuvwxyzABCDEFGH", "server": "nginx", "status": 200, "strict-transport-security": "max-age=604800", "url": "https://acme-v02.api.letsencrypt.org/acme/acct/46161", "x-frame-options": "DENY"}
output_json 字典	输出结果被解析为 JSON 返回：如果输出可以被解析为 JSON 示例： [{"id": 12345}, {"key": [{"kty": "RSA"}, "..."]}]
output_text 字符串	原始文本输出 返回：始终返回 示例： "{\n  \"id\": 12345,\n  \"key\": {\n    \"kty\": \"RSA\",\n ..."

作者

• Felix Fontein (@felixfontein)

资源链接

• 问题追踪
• 代码库 (源码)
• 寻求帮助 (加密)
• 寻求帮助 (ACME)
• 提交错误报告
• 请求新功能
• 通信