community.crypto.get_certificate module – Get a certificate from a host:port
Note
This module is part of the community.crypto collection (version 2.26.5).
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.
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.
Python >= 2.7 when using
proxy_host, and Python >= 3.10 whenget_certificate_chain=truecryptography >= 1.6
Parameters
Parameter |
Comments |
|---|---|
Whether to encode the ASN.1 values in the The documentation claimed for a long time that the values are Base64 encoded, but they never were. For compatibility this option is set to The default value Choices:
|
|
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. |
|
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. |
|
If set to The chain as returned by the server can be found in 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:
|
|
The host to get the cert for (IP is fine). |
|
The port to connect to. |
|
Proxy host used when get a certificate. |
|
Proxy port used when get a certificate. Default: |
|
Determines which crypto backend to use. The default choice is If set to Choices:
|
|
Server name used for SNI (Server Name Indication) when hostname is an IP or is different from server name. |
|
Requests a secure connection for protocols which require clients to initiate encryption. Only available for Choices:
|
|
The timeout in seconds. Default: |
|
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 |
|---|---|---|
Support: none This action does not modify state. |
Can run in |
|
Support: N/A This action does not modify state. |
Will return details on what has changed (or possibly needs changing in |
|
Support: full This action does not modify state. |
When run twice in a row outside check mode, with the same arguments, the second invocation indicates no change. This assumes that the system controlled/queried by the module has not changed in a relevant way. |
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 |
|---|---|
The certificate retrieved from the port. Returned: success |
|
Boolean indicating if the cert is expired. Returned: success |
|
Extensions applied to the cert. Returned: success |
|
The ASN.1 content of the extension. If 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 Returned: success |
|
Whether the extension is critical. Returned: success |
|
The extension’s name. Returned: success |
|
Information about the issuer of the cert. Returned: success |
|
Expiration date of the cert. Returned: success |
|
Issue date of the cert. Returned: success |
|
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 Returned: success |
|
The algorithm used to sign the cert. Returned: success |
|
Information about the subject of the cert ( Returned: success |
|
The certificate chain retrieved from the port. The first entry is always Returned: success and |
|
The verified certificate chain retrieved from the port. The first entry is always The last certificate the root certificate the chain is traced to. If Note that Returned: success and |
|
The version number of the certificate. Returned: success |