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

注意

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

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

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

要在剧本中使用它，请指定： 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	支持： N/A 此操作不会修改状态。	在差异模式下，将返回有关已更改内容（或可能需要在 `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 模块 – 从主机:端口获取证书

作者

资源链接