You are reading an unmaintained version of the Ansible documentation. Unmaintained Ansible versions can contain unfixed security vulnerabilities (CVE). Please upgrade to a maintained version. See the latest Ansible documentation.

community.crypto.x509_certificate_info – Provide information of OpenSSL X.509 certificates

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

Synopsis

• This module allows one to query information on OpenSSL certificates.

• It uses the pyOpenSSL or cryptography python library to interact with OpenSSL. If both the cryptography and PyOpenSSL libraries are available (and meet the minimum version requirements) cryptography will be preferred as a backend over PyOpenSSL (unless the backend is forced with select_crypto_backend). Please note that the PyOpenSSL backend was deprecated in Ansible 2.9 and will be removed in community.crypto 2.0.0.

• Note that this module was called openssl_certificate_info when included directly in Ansible up to version 2.9. When moved to the collection community.crypto, it was renamed to community.crypto.x509_certificate_info. From Ansible 2.10 on, it can still be used by the old short name (or by ansible.builtin.openssl_certificate_info), which redirects to community.crypto.x509_certificate_info. When using FQCNs or when using the collections keyword, the new name community.crypto.x509_certificate_info should be used to avoid a deprecation warning.

Requirements

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

• PyOpenSSL >= 0.15 or cryptography >= 1.6

Parameters

