#!/usr/bin/python # -*- coding: utf-8 -*- # Copyright: (c) 2016-2017, Yanis Guenane # Copyright: (c) 2017, Markus Teufelberger # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) from __future__ import absolute_import, division, print_function __metaclass__ = type DOCUMENTATION = r''' --- module: x509_certificate_info short_description: Provide information of OpenSSL X.509 certificates description: - 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 C(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 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 C(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. requirements: - PyOpenSSL >= 0.15 or cryptography >= 1.6 author: - Felix Fontein (@felixfontein) - Yanis Guenane (@Spredzy) - Markus Teufelberger (@MarkusTeufelberger) options: path: description: - Remote absolute path where the certificate file is loaded from. - Either I(path) or I(content) must be specified, but not both. type: path content: description: - Content of the X.509 certificate in PEM format. - Either I(path) or I(content) must be specified, but not both. type: str version_added: '1.0.0' 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 C(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 C([+-]timespec | ASN.1 TIME) where timespec can be an integer + C([w | d | h | m | s]) (e.g. C(+32w1d2h), and ASN.1 TIME (in other words, pattern C(YYYYMMDDHHMMSSZ)). Note that all timestamps will be treated as being in UTC. type: dict select_crypto_backend: description: - Determines which crypto backend to use. - The default choice is C(auto), which tries to use C(cryptography) if available, and falls back to C(pyopenssl). - If set to C(pyopenssl), will try to use the L(pyOpenSSL,https://pypi.org/project/pyOpenSSL/) library. - If set to C(cryptography), will try to use the L(cryptography,https://cryptography.io/) library. - Please note that the C(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 C(cryptography) backend will be available. type: str default: auto choices: [ auto, cryptography, pyopenssl ] notes: - All timestamp values are provided in ASN.1 TIME format, in other words, following the C(YYYYMMDDHHMMSSZ) pattern. They are all in UTC. - Supports C(check_mode). seealso: - module: community.crypto.x509_certificate - module: community.crypto.x509_certificate_pipe ''' EXAMPLES = r''' - 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 = r''' expired: description: Whether the certificate is expired (in other words, C(notAfter) is in the past). returned: success type: bool basic_constraints: description: Entries in the C(basic_constraints) extension, or C(none) if extension is not present. returned: success type: list elements: str sample: "[CA:TRUE, pathlen:1]" basic_constraints_critical: description: Whether the C(basic_constraints) extension is critical. returned: success type: bool extended_key_usage: description: Entries in the C(extended_key_usage) extension, or C(none) if extension is not present. returned: success type: list elements: str sample: "[Biometric Info, DVCS, Time Stamping]" extended_key_usage_critical: description: Whether the C(extended_key_usage) extension is critical. returned: success type: bool extensions_by_oid: description: Returns a dictionary for every extension OID. returned: success type: dict contains: critical: description: Whether the extension is critical. returned: success type: bool value: description: The Base64 encoded value (in DER format) of the extension. returned: success type: str sample: "MAMCAQU=" sample: '{"1.3.6.1.5.5.7.1.24": { "critical": false, "value": "MAMCAQU="}}' key_usage: description: Entries in the C(key_usage) extension, or C(none) if extension is not present. returned: success type: str sample: "[Key Agreement, Data Encipherment]" key_usage_critical: description: Whether the C(key_usage) extension is critical. returned: success type: bool subject_alt_name: description: Entries in the C(subject_alt_name) extension, or C(none) if extension is not present. returned: success type: list elements: str sample: "[DNS:www.ansible.com, IP:1.2.3.4]" subject_alt_name_critical: description: Whether the C(subject_alt_name) extension is critical. returned: success type: bool ocsp_must_staple: description: C(yes) if the OCSP Must Staple extension is present, C(none) otherwise. returned: success type: bool ocsp_must_staple_critical: description: Whether the C(ocsp_must_staple) extension is critical. returned: success type: bool issuer: description: - The certificate's issuer. - Note that for repeated values, only the last one will be returned. returned: success type: dict sample: '{"organizationName": "Ansible", "commonName": "ca.example.com"}' issuer_ordered: description: The certificate's issuer as an ordered list of tuples. returned: success type: list elements: list sample: '[["organizationName", "Ansible"], ["commonName": "ca.example.com"]]' subject: description: - The certificate's subject as a dictionary. - Note that for repeated values, only the last one will be returned. returned: success type: dict sample: '{"commonName": "www.example.com", "emailAddress": "test@example.com"}' subject_ordered: description: The certificate's subject as an ordered list of tuples. returned: success type: list elements: list sample: '[["commonName", "www.example.com"], ["emailAddress": "test@example.com"]]' not_after: description: C(notAfter) date as ASN.1 TIME. returned: success type: str sample: 20190413202428Z not_before: description: C(notBefore) date as ASN.1 TIME. returned: success type: str sample: 20190331202428Z public_key: description: Certificate's public key in PEM format. returned: success type: str sample: "-----BEGIN PUBLIC KEY-----\nMIICIjANBgkqhkiG9w0BAQEFAAOCAg8A..." public_key_fingerprints: description: - Fingerprints of certificate's public key. - For every hash algorithm available, the fingerprint is computed. returned: success type: dict 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..." fingerprints: description: - Fingerprints of the DER-encoded form of the whole certificate. - For every hash algorithm available, the fingerprint is computed. returned: success type: dict 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..." version_added: 1.2.0 signature_algorithm: description: The signature algorithm used to sign the certificate. returned: success type: str sample: sha256WithRSAEncryption serial_number: description: The certificate's serial number. returned: success type: int sample: 1234 version: description: The certificate version. returned: success type: int sample: 3 valid_at: description: For every time stamp provided in the I(valid_at) option, a boolean whether the certificate is valid at that point in time or not. returned: success type: dict subject_key_identifier: description: - The certificate's subject key identifier. - The identifier is returned in hexadecimal, with C(:) used to separate bytes. - Is C(none) if the C(SubjectKeyIdentifier) extension is not present. returned: success and if the pyOpenSSL backend is I(not) used type: str sample: '00:11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee:ff:00:11:22:33' authority_key_identifier: description: - The certificate's authority key identifier. - The identifier is returned in hexadecimal, with C(:) used to separate bytes. - Is C(none) if the C(AuthorityKeyIdentifier) extension is not present. returned: success and if the pyOpenSSL backend is I(not) used type: str sample: '00:11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee:ff:00:11:22:33' authority_cert_issuer: description: - The certificate's authority cert issuer as a list of general names. - Is C(none) if the C(AuthorityKeyIdentifier) extension is not present. returned: success and if the pyOpenSSL backend is I(not) used type: list elements: str sample: "[DNS:www.ansible.com, IP:1.2.3.4]" authority_cert_serial_number: description: - The certificate's authority cert serial number. - Is C(none) if the C(AuthorityKeyIdentifier) extension is not present. returned: success and if the pyOpenSSL backend is I(not) used type: int sample: '12345' ocsp_uri: description: The OCSP responder URI, if included in the certificate. Will be C(none) if no OCSP responder URI is included. returned: success type: str ''' from ansible.module_utils.basic import AnsibleModule from ansible.module_utils.six import string_types from ansible.module_utils._text import to_native from ansible_collections.community.crypto.plugins.module_utils.crypto.basic import ( OpenSSLObjectError, ) from ansible_collections.community.crypto.plugins.module_utils.crypto.support import ( get_relative_time_option, ) from ansible_collections.community.crypto.plugins.module_utils.crypto.module_backends.certificate_info import ( select_backend, ) def main(): module = AnsibleModule( argument_spec=dict( path=dict(type='path'), content=dict(type='str'), valid_at=dict(type='dict'), select_crypto_backend=dict(type='str', default='auto', choices=['auto', 'cryptography', 'pyopenssl']), ), required_one_of=( ['path', 'content'], ), mutually_exclusive=( ['path', 'content'], ), supports_check_mode=True, ) if module._name == 'community.crypto.openssl_certificate_info': module.deprecate("The 'community.crypto.openssl_certificate_info' module has been renamed to 'community.crypto.x509_certificate_info'", version='2.0.0', collection_name='community.crypto') if module.params['content'] is not None: data = module.params['content'].encode('utf-8') else: try: with open(module.params['path'], 'rb') as f: data = f.read() except (IOError, OSError) as e: module.fail_json(msg='Error while reading certificate file from disk: {0}'.format(e)) backend, module_backend = select_backend(module, module.params['select_crypto_backend'], data) valid_at = module.params['valid_at'] if valid_at: for k, v in valid_at.items(): if not isinstance(v, string_types): module.fail_json( msg='The value for valid_at.{0} must be of type string (got {1})'.format(k, type(v)) ) valid_at[k] = get_relative_time_option(v, 'valid_at.{0}'.format(k)) try: result = module_backend.get_info() not_before = module_backend.get_not_before() not_after = module_backend.get_not_after() result['valid_at'] = dict() if valid_at: for k, v in valid_at.items(): result['valid_at'][k] = not_before <= v <= not_after module.exit_json(**result) except OpenSSLObjectError as exc: module.fail_json(msg=to_native(exc)) if __name__ == "__main__": main()