Revert "Revert all non-bugfixes merged since the last release."

This reverts commit 82251c2.

README.md

@@ -66,7 +66,9 @@ If you use the Ansible package and do not update collections independently, use
 - ACME modules and plugins:
   - acme_account_info module
   - acme_account module
+  - acme_ari_info module
   - acme_certificate module
+  - acme_certificate_deactivate_authz module
   - acme_certificate_revoke module
   - acme_challenge_cert_helper module
   - acme_inspect module

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)."

changelogs/fragments/736-cert-info.yml

@@ -0,0 +1,2 @@
+deprecated_features:
+  - "acme.backends module utils - the ``get_cert_information()`` method for a ACME crypto backend must be implemented from community.crypto 3.0.0 on (https://github.com/ansible-collections/community.crypto/pull/736)."

changelogs/fragments/739-acme_certificate-include_renewal_cert_id.yml

@@ -0,0 +1,2 @@
+minor_changes:
+  - "acme_certificate - add ``include_renewal_cert_id`` option to allow requesting renewal of a specific certificate according to the current ACME Renewal Information specification draft (https://github.com/ansible-collections/community.crypto/pull/739)."

changelogs/fragments/745-absolute-time.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - "x509_crl, x509_certificate, x509_certificate_info - when parsing absolute timestamps which omitted the second count, the first digit of the minutes was used as a one-digit minutes count, and the second digit of the minutes as a one-digit second count (https://github.com/ansible-collections/community.crypto/pull/745)."

changelogs/fragments/749-argspec.yml

@@ -0,0 +1,2 @@
+deprecated_features:
+  - "crypto.module_backends.common module utils - the ``crypto.module_backends.common`` module utils is deprecated and will be removed from community.crypto 3.0.0. Use the improved ``argspec`` module util instead (https://github.com/ansible-collections/community.crypto/pull/749)."

meta/runtime.yml

@@ -8,6 +8,7 @@ requires_ansible: '>=2.9.10'
 action_groups:
   acme:
     - acme_inspect
+    - acme_certificate_deactivate_authz
     - acme_certificate_revoke
     - acme_certificate
     - acme_account

plugins/doc_fragments/acme.py

@@ -11,6 +11,9 @@
 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
@@ -137,3 +140,178 @@ class ModuleDocFragment(object):
     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: {}
+'''
+
+    CERTIFICATE = r'''
+options:
+  csr:
+    description:
+      - "File containing the CSR for the new certificate."
+      - "Can be created with M(community.crypto.openssl_csr)."
+      - "The CSR may contain multiple Subject Alternate Names, but each one
+         will lead to an individual challenge that must be fulfilled for the
+         CSR to be signed."
+      - "B(Note): the private key used to create the CSR B(must not) be the
+         account key. This is a bad idea from a security point of view, and
+         the CA should not accept the CSR. The ACME server should return an
+         error in this case."
+      - Precisely one of O(csr) or O(csr_content) must be specified.
+    type: path
+  csr_content:
+    description:
+      - "Content of the CSR for the new certificate."
+      - "Can be created with M(community.crypto.openssl_csr_pipe)."
+      - "The CSR may contain multiple Subject Alternate Names, but each one
+         will lead to an individual challenge that must be fulfilled for the
+         CSR to be signed."
+      - "B(Note): the private key used to create the CSR B(must not) be the
+         account key. This is a bad idea from a security point of view, and
+         the CA should not accept the CSR. The ACME server should return an
+         error in this case."
+      - Precisely one of O(csr) or O(csr_content) must be specified.
+    type: str
+'''

plugins/module_utils/acme/acme.py

@@ -21,6 +21,8 @@
 from ansible.module_utils.urls import fetch_url
 from ansible.module_utils.six import PY3
 
+from ansible_collections.community.crypto.plugins.module_utils.argspec import ArgumentSpec
+
 from ansible_collections.community.crypto.plugins.module_utils.acme.backend_openssl_cli import (
     OpenSSLCLIBackend,
 )
@@ -42,7 +44,9 @@
 )
 
 from ansible_collections.community.crypto.plugins.module_utils.acme.utils import (
+    compute_cert_id,
     nopad_b64,
+    parse_retry_after,
 )
 
 try:
@@ -153,6 +157,9 @@ def get_nonce(self, resource=None):
                     self.module, msg='Was not able to obtain nonce, giving up after 5 retries', info=info, response=response)
             retry_count += 1
 
+    def has_renewal_info_endpoint(self):
+        return 'renewalInfo' in self.directory
+
 
 class ACMEClient(object):
     '''
@@ -168,9 +175,9 @@ def __init__(self, module, backend):
         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.
@@ -383,24 +390,94 @@ def get_request(self, uri, parse_json_result=True, headers=None, get_only=False,
                 self.module, msg=error_msg, info=info, content=content, content_json=result if parsed_json_result else None)
         return result, info
 
+    def get_renewal_info(
+        self,
+        cert_id=None,
+        cert_info=None,
+        cert_filename=None,
+        cert_content=None,
+        include_retry_after=False,
+        retry_after_relative_with_timezone=True,
+    ):
+        if not self.directory.has_renewal_info_endpoint():
+            raise ModuleFailException('The ACME endpoint does not support ACME Renewal Information retrieval')
+
+        if cert_id is None:
+            cert_id = compute_cert_id(self.backend, cert_info=cert_info, cert_filename=cert_filename, cert_content=cert_content)
+        url = '{base}{cert_id}'.format(base=self.directory.directory['renewalInfo'], cert_id=cert_id)
+
+        data, info = self.get_request(url, parse_json_result=True, fail_on_error=True, get_only=True)
+
+        # Include Retry-After header if asked for
+        if include_retry_after and 'retry-after' in info:
+            try:
+                data['retryAfter'] = parse_retry_after(
+                    info['retry-after'],
+                    relative_with_timezone=retry_after_relative_with_timezone,
+                )
+            except ValueError:
+                pass
+        return data
+
 
 def get_default_argspec():
     '''
     Provides default argument spec for the options documented in the acme doc fragment.
+
+    DEPRECATED: will be removed in community.crypto 3.0.0
     '''
     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'),
         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),
+        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'),
     )
 
 
+def create_default_argspec(
+    with_account=True,
+    require_account_key=True,
+    with_certificate=False,
+):
+    '''
+    Provides default argument spec for the options documented in the acme doc fragment.
+    '''
+    result = ArgumentSpec(
+        argument_spec=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:
+        result.update_argspec(
+            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'),
+        )
+        if require_account_key:
+            result.update(required_one_of=[['account_key_src', 'account_key_content']])
+        result.update(mutually_exclusive=[['account_key_src', 'account_key_content']])
+    if with_certificate:
+        result.update_argspec(
+            csr=dict(type='path'),
+            csr_content=dict(type='str'),
+        )
+        result.update(
+            required_one_of=[['csr', 'csr_content']],
+            mutually_exclusive=[['csr', 'csr_content']],
+        )
+    return result
+
+
 def create_backend(module, needs_acme_v2):
     if not HAS_IPADDRESS:
         module.fail_json(msg=missing_required_lib('ipaddress'), exception=IPADDRESS_IMPORT_ERROR)