diff --git a/changelogs/fragments/735-acme-docs-fragment.yml b/changelogs/fragments/735-acme-docs-fragment.yml new file mode 100644 index 00000000..183f39f5 --- /dev/null +++ b/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)." diff --git a/plugins/doc_fragments/acme.py b/plugins/doc_fragments/acme.py index 2b5bfc23..2f55cdda 100644 --- a/plugins/doc_fragments/acme.py +++ b/plugins/doc_fragments/acme.py @@ -11,6 +11,9 @@ __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 @@ -136,4 +139,149 @@ options: 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: {} ''' diff --git a/plugins/module_utils/acme/acme.py b/plugins/module_utils/acme/acme.py index 74d0bc1e..1fc4992e 100644 --- a/plugins/module_utils/acme/acme.py +++ b/plugins/module_utils/acme/acme.py @@ -168,9 +168,9 @@ class ACMEClient(object): 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. @@ -384,21 +384,25 @@ class ACMEClient(object): return result, info -def get_default_argspec(): +def get_default_argspec(with_account=True): ''' Provides default argument spec for the options documented in the acme doc fragment. ''' - 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'), + argspec = 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: + argspec.update(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'), + )) + return argspec def create_backend(module, needs_acme_v2): diff --git a/plugins/modules/acme_account.py b/plugins/modules/acme_account.py index 1e8d64a5..a808c196 100644 --- a/plugins/modules/acme_account.py +++ b/plugins/modules/acme_account.py @@ -37,7 +37,8 @@ seealso: - module: community.crypto.acme_inspect description: Allows to debug problems. extends_documentation_fragment: - - community.crypto.acme + - community.crypto.acme.basic + - community.crypto.acme.account - community.crypto.attributes - community.crypto.attributes.actiongroup_acme attributes: diff --git a/plugins/modules/acme_account_info.py b/plugins/modules/acme_account_info.py index ac4617c9..fa999c2a 100644 --- a/plugins/modules/acme_account_info.py +++ b/plugins/modules/acme_account_info.py @@ -25,7 +25,8 @@ notes: - "This module was called C(acme_account_facts) before Ansible 2.8. The usage did not change." extends_documentation_fragment: - - community.crypto.acme + - community.crypto.acme.basic + - community.crypto.acme.account - community.crypto.attributes - community.crypto.attributes.actiongroup_acme - community.crypto.attributes.info_module diff --git a/plugins/modules/acme_certificate.py b/plugins/modules/acme_certificate.py index 21a6d6ae..909e60a4 100644 --- a/plugins/modules/acme_certificate.py +++ b/plugins/modules/acme_certificate.py @@ -78,7 +78,8 @@ seealso: - module: community.crypto.acme_inspect description: Allows to debug problems. extends_documentation_fragment: - - community.crypto.acme + - community.crypto.acme.basic + - community.crypto.acme.account - community.crypto.attributes - community.crypto.attributes.files - community.crypto.attributes.actiongroup_acme diff --git a/plugins/modules/acme_certificate_revoke.py b/plugins/modules/acme_certificate_revoke.py index 022862e6..4a68cf34 100644 --- a/plugins/modules/acme_certificate_revoke.py +++ b/plugins/modules/acme_certificate_revoke.py @@ -37,7 +37,8 @@ seealso: - module: community.crypto.acme_inspect description: Allows to debug problems. extends_documentation_fragment: - - community.crypto.acme + - community.crypto.acme.basic + - community.crypto.acme.account - community.crypto.attributes - community.crypto.attributes.actiongroup_acme attributes: diff --git a/plugins/modules/acme_inspect.py b/plugins/modules/acme_inspect.py index a2c76507..2a4c5b93 100644 --- a/plugins/modules/acme_inspect.py +++ b/plugins/modules/acme_inspect.py @@ -42,7 +42,8 @@ seealso: description: The specification of the C(tls-alpn-01) challenge (RFC 8737). link: https://www.rfc-editor.org/rfc/rfc8737.html extends_documentation_fragment: - - community.crypto.acme + - community.crypto.acme.basic + - community.crypto.acme.account - community.crypto.attributes - community.crypto.attributes.actiongroup_acme attributes: