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 协议（例如 Let’s Encrypt 等 CA 支持的协议）向 ACME 服务器发送直接请求。
此模块可用于调试证书请求尝试失败的情况，例如当 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`
内容字符串	如果`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"}
请求头字典	请求的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"}
输出JSON 字典	解析为JSON的输出返回：如果输出可以解析为JSON 示例： `[{"id": 12345}, {"key": [{"kty": "RSA"}, "..."]}]`
输出文本字符串	原始文本输出返回：始终示例： `"{\n \"id\": 12345,\n \"key\": {\n \"kty\": \"RSA\",\n ..."`

作者

Felix Fontein (@felixfontein)

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

作者

资源链接