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

@@ -7,12 +7,11 @@ requires_ansible: '>=2.9.10'
 
 action_groups:
   acme:
-  - acme_inspect
+    - acme_inspect
-  - acme_certificate_revoke
+    - acme_certificate_revoke
-  - acme_certificate
+    - acme_certificate
-  - acme_account
+    - acme_account
-  - acme_account_facts
+    - acme_account_info
-  - acme_account_info
 
 plugin_routing:
   modules:

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.
+'''

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
+  - "Allows to create, modify or delete accounts with a CA supporting the
-      L(ACME protocol,https://tools.ietf.org/html/rfc8555),
+     L(ACME protocol,https://tools.ietf.org/html/rfc8555),
-      such as L(Let's Encrypt,https://letsencrypt.org/)."
+     such as L(Let's Encrypt,https://letsencrypt.org/)."
-   - "This module only works with the ACME v2 protocol."
+  - "This module only works with the ACME v2 protocol."
 notes:
-   - "The M(community.crypto.acme_certificate) module also allows to do basic account management.
+  - "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
+     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
+     for M(community.crypto.acme_certificate). For that, use the C(modify_account) option of
-      M(community.crypto.acme_certificate)."
+     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:

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
+  - "Allows to retrieve information on accounts a CA supporting the
-      L(ACME protocol,https://tools.ietf.org/html/rfc8555),
+     L(ACME protocol,https://tools.ietf.org/html/rfc8555),
-      such as L(Let's Encrypt,https://letsencrypt.org/)."
+     such as L(Let's Encrypt,https://letsencrypt.org/)."
-   - "This module only works with the ACME v2 protocol."
+  - "This module only works with the ACME v2 protocol."
 notes:
-   - "The M(community.crypto.acme_account) module allows to modify, create and delete ACME
+  - "The M(community.crypto.acme_account) module allows to modify, create and delete ACME
-      accounts."
+     accounts."
-   - "This module was called C(acme_account_facts) before Ansible 2.8. The usage
+  - "This module was called C(acme_account_facts) before Ansible 2.8. The usage
-      did not change."
+     did not change."
-   - Supports C(check_mode).
+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
 
 '''
 

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
+  - "Create and renew SSL/TLS certificates with a CA supporting the
-      L(ACME protocol,https://tools.ietf.org/html/rfc8555),
+     L(ACME protocol,https://tools.ietf.org/html/rfc8555),
-      such as L(Let's Encrypt,https://letsencrypt.org/) or
+     such as L(Let's Encrypt,https://letsencrypt.org/) or
-      L(Buypass,https://www.buypass.com/). The current implementation
+     L(Buypass,https://www.buypass.com/). The current implementation
-      supports the C(http-01), C(dns-01) and C(tls-alpn-01) challenges."
+     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
+  - "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
+     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
+     of the first run needs to be recorded and passed to the second run as the
-      module argument C(data)."
+     module argument C(data)."
-   - "Between these two tasks you have to fulfill the required steps for the
+  - "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
+     chosen challenge by whatever means necessary. For C(http-01) that means
-      creating the necessary challenge file on the destination webserver. For
+     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)
+     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.
+     the necessary certificate has to be created and served.
-      It is I(not) the responsibility of this module to perform these steps."
+     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
+  - "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)
+     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).
+     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."
+     Also, consider the examples provided for this module."
-   - "The module includes experimental support for IP identifiers according to
+  - "The module includes experimental support for IP identifiers according to
-      the L(RFC 8738,https://www.rfc-editor.org/rfc/rfc8738.html)."
+     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."
+  - "At least one of C(dest) and C(fullchain_dest) must be specified."
-   - "This module includes basic account management functionality.
+  - "This module includes basic account management functionality.
-      If you want to have more control over your ACME account, use the
+     If you want to have more control over your ACME account, use the
-      M(community.crypto.acme_account) module and disable account management
+     M(community.crypto.acme_account) module and disable account management
-      for this module using the C(modify_account) option."
+     for this module using the C(modify_account) option."
-   - "This module was called C(letsencrypt) before Ansible 2.6. The usage
+  - "This module was called C(letsencrypt) before Ansible 2.6. The usage
-      did not change."
+     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:

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
+  - "Allows to revoke certificates issued by a CA supporting the
-      L(ACME protocol,https://tools.ietf.org/html/rfc8555),
+     L(ACME protocol,https://tools.ietf.org/html/rfc8555),
-      such as L(Let's Encrypt,https://letsencrypt.org/)."
+     such as L(Let's Encrypt,https://letsencrypt.org/)."
 notes:
-   - "Exactly one of C(account_key_src), C(account_key_content),
+  - "Exactly one of C(account_key_src), C(account_key_content),
-      C(private_key_src) or C(private_key_content) must be specified."
+     C(private_key_src) or C(private_key_content) must be specified."
-   - "Trying to revoke an already revoked certificate
+  - "Trying to revoke an already revoked certificate
-      should result in an unchanged status, even if the revocation reason
+     should result in an unchanged status, even if the revocation reason
-      was different than the one specified here. Also, depending on the
+     was different than the one specified here. Also, depending on the
-      server, it can happen that some other error is returned if the
+     server, it can happen that some other error is returned if the
-      certificate has already been revoked."
+     certificate has already been revoked."
-   - Does not support C(check_mode).
 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:

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)."
+  - "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
+  - "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
+     converted to a certificate to be used for challenge validation. This module
-      provides a simple way to generate the required certificates."
+     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 = '''

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
+  - "Allows to send direct requests to an ACME server with the
-      L(ACME protocol,https://tools.ietf.org/html/rfc8555),
+     L(ACME protocol,https://tools.ietf.org/html/rfc8555),
-      which is supported by CAs such as L(Let's Encrypt,https://letsencrypt.org/)."
+     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,
+  - "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
+     for example when M(community.crypto.acme_certificate) fails or encounters a problem which
-      you wish to investigate."
+     you wish to investigate."
-   - "The module can also be used to directly access features of an ACME servers
+  - "The module can also be used to directly access features of an ACME servers
-      which are not yet supported by the Ansible ACME modules."
+     which are not yet supported by the Ansible ACME modules."
 notes:
-   - "The I(account_uri) option must be specified for properly authenticated
+  - "The I(account_uri) option must be specified for properly authenticated
-      ACME v2 requests (except a C(new-account) request)."
+     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
+  - "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
+     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
+     following command retrieves the ACME account with ID 1 from Let's Encrypt
-      (assuming C(/path/to/key) is the correct private account key):
+     (assuming C(/path/to/key) is the correct private account key):
-      C(ansible localhost -m acme_inspect -a \"account_key_src=/path/to/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
+     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
+     account_uri=https://acme-v02.api.letsencrypt.org/acme/acct/1 method=get
-      url=https://acme-v02.api.letsencrypt.org/acme/acct/1\")"
+     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:

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:

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.
+  - Retrieve information on cryptographic capabilities.
-   - The current version retrieves information on the L(Python cryptography library, https://cryptography.io/) available to
+  - 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.
+    Ansible modules, and on the OpenSSL binary C(openssl) found in the path.
-notes:
+extends_documentation_fragment:
-   - Supports C(check_mode).
+  - community.crypto.attributes
+  - community.crypto.attributes.info_module
 options: {}
 '''
 

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'''

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'''

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)"
+    - "python >= 2.7 when using C(proxy_host)"
-  - "cryptography >= 1.6"
+    - "cryptography >= 1.6"
 '''
 
 RETURN = '''

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:

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 = '''

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 = '''

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)
+    - Yanis Guenane (@Spredzy)
-- Felix Fontein (@felixfontein)
+    - 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'''

plugins/modules/openssl_csr_info.py

@@ -22,8 +22,12 @@ description:
 requirements:
     - cryptography >= 1.3
 author:
-  - Felix Fontein (@felixfontein)
+    - Felix Fontein (@felixfontein)
-  - Yanis Guenane (@Spredzy)
+    - 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

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)
+    - Yanis Guenane (@Spredzy)
-- Felix Fontein (@felixfontein)
+    - 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
 '''

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.x509_certificate
-- module: community.crypto.openssl_csr
+    - module: community.crypto.openssl_csr
-- module: community.crypto.openssl_pkcs12
+    - module: community.crypto.openssl_pkcs12
-- module: community.crypto.openssl_privatekey
+    - module: community.crypto.openssl_privatekey
-- module: community.crypto.openssl_publickey
+    - module: community.crypto.openssl_publickey
 '''
 
 EXAMPLES = r'''

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.x509_certificate
-- module: community.crypto.openssl_csr
+    - module: community.crypto.openssl_csr
-- module: community.crypto.openssl_dhparam
+    - module: community.crypto.openssl_dhparam
-- module: community.crypto.openssl_privatekey
+    - module: community.crypto.openssl_privatekey
-- module: community.crypto.openssl_publickey
+    - module: community.crypto.openssl_publickey
 '''
 
 EXAMPLES = r'''

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_pipe
-- module: community.crypto.openssl_privatekey_info
+    - module: community.crypto.openssl_privatekey_info
 '''
 
 EXAMPLES = r'''

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: []
 '''
 

plugins/modules/openssl_privatekey_info.py

@@ -24,8 +24,11 @@ description:
 requirements:
     - cryptography >= 1.2.3
 author:
-  - Felix Fontein (@felixfontein)
+    - Felix Fontein (@felixfontein)
-  - Yanis Guenane (@Spredzy)
+    - 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
-- module: community.crypto.openssl_privatekey_pipe
+    - module: community.crypto.openssl_privatekey_pipe
 '''
 
 EXAMPLES = r'''

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
-- module: community.crypto.openssl_privatekey_info
+    - module: community.crypto.openssl_privatekey_info
 '''
 
 EXAMPLES = r'''

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
-- module: community.crypto.x509_certificate_pipe
+    - module: community.crypto.x509_certificate_pipe
-- module: community.crypto.openssl_csr
+    - module: community.crypto.openssl_csr
-- module: community.crypto.openssl_csr_pipe
+    - module: community.crypto.openssl_csr_pipe
-- module: community.crypto.openssl_dhparam
+    - module: community.crypto.openssl_dhparam
-- module: community.crypto.openssl_pkcs12
+    - module: community.crypto.openssl_pkcs12
-- module: community.crypto.openssl_privatekey
+    - module: community.crypto.openssl_privatekey
-- module: community.crypto.openssl_privatekey_pipe
+    - module: community.crypto.openssl_privatekey_pipe
 '''
 
 EXAMPLES = r'''

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_publickey
-- module: community.crypto.openssl_privatekey_info
+    - module: community.crypto.openssl_privatekey_info
 '''
 
 EXAMPLES = r'''

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:

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

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)
+    - Yanis Guenane (@Spredzy)
-  - Markus Teufelberger (@MarkusTeufelberger)
+    - 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
+    - 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
 '''
 
 EXAMPLES = r'''

plugins/modules/x509_certificate_info.py

@@ -28,9 +28,13 @@ description:
 requirements:
     - cryptography >= 1.6
 author:
-  - Felix Fontein (@felixfontein)
+    - Felix Fontein (@felixfontein)
-  - Yanis Guenane (@Spredzy)
+    - Yanis Guenane (@Spredzy)
-  - Markus Teufelberger (@MarkusTeufelberger)
+    - 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
-- module: community.crypto.x509_certificate_pipe
+    - module: community.crypto.x509_certificate_pipe
 '''
 
 EXAMPLES = r'''

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)
+    - Yanis Guenane (@Spredzy)
-  - Markus Teufelberger (@MarkusTeufelberger)
+    - Markus Teufelberger (@MarkusTeufelberger)
-  - Felix Fontein (@felixfontein)
+    - 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
+    - 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
 '''
 
 EXAMPLES = r'''

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'''

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
 '''