Parameter	Comments
content string added in 1.0.0 of community.crypto	Content of the X.509 certificate in PEM format. Either path or content must be specified, but not both.
path path	Remote absolute path where the certificate file is loaded from. Either path or content must be specified, but not both.
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. Please note that the pyopenssl backend has been deprecated in Ansible 2.9, and will be removed in community.crypto 2.0.0. From that point on, only the cryptography backend will be available. Choices: auto ← (default) cryptography pyopenssl
valid_at dictionary	A dict of names mapping to time specifications. Every time specified here will be checked whether the certificate is valid at this point. See the valid_at return value for informations on the result. Time can be specified either as relative time or as absolute timestamp. Time will always be interpreted as UTC. Valid format is [+-]timespec | ASN.1 TIME where timespec can be an integer + [w | d | h | m | s] (e.g. +32w1d2h, and ASN.1 TIME (in other words, pattern YYYYMMDDHHMMSSZ). Note that all timestamps will be treated as being in UTC.

Notes

Note

• All timestamp values are provided in ASN.1 TIME format, in other words, following the YYYYMMDDHHMMSSZ pattern. They are all in UTC.

• Supports check_mode.

See Also

See also

community.crypto.x509_certificate

The official documentation on the community.crypto.x509_certificate module.

community.crypto.x509_certificate_pipe

The official documentation on the community.crypto.x509_certificate_pipe module.

Examples

- name: Generate a Self Signed OpenSSL certificate
  community.crypto.x509_certificate:
    path: /etc/ssl/crt/ansible.com.crt
    privatekey_path: /etc/ssl/private/ansible.com.pem
    csr_path: /etc/ssl/csr/ansible.com.csr
    provider: selfsigned


# Get information on the certificate

- name: Get information on generated certificate
  community.crypto.x509_certificate_info:
    path: /etc/ssl/crt/ansible.com.crt
  register: result

- name: Dump information
  ansible.builtin.debug:
    var: result


# Check whether the certificate is valid or not valid at certain times, fail
# if this is not the case. The first task (x509_certificate_info) collects
# the information, and the second task (assert) validates the result and
# makes the playbook fail in case something is not as expected.

- name: Test whether that certificate is valid tomorrow and/or in three weeks
  community.crypto.x509_certificate_info:
    path: /etc/ssl/crt/ansible.com.crt
    valid_at:
      point_1: "+1d"
      point_2: "+3w"
  register: result

- name: Validate that certificate is valid tomorrow, but not in three weeks
  assert:
    that:
      - result.valid_at.point_1      # valid in one day
      - not result.valid_at.point_2  # not valid in three weeks

Return Values

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

Key	Description
authority_cert_issuer list / elements=string	The certificate’s authority cert issuer as a list of general names. Is none if the AuthorityKeyIdentifier extension is not present. Returned: success and if the pyOpenSSL backend is not used Sample: “[DNS:www.ansible.com, IP:1.2.3.4]”
authority_cert_serial_number integer	The certificate’s authority cert serial number. Is none if the AuthorityKeyIdentifier extension is not present. Returned: success and if the pyOpenSSL backend is not used Sample: “12345”
authority_key_identifier string	The certificate’s authority key identifier. The identifier is returned in hexadecimal, with : used to separate bytes. Is none if the AuthorityKeyIdentifier extension is not present. Returned: success and if the pyOpenSSL backend is not used Sample: “00:11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee:ff:00:11:22:33”
basic_constraints list / elements=string	Entries in the basic_constraints extension, or none if extension is not present. Returned: success Sample: “[CA:TRUE, pathlen:1]”
basic_constraints_critical boolean	Whether the basic_constraints extension is critical. Returned: success
expired boolean	Whether the certificate is expired (in other words, notAfter is in the past). Returned: success
extended_key_usage list / elements=string	Entries in the extended_key_usage extension, or none if extension is not present. Returned: success Sample: “[Biometric Info, DVCS, Time Stamping]”
extended_key_usage_critical boolean	Whether the extended_key_usage extension is critical. Returned: success
extensions_by_oid dictionary	Returns a dictionary for every extension OID. Returned: success Sample: “{\”1.3.6.1.5.5.7.1.24\”: { \”critical\”: false, \”value\”: \”MAMCAQU=\”}}”
critical boolean	Whether the extension is critical. Returned: success
value string	The Base64 encoded value (in DER format) of the extension. Returned: success Sample: “MAMCAQU=”
fingerprints dictionary added in 1.2.0 of community.crypto	Fingerprints of the DER-encoded form of the whole certificate. For every hash algorithm available, the fingerprint is computed. Returned: success Sample: “{\u0027sha256\u0027: \u0027d4:b3:aa:6d:c8:04:ce:4e:ba:f6:29:4d:92:a3:94:b0:c2:ff:bd:bf:33:63:11:43:34:0f:51:b0:95:09:2f:63\u0027, \u0027sha512\u0027: \u0027f7:07:4a:f0:b0:f0:e6:8b:95:5f:f9:e6:61:0a:32:68:f1…”
issuer dictionary	The certificate’s issuer. Note that for repeated values, only the last one will be returned. Returned: success Sample: “{\”organizationName\”: \”Ansible\”, \”commonName\”: \”ca.example.com\”}”
issuer_ordered list / elements=list	The certificate’s issuer as an ordered list of tuples. Returned: success Sample: “[[\”organizationName\”, \”Ansible\”], [\”commonName\”: \”ca.example.com\”]]”
key_usage string	Entries in the key_usage extension, or none if extension is not present. Returned: success Sample: “[Key Agreement, Data Encipherment]”
key_usage_critical boolean	Whether the key_usage extension is critical. Returned: success
not_after string	notAfter date as ASN.1 TIME. Returned: success Sample: “20190413202428Z”
not_before string	notBefore date as ASN.1 TIME. Returned: success Sample: “20190331202428Z”
ocsp_must_staple boolean	yes if the OCSP Must Staple extension is present, none otherwise. Returned: success
ocsp_must_staple_critical boolean	Whether the ocsp_must_staple extension is critical. Returned: success
ocsp_uri string	The OCSP responder URI, if included in the certificate. Will be none if no OCSP responder URI is included. Returned: success
public_key string	Certificate’s public key in PEM format. Returned: success Sample: “—–BEGIN PUBLIC KEY—–\nMIICIjANBgkqhkiG9w0BAQEFAAOCAg8A…”
public_key_data dictionary added in 1.7.0 of community.crypto	Public key data. Depends on the public key’s type. Returned: success
curve string	The curve’s name for ECC. Returned: When public_key_type=ECC
exponent integer	The RSA key’s public exponent. Returned: When public_key_type=RSA
exponent_size integer	The maximum number of bits of a private key. This is basically the bit size of the subgroup used. Returned: When public_key_type=ECC
g integer	The g value for DSA. This is the element spanning the subgroup of the multiplicative group of the prime field used. Returned: When public_key_type=DSA
modulus integer	The RSA key’s modulus. Returned: When public_key_type=RSA
p integer	The p value for DSA. This is the prime modulus upon which arithmetic takes place. Returned: When public_key_type=DSA
q integer	The q value for DSA. This is a prime that divides p - 1, and at the same time the order of the subgroup of the multiplicative group of the prime field used. Returned: When public_key_type=DSA
size integer	Bit size of modulus (RSA) or prime number (DSA). Returned: When public_key_type=RSA or public_key_type=DSA
x integer	The x coordinate for the public point on the elliptic curve. Returned: When public_key_type=ECC
y integer	For public_key_type=ECC, this is the y coordinate for the public point on the elliptic curve. For public_key_type=DSA, this is the publicly known group element whose discrete logarithm w.r.t. g is the private key. Returned: When public_key_type=DSA or public_key_type=ECC
public_key_fingerprints dictionary	Fingerprints of certificate’s public key. For every hash algorithm available, the fingerprint is computed. Returned: success Sample: “{\u0027sha256\u0027: \u0027d4:b3:aa:6d:c8:04:ce:4e:ba:f6:29:4d:92:a3:94:b0:c2:ff:bd:bf:33:63:11:43:34:0f:51:b0:95:09:2f:63\u0027, \u0027sha512\u0027: \u0027f7:07:4a:f0:b0:f0:e6:8b:95:5f:f9:e6:61:0a:32:68:f1…”
public_key_type string added in 1.7.0 of community.crypto	The certificate’s public key’s type. One of RSA, DSA, ECC, Ed25519, X25519, Ed448, or X448. Will start with unknown if the key type cannot be determined. Returned: success Sample: “RSA”
serial_number integer	The certificate’s serial number. Returned: success Sample: 1234
signature_algorithm string	The signature algorithm used to sign the certificate. Returned: success Sample: “sha256WithRSAEncryption”
subject dictionary	The certificate’s subject as a dictionary. Note that for repeated values, only the last one will be returned. Returned: success Sample: “{\”commonName\”: \”www.example.com\”, \”emailAddress\”: \”test@example.com\”}”
subject_alt_name list / elements=string	Entries in the subject_alt_name extension, or none if extension is not present. Returned: success Sample: “[DNS:www.ansible.com, IP:1.2.3.4]”
subject_alt_name_critical boolean	Whether the subject_alt_name extension is critical. Returned: success
subject_key_identifier string	The certificate’s subject key identifier. The identifier is returned in hexadecimal, with : used to separate bytes. Is none if the SubjectKeyIdentifier extension is not present. Returned: success and if the pyOpenSSL backend is not used Sample: “00:11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee:ff:00:11:22:33”
subject_ordered list / elements=list	The certificate’s subject as an ordered list of tuples. Returned: success Sample: “[[\”commonName\”, \”www.example.com\”], [\”emailAddress\”: \”test@example.com\”]]”
valid_at dictionary	For every time stamp provided in the valid_at option, a boolean whether the certificate is valid at that point in time or not. Returned: success
version integer	The certificate version. Returned: success Sample: 3

Authors

• Felix Fontein (@felixfontein)

• Yanis Guenane (@Spredzy)

• Markus Teufelberger (@MarkusTeufelberger)