diff --git a/plugins/modules/openssh_keypair.py b/plugins/modules/openssh_keypair.py index 8affbb1b..a104045a 100644 --- a/plugins/modules/openssh_keypair.py +++ b/plugins/modules/openssh_keypair.py @@ -12,7 +12,7 @@ DOCUMENTATION = ''' --- module: openssh_keypair author: "David Kainz (@lolcube)" -short_description: Generate OpenSSH private and public keys. +short_description: Generate OpenSSH private and public keys description: - "This module allows one to (re)generate OpenSSH private and public keys. It uses ssh-keygen to generate keys. One can generate C(rsa), C(dsa), C(rsa1), C(ed25519) @@ -59,7 +59,7 @@ options: description: - Allows to configure in which situations the module is allowed to regenerate private keys. The module will always generate a new key if the destination file does not exist. - - By default, the key will be regenerated when it doesn't match the module's options, + - By default, the key will be regenerated when it does not match the module's options, except when the key cannot be read or the passphrase does not match. Please note that this B(changed) for Ansible 2.10. For Ansible 2.9, the behavior was as if C(full_idempotence) is specified. @@ -91,6 +91,7 @@ options: notes: - In case the ssh key is broken or password protected, the module will fail. Set the I(force) option to C(yes) if you want to regenerate the keypair. + - Supports C(check_mode). extends_documentation_fragment: files ''' @@ -118,17 +119,17 @@ EXAMPLES = ''' RETURN = ''' size: - description: Size (in bits) of the SSH private key + description: Size (in bits) of the SSH private key. returned: changed or success type: int sample: 4096 type: - description: Algorithm used to generate the SSH private key + description: Algorithm used to generate the SSH private key. returned: changed or success type: str sample: rsa filename: - description: Path to the generated SSH private key file + description: Path to the generated SSH private key file. returned: changed or success type: str sample: /tmp/id_ssh_rsa @@ -138,12 +139,12 @@ fingerprint: type: str sample: SHA256:r4YCZxihVjedH2OlfjVGI6Y5xAYtdCwk8VxKyzVyYfM public_key: - description: The public key of the generated SSH private key + description: The public key of the generated SSH private key. returned: changed or success type: str sample: ssh-rsa AAAAB3Nza(...omitted...)veL4E3Xcw== test_key comment: - description: The comment of the generated key + description: The comment of the generated key. returned: changed or success type: str sample: test@comment diff --git a/plugins/modules/openssl_dhparam.py b/plugins/modules/openssl_dhparam.py index a02161b4..484f7fbb 100644 --- a/plugins/modules/openssl_dhparam.py +++ b/plugins/modules/openssl_dhparam.py @@ -15,7 +15,7 @@ short_description: Generate OpenSSL Diffie-Hellman Parameters description: - This module allows one to (re)generate OpenSSL DH-params. - This module uses file common arguments to specify generated file permissions. - - "Please note that the module regenerates existing DH params if they don't + - "Please note that the module regenerates existing DH params if they do not match the module's options. If you are concerned that this could overwrite your existing DH params, consider using the I(backup) option." - The module can use the cryptography Python library, or the C(openssl) executable. @@ -71,6 +71,8 @@ options: type: bool default: no version_added: "1.0.0" +notes: +- Supports C(check_mode). extends_documentation_fragment: - files seealso: diff --git a/plugins/modules/openssl_privatekey_info.py b/plugins/modules/openssl_privatekey_info.py index 5fe288ab..648c3d85 100644 --- a/plugins/modules/openssl_privatekey_info.py +++ b/plugins/modules/openssl_privatekey_info.py @@ -65,6 +65,9 @@ options: default: auto choices: [ auto, cryptography, pyopenssl ] +notes: +- Supports C(check_mode). + seealso: - module: community.crypto.openssl_privatekey - module: community.crypto.openssl_privatekey_pipe @@ -81,28 +84,28 @@ EXAMPLES = r''' register: result - name: Dump information - debug: + ansible.builtin.debug: var: result ''' RETURN = r''' can_load_key: - description: Whether the module was able to load the private key from disk + description: Whether the module was able to load the private key from disk. returned: always type: bool can_parse_key: - description: Whether the module was able to parse the private key + description: Whether the module was able to parse the private key. returned: always type: bool key_is_consistent: description: - Whether the key is consistent. Can also return C(none) next to C(yes) and - C(no), to indicate that consistency couldn't be checked. + C(no), to indicate that consistency could not be checked. - In case the check returns C(no), the module will fail. returned: always type: bool public_key: - description: Private key's public key in PEM format + description: Private key's public key in PEM format. returned: success type: str sample: "-----BEGIN PUBLIC KEY-----\nMIICIjANBgkqhkiG9w0BAQEFAAOCAg8A..." diff --git a/plugins/modules/openssl_signature_info.py b/plugins/modules/openssl_signature_info.py index 8a8b2b16..d7f44106 100644 --- a/plugins/modules/openssl_signature_info.py +++ b/plugins/modules/openssl_signature_info.py @@ -14,7 +14,7 @@ module: openssl_signature_info version_added: 1.1.0 short_description: Verify signatures with openssl description: - - This module allows one to verify a signature for a file via a certificate. + - This module allows one to verify a signature for a file by a 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 I(select_crypto_backend) option. Please note that the PyOpenSSL backend @@ -61,6 +61,7 @@ notes: RSA keys: C(cryptography) >= 1.4 DSA and ECDSA keys: C(cryptography) >= 1.5 ed448 and ed25519 keys: C(cryptography) >= 2.6 + - Supports C(check_mode). seealso: - module: community.crypto.openssl_signature - module: community.crypto.x509_certificate @@ -88,7 +89,7 @@ EXAMPLES = r''' RETURN = r''' valid: - description: C(true) means the signature was valid for the given file, C(false) means it wasn't. + description: C(true) means the signature was valid for the given file, C(false) means it was not. returned: success type: bool ''' diff --git a/plugins/modules/x509_certificate.py b/plugins/modules/x509_certificate.py index 7fb649e4..fb6fc2f5 100644 --- a/plugins/modules/x509_certificate.py +++ b/plugins/modules/x509_certificate.py @@ -16,7 +16,7 @@ short_description: Generate and/or check OpenSSL certificates description: - It implements a notion of provider (ie. C(selfsigned), C(ownca), C(acme), C(assertonly), C(entrust)) for your certificate. - - "Please note that the module regenerates existing certificate if it doesn't match the module's + - "Please note that the module regenerates existing certificate if it does not match the module's options, or if it seems to be corrupt. If you are concerned that this could overwrite your existing certificate, consider using the I(backup) option." - Note that this module was called C(openssl_certificate) when included directly in Ansible up to version 2.9. @@ -86,6 +86,9 @@ options: ownca_privatekey_content: version_added: '1.0.0' +notes: +- Supports C(check_mode). + seealso: - module: community.crypto.x509_certificate_pipe @@ -150,8 +153,8 @@ EXAMPLES = r''' # The following example shows one assertonly usage using all existing options for # assertonly, and shows how to emulate the behavior with the x509_certificate_info, # openssl_csr_info, openssl_privatekey_info and assert modules: - -- community.crypto.x509_certificate: +- name: Usage of assertonly with all existing options + community.crypto.x509_certificate: provider: assertonly path: /etc/ssl/crt/ansible.com.crt csr_path: /etc/ssl/csr/ansible.com.csr @@ -182,7 +185,8 @@ EXAMPLES = r''' invalid_at: 20200331202428Z valid_in: 10 # in ten seconds -- community.crypto.x509_certificate_info: +- name: Get certificate information + community.crypto.x509_certificate_info: path: /etc/ssl/crt/ansible.com.crt # for valid_at, invalid_at and valid_in valid_at: @@ -191,12 +195,14 @@ EXAMPLES = r''' ten_seconds: "+10" register: result -- community.crypto.openssl_csr_info: +- name: Get CSR information + community.crypto.openssl_csr_info: # Verifies that the CSR signature is valid; module will fail if not path: /etc/ssl/csr/ansible.com.csr register: result_csr -- community.crypto.openssl_privatekey_info: +- name: Get private key information + community.crypto.openssl_privatekey_info: path: /etc/ssl/csr/ansible.com.key register: result_privatekey diff --git a/plugins/modules/x509_certificate_info.py b/plugins/modules/x509_certificate_info.py index 9cbd9f22..3e7bfc71 100644 --- a/plugins/modules/x509_certificate_info.py +++ b/plugins/modules/x509_certificate_info.py @@ -54,7 +54,7 @@ options: - 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 (i.e. pattern C(YYYYMMDDHHMMSSZ)). + + 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: @@ -70,8 +70,9 @@ options: choices: [ auto, cryptography, pyopenssl ] notes: - - All timestamp values are provided in ASN.1 TIME format, i.e. following the C(YYYYMMDDHHMMSSZ) pattern. + - 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 @@ -94,7 +95,7 @@ EXAMPLES = r''' register: result - name: Dump information - debug: + ansible.builtin.debug: var: result @@ -120,7 +121,7 @@ EXAMPLES = r''' RETURN = r''' expired: - description: Whether the certificate is expired (i.e. C(notAfter) is in the past) + description: Whether the certificate is expired (in other words, C(notAfter) is in the past). returned: success type: bool basic_constraints: @@ -144,7 +145,7 @@ extended_key_usage_critical: returned: success type: bool extensions_by_oid: - description: Returns a dictionary for every extension OID + description: Returns a dictionary for every extension OID. returned: success type: dict contains: @@ -153,7 +154,7 @@ extensions_by_oid: returned: success type: bool value: - description: The Base64 encoded value (in DER format) of the extension + description: The Base64 encoded value (in DER format) of the extension. returned: success type: str sample: "MAMCAQU=" @@ -212,17 +213,17 @@ subject_ordered: elements: list sample: '[["commonName", "www.example.com"], ["emailAddress": "test@example.com"]]' not_after: - description: C(notAfter) date as ASN.1 TIME + description: C(notAfter) date as ASN.1 TIME. returned: success type: str sample: 20190413202428Z not_before: - description: C(notBefore) date as ASN.1 TIME + description: C(notBefore) date as ASN.1 TIME. returned: success type: str sample: 20190331202428Z public_key: - description: Certificate's public key in PEM format + description: Certificate's public key in PEM format. returned: success type: str sample: "-----BEGIN PUBLIC KEY-----\nMIICIjANBgkqhkiG9w0BAQEFAAOCAg8A..." diff --git a/plugins/modules/x509_certificate_pipe.py b/plugins/modules/x509_certificate_pipe.py index 04b5ae8a..07369798 100644 --- a/plugins/modules/x509_certificate_pipe.py +++ b/plugins/modules/x509_certificate_pipe.py @@ -18,7 +18,7 @@ version_added: 1.3.0 description: - It implements a notion of provider (ie. C(selfsigned), C(ownca), C(entrust)) for your certificate. - - "Please note that the module regenerates an existing certificate if it doesn't match the module's + - "Please note that the module regenerates an existing certificate if it does not match the module's options, or if it seems to be corrupt. If you are concerned that this could overwrite your existing certificate, consider using the I(backup) option." author: @@ -43,6 +43,9 @@ options: seealso: - module: community.crypto.x509_certificate +notes: +- Supports C(check_mode). + extends_documentation_fragment: - community.crypto.module_certificate - community.crypto.module_certificate.backend_entrust_documentation @@ -57,7 +60,8 @@ EXAMPLES = r''' privatekey_path: /etc/ssl/private/ansible.com.pem csr_path: /etc/ssl/csr/ansible.com.csr register: result -- ansible.builtin.debug: +- name: Print the certificate + ansible.builtin.debug: var: result.certificate # In the following example, both CSR and certificate file are stored on the diff --git a/plugins/modules/x509_crl.py b/plugins/modules/x509_crl.py index 54adb4fc..62afc3ea 100644 --- a/plugins/modules/x509_crl.py +++ b/plugins/modules/x509_crl.py @@ -15,7 +15,7 @@ version_added: '1.0.0' short_description: Generate Certificate Revocation Lists (CRLs) description: - This module allows one to (re)generate or update Certificate Revocation Lists (CRLs). - - Certificates on the revocation list can be either specified via serial number and (optionally) their issuer, + - Certificates on the revocation list can be either specified by serial number and (optionally) their issuer, or as a path to a certificate file in PEM format. requirements: - cryptography >= 1.2 @@ -233,6 +233,7 @@ extends_documentation_fragment: notes: - All ASN.1 TIME values should be specified following the YYYYMMDDHHMMSSZ pattern. - Date specified should be UTC. Minutes and seconds are mandatory. + - Supports C(check_mode). ''' EXAMPLES = r''' @@ -259,7 +260,7 @@ EXAMPLES = r''' RETURN = r''' filename: - description: Path to the generated CRL + description: Path to the generated CRL. returned: changed or success type: str sample: /path/to/my-ca.crl @@ -269,7 +270,7 @@ backup_file: type: str sample: /path/to/my-ca.crl.2019-03-09@11:22~ privatekey: - description: Path to the private CA key + description: Path to the private CA key. returned: changed or success type: str sample: /path/to/my-ca.pem diff --git a/plugins/modules/x509_crl_info.py b/plugins/modules/x509_crl_info.py index e7e60cfb..916d56fc 100644 --- a/plugins/modules/x509_crl_info.py +++ b/plugins/modules/x509_crl_info.py @@ -32,8 +32,9 @@ options: type: str notes: - - All timestamp values are provided in ASN.1 TIME format, i.e. following the C(YYYYMMDDHHMMSSZ) pattern. + - 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_crl ''' @@ -44,7 +45,8 @@ EXAMPLES = r''' path: /etc/ssl/my-ca.crl register: result -- debug: +- name: Print the information + ansible.builtin.debug: msg: "{{ result }}" '''