Try SpotterProvide information of OpenSSL X.509 certificates
Authors: Felix Fontein (@felixfontein), Yanis Guenane (@Spredzy), Markus Teufelberger (@MarkusTeufelberger)
Install with ansible-galaxy collection install community.crypto:==2.18.0
collections:
- name: community.crypto
version: 2.18.0This module allows one to query information on OpenSSL certificates.
It uses the cryptography python library to interact with OpenSSL.
Note that this module was called C(openssl_certificate_info) when included directly in Ansible up to version 2.9. When moved to the collection C(community.crypto), it was renamed to M(community.crypto.x509_certificate_info). From Ansible 2.10 on, it can still be used by the old short name (or by C(ansible.builtin.openssl_certificate_info)), which redirects to M(community.crypto.x509_certificate_info). When using FQCNs or when using the L(collections,https://docs.ansible.com/ansible/latest/user_guide/collections_using.html#using-collections-in-a-playbook) keyword, the new name M(community.crypto.x509_certificate_info) should be used to avoid a deprecation warning.
- 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
ansible.builtin.assert:
that:
- result.valid_at.point_1 # valid in one day
- not result.valid_at.point_2 # not valid in three weeks
path:
description:
- Remote absolute path where the certificate file is loaded from.
- Either O(path) or O(content) must be specified, but not both.
- PEM and DER formats are supported.
type: path
content:
description:
- Content of the X.509 certificate in PEM format.
- Either O(path) or O(content) must be specified, but not both.
type: str
version_added: 1.0.0
version_added_collection: community.crypto
valid_at:
description:
- 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 RV(valid_at) return
value for information 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 C([+-]timespec | ASN.1 TIME) where timespec can be an integer +
C([w | d | h | m | s]) (for example V(+32w1d2h)), and ASN.1 TIME (in other words,
pattern C(YYYYMMDDHHMMSSZ)). Note that all timestamps will be treated as being in
UTC.
type: dict
name_encoding:
choices:
- ignore
- idna
- unicode
default: ignore
description:
- How to encode names (DNS names, URIs, email addresses) in return values.
- V(ignore) will use the encoding returned by the backend.
- V(idna) will convert all labels of domain names to IDNA encoding. IDNA2008 will
be preferred, and IDNA2003 will be used if IDNA2008 encoding fails.
- V(unicode) will convert all labels of domain names to Unicode. IDNA2008 will be
preferred, and IDNA2003 will be used if IDNA2008 decoding fails.
- B(Note) that V(idna) and V(unicode) require the L(idna Python library,https://pypi.org/project/idna/)
to be installed.
type: str
select_crypto_backend:
choices:
- auto
- cryptography
default: auto
description:
- Determines which crypto backend to use.
- The default choice is V(auto), which tries to use C(cryptography) if available.
- If set to V(cryptography), will try to use the L(cryptography,https://cryptography.io/)
library.
type: str
authority_cert_issuer:
description:
- The certificate's authority cert issuer as a list of general names.
- Is V(none) if the C(AuthorityKeyIdentifier) extension is not present.
- See O(name_encoding) for how IDNs are handled.
elements: str
returned: success
sample:
- DNS:www.ansible.com
- IP:1.2.3.4
type: list
authority_cert_serial_number:
description:
- The certificate's authority cert serial number.
- Is V(none) if the C(AuthorityKeyIdentifier) extension is not present.
- This return value is an B(integer). If you need the serial numbers as a colon-separated
hex string, such as C(11:22:33), you need to convert it to that form with P(community.crypto.to_serial#filter).
returned: success
sample: 12345
type: int
authority_key_identifier:
description:
- The certificate's authority key identifier.
- The identifier is returned in hexadecimal, with V(:) used to separate bytes.
- Is V(none) if the C(AuthorityKeyIdentifier) extension is not present.
returned: success
sample: 00:11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee:ff:00:11:22:33
type: str
basic_constraints:
description: Entries in the C(basic_constraints) extension, or V(none) if extension
is not present.
elements: str
returned: success
sample:
- CA:TRUE
- pathlen:1
type: list
basic_constraints_critical:
description: Whether the C(basic_constraints) extension is critical.
returned: success
type: bool
expired:
description: Whether the certificate is expired (in other words, C(notAfter) is
in the past).
returned: success
type: bool
extended_key_usage:
description: Entries in the C(extended_key_usage) extension, or V(none) if extension
is not present.
elements: str
returned: success
sample:
- Biometric Info
- DVCS
- Time Stamping
type: list
extended_key_usage_critical:
description: Whether the C(extended_key_usage) extension is critical.
returned: success
type: bool
extensions_by_oid:
contains:
critical:
description: Whether the extension is critical.
returned: success
type: bool
value:
description:
- The Base64 encoded value (in DER format) of the extension.
- B(Note) that depending on the C(cryptography) version used, it is not possible
to extract the ASN.1 content of the extension, but only to provide the re-encoded
content of the extension in case it was parsed by C(cryptography). This should
usually result in exactly the same value, except if the original extension
value was malformed.
returned: success
sample: MAMCAQU=
type: str
description: Returns a dictionary for every extension OID.
returned: success
sample:
1.3.6.1.5.5.7.1.24:
critical: false
value: MAMCAQU=
type: dict
fingerprints:
description:
- Fingerprints of the DER-encoded form of the whole certificate.
- For every hash algorithm available, the fingerprint is computed.
returned: success
sample: '{''sha256'': ''d4: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'',
''sha512'': ''f7:07:4a:f0:b0:f0:e6:8b:95:5f:f9:e6:61:0a:32:68:f1...'
type: dict
version_added: 1.2.0
version_added_collection: community.crypto
issuer:
description:
- The certificate's issuer.
- Note that for repeated values, only the last one will be returned.
returned: success
sample:
commonName: ca.example.com
organizationName: Ansible
type: dict
issuer_ordered:
description: The certificate's issuer as an ordered list of tuples.
elements: list
returned: success
sample:
- - organizationName
- Ansible
- - commonName: ca.example.com
type: list
issuer_uri:
description: The Issuer URI, if included in the certificate. Will be V(none) if
no issuer URI is included.
returned: success
type: str
version_added: 2.9.0
version_added_collection: community.crypto
key_usage:
description: Entries in the C(key_usage) extension, or V(none) if extension is not
present.
returned: success
sample:
- Key Agreement
- Data Encipherment
type: str
key_usage_critical:
description: Whether the C(key_usage) extension is critical.
returned: success
type: bool
not_after:
description: C(notAfter) date as ASN.1 TIME.
returned: success
sample: 20190413202428Z
type: str
not_before:
description: C(notBefore) date as ASN.1 TIME.
returned: success
sample: 20190331202428Z
type: str
ocsp_must_staple:
description: V(true) if the OCSP Must Staple extension is present, V(none) otherwise.
returned: success
type: bool
ocsp_must_staple_critical:
description: Whether the C(ocsp_must_staple) extension is critical.
returned: success
type: bool
ocsp_uri:
description: The OCSP responder URI, if included in the certificate. Will be V(none)
if no OCSP responder URI is included.
returned: success
type: str
public_key:
description: Certificate's public key in PEM format.
returned: success
sample: '-----BEGIN PUBLIC KEY-----
MIICIjANBgkqhkiG9w0BAQEFAAOCAg8A...'
type: str
public_key_data:
contains:
curve:
description:
- The curve's name for ECC.
returned: When RV(public_key_type=ECC)
type: str
exponent:
description:
- The RSA key's public exponent.
returned: When RV(public_key_type=RSA)
type: int
exponent_size:
description:
- The maximum number of bits of a private key. This is basically the bit size
of the subgroup used.
returned: When RV(public_key_type=ECC)
type: int
g:
description:
- The C(g) value for DSA.
- This is the element spanning the subgroup of the multiplicative group of the
prime field used.
returned: When RV(public_key_type=DSA)
type: int
modulus:
description:
- The RSA key's modulus.
returned: When RV(public_key_type=RSA)
type: int
p:
description:
- The C(p) value for DSA.
- This is the prime modulus upon which arithmetic takes place.
returned: When RV(public_key_type=DSA)
type: int
q:
description:
- The C(q) value for DSA.
- This is a prime that divides C(p - 1), and at the same time the order of the
subgroup of the multiplicative group of the prime field used.
returned: When RV(public_key_type=DSA)
type: int
size:
description:
- Bit size of modulus (RSA) or prime number (DSA).
returned: When RV(public_key_type=RSA) or RV(public_key_type=DSA)
type: int
x:
description:
- The C(x) coordinate for the public point on the elliptic curve.
returned: When RV(public_key_type=ECC)
type: int
y:
description:
- For RV(public_key_type=ECC), this is the C(y) coordinate for the public point
on the elliptic curve.
- For RV(public_key_type=DSA), this is the publicly known group element whose
discrete logarithm w.r.t. C(g) is the private key.
returned: When RV(public_key_type=DSA) or RV(public_key_type=ECC)
type: int
description:
- Public key data. Depends on the public key's type.
returned: success
type: dict
version_added: 1.7.0
version_added_collection: community.crypto
public_key_fingerprints:
description:
- Fingerprints of certificate's public key.
- For every hash algorithm available, the fingerprint is computed.
returned: success
sample: '{''sha256'': ''d4: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'',
''sha512'': ''f7:07:4a:f0:b0:f0:e6:8b:95:5f:f9:e6:61:0a:32:68:f1...'
type: dict
public_key_type:
description:
- The certificate's public key's type.
- One of V(RSA), V(DSA), V(ECC), V(Ed25519), V(X25519), V(Ed448), or V(X448).
- Will start with V(unknown) if the key type cannot be determined.
returned: success
sample: RSA
type: str
version_added: 1.7.0
version_added_collection: community.crypto
serial_number:
description:
- The certificate's serial number.
- This return value is an B(integer). If you need the serial numbers as a colon-separated
hex string, such as C(11:22:33), you need to convert it to that form with P(community.crypto.to_serial#filter).
returned: success
sample: 1234
type: int
signature_algorithm:
description: The signature algorithm used to sign the certificate.
returned: success
sample: sha256WithRSAEncryption
type: str
subject:
description:
- 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
type: dict
subject_alt_name:
description:
- Entries in the C(subject_alt_name) extension, or V(none) if extension is not present.
- See O(name_encoding) for how IDNs are handled.
elements: str
returned: success
sample:
- DNS:www.ansible.com
- IP:1.2.3.4
type: list
subject_alt_name_critical:
description: Whether the C(subject_alt_name) extension is critical.
returned: success
type: bool
subject_key_identifier:
description:
- The certificate's subject key identifier.
- The identifier is returned in hexadecimal, with V(:) used to separate bytes.
- Is V(none) if the C(SubjectKeyIdentifier) extension is not present.
returned: success
sample: 00:11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee:ff:00:11:22:33
type: str
subject_ordered:
description: The certificate's subject as an ordered list of tuples.
elements: list
returned: success
sample:
- - commonName
- www.example.com
- - emailAddress: test@example.com
type: list
valid_at:
description: For every time stamp provided in the O(valid_at) option, a boolean
whether the certificate is valid at that point in time or not.
returned: success
type: dict
version:
description: The certificate version.
returned: success
sample: 3
type: int