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

Note

This plugin is part of the community.crypto collection (version 1.4.0).

To install it use: ansible-galaxy collection install community.crypto.

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 can use the cryptography Python library, or the pyOpenSSL Python library. By default, it tries to detect which one is available. This can be overridden with the select_crypto_backend option. Please note that the PyOpenSSL backend was deprecated in Ansible 2.9 and will be removed in community.crypto 2.0.0.

• Support SNI (Server Name Indication) only with python >= 2.7.

Requirements

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

• python >= 2.7 when using proxy_host

• cryptography >= 1.6 or pyOpenSSL >= 0.15

Parameters

Parameter	Choices/Defaults	Comments
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.
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	Default: 8080	Proxy port used when get a certificate.
select_crypto_backend string	Choices: auto ← cryptography pyopenssl	Determines which crypto backend to use. The default choice is auto, which tries to use cryptography if available, and falls back to pyopenssl. If set to pyopenssl, will try to use the pyOpenSSL library. If set to cryptography, will try to use the cryptography library.
server_name string added in 1.4.0 of community.crypto		Server name used for SNI (Server Name Indication) when hostname is an IP or is different from server name.
timeout integer	Default: 10	The timeout in seconds

Notes

Note

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

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
  debug:
    msg: "cert expires in: {{ expire_days }} days."
  vars:
    expire_days: "{{ (( cert.not_after | to_datetime('%Y%m%d%H%M%SZ')) - (ansible_date_time.iso8601 | to_datetime('%Y-%m-%dT%H:%M:%SZ')) ).days }}"

Return Values

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

Key		Returned	Description
cert string		success	The certificate retrieved from the port
expired boolean		success	Boolean indicating if the cert is expired
extensions list / elements=dictionary		success	Extensions applied to the cert
	asn1_data string	success	The Base64 encoded ASN.1 content of the extnesion.
	critical boolean	success	Whether the extension is critical.
	name string	success	The extension's name.
issuer dictionary		success	Information about the issuer of the cert
not_after string		success	Expiration date of the cert
not_before string		success	Issue date of the cert
serial_number string		success	The serial number of the cert
signature_algorithm string		success	The algorithm used to sign the cert
subject dictionary		success	Information about the subject of the cert (OU, CN, etc)
version string		success	The version number of the certificate

Authors

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