Split up the default acme docs fragment to allow modules ot not need account data. (#735)

changelogs/fragments/735-acme-docs-fragment.yml

@@ -0,0 +1,2 @@
+deprecated_features:
+  - "acme documentation fragment - the default ``community.crypto.acme[.documentation]`` docs fragment is deprecated and will be removed from community.crypto 3.0.0. Replace it with both the new ``community.crypto.acme.basic`` and ``community.crypto.acme.account`` fragments (https://github.com/ansible-collections/community.crypto/pull/735)."

plugins/doc_fragments/acme.py

@@ -11,6 +11,9 @@ __metaclass__ = type
 class ModuleDocFragment(object):
 
     # Standard files documentation fragment
+    #
+    # NOTE: This document fragment is DEPRECATED and will be removed from community.crypto 3.0.0.
+    #       Use both the BASIC and ACCOUNT fragments as a replacement.
     DOCUMENTATION = r'''
 notes:
   - "If a new enough version of the C(cryptography) library
@@ -136,4 +139,149 @@ options:
     type: int
     default: 10
     version_added: 2.3.0
+'''
+
+    # Basic documentation fragment without account data
+    BASIC = r'''
+notes:
+  - "Although the defaults are chosen so that the module can be used with
+     the L(Let's Encrypt,https://letsencrypt.org/) CA, the module can in
+     principle be used with any CA providing an ACME endpoint, such as
+     L(Buypass Go SSL,https://www.buypass.com/ssl/products/acme)."
+  - "So far, the ACME modules have only been tested by the developers against
+     Let's Encrypt (staging and production), Buypass (staging and production), ZeroSSL (production),
+     and L(Pebble testing server,https://github.com/letsencrypt/Pebble). We have got
+     community feedback that they also work with Sectigo ACME Service for InCommon.
+     If you experience problems with another ACME server, please
+     L(create an issue,https://github.com/ansible-collections/community.crypto/issues/new/choose)
+     to help us supporting it. Feedback that an ACME server not mentioned does work
+     is also appreciated."
+requirements:
+  - either openssl or L(cryptography,https://cryptography.io/) >= 1.5
+  - ipaddress
+options:
+  acme_version:
+    description:
+      - "The ACME version of the endpoint."
+      - "Must be V(1) for the classic Let's Encrypt and Buypass ACME endpoints,
+         or V(2) for standardized ACME v2 endpoints."
+      - "The value V(1) is deprecated since community.crypto 2.0.0 and will be
+         removed from community.crypto 3.0.0."
+    required: true
+    type: int
+    choices: [ 1, 2 ]
+  acme_directory:
+    description:
+      - "The ACME directory to use. This is the entry point URL to access
+         the ACME CA server API."
+      - "For safety reasons the default is set to the Let's Encrypt staging
+         server (for the ACME v1 protocol). This will create technically correct,
+         but untrusted certificates."
+      - "For Let's Encrypt, all staging endpoints can be found here:
+         U(https://letsencrypt.org/docs/staging-environment/). For Buypass, all
+         endpoints can be found here:
+         U(https://community.buypass.com/t/63d4ay/buypass-go-ssl-endpoints)"
+      - "For B(Let's Encrypt), the production directory URL for ACME v2 is
+         U(https://acme-v02.api.letsencrypt.org/directory)."
+      - "For B(Buypass), the production directory URL for ACME v2 and v1 is
+         U(https://api.buypass.com/acme/directory)."
+      - "For B(ZeroSSL), the production directory URL for ACME v2 is
+         U(https://acme.zerossl.com/v2/DV90)."
+      - "For B(Sectigo), the production directory URL for ACME v2 is
+         U(https://acme-qa.secure.trust-provider.com/v2/DV)."
+      - The notes for this module contain a list of ACME services this module has
+        been tested against.
+    required: true
+    type: str
+  validate_certs:
+    description:
+      - Whether calls to the ACME directory will validate TLS certificates.
+      - "B(Warning:) Should B(only ever) be set to V(false) for testing purposes,
+         for example when testing against a local Pebble server."
+    type: bool
+    default: true
+  select_crypto_backend:
+    description:
+      - Determines which crypto backend to use.
+      - The default choice is V(auto), which tries to use C(cryptography) if available, and falls back to
+        C(openssl).
+      - If set to V(openssl), will try to use the C(openssl) binary.
+      - If set to V(cryptography), will try to use the
+        L(cryptography,https://cryptography.io/) library.
+    type: str
+    default: auto
+    choices: [ auto, cryptography, openssl ]
+  request_timeout:
+    description:
+      - The time Ansible should wait for a response from the ACME API.
+      - This timeout is applied to all HTTP(S) requests (HEAD, GET, POST).
+    type: int
+    default: 10
+    version_added: 2.3.0
+'''
+
+    # Account data documentation fragment
+    ACCOUNT = r'''
+notes:
+  - "If a new enough version of the C(cryptography) library
+     is available (see Requirements for details), it will be used
+     instead of the C(openssl) binary. This can be explicitly disabled
+     or enabled with the O(select_crypto_backend) option. Note that using
+     the C(openssl) binary will be slower and less secure, as private key
+     contents always have to be stored on disk (see
+     O(account_key_content))."
+options:
+  account_key_src:
+    description:
+      - "Path to a file containing the ACME account RSA or Elliptic Curve
+         key."
+      - "Private keys can be created with the
+         M(community.crypto.openssl_privatekey) or M(community.crypto.openssl_privatekey_pipe)
+         modules. If the requisite (cryptography) is not available,
+         keys can also be created directly with the C(openssl) command line tool:
+         RSA keys can be created with C(openssl genrsa ...). Elliptic curve keys
+         can be created with C(openssl ecparam -genkey ...). Any other tool creating
+         private keys in PEM format can be used as well."
+      - "Mutually exclusive with O(account_key_content)."
+      - "Required if O(account_key_content) is not used."
+    type: path
+    aliases: [ account_key ]
+  account_key_content:
+    description:
+      - "Content of the ACME account RSA or Elliptic Curve key."
+      - "Mutually exclusive with O(account_key_src)."
+      - "Required if O(account_key_src) is not used."
+      - "B(Warning:) the content will be written into a temporary file, which will
+         be deleted by Ansible when the module completes. Since this is an
+         important private key — it can be used to change the account key,
+         or to revoke your certificates without knowing their private keys
+         —, this might not be acceptable."
+      - "In case C(cryptography) is used, the content is not written into a
+         temporary file. It can still happen that it is written to disk by
+         Ansible in the process of moving the module with its argument to
+         the node where it is executed."
+    type: str
+  account_key_passphrase:
+    description:
+      - Phassphrase to use to decode the account key.
+      - "B(Note:) this is not supported by the C(openssl) backend, only by the C(cryptography) backend."
+    type: str
+    version_added: 1.6.0
+  account_uri:
+    description:
+      - "If specified, assumes that the account URI is as given. If the
+         account key does not match this account, or an account with this
+         URI does not exist, the module fails."
+    type: str
+'''
+
+    # No account data documentation fragment
+    NO_ACCOUNT = r'''
+notes:
+  - "If a new enough version of the C(cryptography) library
+     is available (see Requirements for details), it will be used
+     instead of the C(openssl) binary. This can be explicitly disabled
+     or enabled with the O(select_crypto_backend) option. Note that using
+     the C(openssl) binary will be slower."
+options: {}
 '''

plugins/module_utils/acme/acme.py

@@ -168,9 +168,9 @@ class ACMEClient(object):
         self.backend = backend
         self.version = module.params['acme_version']
         # account_key path and content are mutually exclusive
-        self.account_key_file = module.params['account_key_src']
-        self.account_key_content = module.params['account_key_content']
-        self.account_key_passphrase = module.params['account_key_passphrase']
+        self.account_key_file = module.params.get('account_key_src')
+        self.account_key_content = module.params.get('account_key_content')
+        self.account_key_passphrase = module.params.get('account_key_passphrase')
 
         # Grab account URI from module parameters.
         # Make sure empty string is treated as None.
@@ -384,21 +384,25 @@ class ACMEClient(object):
         return result, info
 
 
-def get_default_argspec():
+def get_default_argspec(with_account=True):
     '''
     Provides default argument spec for the options documented in the acme doc fragment.
     '''
-    return dict(
-        account_key_src=dict(type='path', aliases=['account_key']),
-        account_key_content=dict(type='str', no_log=True),
-        account_key_passphrase=dict(type='str', no_log=True),
-        account_uri=dict(type='str'),
+    argspec = dict(
         acme_directory=dict(type='str', required=True),
         acme_version=dict(type='int', required=True, choices=[1, 2]),
         validate_certs=dict(type='bool', default=True),
         select_crypto_backend=dict(type='str', default='auto', choices=['auto', 'openssl', 'cryptography']),
         request_timeout=dict(type='int', default=10),
     )
+    if with_account:
+        argspec.update(dict(
+            account_key_src=dict(type='path', aliases=['account_key']),
+            account_key_content=dict(type='str', no_log=True),
+            account_key_passphrase=dict(type='str', no_log=True),
+            account_uri=dict(type='str'),
+        ))
+    return argspec
 
 
 def create_backend(module, needs_acme_v2):

plugins/modules/acme_account.py

@@ -37,7 +37,8 @@ seealso:
   - module: community.crypto.acme_inspect
     description: Allows to debug problems.
 extends_documentation_fragment:
-  - community.crypto.acme
+  - community.crypto.acme.basic
+  - community.crypto.acme.account
   - community.crypto.attributes
   - community.crypto.attributes.actiongroup_acme
 attributes:

plugins/modules/acme_account_info.py

@@ -25,7 +25,8 @@ notes:
   - "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.acme.basic
+  - community.crypto.acme.account
   - community.crypto.attributes
   - community.crypto.attributes.actiongroup_acme
   - community.crypto.attributes.info_module

plugins/modules/acme_certificate.py

@@ -78,7 +78,8 @@ seealso:
   - module: community.crypto.acme_inspect
     description: Allows to debug problems.
 extends_documentation_fragment:
-  - community.crypto.acme
+  - community.crypto.acme.basic
+  - community.crypto.acme.account
   - community.crypto.attributes
   - community.crypto.attributes.files
   - community.crypto.attributes.actiongroup_acme

plugins/modules/acme_certificate_revoke.py

@@ -37,7 +37,8 @@ seealso:
   - module: community.crypto.acme_inspect
     description: Allows to debug problems.
 extends_documentation_fragment:
-  - community.crypto.acme
+  - community.crypto.acme.basic
+  - community.crypto.acme.account
   - community.crypto.attributes
   - community.crypto.attributes.actiongroup_acme
 attributes:

plugins/modules/acme_inspect.py

@@ -42,7 +42,8 @@ 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.basic
+  - community.crypto.acme.account
   - community.crypto.attributes
   - community.crypto.attributes.actiongroup_acme
 attributes: