get_certificate – Get a certificate from a host:port — Ansible Documentation

- AnsibleFest
- Products
- Community
- Webinars & Training
- Blog

Documentation

# get_certificate – Get a certificate from a host:port

New in version 2.8.

- Synopsis
- Requirements
- Parameters
- Notes
- Examples
- Return Values
- Status

## 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 Ansible 2.13.”

## 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 added in 2.9 |  | Proxy host used when get a certificate.
proxy_port integer added in 2.9 | Default: 8080 | Proxy port used when get a certificate.
select_crypto_backend string added in 2.9 | 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.
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
      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
      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

## Status

- This module is not guaranteed to have a backwards compatible interface. [preview]
- This module is maintained by the Ansible Community. [community]

### Authors

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

Hint

If you notice any issues in this documentation, you can edit this document to improve it.