From 62272296da9b092fcc3cf06adc07775fa4c01068 Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Mon, 10 Jan 2022 13:05:09 +0100 Subject: [PATCH] Small docs improvements (#374) * Small improvements. * Document behavior changes. --- changelogs/fragments/374-docs.yml | 2 ++ plugins/doc_fragments/module_certificate.py | 8 ++++---- plugins/doc_fragments/module_csr.py | 9 ++++----- plugins/doc_fragments/module_privatekey.py | 6 +++--- plugins/module_utils/acme/account.py | 4 ++-- plugins/module_utils/acme/backend_cryptography.py | 2 +- plugins/module_utils/acme/backend_openssl_cli.py | 4 ++-- plugins/module_utils/crypto/cryptography_crl.py | 2 +- plugins/module_utils/crypto/cryptography_support.py | 4 ++-- plugins/module_utils/crypto/math.py | 2 +- .../module_utils/crypto/module_backends/certificate.py | 4 ++-- .../crypto/module_backends/certificate_info.py | 2 +- plugins/module_utils/crypto/module_backends/csr.py | 2 +- .../module_utils/crypto/module_backends/csr_info.py | 2 +- .../module_utils/crypto/module_backends/privatekey.py | 2 +- .../crypto/module_backends/privatekey_info.py | 4 ++-- .../crypto/module_backends/publickey_info.py | 2 +- plugins/module_utils/crypto/support.py | 4 ++-- plugins/module_utils/ecs/api.py | 2 +- plugins/modules/acme_account.py | 2 +- plugins/modules/acme_certificate.py | 8 ++++---- plugins/modules/acme_certificate_revoke.py | 2 +- plugins/modules/certificate_complete_chain.py | 2 +- plugins/modules/ecs_certificate.py | 10 +++++----- plugins/modules/ecs_domain.py | 4 ++-- plugins/modules/get_certificate.py | 2 +- plugins/modules/luks_device.py | 6 +++--- plugins/modules/openssh_cert.py | 4 ++-- plugins/modules/openssh_keypair.py | 2 +- plugins/modules/openssl_csr.py | 2 +- plugins/modules/openssl_csr_pipe.py | 2 +- plugins/modules/openssl_dhparam.py | 6 +++--- plugins/modules/openssl_pkcs12.py | 2 +- plugins/modules/openssl_privatekey_info.py | 2 +- plugins/modules/openssl_publickey.py | 2 +- plugins/modules/openssl_signature.py | 2 +- plugins/modules/openssl_signature_info.py | 2 +- plugins/modules/x509_certificate_info.py | 2 +- plugins/modules/x509_crl.py | 10 +++++----- plugins/plugin_utils/action_module.py | 6 +++--- 40 files changed, 74 insertions(+), 73 deletions(-) create mode 100644 changelogs/fragments/374-docs.yml diff --git a/changelogs/fragments/374-docs.yml b/changelogs/fragments/374-docs.yml new file mode 100644 index 00000000..632ac96d --- /dev/null +++ b/changelogs/fragments/374-docs.yml @@ -0,0 +1,2 @@ +minor_changes: + - "Adjust error messages that indicate ``cryptography`` is not installed from ``Can't`` to ``Cannot`` (https://github.com/ansible-collections/community.crypto/pull/374)." diff --git a/plugins/doc_fragments/module_certificate.py b/plugins/doc_fragments/module_certificate.py index 28df5995..752cdbc4 100644 --- a/plugins/doc_fragments/module_certificate.py +++ b/plugins/doc_fragments/module_certificate.py @@ -264,7 +264,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). + + C([w | d | h | m | s]) (for example C(+32w1d2h)). - If this value is not specified, the certificate will start being valid from now. - Note that this value is B(not used to determine whether an existing certificate should be regenerated). This can be changed by setting the I(ignore_timestamps) option to C(false). Please note that you should @@ -279,7 +279,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). + + C([w | d | h | m | s]) (for example C(+32w1d2h)). - If this value is not specified, the certificate will stop being valid 10 years from now. - Note that this value is B(not used to determine whether an existing certificate should be regenerated). This can be changed by setting the I(ignore_timestamps) option to C(false). Please note that you should @@ -359,7 +359,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). + + C([w | d | h | m | s]) (for example C(+32w1d2h)). - If this value is not specified, the certificate will start being valid from now. - Note that this value is B(not used to determine whether an existing certificate should be regenerated). This can be changed by setting the I(ignore_timestamps) option to C(false). Please note that you should @@ -375,7 +375,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). + + C([w | d | h | m | s]) (for example C(+32w1d2h)). - If this value is not specified, the certificate will stop being valid 10 years from now. - Note that this value is B(not used to determine whether an existing certificate should be regenerated). This can be changed by setting the I(ignore_timestamps) option to C(false). Please note that you should diff --git a/plugins/doc_fragments/module_csr.py b/plugins/doc_fragments/module_csr.py index 0f8d57ac..adaef19b 100644 --- a/plugins/doc_fragments/module_csr.py +++ b/plugins/doc_fragments/module_csr.py @@ -104,9 +104,8 @@ options: subject_alt_name: description: - Subject Alternative Name (SAN) extension to attach to the certificate signing request. - - This can either be a 'comma separated string' or a YAML list. - - Values must be prefixed by their options. (i.e., C(email), C(URI), C(DNS), C(RID), C(IP), C(dirName), - C(otherName) and the ones specific to your CA). + - Values must be prefixed by their options. (These are C(email), C(URI), C(DNS), C(RID), C(IP), C(dirName), + C(otherName), and the ones specific to your CA). - Note that if no SAN is specified, but a common name, the common name will be added as a SAN except if C(useCommonNameForSAN) is set to I(false). @@ -129,7 +128,7 @@ options: aliases: [ useCommonNameForSAN ] key_usage: description: - - This defines the purpose (e.g. encipherment, signature, certificate signing) + - This defines the purpose (for example encipherment, signature, certificate signing) of the key contained in the certificate. type: list elements: str @@ -142,7 +141,7 @@ options: aliases: [ keyUsage_critical ] extended_key_usage: description: - - Additional restrictions (e.g. client authentication, server authentication) + - Additional restrictions (for example client authentication, server authentication) on the allowed purposes for which the public key may be used. type: list elements: str diff --git a/plugins/doc_fragments/module_privatekey.py b/plugins/doc_fragments/module_privatekey.py index 1ee92554..9c2de991 100644 --- a/plugins/doc_fragments/module_privatekey.py +++ b/plugins/doc_fragments/module_privatekey.py @@ -17,7 +17,7 @@ description: L(ECC,https://en.wikipedia.org/wiki/Elliptic-curve_cryptography) or L(EdDSA,https://en.wikipedia.org/wiki/EdDSA) private keys. - Keys are generated in PEM format. - - "Please note that the module regenerates private keys if they don't match + - "Please note that the module regenerates private keys if they do not match the module's options. In particular, if you provide another passphrase (or specify none), change the keysize, etc., the private key will be regenerated. If you are concerned that this could B(overwrite your private key), @@ -111,12 +111,12 @@ 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. - If set to C(never), the module will fail if the key cannot be read or the passphrase - isn't matching, and will never regenerate an existing key. + is not matching, and will never regenerate an existing key. - If set to C(fail), the module will fail if the key does not correspond to the module's options. - If set to C(partial_idempotence), the key will be regenerated if it does not conform to diff --git a/plugins/module_utils/acme/account.py b/plugins/module_utils/acme/account.py index 66519d10..31096faa 100644 --- a/plugins/module_utils/acme/account.py +++ b/plugins/module_utils/acme/account.py @@ -118,10 +118,10 @@ class ACMEAccount(object): self.client.set_account_uri(info['location']) return False, result elif info['status'] == 400 and result['type'] == 'urn:ietf:params:acme:error:accountDoesNotExist' and not allow_creation: - # Account does not exist (and we didn't try to create it) + # Account does not exist (and we did not try to create it) return False, None elif info['status'] == 403 and result['type'] == 'urn:ietf:params:acme:error:unauthorized' and 'deactivated' in (result.get('detail') or ''): - # Account has been deactivated; currently works for Pebble; hasn't been + # Account has been deactivated; currently works for Pebble; has not been # implemented for Boulder (https://github.com/letsencrypt/boulder/issues/3971), # might need adjustment in error detection. if not allow_creation: diff --git a/plugins/module_utils/acme/backend_cryptography.py b/plugins/module_utils/acme/backend_cryptography.py index 32a21b2c..f6ce4366 100644 --- a/plugins/module_utils/acme/backend_cryptography.py +++ b/plugins/module_utils/acme/backend_cryptography.py @@ -192,7 +192,7 @@ class CryptographyBackend(CryptoBackend): Parses an RSA or Elliptic Curve key file in PEM format and returns key_data. Raises KeyParsingError in case of errors. ''' - # If key_content isn't given, read key_file + # If key_content is not given, read key_file if key_content is None: key_content = read_file(key_file) else: diff --git a/plugins/module_utils/acme/backend_openssl_cli.py b/plugins/module_utils/acme/backend_openssl_cli.py index ba67228b..2dbb69a8 100644 --- a/plugins/module_utils/acme/backend_openssl_cli.py +++ b/plugins/module_utils/acme/backend_openssl_cli.py @@ -52,7 +52,7 @@ class OpenSSLCLIBackend(CryptoBackend): ''' if passphrase is not None: raise KeyParsingError('openssl backend does not support key passphrases') - # If key_file isn't given, but key_content, write that to a temporary file + # If key_file is not given, but key_content, write that to a temporary file if key_file is None: fd, tmpsrc = tempfile.mkstemp() self.module.add_cleanup_file(tmpsrc) # Ansible will delete the file on exit @@ -221,7 +221,7 @@ class OpenSSLCLIBackend(CryptoBackend): try: return to_native(ipaddress.ip_address(to_text(ip)).compressed) except ValueError: - # We don't want to error out on something IPAddress() can't parse + # We do not want to error out on something IPAddress() cannot parse return ip def get_csr_identifiers(self, csr_filename=None, csr_content=None): diff --git a/plugins/module_utils/crypto/cryptography_crl.py b/plugins/module_utils/crypto/cryptography_crl.py index aa73b512..a7148687 100644 --- a/plugins/module_utils/crypto/cryptography_crl.py +++ b/plugins/module_utils/crypto/cryptography_crl.py @@ -116,7 +116,7 @@ def cryptography_get_signature_algorithm_oid_from_crl(crl): try: return crl.signature_algorithm_oid except AttributeError: - # Older cryptography versions don't have signature_algorithm_oid yet + # Older cryptography versions do not have signature_algorithm_oid yet dotted = obj2txt( crl._backend._lib, crl._backend._ffi, diff --git a/plugins/module_utils/crypto/cryptography_support.py b/plugins/module_utils/crypto/cryptography_support.py index d1430324..6ddb977c 100644 --- a/plugins/module_utils/crypto/cryptography_support.py +++ b/plugins/module_utils/crypto/cryptography_support.py @@ -79,7 +79,7 @@ DOTTED_OID = re.compile(r'^\d+(?:\.\d+)+$') def cryptography_get_extensions_from_cert(cert): result = dict() try: - # Since cryptography won't give us the DER value for an extension + # Since cryptography will not give us the DER value for an extension # (that is only stored for unrecognized extensions), we have to re-do # the extension parsing outselves. backend = default_backend() @@ -131,7 +131,7 @@ def cryptography_get_extensions_from_cert(cert): def cryptography_get_extensions_from_csr(csr): result = dict() try: - # Since cryptography won't give us the DER value for an extension + # Since cryptography will not give us the DER value for an extension # (that is only stored for unrecognized extensions), we have to re-do # the extension parsing outselves. backend = default_backend() diff --git a/plugins/module_utils/crypto/math.py b/plugins/module_utils/crypto/math.py index c98eb1ed..c6492c25 100644 --- a/plugins/module_utils/crypto/math.py +++ b/plugins/module_utils/crypto/math.py @@ -50,7 +50,7 @@ def quick_is_not_prime(n): '''Does some quick checks to see if we can poke a hole into the primality of n. A result of `False` does **not** mean that the number is prime; it just means - that we couldn't detect quickly whether it is not prime. + that we could not detect quickly whether it is not prime. ''' if n <= 2: return True diff --git a/plugins/module_utils/crypto/module_backends/certificate.py b/plugins/module_utils/crypto/module_backends/certificate.py index 81f1898b..f8f1f67f 100644 --- a/plugins/module_utils/crypto/module_backends/certificate.py +++ b/plugins/module_utils/crypto/module_backends/certificate.py @@ -219,7 +219,7 @@ class CertificateBackend(object): if ext.value.digest != x509.SubjectKeyIdentifier.from_public_key(self.existing_certificate.public_key()).digest: return False else: - # If CSR had SKI and we didn't ignore it ('create_if_not_provided'), compare SKIs + # If CSR had SKI and we did not ignore it ('create_if_not_provided'), compare SKIs if ext.value.digest != csr_ext.value.digest: return False return True @@ -318,7 +318,7 @@ def select_backend(module, backend, provider): # Fail if no backend has been found if backend == 'auto': - module.fail_json(msg=("Can't detect the required Python library " + module.fail_json(msg=("Cannot detect the required Python library " "cryptography (>= {0})").format(MINIMAL_CRYPTOGRAPHY_VERSION)) if backend == 'cryptography': diff --git a/plugins/module_utils/crypto/module_backends/certificate_info.py b/plugins/module_utils/crypto/module_backends/certificate_info.py index 49247c0d..252e730b 100644 --- a/plugins/module_utils/crypto/module_backends/certificate_info.py +++ b/plugins/module_utils/crypto/module_backends/certificate_info.py @@ -382,7 +382,7 @@ def select_backend(module, backend, content): # Success? if backend == 'auto': - module.fail_json(msg=("Can't detect any of the required Python libraries " + module.fail_json(msg=("Cannot detect any of the required Python libraries " "cryptography (>= {0})").format(MINIMAL_CRYPTOGRAPHY_VERSION)) if backend == 'cryptography': diff --git a/plugins/module_utils/crypto/module_backends/csr.py b/plugins/module_utils/crypto/module_backends/csr.py index 449e3bea..697afe47 100644 --- a/plugins/module_utils/crypto/module_backends/csr.py +++ b/plugins/module_utils/crypto/module_backends/csr.py @@ -584,7 +584,7 @@ def select_backend(module, backend): # Success? if backend == 'auto': - module.fail_json(msg=("Can't detect any of the required Python libraries " + module.fail_json(msg=("Cannot detect any of the required Python libraries " "cryptography (>= {0})").format(MINIMAL_CRYPTOGRAPHY_VERSION)) if backend == 'cryptography': diff --git a/plugins/module_utils/crypto/module_backends/csr_info.py b/plugins/module_utils/crypto/module_backends/csr_info.py index 6d4962f1..4f528659 100644 --- a/plugins/module_utils/crypto/module_backends/csr_info.py +++ b/plugins/module_utils/crypto/module_backends/csr_info.py @@ -321,7 +321,7 @@ def select_backend(module, backend, content, validate_signature=True): # Success? if backend == 'auto': - module.fail_json(msg=("Can't detect the required Python library " + module.fail_json(msg=("Cannot detect the required Python library " "cryptography (>= {0})").format(MINIMAL_CRYPTOGRAPHY_VERSION)) if backend == 'cryptography': diff --git a/plugins/module_utils/crypto/module_backends/privatekey.py b/plugins/module_utils/crypto/module_backends/privatekey.py index ce72276c..0d12a711 100644 --- a/plugins/module_utils/crypto/module_backends/privatekey.py +++ b/plugins/module_utils/crypto/module_backends/privatekey.py @@ -490,7 +490,7 @@ def select_backend(module, backend): # Success? if backend == 'auto': - module.fail_json(msg=("Can't detect the required Python library " + module.fail_json(msg=("Cannot detect the required Python library " "cryptography (>= {0})").format(MINIMAL_CRYPTOGRAPHY_VERSION)) if backend == 'cryptography': if not CRYPTOGRAPHY_FOUND: diff --git a/plugins/module_utils/crypto/module_backends/privatekey_info.py b/plugins/module_utils/crypto/module_backends/privatekey_info.py index 146f455b..520c6fb1 100644 --- a/plugins/module_utils/crypto/module_backends/privatekey_info.py +++ b/plugins/module_utils/crypto/module_backends/privatekey_info.py @@ -228,7 +228,7 @@ class PrivateKeyInfoRetrieval(object): if self.check_consistency: result['key_is_consistent'] = self._is_key_consistent(key_public_data, key_private_data) if result['key_is_consistent'] is False: - # Only fail when it is False, to avoid to fail on None (which means "we don't know") + # Only fail when it is False, to avoid to fail on None (which means "we do not know") msg = ( "Private key is not consistent! (See " "https://blog.hboeck.de/archives/888-How-I-tricked-Symantec-with-a-Fake-Private-Key.html)" @@ -273,7 +273,7 @@ def select_backend(module, backend, content, passphrase=None, return_private_key # Success? if backend == 'auto': - module.fail_json(msg=("Can't detect the required Python library " + module.fail_json(msg=("Cannot detect the required Python library " "cryptography (>= {0})").format(MINIMAL_CRYPTOGRAPHY_VERSION)) if backend == 'cryptography': diff --git a/plugins/module_utils/crypto/module_backends/publickey_info.py b/plugins/module_utils/crypto/module_backends/publickey_info.py index 55a46776..789adc43 100644 --- a/plugins/module_utils/crypto/module_backends/publickey_info.py +++ b/plugins/module_utils/crypto/module_backends/publickey_info.py @@ -155,7 +155,7 @@ def select_backend(module, backend, content=None, key=None): # Success? if backend == 'auto': - module.fail_json(msg=("Can't detect any of the required Python libraries " + module.fail_json(msg=("Cannot detect any of the required Python libraries " "cryptography (>= {0})").format(MINIMAL_CRYPTOGRAPHY_VERSION)) if backend == 'cryptography': diff --git a/plugins/module_utils/crypto/support.py b/plugins/module_utils/crypto/support.py index 5a265498..64619985 100644 --- a/plugins/module_utils/crypto/support.py +++ b/plugins/module_utils/crypto/support.py @@ -162,13 +162,13 @@ def load_privatekey(path, passphrase=None, check_passphrase=True, content=None, to_bytes('y' if passphrase == 'x' else 'x')) if passphrase is not None: # Since we can load the key without an exception, the - # key isn't password-protected + # key is not password-protected raise OpenSSLBadPassphraseError('Passphrase provided, but private key is not password-protected!') except crypto.Error as e: if passphrase is None and len(e.args) > 0 and len(e.args[0]) > 0: if e.args[0][0][2] in ('bad decrypt', 'bad password read'): # The key is obviously protected by the empty string. - # Don't do this at home (if it's possible at all)... + # Do not do this at home (if it's possible at all)... raise OpenSSLBadPassphraseError('No passphrase provided, but private key is password-protected!') elif backend == 'cryptography': try: diff --git a/plugins/module_utils/ecs/api.py b/plugins/module_utils/ecs/api.py index 71c2fde5..0c98dbd4 100644 --- a/plugins/module_utils/ecs/api.py +++ b/plugins/module_utils/ecs/api.py @@ -105,7 +105,7 @@ def bind(instance, method, operation_spec): def binding_scope_fn(*args, **kwargs): return method(instance, *args, **kwargs) - # Make sure we don't confuse users; add the proper name and documentation to the function. + # Make sure we do not confuse users; add the proper name and documentation to the function. # Users can use !help() to get help on the function from interactive python or pdb operation_name = operation_spec.get("operationId").split("Using")[0] binding_scope_fn.__name__ = str(operation_name) diff --git a/plugins/modules/acme_account.py b/plugins/modules/acme_account.py index bb90e0b0..1000ceeb 100644 --- a/plugins/modules/acme_account.py +++ b/plugins/modules/acme_account.py @@ -133,7 +133,7 @@ EXAMPLES = ''' - mailto:me@example.com - mailto:myself@example.org -- name: Make sure account has given email address. Don't create account if it doesn't exist +- name: Make sure account has given email address. Do not create account if it does not exist community.crypto.acme_account: account_key_src: /etc/pki/cert/private/account.key state: present diff --git a/plugins/modules/acme_certificate.py b/plugins/modules/acme_certificate.py index de3e1374..ee6a05f8 100644 --- a/plugins/modules/acme_certificate.py +++ b/plugins/modules/acme_certificate.py @@ -170,7 +170,7 @@ options: aliases: ['cert'] fullchain_dest: description: - - "The destination file for the full chain (i.e. certificate followed + - "The destination file for the full chain (that is, a certificate followed by chain of intermediate certificates)." - "Required if C(dest) is not specified." type: path @@ -204,7 +204,7 @@ options: description: - Enforces the execution of the challenge and validation, even if an existing certificate is still valid for more than C(remaining_days). - - This is especially helpful when having an updated CSR e.g. with + - This is especially helpful when having an updated CSR, for example with additional domains for which a new certificate is desired. type: bool default: no @@ -238,9 +238,9 @@ options: - "Determines which certificates in the chain will be tested." - "I(all) tests all certificates in the chain (excluding the leaf, which is identical in all chains)." - - "I(first) only tests the first certificate in the chain, i.e. the one which + - "I(first) only tests the first certificate in the chain, that is the one which signed the leaf." - - "I(last) only tests the last certificate in the chain, i.e. the one furthest + - "I(last) only tests the last certificate in the chain, that is the one furthest away from the leaf. Its issuer is the root certificate of this chain." type: str default: all diff --git a/plugins/modules/acme_certificate_revoke.py b/plugins/modules/acme_certificate_revoke.py index 201b26d3..d0711b66 100644 --- a/plugins/modules/acme_certificate_revoke.py +++ b/plugins/modules/acme_certificate_revoke.py @@ -225,7 +225,7 @@ def main(): if result.get('type') == error_type and result.get('detail') == 'Certificate already revoked': # Fallback: boulder returns this in case the certificate was already revoked. already_revoked = True - # If we know the certificate was already revoked, we don't fail, + # If we know the certificate was already revoked, we do not fail, # but successfully terminate while indicating no change if already_revoked: module.exit_json(changed=False) diff --git a/plugins/modules/certificate_complete_chain.py b/plugins/modules/certificate_complete_chain.py index 5a6c02bc..f3038028 100644 --- a/plugins/modules/certificate_complete_chain.py +++ b/plugins/modules/certificate_complete_chain.py @@ -327,7 +327,7 @@ def main(): completed = [] occured_certificates = set([cert.cert for cert in chain]) if current.cert in roots.certificate_by_cert: - # Don't try to complete the chain when it's already ending with a root certificate + # Do not try to complete the chain when it's already ending with a root certificate current = None while current: root = roots.find_parent(current) diff --git a/plugins/modules/ecs_certificate.py b/plugins/modules/ecs_certificate.py index 1eca89aa..d7d61d8c 100644 --- a/plugins/modules/ecs_certificate.py +++ b/plugins/modules/ecs_certificate.py @@ -81,8 +81,8 @@ options: - The number of days the certificate must have left being valid. If C(cert_days < remaining_days) then a new certificate will be obtained using I(request_type). - If C(request_type=renew), a renewal will fail if the certificate being renewed has been issued within the past 30 days, so do not set a - I(remaining_days) value that is within 30 days of the full lifetime of the certificate being acted upon. (e.g. if you are requesting Certificates - with a 90 day lifetime, do not set remaining_days to a value C(60) or higher). + I(remaining_days) value that is within 30 days of the full lifetime of the certificate being acted upon. + - For exmaple, if you are requesting Certificates with a 90 day lifetime, do not set I(remaining_days) to a value C(60) or higher). - The I(force) option may be used to ensure that a new certificate is always obtained. type: int default: 30 @@ -97,8 +97,8 @@ options: - Specifying C(request_type=reissue) means that an existing certificate (specified by I(tracking_id) if present, otherwise I(path)) will be reissued. If there is no certificate to reissue, a new certificate is requested. - - If a certificate was issued within the past 30 days, the 'renew' operation is not a valid operation and will fail. - - Note that C(reissue) is an operation that will result in the revocation of the certificate that is reissued, be cautious with it's use. + - If a certificate was issued within the past 30 days, the C(renew) operation is not a valid operation and will fail. + - Note that C(reissue) is an operation that will result in the revocation of the certificate that is reissued, be cautious with its use. - I(check_mode) is only supported if C(request_type=new) - For example, setting C(request_type=renew) and C(remaining_days=30) and pointing to the same certificate on multiple playbook runs means that on the first run new certificate will be requested. It will then be left along on future runs until it is within 30 days of expiry, then the @@ -690,7 +690,7 @@ class EcsCertificate(object): if len(cert_results) == 1: self.tracking_id = cert_results[0].get('trackingId') except RestOperationException as dummy: - # If we fail to find a cert by serial number, that's fine, we just don't set self.tracking_id + # If we fail to find a cert by serial number, that's fine, we just do not set self.tracking_id return def set_cert_details(self, module): diff --git a/plugins/modules/ecs_domain.py b/plugins/modules/ecs_domain.py index 7bfbe95f..201c4144 100644 --- a/plugins/modules/ecs_domain.py +++ b/plugins/modules/ecs_domain.py @@ -63,11 +63,11 @@ options: description: - Email address to be used to verify domain ownership. - 'Email address must be either an email address present in the WHOIS data for I(domain_name), or one of the following constructed emails: - admin@I(domain_name), administrator@I(domain_name), webmaster@I(domain_name), hostmaster@I(domain_name), postmaster@I(domain_name)' + admin@I(domain_name), administrator@I(domain_name), webmaster@I(domain_name), hostmaster@I(domain_name), postmaster@I(domain_name).' - 'Note that if I(domain_name) includes subdomains, the top level domain should be used. For example, if requesting validation of example1.ansible.com, or test.example2.ansible.com, and you want to use the "admin" preconstructed name, the email address should be admin@ansible.com.' - - If using the email values from the WHOIS data for the domain or it's top level namespace, they must be exact matches. + - If using the email values from the WHOIS data for the domain or its top level namespace, they must be exact matches. - If C(verification_method=email) but I(verification_email) is not provided, the first email address found in WHOIS data for the domain will be used. - To verify domain ownership, domain owner must follow the instructions in the email they receive. diff --git a/plugins/modules/get_certificate.py b/plugins/modules/get_certificate.py index dba84615..d2fa045a 100644 --- a/plugins/modules/get_certificate.py +++ b/plugins/modules/get_certificate.py @@ -257,7 +257,7 @@ def main(): # Success? if backend == 'auto': - module.fail_json(msg=("Can't detect the required Python library " + module.fail_json(msg=("Cannot detect the required Python library " "cryptography (>= {0})").format(MINIMAL_CRYPTOGRAPHY_VERSION)) if backend == 'cryptography': diff --git a/plugins/modules/luks_device.py b/plugins/modules/luks_device.py index ddaedd24..4e6bde08 100644 --- a/plugins/modules/luks_device.py +++ b/plugins/modules/luks_device.py @@ -21,7 +21,7 @@ description: options: device: description: - - "Device to work with (e.g. C(/dev/sda1)). Needed in most cases. + - "Device to work with (for example C(/dev/sda1)). Needed in most cases. Can be omitted only when I(state=closed) together with I(name) is provided." type: str @@ -53,7 +53,7 @@ options: description: - "Sets container name when I(state=opened). Can be used instead of I(device) when closing the existing container - (i.e. when I(state=closed))." + (that is, when I(state=closed))." type: str keyfile: description: @@ -159,7 +159,7 @@ options: - "This option allows the user to define the cipher specification string for the LUKS container." - "Will only be used on container creation." - - "For pre-2.6.10 kernels, use C(aes-plain) as they don't understand + - "For pre-2.6.10 kernels, use C(aes-plain) as they do not understand the new cipher spec strings. To use ESSIV, use C(aes-cbc-essiv:sha256)." type: str version_added: '1.1.0' diff --git a/plugins/modules/openssh_cert.py b/plugins/modules/openssh_cert.py index e79b09a4..b6567941 100644 --- a/plugins/modules/openssh_cert.py +++ b/plugins/modules/openssh_cert.py @@ -110,7 +110,7 @@ options: description: - "The point in time the certificate is valid from. Time can be specified either as relative time or as absolute timestamp. Time will always be interpreted as UTC. Valid formats are: C([+-]timespec | YYYY-MM-DD | YYYY-MM-DDTHH:MM:SS | YYYY-MM-DD HH:MM:SS | always) - where timespec can be an integer + C([w | d | h | m | s]) (e.g. C(+32w1d2h). + where timespec can be an integer + C([w | d | h | m | s]) (for example C(+32w1d2h)). Note that if using relative time this module is NOT idempotent." - Required if I(state) is C(present). type: str @@ -118,7 +118,7 @@ options: description: - "The point in time the certificate is valid to. Time can be specified either as relative time or as absolute timestamp. Time will always be interpreted as UTC. Valid formats are: C([+-]timespec | YYYY-MM-DD | YYYY-MM-DDTHH:MM:SS | YYYY-MM-DD HH:MM:SS | forever) - where timespec can be an integer + C([w | d | h | m | s]) (e.g. C(+32w1d2h). + where timespec can be an integer + C([w | d | h | m | s]) (for example C(+32w1d2h)). Note that if using relative time this module is NOT idempotent." - Required if I(state) is C(present). type: str diff --git a/plugins/modules/openssh_keypair.py b/plugins/modules/openssh_keypair.py index 62a975b2..b3c9b72a 100644 --- a/plugins/modules/openssh_keypair.py +++ b/plugins/modules/openssh_keypair.py @@ -94,7 +94,7 @@ options: this B(changed) for Ansible 2.10. For Ansible 2.9, the behavior was as if C(full_idempotence) is specified. - If set to C(never), the module will fail if the key cannot be read or the passphrase - isn't matching, and will never regenerate an existing key. + is not matching, and will never regenerate an existing key. - If set to C(fail), the module will fail if the key does not correspond to the module's options. - If set to C(partial_idempotence), the key will be regenerated if it does not conform to diff --git a/plugins/modules/openssl_csr.py b/plugins/modules/openssl_csr.py index 0c664bda..d2ca76b5 100644 --- a/plugins/modules/openssl_csr.py +++ b/plugins/modules/openssl_csr.py @@ -14,7 +14,7 @@ DOCUMENTATION = r''' module: openssl_csr short_description: Generate OpenSSL Certificate Signing Request (CSR) description: - - "Please note that the module regenerates an existing CSR if it doesn't match the module's + - "Please note that the module regenerates an existing CSR 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 CSR, consider using the I(backup) option." author: diff --git a/plugins/modules/openssl_csr_pipe.py b/plugins/modules/openssl_csr_pipe.py index e76e0cb7..eb83e17e 100644 --- a/plugins/modules/openssl_csr_pipe.py +++ b/plugins/modules/openssl_csr_pipe.py @@ -15,7 +15,7 @@ module: openssl_csr_pipe short_description: Generate OpenSSL Certificate Signing Request (CSR) version_added: 1.3.0 description: - - "Please note that the module regenerates an existing CSR if it doesn't match the module's + - "Please note that the module regenerates an existing CSR if it does not match the module's options, or if it seems to be corrupt." author: - Yanis Guenane (@Spredzy) diff --git a/plugins/modules/openssl_dhparam.py b/plugins/modules/openssl_dhparam.py index 1ba647d7..b5effdeb 100644 --- a/plugins/modules/openssl_dhparam.py +++ b/plugins/modules/openssl_dhparam.py @@ -67,7 +67,7 @@ options: version_added: "1.0.0" return_content: description: - - If set to C(yes), will return the (current or generated) DH params' content as I(dhparams). + - If set to C(yes), will return the (current or generated) DH parameter's content as I(dhparams). type: bool default: no version_added: "1.0.0" @@ -286,7 +286,7 @@ class DHParameterOpenSSL(DHParameterBase): rc, out, err = module.run_command(command, check_rc=False) result = to_native(out) if rc != 0: - # If the call failed the file probably doesn't exist or is + # If the call failed the file probably does not exist or is # unreadable return False # output contains "(xxxx bit)" @@ -380,7 +380,7 @@ def main(): # Success? if backend == 'auto': - module.fail_json(msg=("Can't detect either the required Python library cryptography (>= {0}) " + module.fail_json(msg=("Cannot detect either the required Python library cryptography (>= {0}) " "or the OpenSSL binary openssl").format(MINIMAL_CRYPTOGRAPHY_VERSION)) if backend == 'openssl': diff --git a/plugins/modules/openssl_pkcs12.py b/plugins/modules/openssl_pkcs12.py index d891c9cd..5c91d6e8 100644 --- a/plugins/modules/openssl_pkcs12.py +++ b/plugins/modules/openssl_pkcs12.py @@ -648,7 +648,7 @@ def select_backend(module, backend): # Success? if backend == 'auto': - module.fail_json(msg=("Can't detect any of the required Python libraries " + module.fail_json(msg=("Cannot detect any of the required Python libraries " "cryptography (>= {0}) or PyOpenSSL (>= {1})").format( MINIMAL_CRYPTOGRAPHY_VERSION, MINIMAL_PYOPENSSL_VERSION)) diff --git a/plugins/modules/openssl_privatekey_info.py b/plugins/modules/openssl_privatekey_info.py index 338f8d55..d29a25e8 100644 --- a/plugins/modules/openssl_privatekey_info.py +++ b/plugins/modules/openssl_privatekey_info.py @@ -45,7 +45,7 @@ options: - Whether to return private key data. - Only set this to C(yes) when you want private information about this key to leave the remote machine. - - "B(WARNING:) you have to make sure that private key data isn't accidentally logged!" + - "B(WARNING:) you have to make sure that private key data is not accidentally logged!" type: bool default: no check_consistency: diff --git a/plugins/modules/openssl_publickey.py b/plugins/modules/openssl_publickey.py index 7f597ca6..9870e9ad 100644 --- a/plugins/modules/openssl_publickey.py +++ b/plugins/modules/openssl_publickey.py @@ -431,7 +431,7 @@ def main(): # Success? if backend == 'auto': - module.fail_json(msg=("Can't detect the required Python library " + module.fail_json(msg=("Cannot detect the required Python library " "cryptography (>= {0})").format(minimal_cryptography_version)) if module.params['format'] == 'OpenSSH' and backend != 'cryptography': diff --git a/plugins/modules/openssl_signature.py b/plugins/modules/openssl_signature.py index 93cd29f0..ca71988b 100644 --- a/plugins/modules/openssl_signature.py +++ b/plugins/modules/openssl_signature.py @@ -246,7 +246,7 @@ def main(): # Success? if backend == 'auto': - module.fail_json(msg=("Can't detect the required Python library " + module.fail_json(msg=("Cannot detect the required Python library " "cryptography (>= {0})").format(MINIMAL_CRYPTOGRAPHY_VERSION)) try: if backend == 'cryptography': diff --git a/plugins/modules/openssl_signature_info.py b/plugins/modules/openssl_signature_info.py index 4813c286..9a945f35 100644 --- a/plugins/modules/openssl_signature_info.py +++ b/plugins/modules/openssl_signature_info.py @@ -276,7 +276,7 @@ def main(): # Success? if backend == 'auto': - module.fail_json(msg=("Can't detect any of the required Python libraries " + module.fail_json(msg=("Cannot detect any of the required Python libraries " "cryptography (>= {0})").format(MINIMAL_CRYPTOGRAPHY_VERSION)) try: if backend == 'cryptography': diff --git a/plugins/modules/x509_certificate_info.py b/plugins/modules/x509_certificate_info.py index a666bb04..ae3ed9cd 100644 --- a/plugins/modules/x509_certificate_info.py +++ b/plugins/modules/x509_certificate_info.py @@ -50,7 +50,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 (in other words, pattern C(YYYYMMDDHHMMSSZ)). + + C([w | d | h | m | s]) (for example 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: diff --git a/plugins/modules/x509_crl.py b/plugins/modules/x509_crl.py index ce07ef49..5a5267b0 100644 --- a/plugins/modules/x509_crl.py +++ b/plugins/modules/x509_crl.py @@ -114,7 +114,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). + + C([w | d | h | m | s]) (for example C(+32w1d2h)). - Note that if using relative time this module is NOT idempotent, except when I(ignore_timestamps) is set to C(yes). type: str @@ -127,7 +127,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). + + C([w | d | h | m | s]) (for example C(+32w1d2h)). - Note that if using relative time this module is NOT idempotent, except when I(ignore_timestamps) is set to C(yes). - Required if I(state) is C(present). @@ -172,7 +172,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). + + C([w | d | h | m | s]) (for example C(+32w1d2h)). - Note that if using relative time this module is NOT idempotent, except when I(ignore_timestamps) is set to C(yes). type: str @@ -215,7 +215,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). + + C([w | d | h | m | s]) (for example C(+32w1d2h)). - Note that if using relative time this module is NOT idempotent. This will NOT change when I(ignore_timestamps) is set to C(yes). type: str @@ -647,7 +647,7 @@ class CRL(OpenSSLObject): old_entries = [self._compress_entry(cryptography_decode_revoked_certificate(cert)) for cert in self.crl] new_entries = [self._compress_entry(cert) for cert in self.revoked_certificates] if self.update: - # We don't simply use a set so that duplicate entries are treated correctly + # We do not simply use a set so that duplicate entries are treated correctly for entry in new_entries: try: old_entries.remove(entry) diff --git a/plugins/plugin_utils/action_module.py b/plugins/plugin_utils/action_module.py index 8ff0a820..5a5a8dad 100644 --- a/plugins/plugin_utils/action_module.py +++ b/plugins/plugin_utils/action_module.py @@ -166,7 +166,7 @@ class AnsibleActionModule(object): try: self.aliases = self._handle_aliases() except (ValueError, TypeError) as e: - # Use exceptions here because it isn't safe to call fail_json until no_log is processed + # Use exceptions here because it is not safe to call fail_json until no_log is processed raise _ModuleExitException(dict(failed=True, msg="Module alias error: %s" % to_native(e))) # Save parameter values that should never be logged @@ -405,7 +405,7 @@ class AnsibleActionModule(object): self.fail_json(msg=msg) elif param[k] not in choices: # PyYaml converts certain strings to bools. If we can unambiguously convert back, do so before checking - # the value. If we can't figure this out, module author is responsible. + # the value. If we cannot figure this out, module author is responsible. lowered_choices = None if param[k] == 'False': lowered_choices = lenient_lowercase(choices) @@ -545,7 +545,7 @@ class AnsibleActionModule(object): except KeyError: self.fail_json(msg="implementation error: unknown type %s requested for %s" % (wanted, k)) else: - # set the type_checker to the callable, and reset wanted to the callable's name (or type if it doesn't have one, ala MagicMock) + # set the type_checker to the callable, and reset wanted to the callable's name (or type if it does not have one, ala MagicMock) type_checker = wanted wanted = getattr(wanted, '__name__', to_native(type(wanted)))