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 LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later

from __future__ import absolute_import, division, print_function
__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 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)).
  - 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:
  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
  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
"""

    # 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
"""