ACME: improve documentation (#44691)

* Override description for account_key_src and account_key_content to also mention private_key_*.

* Convert generic OpenSSL/cryptography remark from description to note.

This avoids the whole description list to be sorted alphabetically, which will be done by plugin_docs.py in case description is mentioned in both module fragment and module itself.

* Moving more notes to the notes: section.

* Uniformization of first paragraph. Mainly mention ACME supporting CAs, and only then mention Let's Encrypt as one of them.

* Adjusting to current drafts.

* Adjusting to updated drafts.

* Harmonizing short module descriptions.

* Referencing helper modules.

* Move general Let's Encrypt remark to doc fragment.

* Changing some Let's Encrypt references to more generic statements.

lib/ansible/modules/crypto/acme/acme_account.py

@@ -18,16 +18,19 @@ DOCUMENTATION = '''
 module: acme_account
 author: "Felix Fontein (@felixfontein)"
 version_added: "2.6"
-short_description: Create, modify or delete accounts with Let's Encrypt
+short_description: Create, modify or delete ACME accounts
 description:
-   - "Allows to create, modify or delete accounts with Let's Encrypt.
-      Let's Encrypt is a free, automated, and open certificate authority
-      (CA), run for the public's benefit. For details see U(https://letsencrypt.org)."
+   - "Allows to create, modify or delete accounts with a CA supporting the
+      L(ACME protocol,https://tools.ietf.org/html/draft-ietf-acme-acme-14),
+      such as L(Let's Encrypt,https://letsencrypt.org/)."
+   - "This module only works with the ACME v2 protocol."
+notes:
+   - "Facts about an ACME account can be retrieved with the M(acme_account_facts)
+      module."
    - "The M(acme_certificate) module also allows to do basic account management.
       When using both modules, it is recommended to disable account management
       for M(acme_certificate). For that, use the C(modify_account) option of
       M(acme_certificate)."
-   - "This module only works with the ACME v2 protocol."
 extends_documentation_fragment:
   - acme
 options:
@@ -52,7 +55,7 @@ options:
     description:
       - "A list of contact URLs."
       - "Email addresses must be prefixed with C(mailto:)."
-      - "See https://tools.ietf.org/html/draft-ietf-acme-acme-12#section-7.1.2
+      - "See https://tools.ietf.org/html/draft-ietf-acme-acme-14#section-7.1.2
          for what is allowed."
       - "Must be specified when state is C(present). Will be ignored
          if state is C(absent) or C(changed_key)."
@@ -65,14 +68,13 @@ options:
     type: bool
   new_account_key_src:
     description:
-      - "Path to a file containing the Let's Encrypt account RSA or Elliptic Curve
-         key to change to."
+      - "Path to a file containing the ACME account RSA or Elliptic Curve key to change to."
       - "Same restrictions apply as to C(account_key_src)."
       - "Mutually exclusive with C(new_account_key_content)."
       - "Required if C(new_account_key_content) is not used and state is C(changed_key)."
   new_account_key_content:
     description:
-      - "Content of the Let's Encrypt account RSA or Elliptic Curve key to change to."
+      - "Content of the ACME account RSA or Elliptic Curve key to change to."
       - "Same restrictions apply as to C(account_key_content)."
       - "Mutually exclusive with C(new_account_key_src)."
       - "Required if C(new_account_key_src) is not used and state is C(changed_key)."
@@ -221,7 +223,7 @@ def main():
             # Now we can start the account key rollover
             if not module.check_mode:
                 # Compose inner signed message
-                # https://tools.ietf.org/html/draft-ietf-acme-acme-12#section-7.3.6
+                # https://tools.ietf.org/html/draft-ietf-acme-acme-14#section-7.3.6
                 url = account.directory['keyChange']
                 protected = {
                     "alg": new_key_data['alg'],
@@ -230,9 +232,8 @@ def main():
                 }
                 payload = {
                     "account": account.uri,
-                    "newKey": new_key_data['jwk'],  # specified in draft 12
-                    "oldKey": account.jwk,  # discussed in https://github.com/ietf-wg-acme/acme/pull/425,
-                                            # might be required in draft 13
+                    "newKey": new_key_data['jwk'],  # specified in draft 12 and older
+                    "oldKey": account.jwk,  # specified in draft 13 and newer
                 }
                 data = account.sign_request(protected, payload, new_key_data)
                 # Send request and verify result