community.crypto.get_certificate 模块 – 从主机:端口获取证书

注意

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

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

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

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

概要 

建立安全连接并返回有关呈现的证书的信息。
该模块使用 cryptography Python 库。
仅在 Python 2.7 及更高版本中支持 SNI（服务器名称指示）。

要求 

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

当使用 proxy_host 时，Python >= 2.7，当 get_certificate_chain=true 时，Python >= 3.10
cryptography >= 1.6

参数 

参数	注释
asn1_base64 布尔值在 community.crypto 2.12.0 中添加	是否使用 Base64 对 `extensions` 返回值中的 ASN.1 值进行编码。文档长期以来声称这些值是 Base64 编码的，但它们从来都不是。为了兼容性，此选项设置为 `false`。默认值 `false` 已弃用，将在 community.crypto 3.0.0 中更改为 `true`。选项 `false` `true`
ca_cert 路径	包含一个或多个根证书的 PEM 文件；如果存在，则将根据这些根证书验证证书。请注意，这仅验证证书是否由链签名；而不是该证书对于呈现它的主机是否有效。
ciphers 列表 / 元素=字符串在 community.crypto 2.11.0 中添加	用于请求的 SSL/TLS 密码。当提供列表时，所有密码都按顺序用 `:` 连接。有关更多详细信息，请参阅 OpenSSL 密码列表格式。可用的密码取决于 Python 和 OpenSSL/LibreSSL 版本。
get_certificate_chain 布尔值在 community.crypto 2.21.0 中添加	如果设置为 `true`，则将获取证书本身的证书链。服务器返回的链可以在 `unverified_chain` 中找到，通过验证的链可以在 `verified_chain` 中找到。注意，这需要 Python 3.10 或更高版本。另请注意，只有 Python 3.13 或更高版本才正式支持此功能。该模块使用 Python 3.10、3.11 和 3.12 的内部 API 来实现相同的功能。Python 3.10、3.11 或 3.12 的未来版本可能会破坏此功能。选项 `false` ← (默认) `true`
host 字符串 / 必需	要获取证书的主机（IP 也可以）。
port 整数 / 必需	要连接的端口。
proxy_host 字符串	获取证书时使用的代理主机。
proxy_port 整数	获取证书时使用的代理端口。默认值： `8080`
select_crypto_backend 字符串	确定要使用的加密后端。默认选择是 `auto`，它会尝试使用 `cryptography` （如果可用）。如果设置为 `cryptography`，将尝试使用 cryptography 库。选项 `"auto"` ← (默认) `"cryptography"`
server_name 字符串在 community.crypto 1.4.0 中添加	当主机名是 IP 或与服务器名称不同时，用于 SNI (服务器名称指示) 的服务器名称。
starttls 字符串在 community.crypto 1.9.0 中添加	为需要客户端启动加密的协议请求安全连接。目前仅适用于 `mysql`。选项 `"mysql"`
timeout 整数	超时时间，单位为秒。默认值： `10`
tls_ctx_options 列表 / 元素=任何在 community.crypto 2.21.0 中添加	用于请求的 TLS 上下文选项 (TLS/SSL OP 标志)。有关详细信息，请参阅 SSL OP 标志列表。可用的 TLS 上下文选项取决于 Python 和 OpenSSL/LibreSSL 版本。

属性 

属性	支持	描述
check_mode	支持：无此操作不会修改状态。	可以在 `check_mode` 中运行，并返回已更改状态预测，而无需修改目标。
diff_mode	支持：不适用此操作不会修改状态。	当处于 diff 模式时，将返回有关已更改内容（或可能需要在 `check_mode` 中更改的内容）的详细信息。

注释 

注意

据报告，在 OS X 上使用 ca_cert 时，在某些情况下验证总是会成功。

另请参阅 

另请参阅

community.crypto.to_serial 过滤器插件: 将整数转换为以冒号分隔的十六进制数字列表。

示例 

- name: Get the cert from an RDP port
  community.crypto.get_certificate:
    host: "1.2.3.4"
    port: 3389
  delegate_to: localhost
  run_once: true
  register: cert

- name: Get a cert from an https port
  community.crypto.get_certificate:
    host: "www.google.com"
    port: 443
  delegate_to: localhost
  run_once: true
  register: cert

- name: How many days until cert expires
  ansible.builtin.debug:
    msg: "cert expires in: {{ expire_days }} days."
  vars:
    expire_days: >-
      {{ (
        (cert.not_after | ansible.builtin.to_datetime('%Y%m%d%H%M%SZ')) -
        (ansible_date_time.iso8601 | ansible.builtin.to_datetime('%Y-%m-%dT%H:%M:%SZ'))
      ).days }}

- name: Allow legacy insecure renegotiation to get a cert from a legacy device
  community.crypto.get_certificate:
    host: "legacy-device.domain.com"
    port: 443
    ciphers:
      - HIGH
    tls_ctx_options:
      - OP_ALL
      - OP_NO_SSLv3
      - OP_CIPHER_SERVER_PREFERENCE
      - OP_ENABLE_MIDDLEBOX_COMPAT
      - OP_NO_COMPRESSION
      - 4 # OP_LEGACY_SERVER_CONNECT
  delegate_to: localhost
  run_once: true
  register: legacy_cert

返回值 

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

键	描述
cert 字符串	从端口检索的证书。已返回：成功
expired 布尔值	指示证书是否已过期的布尔值。已返回：成功
extensions 列表 / 元素=字典	应用于证书的扩展。已返回：成功
asn1_data 字符串	扩展的 ASN.1 内容。如果 `asn1_base64=true`，则此值将进行 Base64 编码，否则将返回原始二进制值。请注意，原始二进制值可能无法在 JSON 序列化到 Ansible 控制器时幸存，并且在显示时也可能导致失败。有关详细信息，请参阅 https://github.com/ansible/ansible/issues/80258。请注意，根据使用的 `cryptography` 版本，可能无法提取扩展的 ASN.1 内容，而只能在 `cryptography` 解析后提供扩展的重新编码内容。如果原始扩展值格式不正确，则通常应产生完全相同的值。已返回：成功
critical 布尔值	扩展是否关键。已返回：成功
name 字符串	扩展的名称。已返回：成功
issuer 字典	有关证书颁发者的信息。已返回：成功
not_after 字符串	证书的到期日期。已返回：成功
not_before 字符串	证书的颁发日期。已返回：成功
serial_number 整数	证书的序列号。此返回值是一个整数。如果需要将序列号作为以冒号分隔的十六进制字符串（例如 `11:22:33`），则需要使用 community.crypto.to_serial 将其转换为该形式。已返回：成功
signature_algorithm 字符串	用于签署证书的算法。已返回：成功
subject 字典	有关证书主题的信息（`OU`，`CN` 等）。已返回：成功
unverified_chain 列表 / 元素=字符串在 community.crypto 2.21.0 中添加	从端口检索的证书链。第一个条目始终为 `cert`。已返回：成功，且 `get_certificate_chain=true`
verified_chain 列表 / 元素=字符串在 community.crypto 2.21.0 中添加	从端口检索的已验证证书链。第一个条目始终为 `cert`。最后一个证书是链追溯到的根证书。如果提供了 `ca_cert`，则此证书是该存储的一部分；否则，它是 Python 默认使用的存储的一部分。请注意，`unverified_chain` 通常不包含根证书，并且可能包含不属于已验证链的其他证书。已返回：成功，且 `get_certificate_chain=true`
version 字符串	证书的版本号。已返回：成功

作者

John Westcott IV (@john-westcott-iv)

community.crypto.get_certificate 模块 – 从主机:端口获取证书

作者

集合链接