community.crypto/plugins/doc_fragments/acme.py

# -*- coding: utf-8 -*-

# Copyright: (c) 2016 Michael Gruener <michael.gruener@chaosmoon.net>
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)

from __future__ import absolute_import, division, print_function
__metaclass__ = type


class ModuleDocFragment(object):

    # Standard files documentation fragment
    DOCUMENTATION = 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 C(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
     C(account_key_content))."
  - "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)."
requirements:
  - either openssl or L(cryptography,https://cryptography.io/) >= 1.5
  - ipaddress
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 C(account_key_content)."
      - "Required if C(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 C(account_key_src)."
      - "Required if C(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
  acme_version:
    description:
      - "The ACME version of the endpoint."
      - "Must be C(1) for the classic Let's Encrypt and Buypass ACME endpoints,
         or C(2) for standardized ACME v2 endpoints."
      - "The default value is C(1). Note that in community.crypto 2.0.0, this
         option B(will be required) and will no longer have a default."
      - "The value C(1) is deprecated since community.crypto 2.0.0 and will be
         removed from community.crypto 3.0.0."
    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."
      - "The default value is C(https://acme-staging.api.letsencrypt.org/directory).
         Note that in community.crypto 2.0.0, this option B(will be required) and
         will no longer have a default. Note that the default is the Let's Encrypt
         staging server for the ACME v1 protocol, which is deprecated and will
         be disabled in May 2021 (see
         L(here,https://community.letsencrypt.org/t/end-of-life-plan-for-acmev1/88430/7)
         for details)."
      - "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).
         (The production directory URL for ACME v1 is
         U(https://acme-v01.api.letsencrypt.org/directory) and will be
         disabled in July 2021.)"
      - "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)."
      - "B(Warning:) So far, the ACME modules have only been tested against Let's Encrypt
         (staging and production), Buypass (staging and production), ZeroSSL (production),
         and L(Pebble testing server,https://github.com/letsencrypt/Pebble). 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."
    type: str
  validate_certs:
    description:
      - Whether calls to the ACME directory will validate TLS certificates.
      - "B(Warning:) Should B(only ever) be set to C(no) for testing purposes,
         for example when testing against a local Pebble server."
    type: bool
    default: yes
  select_crypto_backend:
    description:
      - Determines which crypto backend to use.
      - The default choice is C(auto), which tries to use C(cryptography) if available, and falls back to
        C(openssl).
      - If set to C(openssl), will try to use the C(openssl) binary.
      - If set to C(cryptography), will try to use the
        L(cryptography,https://cryptography.io/) library.
    type: str
    default: auto
    choices: [ auto, cryptography, openssl ]
'''