From 7bbe8f467c905cad38ae1f2258286c547b041d1b Mon Sep 17 00:00:00 2001 From: Felix Fontein Date: Sun, 6 Nov 2022 21:10:56 +0100 Subject: [PATCH] Document attributes (#526) * Add 'acme' action group attribute. * Compatibility with older ansible-core releases. * Fix typo. * Document standard attributes. * Improve docs. * Add shortcuts for common combinations. --- meta/runtime.yml | 11 ++- plugins/doc_fragments/attributes.py | 85 +++++++++++++++++++ plugins/modules/acme_account.py | 26 +++--- plugins/modules/acme_account_info.py | 24 +++--- plugins/modules/acme_certificate.py | 69 ++++++++------- plugins/modules/acme_certificate_revoke.py | 31 ++++--- plugins/modules/acme_challenge_cert_helper.py | 23 +++-- plugins/modules/acme_inspect.py | 46 +++++----- plugins/modules/certificate_complete_chain.py | 11 +++ plugins/modules/crypto_info.py | 11 +-- plugins/modules/ecs_certificate.py | 16 +++- plugins/modules/ecs_domain.py | 11 ++- plugins/modules/get_certificate.py | 17 +++- plugins/modules/luks_device.py | 10 ++- plugins/modules/openssh_cert.py | 13 ++- plugins/modules/openssh_keypair.py | 14 ++- plugins/modules/openssl_csr.py | 21 +++-- plugins/modules/openssl_csr_info.py | 11 +-- plugins/modules/openssl_csr_pipe.py | 14 ++- plugins/modules/openssl_dhparam.py | 25 ++++-- plugins/modules/openssl_pkcs12.py | 23 +++-- plugins/modules/openssl_privatekey.py | 19 +++-- plugins/modules/openssl_privatekey_convert.py | 15 +++- plugins/modules/openssl_privatekey_info.py | 14 +-- plugins/modules/openssl_privatekey_pipe.py | 21 ++++- plugins/modules/openssl_publickey.py | 29 ++++--- plugins/modules/openssl_publickey_info.py | 10 +-- plugins/modules/openssl_signature.py | 9 ++ plugins/modules/openssl_signature_info.py | 4 +- plugins/modules/x509_certificate.py | 33 ++++--- plugins/modules/x509_certificate_info.py | 18 ++-- plugins/modules/x509_certificate_pipe.py | 28 +++--- plugins/modules/x509_crl.py | 17 ++-- plugins/modules/x509_crl_info.py | 8 +- 34 files changed, 509 insertions(+), 228 deletions(-) create mode 100644 plugins/doc_fragments/attributes.py diff --git a/meta/runtime.yml b/meta/runtime.yml index 2ef38b4c..76500748 100644 --- a/meta/runtime.yml +++ b/meta/runtime.yml @@ -7,12 +7,11 @@ requires_ansible: '>=2.9.10' action_groups: acme: - - acme_inspect - - acme_certificate_revoke - - acme_certificate - - acme_account - - acme_account_facts - - acme_account_info + - acme_inspect + - acme_certificate_revoke + - acme_certificate + - acme_account + - acme_account_info plugin_routing: modules: diff --git a/plugins/doc_fragments/attributes.py b/plugins/doc_fragments/attributes.py new file mode 100644 index 00000000..11f6b575 --- /dev/null +++ b/plugins/doc_fragments/attributes.py @@ -0,0 +1,85 @@ +# -*- coding: utf-8 -*- + +# Copyright (c) Ansible Project +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) +# SPDX-License-Identifier: GPL-3.0-or-later + +from __future__ import (absolute_import, division, print_function) +__metaclass__ = type + + +class ModuleDocFragment(object): + + # Standard documentation fragment + DOCUMENTATION = r''' +options: {} +attributes: + check_mode: + description: Can run in C(check_mode) and return changed status prediction without modifying target. + diff_mode: + description: Will return details on what has changed (or possibly needs changing in C(check_mode)), when in diff mode. +''' + + # Should be used together with the standard fragment + INFO_MODULE = r''' +options: {} +attributes: + check_mode: + support: full + details: + - This action does not modify state. + diff_mode: + support: N/A + details: + - This action does not modify state. +''' + + ACTIONGROUP_ACME = r''' +options: {} +attributes: + action_group: + description: Use C(group/acme) or C(group/community.crypto.acme) in C(module_defaults) to set defaults for this module. + support: full + membership: + - community.crypto.acme + - acme +''' + + FACTS = r''' +options: {} +attributes: + facts: + description: Action returns an C(ansible_facts) dictionary that will update existing host facts. +''' + + # Should be used together with the standard fragment and the FACTS fragment + FACTS_MODULE = r''' +options: {} +attributes: + check_mode: + support: full + details: + - This action does not modify state. + diff_mode: + support: N/A + details: + - This action does not modify state. + facts: + support: full +''' + + FILES = r''' +options: {} +attributes: + safe_file_operations: + description: Uses Ansible's strict file operation functions to ensure proper permissions and avoid data corruption. +''' + + FLOW = r''' +options: {} +attributes: + action: + description: Indicates this has a corresponding action plugin so some parts of the options can be executed on the controller. + async: + description: Supports being used with the C(async) keyword. +''' diff --git a/plugins/modules/acme_account.py b/plugins/modules/acme_account.py index 2a3bb1bb..13de49ab 100644 --- a/plugins/modules/acme_account.py +++ b/plugins/modules/acme_account.py @@ -15,15 +15,15 @@ module: acme_account author: "Felix Fontein (@felixfontein)" short_description: Create, modify or delete ACME accounts description: - - "Allows to create, modify or delete accounts with a CA supporting the - L(ACME protocol,https://tools.ietf.org/html/rfc8555), - such as L(Let's Encrypt,https://letsencrypt.org/)." - - "This module only works with the ACME v2 protocol." + - "Allows to create, modify or delete accounts with a CA supporting the + L(ACME protocol,https://tools.ietf.org/html/rfc8555), + such as L(Let's Encrypt,https://letsencrypt.org/)." + - "This module only works with the ACME v2 protocol." notes: - - "The M(community.crypto.acme_certificate) module also allows to do basic account management. - When using both modules, it is recommended to disable account management - for M(community.crypto.acme_certificate). For that, use the C(modify_account) option of - M(community.crypto.acme_certificate)." + - "The M(community.crypto.acme_certificate) module also allows to do basic account management. + When using both modules, it is recommended to disable account management + for M(community.crypto.acme_certificate). For that, use the C(modify_account) option of + M(community.crypto.acme_certificate)." seealso: - name: Automatic Certificate Management Environment (ACME) description: The specification of the ACME protocol (RFC 8555). @@ -37,8 +37,14 @@ seealso: - module: community.crypto.acme_inspect description: Allows to debug problems. extends_documentation_fragment: -- community.crypto.acme - + - community.crypto.acme + - community.crypto.attributes + - community.crypto.attributes.actiongroup_acme +attributes: + check_mode: + support: full + diff_mode: + support: full options: state: description: diff --git a/plugins/modules/acme_account_info.py b/plugins/modules/acme_account_info.py index 92033fe9..3f240649 100644 --- a/plugins/modules/acme_account_info.py +++ b/plugins/modules/acme_account_info.py @@ -15,16 +15,20 @@ module: acme_account_info author: "Felix Fontein (@felixfontein)" short_description: Retrieves information on ACME accounts description: - - "Allows to retrieve information on accounts a CA supporting the - L(ACME protocol,https://tools.ietf.org/html/rfc8555), - such as L(Let's Encrypt,https://letsencrypt.org/)." - - "This module only works with the ACME v2 protocol." + - "Allows to retrieve information on accounts a CA supporting the + L(ACME protocol,https://tools.ietf.org/html/rfc8555), + such as L(Let's Encrypt,https://letsencrypt.org/)." + - "This module only works with the ACME v2 protocol." notes: - - "The M(community.crypto.acme_account) module allows to modify, create and delete ACME - accounts." - - "This module was called C(acme_account_facts) before Ansible 2.8. The usage - did not change." - - Supports C(check_mode). + - "The M(community.crypto.acme_account) module allows to modify, create and delete ACME + accounts." + - "This module was called C(acme_account_facts) before Ansible 2.8. The usage + did not change." +extends_documentation_fragment: + - community.crypto.acme + - community.crypto.attributes + - community.crypto.attributes.actiongroup_acme + - community.crypto.attributes.info_module options: retrieve_orders: description: @@ -45,8 +49,6 @@ options: seealso: - module: community.crypto.acme_account description: Allows to create, modify or delete an ACME account. -extends_documentation_fragment: -- community.crypto.acme ''' diff --git a/plugins/modules/acme_certificate.py b/plugins/modules/acme_certificate.py index cbe06bdc..274ed1d2 100644 --- a/plugins/modules/acme_certificate.py +++ b/plugins/modules/acme_certificate.py @@ -15,35 +15,35 @@ module: acme_certificate author: "Michael Gruener (@mgruener)" short_description: Create SSL/TLS certificates with the ACME protocol description: - - "Create and renew SSL/TLS certificates with a CA supporting the - L(ACME protocol,https://tools.ietf.org/html/rfc8555), - such as L(Let's Encrypt,https://letsencrypt.org/) or - L(Buypass,https://www.buypass.com/). The current implementation - supports the C(http-01), C(dns-01) and C(tls-alpn-01) challenges." - - "To use this module, it has to be executed twice. Either as two - different tasks in the same run or during two runs. Note that the output - of the first run needs to be recorded and passed to the second run as the - module argument C(data)." - - "Between these two tasks you have to fulfill the required steps for the - chosen challenge by whatever means necessary. For C(http-01) that means - creating the necessary challenge file on the destination webserver. For - C(dns-01) the necessary dns record has to be created. For C(tls-alpn-01) - the necessary certificate has to be created and served. - It is I(not) the responsibility of this module to perform these steps." - - "For details on how to fulfill these challenges, you might have to read through - L(the main ACME specification,https://tools.ietf.org/html/rfc8555#section-8) - and the L(TLS-ALPN-01 specification,https://www.rfc-editor.org/rfc/rfc8737.html#section-3). - Also, consider the examples provided for this module." - - "The module includes experimental support for IP identifiers according to - the L(RFC 8738,https://www.rfc-editor.org/rfc/rfc8738.html)." + - "Create and renew SSL/TLS certificates with a CA supporting the + L(ACME protocol,https://tools.ietf.org/html/rfc8555), + such as L(Let's Encrypt,https://letsencrypt.org/) or + L(Buypass,https://www.buypass.com/). The current implementation + supports the C(http-01), C(dns-01) and C(tls-alpn-01) challenges." + - "To use this module, it has to be executed twice. Either as two + different tasks in the same run or during two runs. Note that the output + of the first run needs to be recorded and passed to the second run as the + module argument C(data)." + - "Between these two tasks you have to fulfill the required steps for the + chosen challenge by whatever means necessary. For C(http-01) that means + creating the necessary challenge file on the destination webserver. For + C(dns-01) the necessary dns record has to be created. For C(tls-alpn-01) + the necessary certificate has to be created and served. + It is I(not) the responsibility of this module to perform these steps." + - "For details on how to fulfill these challenges, you might have to read through + L(the main ACME specification,https://tools.ietf.org/html/rfc8555#section-8) + and the L(TLS-ALPN-01 specification,https://www.rfc-editor.org/rfc/rfc8737.html#section-3). + Also, consider the examples provided for this module." + - "The module includes experimental support for IP identifiers according to + the L(RFC 8738,https://www.rfc-editor.org/rfc/rfc8738.html)." notes: - - "At least one of C(dest) and C(fullchain_dest) must be specified." - - "This module includes basic account management functionality. - If you want to have more control over your ACME account, use the - M(community.crypto.acme_account) module and disable account management - for this module using the C(modify_account) option." - - "This module was called C(letsencrypt) before Ansible 2.6. The usage - did not change." + - "At least one of C(dest) and C(fullchain_dest) must be specified." + - "This module includes basic account management functionality. + If you want to have more control over your ACME account, use the + M(community.crypto.acme_account) module and disable account management + for this module using the C(modify_account) option." + - "This module was called C(letsencrypt) before Ansible 2.6. The usage + did not change." seealso: - name: The Let's Encrypt documentation description: Documentation for the Let's Encrypt Certification Authority. @@ -78,8 +78,17 @@ seealso: - module: community.crypto.acme_inspect description: Allows to debug problems. extends_documentation_fragment: -- community.crypto.acme - + - community.crypto.acme + - community.crypto.attributes + - community.crypto.attributes.files + - community.crypto.attributes.actiongroup_acme +attributes: + check_mode: + support: full + diff_mode: + support: none + safe_file_operations: + support: full options: account_email: description: diff --git a/plugins/modules/acme_certificate_revoke.py b/plugins/modules/acme_certificate_revoke.py index 957262c4..f1922384 100644 --- a/plugins/modules/acme_certificate_revoke.py +++ b/plugins/modules/acme_certificate_revoke.py @@ -15,18 +15,17 @@ module: acme_certificate_revoke author: "Felix Fontein (@felixfontein)" short_description: Revoke certificates with the ACME protocol description: - - "Allows to revoke certificates issued by a CA supporting the - L(ACME protocol,https://tools.ietf.org/html/rfc8555), - such as L(Let's Encrypt,https://letsencrypt.org/)." + - "Allows to revoke certificates issued by a CA supporting the + L(ACME protocol,https://tools.ietf.org/html/rfc8555), + such as L(Let's Encrypt,https://letsencrypt.org/)." notes: - - "Exactly one of C(account_key_src), C(account_key_content), - C(private_key_src) or C(private_key_content) must be specified." - - "Trying to revoke an already revoked certificate - should result in an unchanged status, even if the revocation reason - was different than the one specified here. Also, depending on the - server, it can happen that some other error is returned if the - certificate has already been revoked." - - Does not support C(check_mode). + - "Exactly one of C(account_key_src), C(account_key_content), + C(private_key_src) or C(private_key_content) must be specified." + - "Trying to revoke an already revoked certificate + should result in an unchanged status, even if the revocation reason + was different than the one specified here. Also, depending on the + server, it can happen that some other error is returned if the + certificate has already been revoked." seealso: - name: The Let's Encrypt documentation description: Documentation for the Let's Encrypt Certification Authority. @@ -38,8 +37,14 @@ seealso: - module: community.crypto.acme_inspect description: Allows to debug problems. extends_documentation_fragment: -- community.crypto.acme - + - community.crypto.acme + - community.crypto.attributes + - community.crypto.attributes.actiongroup_acme +attributes: + check_mode: + support: none + diff_mode: + support: none options: certificate: description: diff --git a/plugins/modules/acme_challenge_cert_helper.py b/plugins/modules/acme_challenge_cert_helper.py index 5777c04a..1b963e8c 100644 --- a/plugins/modules/acme_challenge_cert_helper.py +++ b/plugins/modules/acme_challenge_cert_helper.py @@ -15,10 +15,10 @@ module: acme_challenge_cert_helper author: "Felix Fontein (@felixfontein)" short_description: Prepare certificates required for ACME challenges such as C(tls-alpn-01) description: - - "Prepares certificates for ACME challenges such as C(tls-alpn-01)." - - "The raw data is provided by the M(community.crypto.acme_certificate) module, and needs to be - converted to a certificate to be used for challenge validation. This module - provides a simple way to generate the required certificates." + - "Prepares certificates for ACME challenges such as C(tls-alpn-01)." + - "The raw data is provided by the M(community.crypto.acme_certificate) module, and needs to be + converted to a certificate to be used for challenge validation. This module + provides a simple way to generate the required certificates." seealso: - name: Automatic Certificate Management Environment (ACME) description: The specification of the ACME protocol (RFC 8555). @@ -27,7 +27,18 @@ seealso: description: The specification of the C(tls-alpn-01) challenge (RFC 8737). link: https://www.rfc-editor.org/rfc/rfc8737.html requirements: - - "cryptography >= 1.3" + - "cryptography >= 1.3" +extends_documentation_fragment: + - community.crypto.attributes +attributes: + check_mode: + support: none + details: + - This action does not modify state. + diff_mode: + support: N/A + details: + - This action does not modify state. options: challenge: description: @@ -58,8 +69,6 @@ options: - Phassphrase to use to decode the private key. type: str version_added: 1.6.0 -notes: - - Does not support C(check_mode). ''' EXAMPLES = ''' diff --git a/plugins/modules/acme_inspect.py b/plugins/modules/acme_inspect.py index 6ee1f980..d5c96b72 100644 --- a/plugins/modules/acme_inspect.py +++ b/plugins/modules/acme_inspect.py @@ -15,25 +15,25 @@ module: acme_inspect author: "Felix Fontein (@felixfontein)" short_description: Send direct requests to an ACME server description: - - "Allows to send direct requests to an ACME server with the - L(ACME protocol,https://tools.ietf.org/html/rfc8555), - which is supported by CAs such as L(Let's Encrypt,https://letsencrypt.org/)." - - "This module can be used to debug failed certificate request attempts, - for example when M(community.crypto.acme_certificate) fails or encounters a problem which - you wish to investigate." - - "The module can also be used to directly access features of an ACME servers - which are not yet supported by the Ansible ACME modules." + - "Allows to send direct requests to an ACME server with the + L(ACME protocol,https://tools.ietf.org/html/rfc8555), + which is supported by CAs such as L(Let's Encrypt,https://letsencrypt.org/)." + - "This module can be used to debug failed certificate request attempts, + for example when M(community.crypto.acme_certificate) fails or encounters a problem which + you wish to investigate." + - "The module can also be used to directly access features of an ACME servers + which are not yet supported by the Ansible ACME modules." notes: - - "The I(account_uri) option must be specified for properly authenticated - ACME v2 requests (except a C(new-account) request)." - - "Using the C(ansible) tool, M(community.crypto.acme_inspect) can be used to directly execute - ACME requests without the need of writing a playbook. For example, the - following command retrieves the ACME account with ID 1 from Let's Encrypt - (assuming C(/path/to/key) is the correct private account key): - C(ansible localhost -m acme_inspect -a \"account_key_src=/path/to/key - acme_directory=https://acme-v02.api.letsencrypt.org/directory acme_version=2 - account_uri=https://acme-v02.api.letsencrypt.org/acme/acct/1 method=get - url=https://acme-v02.api.letsencrypt.org/acme/acct/1\")" + - "The I(account_uri) option must be specified for properly authenticated + ACME v2 requests (except a C(new-account) request)." + - "Using the C(ansible) tool, M(community.crypto.acme_inspect) can be used to directly execute + ACME requests without the need of writing a playbook. For example, the + following command retrieves the ACME account with ID 1 from Let's Encrypt + (assuming C(/path/to/key) is the correct private account key): + C(ansible localhost -m acme_inspect -a \"account_key_src=/path/to/key + acme_directory=https://acme-v02.api.letsencrypt.org/directory acme_version=2 + account_uri=https://acme-v02.api.letsencrypt.org/acme/acct/1 method=get + url=https://acme-v02.api.letsencrypt.org/acme/acct/1\")" seealso: - name: Automatic Certificate Management Environment (ACME) description: The specification of the ACME protocol (RFC 8555). @@ -42,8 +42,14 @@ seealso: description: The specification of the C(tls-alpn-01) challenge (RFC 8737). link: https://www.rfc-editor.org/rfc/rfc8737.html extends_documentation_fragment: -- community.crypto.acme - + - community.crypto.acme + - community.crypto.attributes + - community.crypto.attributes.actiongroup_acme +attributes: + check_mode: + support: none + diff_mode: + support: none options: url: description: diff --git a/plugins/modules/certificate_complete_chain.py b/plugins/modules/certificate_complete_chain.py index b69fc14e..c05718e0 100644 --- a/plugins/modules/certificate_complete_chain.py +++ b/plugins/modules/certificate_complete_chain.py @@ -26,6 +26,17 @@ description: generated chain is valid, please use C(openssl verify ...)." requirements: - "cryptography >= 1.5" +extends_documentation_fragment: + - community.crypto.attributes +attributes: + check_mode: + support: full + details: + - This action does not modify state. + diff_mode: + support: N/A + details: + - This action does not modify state. options: input_chain: description: diff --git a/plugins/modules/crypto_info.py b/plugins/modules/crypto_info.py index 8f0076ff..1988eb32 100644 --- a/plugins/modules/crypto_info.py +++ b/plugins/modules/crypto_info.py @@ -16,11 +16,12 @@ author: "Felix Fontein (@felixfontein)" short_description: Retrieve cryptographic capabilities version_added: 2.1.0 description: - - Retrieve information on cryptographic capabilities. - - The current version retrieves information on the L(Python cryptography library, https://cryptography.io/) available to - Ansible modules, and on the OpenSSL binary C(openssl) found in the path. -notes: - - Supports C(check_mode). + - Retrieve information on cryptographic capabilities. + - The current version retrieves information on the L(Python cryptography library, https://cryptography.io/) available to + Ansible modules, and on the OpenSSL binary C(openssl) found in the path. +extends_documentation_fragment: + - community.crypto.attributes + - community.crypto.attributes.info_module options: {} ''' diff --git a/plugins/modules/ecs_certificate.py b/plugins/modules/ecs_certificate.py index 465e0b74..b19b86f5 100644 --- a/plugins/modules/ecs_certificate.py +++ b/plugins/modules/ecs_certificate.py @@ -24,6 +24,19 @@ notes: - C(path) must be specified as the output location of the certificate. requirements: - cryptography >= 1.6 +extends_documentation_fragment: + - community.crypto.attributes + - community.crypto.attributes.files + - community.crypto.ecs_credential +attributes: + check_mode: + support: partial + details: + - Check mode is only supported if I(request_type=new). + diff_mode: + support: none + safe_file_operations: + support: full options: backup: description: @@ -337,9 +350,6 @@ seealso: description: Can be used to create private keys (both for certificates and accounts). - module: community.crypto.openssl_csr description: Can be used to create a Certificate Signing Request (CSR). -extends_documentation_fragment: -- community.crypto.ecs_credential - ''' EXAMPLES = r''' diff --git a/plugins/modules/ecs_domain.py b/plugins/modules/ecs_domain.py index 24a82f47..ec7ad98b 100644 --- a/plugins/modules/ecs_domain.py +++ b/plugins/modules/ecs_domain.py @@ -33,6 +33,14 @@ description: notes: - There is a small delay (typically about 5 seconds, but can be as long as 60 seconds) before obtaining the random values when requesting a validation while C(verification_method=dns) or C(verification_method=web_server). Be aware of that if doing many domain validation requests. +extends_documentation_fragment: + - community.crypto.attributes + - community.crypto.ecs_credential +attributes: + check_mode: + support: none + diff_mode: + support: none options: client_id: description: @@ -79,9 +87,6 @@ seealso: description: Can be used to request certificates from ECS, with C(provider=entrust). - module: community.crypto.ecs_certificate description: Can be used to request a Certificate from ECS using a verified domain. -extends_documentation_fragment: -- community.crypto.ecs_credential - ''' EXAMPLES = r''' diff --git a/plugins/modules/get_certificate.py b/plugins/modules/get_certificate.py index 7b238fa8..6ccfae51 100644 --- a/plugins/modules/get_certificate.py +++ b/plugins/modules/get_certificate.py @@ -18,6 +18,17 @@ description: - Makes a secure connection and returns information about the presented certificate - The module uses the cryptography Python library. - Support SNI (L(Server Name Indication,https://en.wikipedia.org/wiki/Server_Name_Indication)) only with python >= 2.7. +extends_documentation_fragment: + - community.crypto.attributes +attributes: + check_mode: + support: none + details: + - This action does not modify state. + diff_mode: + support: N/A + details: + - This action does not modify state. options: host: description: @@ -72,11 +83,11 @@ options: choices: [ auto, cryptography ] notes: - - When using ca_cert on OS X it has been reported that in some conditions the validate will always succeed. + - When using ca_cert on OS X it has been reported that in some conditions the validate will always succeed. requirements: - - "python >= 2.7 when using C(proxy_host)" - - "cryptography >= 1.6" + - "python >= 2.7 when using C(proxy_host)" + - "cryptography >= 1.6" ''' RETURN = ''' diff --git a/plugins/modules/luks_device.py b/plugins/modules/luks_device.py index 78ee105b..d8b70e74 100644 --- a/plugins/modules/luks_device.py +++ b/plugins/modules/luks_device.py @@ -13,12 +13,20 @@ module: luks_device short_description: Manage encrypted (LUKS) devices - description: - "Module manages L(LUKS,https://en.wikipedia.org/wiki/Linux_Unified_Key_Setup) on given device. Supports creating, destroying, opening and closing of LUKS container and adding or removing new keys and passphrases." +extends_documentation_fragment: + - community.crypto.attributes + +attributes: + check_mode: + support: full + diff_mode: + support: none + options: device: description: diff --git a/plugins/modules/openssh_cert.py b/plugins/modules/openssh_cert.py index 92fb5b99..8f428107 100644 --- a/plugins/modules/openssh_cert.py +++ b/plugins/modules/openssh_cert.py @@ -18,6 +18,17 @@ description: - Generate and regenerate OpenSSH host or user certificates. requirements: - "ssh-keygen" +extends_documentation_fragment: + - ansible.builtin.files + - community.crypto.attributes + - community.crypto.attributes.files +attributes: + check_mode: + support: full + diff_mode: + support: full + safe_file_operations: + support: full options: state: description: @@ -180,8 +191,6 @@ options: The serial number may be omitted for checks, but must be specified again for a new certificate. Note: The default value set by ssh-keygen is 0." type: int - -extends_documentation_fragment: files ''' EXAMPLES = ''' diff --git a/plugins/modules/openssh_keypair.py b/plugins/modules/openssh_keypair.py index b7cbb823..274125fc 100644 --- a/plugins/modules/openssh_keypair.py +++ b/plugins/modules/openssh_keypair.py @@ -21,6 +21,17 @@ requirements: - ssh-keygen (if I(backend=openssh)) - cryptography >= 2.6 (if I(backend=cryptography) and OpenSSH < 7.8 is installed) - cryptography >= 3.0 (if I(backend=cryptography) and OpenSSH >= 7.8 is installed) +extends_documentation_fragment: + - ansible.builtin.files + - community.crypto.attributes + - community.crypto.attributes.files +attributes: + check_mode: + support: full + diff_mode: + support: full + safe_file_operations: + support: full options: state: description: @@ -128,10 +139,7 @@ options: notes: - In case the ssh key is broken or password protected, the module will fail. Set the I(force) option to C(true) if you want to regenerate the keypair. - - Supports C(check_mode). - In the case a custom C(mode), C(group), C(owner), or other file attribute is provided it will be applied to both key files. - -extends_documentation_fragment: files ''' EXAMPLES = ''' diff --git a/plugins/modules/openssl_csr.py b/plugins/modules/openssl_csr.py index d416ee1f..d79df0f9 100644 --- a/plugins/modules/openssl_csr.py +++ b/plugins/modules/openssl_csr.py @@ -19,8 +19,20 @@ description: 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: -- Yanis Guenane (@Spredzy) -- Felix Fontein (@felixfontein) + - Yanis Guenane (@Spredzy) + - Felix Fontein (@felixfontein) +extends_documentation_fragment: + - ansible.builtin.files + - community.crypto.attributes + - community.crypto.attributes.files + - community.crypto.module_csr +attributes: + check_mode: + support: full + diff_mode: + support: full + safe_file_operations: + support: full options: state: description: @@ -58,11 +70,8 @@ options: version_added: 1.1.0 name_constraints_critical: version_added: 1.1.0 -extends_documentation_fragment: -- ansible.builtin.files -- community.crypto.module_csr seealso: -- module: community.crypto.openssl_csr_pipe + - module: community.crypto.openssl_csr_pipe ''' EXAMPLES = r''' diff --git a/plugins/modules/openssl_csr_info.py b/plugins/modules/openssl_csr_info.py index 05277ac9..08a28668 100644 --- a/plugins/modules/openssl_csr_info.py +++ b/plugins/modules/openssl_csr_info.py @@ -22,8 +22,12 @@ description: requirements: - cryptography >= 1.3 author: - - Felix Fontein (@felixfontein) - - Yanis Guenane (@Spredzy) + - Felix Fontein (@felixfontein) + - Yanis Guenane (@Spredzy) +extends_documentation_fragment: + - community.crypto.attributes + - community.crypto.attributes.info_module + - community.crypto.name_encoding options: path: description: @@ -45,9 +49,6 @@ options: default: auto choices: [ auto, cryptography ] -extends_documentation_fragment: - - community.crypto.name_encoding - seealso: - module: community.crypto.openssl_csr - module: community.crypto.openssl_csr_pipe diff --git a/plugins/modules/openssl_csr_pipe.py b/plugins/modules/openssl_csr_pipe.py index f5ac86cf..abb5cdae 100644 --- a/plugins/modules/openssl_csr_pipe.py +++ b/plugins/modules/openssl_csr_pipe.py @@ -19,15 +19,21 @@ description: - "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) -- Felix Fontein (@felixfontein) + - Yanis Guenane (@Spredzy) + - Felix Fontein (@felixfontein) +extends_documentation_fragment: + - community.crypto.attributes + - community.crypto.module_csr +attributes: + check_mode: + support: full + diff_mode: + support: full options: content: description: - The existing CSR. type: str -extends_documentation_fragment: -- community.crypto.module_csr seealso: - module: community.crypto.openssl_csr ''' diff --git a/plugins/modules/openssl_dhparam.py b/plugins/modules/openssl_dhparam.py index 05379e8e..d9e1e982 100644 --- a/plugins/modules/openssl_dhparam.py +++ b/plugins/modules/openssl_dhparam.py @@ -27,6 +27,17 @@ requirements: - Or OpenSSL binary C(openssl) author: - Thom Wiggers (@thomwiggers) +extends_documentation_fragment: + - ansible.builtin.files + - community.crypto.attributes + - community.crypto.attributes.files +attributes: + check_mode: + support: full + diff_mode: + support: none + safe_file_operations: + support: full options: state: description: @@ -72,16 +83,12 @@ options: type: bool default: false version_added: "1.0.0" -notes: -- Supports C(check_mode). -extends_documentation_fragment: -- files seealso: -- module: community.crypto.x509_certificate -- module: community.crypto.openssl_csr -- module: community.crypto.openssl_pkcs12 -- module: community.crypto.openssl_privatekey -- module: community.crypto.openssl_publickey + - module: community.crypto.x509_certificate + - module: community.crypto.openssl_csr + - module: community.crypto.openssl_pkcs12 + - module: community.crypto.openssl_privatekey + - module: community.crypto.openssl_publickey ''' EXAMPLES = r''' diff --git a/plugins/modules/openssl_pkcs12.py b/plugins/modules/openssl_pkcs12.py index 53a458f3..e74553b5 100644 --- a/plugins/modules/openssl_pkcs12.py +++ b/plugins/modules/openssl_pkcs12.py @@ -25,6 +25,17 @@ description: # and will be removed in community.crypto (x+1).0.0. requirements: - PyOpenSSL >= 0.15 or cryptography >= 3.0 +extends_documentation_fragment: + - ansible.builtin.files + - community.crypto.attributes + - community.crypto.attributes.files +attributes: + check_mode: + support: full + diff_mode: + support: none + safe_file_operations: + support: full options: action: description: @@ -154,14 +165,12 @@ options: default: auto choices: [ auto, cryptography, pyopenssl ] version_added: 1.7.0 -extends_documentation_fragment: - - files seealso: -- module: community.crypto.x509_certificate -- module: community.crypto.openssl_csr -- module: community.crypto.openssl_dhparam -- module: community.crypto.openssl_privatekey -- module: community.crypto.openssl_publickey + - module: community.crypto.x509_certificate + - module: community.crypto.openssl_csr + - module: community.crypto.openssl_dhparam + - module: community.crypto.openssl_privatekey + - module: community.crypto.openssl_publickey ''' EXAMPLES = r''' diff --git a/plugins/modules/openssl_privatekey.py b/plugins/modules/openssl_privatekey.py index a373241c..ae9604da 100644 --- a/plugins/modules/openssl_privatekey.py +++ b/plugins/modules/openssl_privatekey.py @@ -19,6 +19,18 @@ description: author: - Yanis Guenane (@Spredzy) - Felix Fontein (@felixfontein) +extends_documentation_fragment: + - ansible.builtin.files + - community.crypto.attributes + - community.crypto.attributes.files + - community.crypto.module_privatekey +attributes: + check_mode: + support: full + diff_mode: + support: full + safe_file_operations: + support: full options: state: description: @@ -59,12 +71,9 @@ options: version_added: '1.0.0' regenerate: version_added: '1.0.0' -extends_documentation_fragment: -- ansible.builtin.files -- community.crypto.module_privatekey seealso: -- module: community.crypto.openssl_privatekey_pipe -- module: community.crypto.openssl_privatekey_info + - module: community.crypto.openssl_privatekey_pipe + - module: community.crypto.openssl_privatekey_info ''' EXAMPLES = r''' diff --git a/plugins/modules/openssl_privatekey_convert.py b/plugins/modules/openssl_privatekey_convert.py index 9a9044c3..5aec5cbe 100644 --- a/plugins/modules/openssl_privatekey_convert.py +++ b/plugins/modules/openssl_privatekey_convert.py @@ -19,6 +19,18 @@ description: - The default mode for the private key file will be C(0600) if I(mode) is not explicitly set. author: - Felix Fontein (@felixfontein) +extends_documentation_fragment: + - ansible.builtin.files + - community.crypto.attributes + - community.crypto.attributes.files + - community.crypto.module_privatekey_convert +attributes: + check_mode: + support: full + diff_mode: + support: none + safe_file_operations: + support: full options: dest_path: description: @@ -32,9 +44,6 @@ options: the original private key back if you overwrote it with a new one by accident. type: bool default: false -extends_documentation_fragment: - - ansible.builtin.files - - community.crypto.module_privatekey_convert seealso: [] ''' diff --git a/plugins/modules/openssl_privatekey_info.py b/plugins/modules/openssl_privatekey_info.py index ff47fc2c..30870b28 100644 --- a/plugins/modules/openssl_privatekey_info.py +++ b/plugins/modules/openssl_privatekey_info.py @@ -24,8 +24,11 @@ description: requirements: - cryptography >= 1.2.3 author: - - Felix Fontein (@felixfontein) - - Yanis Guenane (@Spredzy) + - Felix Fontein (@felixfontein) + - Yanis Guenane (@Spredzy) +extends_documentation_fragment: + - community.crypto.attributes + - community.crypto.attributes.info_module options: path: description: @@ -70,12 +73,9 @@ options: default: auto choices: [ auto, cryptography ] -notes: -- Supports C(check_mode). - seealso: -- module: community.crypto.openssl_privatekey -- module: community.crypto.openssl_privatekey_pipe + - module: community.crypto.openssl_privatekey + - module: community.crypto.openssl_privatekey_pipe ''' EXAMPLES = r''' diff --git a/plugins/modules/openssl_privatekey_pipe.py b/plugins/modules/openssl_privatekey_pipe.py index a7f0c645..94fc3826 100644 --- a/plugins/modules/openssl_privatekey_pipe.py +++ b/plugins/modules/openssl_privatekey_pipe.py @@ -23,6 +23,21 @@ description: author: - Yanis Guenane (@Spredzy) - Felix Fontein (@felixfontein) +extends_documentation_fragment: + - community.crypto.attributes + - community.crypto.attributes.flow + - community.crypto.module_privatekey +attributes: + action: + support: full + async: + support: none + details: + - This action runs completely on the controller. + check_mode: + support: full + diff_mode: + support: full options: content: description: @@ -42,11 +57,9 @@ options: current key (if it was provided) and Ansible will replace it by C(VALUE_SPECIFIED_IN_NO_LOG_PARAMETER). type: bool default: false -extends_documentation_fragment: -- community.crypto.module_privatekey seealso: -- module: community.crypto.openssl_privatekey -- module: community.crypto.openssl_privatekey_info + - module: community.crypto.openssl_privatekey + - module: community.crypto.openssl_privatekey_info ''' EXAMPLES = r''' diff --git a/plugins/modules/openssl_publickey.py b/plugins/modules/openssl_publickey.py index f313acd5..b97a4ebf 100644 --- a/plugins/modules/openssl_publickey.py +++ b/plugins/modules/openssl_publickey.py @@ -23,6 +23,17 @@ requirements: author: - Yanis Guenane (@Spredzy) - Felix Fontein (@felixfontein) +extends_documentation_fragment: + - ansible.builtin.files + - community.crypto.attributes + - community.crypto.attributes.files +attributes: + check_mode: + support: full + diff_mode: + support: full + safe_file_operations: + support: full options: state: description: @@ -83,17 +94,15 @@ options: type: bool default: false version_added: '1.0.0' -extends_documentation_fragment: -- files seealso: -- module: community.crypto.x509_certificate -- module: community.crypto.x509_certificate_pipe -- module: community.crypto.openssl_csr -- module: community.crypto.openssl_csr_pipe -- module: community.crypto.openssl_dhparam -- module: community.crypto.openssl_pkcs12 -- module: community.crypto.openssl_privatekey -- module: community.crypto.openssl_privatekey_pipe + - module: community.crypto.x509_certificate + - module: community.crypto.x509_certificate_pipe + - module: community.crypto.openssl_csr + - module: community.crypto.openssl_csr_pipe + - module: community.crypto.openssl_dhparam + - module: community.crypto.openssl_pkcs12 + - module: community.crypto.openssl_privatekey + - module: community.crypto.openssl_privatekey_pipe ''' EXAMPLES = r''' diff --git a/plugins/modules/openssl_publickey_info.py b/plugins/modules/openssl_publickey_info.py index 2ba065bc..611a905d 100644 --- a/plugins/modules/openssl_publickey_info.py +++ b/plugins/modules/openssl_publickey_info.py @@ -21,6 +21,9 @@ requirements: - cryptography >= 1.2.3 author: - Felix Fontein (@felixfontein) +extends_documentation_fragment: + - community.crypto.attributes + - community.crypto.attributes.info_module options: path: description: @@ -41,12 +44,9 @@ options: default: auto choices: [ auto, cryptography ] -notes: -- Supports C(check_mode). - seealso: -- module: community.crypto.openssl_publickey -- module: community.crypto.openssl_privatekey_info + - module: community.crypto.openssl_publickey + - module: community.crypto.openssl_privatekey_info ''' EXAMPLES = r''' diff --git a/plugins/modules/openssl_signature.py b/plugins/modules/openssl_signature.py index 60d74469..363a0553 100644 --- a/plugins/modules/openssl_signature.py +++ b/plugins/modules/openssl_signature.py @@ -22,6 +22,15 @@ requirements: author: - Patrick Pichler (@aveexy) - Markus Teufelberger (@MarkusTeufelberger) +extends_documentation_fragment: + - community.crypto.attributes +attributes: + check_mode: + support: full + details: + - This action does not modify state. + diff_mode: + support: none options: privatekey_path: description: diff --git a/plugins/modules/openssl_signature_info.py b/plugins/modules/openssl_signature_info.py index cb512f31..508a47c0 100644 --- a/plugins/modules/openssl_signature_info.py +++ b/plugins/modules/openssl_signature_info.py @@ -22,6 +22,9 @@ requirements: author: - Patrick Pichler (@aveexy) - Markus Teufelberger (@MarkusTeufelberger) +extends_documentation_fragment: + - community.crypto.attributes + - community.crypto.attributes.info_module options: path: description: @@ -57,7 +60,6 @@ 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 diff --git a/plugins/modules/x509_certificate.py b/plugins/modules/x509_certificate.py index e16d8e65..398dfabc 100644 --- a/plugins/modules/x509_certificate.py +++ b/plugins/modules/x509_certificate.py @@ -29,8 +29,24 @@ description: keyword, the new name M(community.crypto.x509_certificate) should be used to avoid a deprecation warning. author: - - Yanis Guenane (@Spredzy) - - Markus Teufelberger (@MarkusTeufelberger) + - Yanis Guenane (@Spredzy) + - Markus Teufelberger (@MarkusTeufelberger) +extends_documentation_fragment: + - ansible.builtin.files + - community.crypto.attributes + - community.crypto.attributes.files + - community.crypto.module_certificate + - community.crypto.module_certificate.backend_acme_documentation + - community.crypto.module_certificate.backend_entrust_documentation + - community.crypto.module_certificate.backend_ownca_documentation + - community.crypto.module_certificate.backend_selfsigned_documentation +attributes: + check_mode: + support: full + diff_mode: + support: full + safe_file_operations: + support: full options: state: description: @@ -82,19 +98,8 @@ options: ownca_privatekey_content: version_added: '1.0.0' -notes: -- Supports C(check_mode). - seealso: -- module: community.crypto.x509_certificate_pipe - -extends_documentation_fragment: - - ansible.builtin.files - - community.crypto.module_certificate - - community.crypto.module_certificate.backend_acme_documentation - - community.crypto.module_certificate.backend_entrust_documentation - - community.crypto.module_certificate.backend_ownca_documentation - - community.crypto.module_certificate.backend_selfsigned_documentation + - module: community.crypto.x509_certificate_pipe ''' EXAMPLES = r''' diff --git a/plugins/modules/x509_certificate_info.py b/plugins/modules/x509_certificate_info.py index 6a3678f0..5696767b 100644 --- a/plugins/modules/x509_certificate_info.py +++ b/plugins/modules/x509_certificate_info.py @@ -28,9 +28,13 @@ description: requirements: - cryptography >= 1.6 author: - - Felix Fontein (@felixfontein) - - Yanis Guenane (@Spredzy) - - Markus Teufelberger (@MarkusTeufelberger) + - Felix Fontein (@felixfontein) + - Yanis Guenane (@Spredzy) + - Markus Teufelberger (@MarkusTeufelberger) +extends_documentation_fragment: + - community.crypto.attributes + - community.crypto.attributes.info_module + - community.crypto.name_encoding options: path: description: @@ -63,16 +67,12 @@ options: default: auto choices: [ auto, cryptography ] -extends_documentation_fragment: - - community.crypto.name_encoding - 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 + - module: community.crypto.x509_certificate + - module: community.crypto.x509_certificate_pipe ''' EXAMPLES = r''' diff --git a/plugins/modules/x509_certificate_pipe.py b/plugins/modules/x509_certificate_pipe.py index 24c16b5f..440a2cdf 100644 --- a/plugins/modules/x509_certificate_pipe.py +++ b/plugins/modules/x509_certificate_pipe.py @@ -23,9 +23,20 @@ description: 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: - - Yanis Guenane (@Spredzy) - - Markus Teufelberger (@MarkusTeufelberger) - - Felix Fontein (@felixfontein) + - Yanis Guenane (@Spredzy) + - Markus Teufelberger (@MarkusTeufelberger) + - Felix Fontein (@felixfontein) +extends_documentation_fragment: + - community.crypto.attributes + - community.crypto.module_certificate + - community.crypto.module_certificate.backend_entrust_documentation + - community.crypto.module_certificate.backend_ownca_documentation + - community.crypto.module_certificate.backend_selfsigned_documentation +attributes: + check_mode: + support: full + diff_mode: + support: full options: provider: description: @@ -42,16 +53,7 @@ options: type: str 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 - - community.crypto.module_certificate.backend_ownca_documentation - - community.crypto.module_certificate.backend_selfsigned_documentation + - module: community.crypto.x509_certificate ''' EXAMPLES = r''' diff --git a/plugins/modules/x509_crl.py b/plugins/modules/x509_crl.py index 694539f9..cb0ea24f 100644 --- a/plugins/modules/x509_crl.py +++ b/plugins/modules/x509_crl.py @@ -22,6 +22,18 @@ requirements: - cryptography >= 1.2 author: - Felix Fontein (@felixfontein) +extends_documentation_fragment: + - ansible.builtin.files + - community.crypto.attributes + - community.crypto.attributes.files + - community.crypto.name_encoding +attributes: + check_mode: + support: full + diff_mode: + support: full + safe_file_operations: + support: full options: state: description: @@ -241,14 +253,9 @@ options: type: bool default: false -extends_documentation_fragment: - - files - - community.crypto.name_encoding - 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''' diff --git a/plugins/modules/x509_crl_info.py b/plugins/modules/x509_crl_info.py index c3d335f0..f7d140b7 100644 --- a/plugins/modules/x509_crl_info.py +++ b/plugins/modules/x509_crl_info.py @@ -20,6 +20,10 @@ requirements: - cryptography >= 1.2 author: - Felix Fontein (@felixfontein) +extends_documentation_fragment: + - community.crypto.attributes + - community.crypto.attributes.info_module + - community.crypto.name_encoding options: path: description: @@ -41,13 +45,9 @@ options: default: true version_added: 1.7.0 -extends_documentation_fragment: - - community.crypto.name_encoding - 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_crl '''