diff --git a/plugins/doc_fragments/acme.py b/plugins/doc_fragments/acme.py index 98c673f7..4eccd656 100644 --- a/plugins/doc_fragments/acme.py +++ b/plugins/doc_fragments/acme.py @@ -32,11 +32,11 @@ options: - "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) module. If the requisites - (pyOpenSSL or cryptography) are 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 + M(community.crypto.openssl_privatekey) or M(community.crypto.openssl_privatekey_pipe) + modules. If the requisites (pyOpenSSL or cryptography) are 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." @@ -47,7 +47,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 + - "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 @@ -66,40 +66,52 @@ options: acme_version: description: - "The ACME version of the endpoint." - - "Must be 1 for the classic Let's Encrypt and Buypass ACME endpoints, - or 2 for standardized ACME v2 endpoints." - - "The default value is 1. Note that in community.crypto 2.0.0, this - option *will be required* and will no longer have a default." + - "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." - "Please also note that we will deprecate ACME v1 support eventually." type: int choices: [ 1, 2 ] acme_directory: description: - "The ACME directory to use. This is the entry point URL to access - CA server API." + 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 U(https://acme-staging.api.letsencrypt.org/directory). - Note that in community.crypto 2.0.0, this option *will be required* and - will no longer have a default." + - "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 Let's Encrypt, the production directory URL for ACME v1 is - U(https://acme-v01.api.letsencrypt.org/directory), and the production - directory URL for ACME v2 is U(https://acme-v02.api.letsencrypt.org/directory)." - - "For Buypass, the production directory URL for ACME v2 and v1 is + - "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)." - - "*Warning:* So far, the module has only been tested against Let's Encrypt - (staging and production), Buypass (staging and production), and - L(Pebble testing server,https://github.com/letsencrypt/Pebble)." + - "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. - - "*Warning:* Should *only ever* be set to C(no) for testing purposes, + - "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 diff --git a/plugins/doc_fragments/module_csr.py b/plugins/doc_fragments/module_csr.py index 8d9f0b73..59bb1497 100644 --- a/plugins/doc_fragments/module_csr.py +++ b/plugins/doc_fragments/module_csr.py @@ -183,7 +183,7 @@ options: name_constraints_excluded: description: - For CA certificates, this specifies a list of identifiers which describe - subtrees of names that this CA is *not* allowed to issue certificates for. + subtrees of names that this CA is B(not) allowed to issue certificates for. - Values must be prefixed by their options. (i.e., C(email), C(URI), C(DNS), C(RID), C(IP), C(dirName), C(otherName) and the ones specific to your CA). type: list diff --git a/plugins/doc_fragments/module_privatekey.py b/plugins/doc_fragments/module_privatekey.py index e8141631..d93ab7f4 100644 --- a/plugins/doc_fragments/module_privatekey.py +++ b/plugins/doc_fragments/module_privatekey.py @@ -20,7 +20,7 @@ description: - "Please note that the module regenerates private keys if they don't match the module's options. In particular, if you provide another passphrase (or specify none), change the keysize, etc., the private key will be - regenerated. If you are concerned that this could **overwrite your private key**, + regenerated. If you are concerned that this could B(overwrite your private key), consider using the I(backup) option." - "The module can use the cryptography Python library, or the pyOpenSSL Python library. By default, it tries to detect which one is available. This can be @@ -103,7 +103,7 @@ options: - The value C(auto) selects a fromat based on the key format. The value C(auto_ignore) does the same, but for existing private key files, it will not force a regenerate when its format is not the automatically selected one for generation. - - Note that if the format for an existing private key mismatches, the key is *regenerated* by default. + - Note that if the format for an existing private key mismatches, the key is B(regenerated) by default. To change this behavior, use the I(format_mismatch) option. - The I(format) option is only supported by the C(cryptography) backend. The C(pyopenssl) backend will fail if a value different from C(auto_ignore) is used. diff --git a/plugins/modules/acme_account.py b/plugins/modules/acme_account.py index 1d538e3b..addac552 100644 --- a/plugins/modules/acme_account.py +++ b/plugins/modules/acme_account.py @@ -31,6 +31,8 @@ seealso: description: Retrieves facts about an ACME account. - module: community.crypto.openssl_privatekey description: Can be used to create a private account key. + - module: community.crypto.openssl_privatekey_pipe + description: Can be used to create a private account key without writing it to disk. - module: community.crypto.acme_inspect description: Allows to debug problems. extends_documentation_fragment: diff --git a/plugins/modules/acme_certificate.py b/plugins/modules/acme_certificate.py index 20c0e843..120eb3be 100644 --- a/plugins/modules/acme_certificate.py +++ b/plugins/modules/acme_certificate.py @@ -62,8 +62,12 @@ seealso: description: Helps preparing C(tls-alpn-01) challenges. - module: community.crypto.openssl_privatekey description: Can be used to create private keys (both for certificates and accounts). + - module: community.crypto.openssl_privatekey_pipe + description: Can be used to create private keys without writing it to disk (both for certificates and accounts). - module: community.crypto.openssl_csr description: Can be used to create a Certificate Signing Request (CSR). + - module: community.crypto.openssl_csr_pipe + description: Can be used to create a Certificate Signing Request (CSR) without writing it to disk. - module: community.crypto.certificate_complete_chain description: Allows to find the root certificate for the returned fullchain. - module: community.crypto.acme_certificate_revoke @@ -117,7 +121,7 @@ options: csr: description: - "File containing the CSR for the new certificate." - - "Can be created with C(openssl req ...)." + - "Can be created with M(community.crypto.openssl_csr) or C(openssl req ...)." - "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." @@ -131,7 +135,7 @@ options: csr_content: description: - "Content of the CSR for the new certificate." - - "Can be created with C(openssl req ...)." + - "Can be created with M(community.crypto.openssl_csr_pipe) or C(openssl req ...)." - "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."