ACME modules: documentation improvements (#42165)

* Always using current draft when referring to ACME v2. * Adding URL for ACME v1 protocol. * Improve cross-referencing of acme_* modules. * General improvements. * Fixing syntax error.
6 years ago · 6b6c017dd1
parent 6412cbf84b
commit 6b6c017dd1
5 changed files with 44 additions and 29 deletions
--- a/lib/ansible/module_utils/acme.py
+++ b/lib/ansible/module_utils/acme.py
@ -147,7 +147,7 @@ class ACMEDirectory(object):
    and allows to obtain a Replay-Nonce. The acme_directory URL
    needs to support unauthenticated GET requests; ACME endpoints
    requiring authentication are not supported.
-    https://tools.ietf.org/html/draft-ietf-acme-acme-09#section-7.1.1
+    https://tools.ietf.org/html/draft-ietf-acme-acme-12#section-7.1.1
    '''

    def __init__(self, module):
@ -228,7 +228,7 @@ class ACMEAccount(object):
    def get_keyauthorization(self, token):
        '''
        Returns the key authorization for the given token
-        https://tools.ietf.org/html/draft-ietf-acme-acme-09#section-8.1
+        https://tools.ietf.org/html/draft-ietf-acme-acme-12#section-8.1
        '''
        accountkey_json = json.dumps(self.jwk, sort_keys=True, separators=(',', ':'))
        thumbprint = nopad_b64(hashlib.sha256(accountkey_json.encode('utf8')).digest())
@ -360,7 +360,7 @@ class ACMEAccount(object):
        '''
        Sends a JWS signed HTTP POST request to the ACME server and returns
        the response as dictionary
-        https://tools.ietf.org/html/draft-ietf-acme-acme-10#section-6.2
+        https://tools.ietf.org/html/draft-ietf-acme-acme-12#section-6.2
        '''
        key_data = key_data or self.key_data
        key = key or self.key
@ -392,7 +392,7 @@ class ACMEAccount(object):
                    try:
                        result = self.module.from_json(content.decode('utf8'))
                        # In case of badNonce error, try again (up to 5 times)
-                        # (https://tools.ietf.org/html/draft-ietf-acme-acme-09#section-6.6)
+                        # (https://tools.ietf.org/html/draft-ietf-acme-acme-12#section-6.6)
                        if (400 <= info['status'] < 600 and
                                result.get('type') == 'urn:ietf:params:acme:error:badNonce' and
                                failed_tries <= 5):
@ -420,7 +420,7 @@ class ACMEAccount(object):
        Registers a new ACME account. Returns True if the account was
        created and False if it already existed (e.g. it was not newly
        created).
-        https://tools.ietf.org/html/draft-ietf-acme-acme-10#section-7.3
+        https://tools.ietf.org/html/draft-ietf-acme-acme-12#section-7.3
        '''
        contact = [] if contact is None else contact

@ -498,7 +498,7 @@ class ACMEAccount(object):
        will be stored in self.uri; if it is None, the account does not
        exist.

-        https://tools.ietf.org/html/draft-ietf-acme-acme-10#section-7.3
+        https://tools.ietf.org/html/draft-ietf-acme-acme-12#section-7.3
        '''

        new_account = True
--- a/lib/ansible/modules/web_infrastructure/acme_account.py
+++ b/lib/ansible/modules/web_infrastructure/acme_account.py
@ -23,6 +23,10 @@ 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)."
+   - "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
@ -48,7 +52,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-10#section-7.1.2
+      - "See https://tools.ietf.org/html/draft-ietf-acme-acme-12#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)."
--- a/lib/ansible/modules/web_infrastructure/acme_certificate.py
+++ b/lib/ansible/modules/web_infrastructure/acme_certificate.py
@ -20,10 +20,10 @@ author: "Michael Gruener (@mgruener)"
 version_added: "2.2"
 short_description: Create SSL certificates with an ACME protocol endpoint
 description:
-   - "Create and renew SSL certificates with a CA supporting the ACME protocol,
-      such as Let's Encrypt (U(https://letsencrypt.org)). For details see
-      U(https://letsencrypt.org). The current implementation supports the
-      C(http-01) and C(dns-01) challenges."
+   - "Create and renew SSL certificates with a CA supporting the
+      L(ACME protocol,https://tools.ietf.org/html/draft-ietf-acme-acme-12),
+      such as L(Let's Encrypt,https://letsencrypt.org/). The current
+      implementation supports the C(http-01) and C(dns-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
@ -34,12 +34,16 @@ description:
      C(dns-01) the necessary dns record has to be created.
      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
-      U(https://tools.ietf.org/html/draft-ietf-acme-acme-12#section-8).
+      L(the specification,https://tools.ietf.org/html/draft-ietf-acme-acme-12#section-8).
      Also, consider the examples provided for this module."
   - "Although the defaults are chosen so that the module can be used with
      the Let's Encrypt CA, the module can be used with any service using the ACME
      v1 or v2 protocol."
   - "At least one of C(dest) and C(fullchain_dest) must be specified."
+   - "Note that this module includes basic account management functionality.
+      If you want to have more control over your ACME account, use the M(acme_account)
+      module and disable account management for this module using the C(modify_account)
+      option."
   - "Note: this module was called C(letsencrypt) before Ansible 2.6. The usage
      did not change."
 extends_documentation_fragment:
@ -49,6 +53,10 @@ options:
    description:
      - "The email address associated with this account."
      - "It will be used for certificate expiration warnings."
+      - "Note that when C(modify_account) is not set to C(no) and you also
+         used the M(acme_account) module to specify more than one contact
+         for your account, this module will update your account and restrict
+         it to the (at most one) contact email address specified here."
  agreement:
    description:
      - "URI to a terms of service document you agree to when using the
@ -67,9 +75,9 @@ options:
    description:
      - "Boolean indicating whether the module should create the account if
         necessary, and update its contact data."
-      - "Set to C(no) if you want to use C(acme_account) to manage your
-         account instead, and to avoid accidental creation of a new account
-         using an old key if you changed the account key with C(acme_account)."
+      - "Set to C(no) if you want to use the M(acme_account) module to manage
+         your account instead, and to avoid accidental creation of a new account
+         using an old key if you changed the account key with M(acme_account)."
      - "If set to C(no), C(terms_agreed) and C(account_email) are ignored."
    type: bool
    default: 'yes'
@ -465,11 +473,11 @@ class ACMEClient(object):
            keyauthorization = self.account.get_keyauthorization(token)

            if type == 'http-01':
-                # https://tools.ietf.org/html/draft-ietf-acme-acme-09#section-8.3
+                # https://tools.ietf.org/html/draft-ietf-acme-acme-12#section-8.3
                resource = '.well-known/acme-challenge/' + token
                data[type] = {'resource': resource, 'resource_value': keyauthorization}
            elif type == 'dns-01':
-                # https://tools.ietf.org/html/draft-ietf-acme-acme-09#section-8.5
+                # https://tools.ietf.org/html/draft-ietf-acme-acme-12#section-8.4
                resource = '_acme-challenge'
                value = nopad_b64(hashlib.sha256(to_bytes(keyauthorization)).digest())
                record = (resource + domain[1:]) if domain.startswith('*.') else (resource + '.' + domain)
@ -523,7 +531,7 @@ class ACMEClient(object):
            result['uri'] = auth['uri']
            if self._add_or_update_auth(domain, result):
                self.changed = True
-            # draft-ietf-acme-acme-02
+            # https://tools.ietf.org/html/draft-ietf-acme-acme-02#section-6.1.2
            # "status (required, string): ...
            # If this field is missing, then the default value is "pending"."
            if self.version == 1 and 'status' not in result:
@ -541,7 +549,7 @@ class ACMEClient(object):
        '''
        Create a new certificate based on the csr.
        Return the certificate object as dict
-        https://tools.ietf.org/html/draft-ietf-acme-acme-09#section-7.4
+        https://tools.ietf.org/html/draft-ietf-acme-acme-12#section-7.4
        '''
        openssl_csr_cmd = [self._openssl_bin, "req", "-in", self.csr, "-outform", "DER"]
        dummy, out, dummy = self.module.run_command(openssl_csr_cmd, check_rc=True)
@ -577,7 +585,7 @@ class ACMEClient(object):
    def _download_cert(self, url):
        '''
        Download and parse the certificate chain.
-        https://tools.ietf.org/html/draft-ietf-acme-acme-09#section-7.4.2
+        https://tools.ietf.org/html/draft-ietf-acme-acme-12#section-7.4.2
        '''
        resp, info = fetch_url(self.module, url, headers={'Accept': 'application/pem-certificate-chain'})
        try:
@ -651,7 +659,7 @@ class ACMEClient(object):
    def _new_order_v2(self):
        '''
        Start a new certificate order (ACME v2 protocol).
-        https://tools.ietf.org/html/draft-ietf-acme-acme-09#section-7.4
+        https://tools.ietf.org/html/draft-ietf-acme-acme-12#section-7.4
        '''
        identifiers = []
        for domain in self.domains:
@ -813,7 +821,7 @@ class ACMEClient(object):
        '''
        Deactivates all valid authz's. Does not raise exceptions.
        https://community.letsencrypt.org/t/authorization-deactivation/19860/2
-        https://tools.ietf.org/html/draft-ietf-acme-acme-09#section-7.5.2
+        https://tools.ietf.org/html/draft-ietf-acme-acme-12#section-7.5.2
        '''
        authz_deactivate = {
            'status': 'deactivated'
--- a/lib/ansible/modules/web_infrastructure/acme_certificate_revoke.py
+++ b/lib/ansible/modules/web_infrastructure/acme_certificate_revoke.py
@ -20,8 +20,10 @@ author: "Felix Fontein (@felixfontein)"
 version_added: "2.7"
 short_description: Revoke certificates with the ACME protocol.
 description:
-   - "Allows to revoke certificates with the ACME protocol. This protocol
-      is, for example, used by Let's Encrypt."
+   - "Allows to revoke certificates with the ACME protocol, for example
+      for certificates obtained by the M(acme_certificate) module. The
+      ACME protocol is used by some Certificate Authorities such as
+      L(Let's Encrypt,https://letsencrypt.org/)."
   - "Note that exactly one of C(account_key_src), C(account_key_content),
      C(private_key_src) or C(private_key_content) must be specified."
   - "Also note that in general, trying to revoke an already revoked
@ -48,7 +50,7 @@ options:
      - "Content of the certificate's private key."
      - "Note that exactly one of C(account_key_src), C(account_key_content),
         C(private_key_src) or C(private_key_content) must be specified."
-      - "Warning: the content will be written into a temporary file, which will
+      - "I(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
--- a/lib/ansible/utils/module_docs_fragments/acme.py
+++ b/lib/ansible/utils/module_docs_fragments/acme.py
@ -17,7 +17,8 @@ options:
      - "Path to a file containing the ACME account RSA or Elliptic Curve
         key."
      - "RSA keys can be created with C(openssl rsa ...). Elliptic curve keys can
-         be created with C(openssl ecparam -genkey ...)."
+         be created with C(openssl ecparam -genkey ...). Any other tool creating
+         private keys in PEM format can be used as well."
      - "Mutually exclusive with C(account_key_content)."
      - "Required if C(account_key_content) is not used."
    aliases: [ account_key ]
@ -26,7 +27,7 @@ options:
      - "Content of the ACME account RSA or Elliptic Curve key."
      - "Mutually exclusive with C(account_key_src)."
      - "Required if C(account_key_src) is not used."
-      - "Warning: the content will be written into a temporary file, which will
+      - "I(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
@ -59,8 +60,8 @@ options:
  validate_certs:
    description:
      - Whether calls to the ACME directory will validate TLS certificates.
-      - I(Warning:) Should I(only ever) be set to C(no) for testing purposes,
-        for example when testing against a local Pebble server.
+      - "I(Warning): Should I(only ever) be set to C(no) for testing purposes,
+         for example when testing against a local Pebble server."
    type: bool
    default: 'yes'
    version_added: 2.5