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

Note

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

You might already have this collection installed if you are using the ansible package. 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.

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

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

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, 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.

Choices:

  • auto ← (default)

  • cryptography

  • pyopenssl

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.

starttls

string

added in 1.9.0 of community.crypto

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

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

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 Base64 encoded ASN.1 content of the extnesion.

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

string

The serial number of the cert

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, etc)

Returned: success

version

string

The version number of the certificate

Returned: success

Authors

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