community.crypto.get_certificate module – Get a certificate from a host:port

Note

This module is part of the community.crypto collection (version 2.22.0).

It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.crypto. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: community.crypto.get_certificate.

Synopsis

  • Makes a secure connection and returns information about the presented certificate.

  • The module uses the cryptography Python library.

  • Support SNI (Server Name Indication) only with Python 2.7 and newer.

Requirements

The below requirements are needed on the host that executes this module.

Parameters

Parameter

Comments

asn1_base64

boolean

added in community.crypto 2.12.0

Whether to encode the ASN.1 values in the extensions return value with Base64 or not.

The documentation claimed for a long time that the values are Base64 encoded, but they never were. For compatibility this option is set to false.

The default value false is deprecated and will change to true in community.crypto 3.0.0.

Choices:

  • false

  • true

ca_cert

path

A PEM file containing one or more root certificates; if present, the cert will be validated against these root certs.

Note that this only validates the certificate is signed by the chain; not that the cert is valid for the host presenting it.

ciphers

list / elements=string

added in community.crypto 2.11.0

SSL/TLS Ciphers to use for the request.

When a list is provided, all ciphers are joined in order with :.

See the OpenSSL Cipher List Format for more details.

The available ciphers is dependent on the Python and OpenSSL/LibreSSL versions.

get_certificate_chain

boolean

added in community.crypto 2.21.0

If set to true, will obtain the certificate chain next to the certificate itself.

The chain as returned by the server can be found in unverified_chain, and the chain that passed validation in verified_chain.

Note that this needs Python 3.10 or newer. Also note that only Python 3.13 or newer officially supports this. The module uses internal APIs of Python 3.10, 3.11, and 3.12 to achieve the same. It can be that future versions of Python 3.10, 3.11, or 3.12 break this.

Choices:

  • false ← (default)

  • true

host

string / required

The host to get the cert for (IP is fine).

port

integer / required

The port to connect to.

proxy_host

string

Proxy host used when get a certificate.

proxy_port

integer

Proxy port used when get a certificate.

Default: 8080

select_crypto_backend

string

Determines which crypto backend to use.

The default choice is auto, which tries to use cryptography if available.

If set to cryptography, will try to use the cryptography library.

Choices:

  • "auto" ← (default)

  • "cryptography"

server_name

string

added in community.crypto 1.4.0

Server name used for SNI (Server Name Indication) when hostname is an IP or is different from server name.

starttls

string

added in community.crypto 1.9.0

Requests a secure connection for protocols which require clients to initiate encryption.

Only available for mysql currently.

Choices:

  • "mysql"

timeout

integer

The timeout in seconds.

Default: 10

tls_ctx_options

list / elements=any

added in community.crypto 2.21.0

TLS context options (TLS/SSL OP flags) to use for the request.

See the List of SSL OP Flags for more details.

The available TLS context options is dependent on the Python and OpenSSL/LibreSSL versions.

Attributes

Attribute

Support

Description

check_mode

Support: none

This action does not modify state.

Can run in check_mode and return changed status prediction without modifying target.

diff_mode

Support: N/A

This action does not modify state.

Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode.

Notes

Note

  • When using ca_cert on OS X it has been reported that in some conditions the validate will always succeed.

See Also

See also

community.crypto.to_serial filter plugin

Convert an integer to a colon-separated list of hex numbers.

Examples

- 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

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key

Description

cert

string

The certificate retrieved from the port.

Returned: success

expired

boolean

Boolean indicating if the cert is expired.

Returned: success

extensions

list / elements=dictionary

Extensions applied to the cert.

Returned: success

asn1_data

string

The ASN.1 content of the extension.

If asn1_base64=true this will be Base64 encoded, otherwise the raw binary value will be returned.

Please note that the raw binary value might not survive JSON serialization to the Ansible controller, and also might cause failures when displaying it. See https://github.com/ansible/ansible/issues/80258 for more information.

Note that depending on the cryptography version used, it is not possible to extract the ASN.1 content of the extension, but only to provide the re-encoded content of the extension in case it was parsed by cryptography. This should usually result in exactly the same value, except if the original extension value was malformed.

Returned: success

critical

boolean

Whether the extension is critical.

Returned: success

name

string

The extension’s name.

Returned: success

issuer

dictionary

Information about the issuer of the cert.

Returned: success

not_after

string

Expiration date of the cert.

Returned: success

not_before

string

Issue date of the cert.

Returned: success

serial_number

integer

The serial number of the cert.

This return value is an integer. If you need the serial numbers as a colon-separated hex string, such as 11:22:33, you need to convert it to that form with community.crypto.to_serial.

Returned: success

signature_algorithm

string

The algorithm used to sign the cert.

Returned: success

subject

dictionary

Information about the subject of the cert (OU, CN, and so on).

Returned: success

unverified_chain

list / elements=string

added in community.crypto 2.21.0

The certificate chain retrieved from the port.

The first entry is always cert.

Returned: success and get_certificate_chain=true

verified_chain

list / elements=string

added in community.crypto 2.21.0

The verified certificate chain retrieved from the port.

The first entry is always cert.

The last certificate the root certificate the chain is traced to. If ca_cert is provided this certificate is part of that store; otherwise it is part of the store used by default by Python.

Note that unverified_chain generally does not contain the root certificate, and might contain other certificates that are not part of the validated chain.

Returned: success and get_certificate_chain=true

version

string

The version number of the certificate.

Returned: success

Authors

  • John Westcott IV (@john-westcott-iv)