internet/community.crypto
3
0
Fork 0
mirror of https://github.com/ansible-collections/community.crypto.git synced 2026-05-08 22:33:53 +00:00
Code Issues Packages Projects Releases Wiki Activity

Reformat documentation with 'andebox yaml-doc' (#828)

Browse Source 
* Reformat documentation with 'andebox yaml-doc'.

* Fix/improve.

* Remaining fixes.

* One more.
This commit is contained in:
Felix Fontein
2024-12-28 17:00:28 +01:00
committed by GitHub
parent 2ed7f69b83
commit 942be86635
54 changed files with 5605 additions and 5968 deletions
Download Patch File Download Diff File Expand all files Collapse all files

254
plugins/doc_fragments/module_privatekey.py
View File

@@ -11,138 +11,130 @@ __metaclass__ = type
class ModuleDocFragment(object):
# Standard files documentation fragment
DOCUMENTATION = r'''
DOCUMENTATION = r"""
description:
- One can generate L(RSA,https://en.wikipedia.org/wiki/RSA_%28cryptosystem%29),
L(DSA,https://en.wikipedia.org/wiki/Digital_Signature_Algorithm),
L(ECC,https://en.wikipedia.org/wiki/Elliptic-curve_cryptography) or
L(EdDSA,https://en.wikipedia.org/wiki/EdDSA) private keys.
- Keys are generated in PEM format.
- One can generate L(RSA,https://en.wikipedia.org/wiki/RSA_%28cryptosystem%29), L(DSA,https://en.wikipedia.org/wiki/Digital_Signature_Algorithm),
L(ECC,https://en.wikipedia.org/wiki/Elliptic-curve_cryptography) or L(EdDSA,https://en.wikipedia.org/wiki/EdDSA) private
keys.
- Keys are generated in PEM format.
requirements:
- cryptography >= 1.2.3 (older versions might work as well)
- cryptography >= 1.2.3 (older versions might work as well)
options:
size:
description:
- Size (in bits) of the TLS/SSL key to generate.
type: int
default: 4096
type:
description:
- The algorithm used to generate the TLS/SSL private key.
- Note that V(ECC), V(X25519), V(X448), V(Ed25519), and V(Ed448) require the C(cryptography) backend.
V(X25519) needs cryptography 2.5 or newer, while V(X448), V(Ed25519), and V(Ed448) require
cryptography 2.6 or newer. For V(ECC), the minimal cryptography version required depends on the
O(curve) option.
type: str
default: RSA
choices: [ DSA, ECC, Ed25519, Ed448, RSA, X25519, X448 ]
curve:
description:
- Note that not all curves are supported by all versions of C(cryptography).
- For maximal interoperability, V(secp384r1) or V(secp256r1) should be used.
- We use the curve names as defined in the
L(IANA registry for TLS,https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-8).
- Please note that all curves except V(secp224r1), V(secp256k1), V(secp256r1), V(secp384r1), and V(secp521r1)
are discouraged for new private keys.
type: str
choices:
- secp224r1
- secp256k1
- secp256r1
- secp384r1
- secp521r1
- secp192r1
- brainpoolP256r1
- brainpoolP384r1
- brainpoolP512r1
- sect163k1
- sect163r2
- sect233k1
- sect233r1
- sect283k1
- sect283r1
- sect409k1
- sect409r1
- sect571k1
- sect571r1
passphrase:
description:
- The passphrase for the private key.
type: str
cipher:
description:
- The cipher to encrypt the private key. This is only used when O(passphrase) is provided.
- Must be V(auto).
type: str
default: auto
select_crypto_backend:
description:
- Determines which crypto backend to use.
- The default choice is V(auto), which tries to use C(cryptography) if available.
- If set to V(cryptography), will try to use the L(cryptography,https://cryptography.io/) library.
type: str
default: auto
choices: [ auto, cryptography ]
format:
description:
- Determines which format the private key is written in. By default, PKCS1 (traditional OpenSSL format)
is used for all keys which support it. Please note that not every key can be exported in any format.
- The value V(auto) selects a format based on the key format. The value V(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 B(regenerated) by default.
To change this behavior, use the O(format_mismatch) option.
type: str
default: auto_ignore
choices: [ pkcs1, pkcs8, raw, auto, auto_ignore ]
format_mismatch:
description:
- Determines behavior of the module if the format of a private key does not match the expected format, but all
other parameters are as expected.
- If set to V(regenerate) (default), generates a new private key.
- If set to V(convert), the key will be converted to the new format instead.
- Only supported by the C(cryptography) backend.
type: str
default: regenerate
choices: [ regenerate, convert ]
regenerate:
description:
- Allows to configure in which situations the module is allowed to regenerate private keys.
The module will always generate a new key if the destination file does not exist.
- By default, the key will be regenerated when it does not match the module's options,
except when the key cannot be read or the passphrase does not match. Please note that
this B(changed) for Ansible 2.10. For Ansible 2.9, the behavior was as if V(full_idempotence)
is specified.
- If set to V(never), the module will fail if the key cannot be read or the passphrase
is not matching, and will never regenerate an existing key.
- If set to V(fail), the module will fail if the key does not correspond to the module's
options.
- If set to V(partial_idempotence), the key will be regenerated if it does not conform to
the module's options. The key is B(not) regenerated if it cannot be read (broken file),
the key is protected by an unknown passphrase, or when they key is not protected by a
passphrase, but a passphrase is specified.
- If set to V(full_idempotence), the key will be regenerated if it does not conform to the
module's options. This is also the case if the key cannot be read (broken file), the key
is protected by an unknown passphrase, or when they key is not protected by a passphrase,
but a passphrase is specified. Make sure you have a B(backup) when using this option!
- If set to V(always), the module will always regenerate the key. This is equivalent to
setting O(force) to V(true).
- Note that if O(format_mismatch) is set to V(convert) and everything matches except the
format, the key will always be converted, except if O(regenerate) is set to V(always).
type: str
choices:
- never
- fail
- partial_idempotence
- full_idempotence
- always
default: full_idempotence
size:
description:
- Size (in bits) of the TLS/SSL key to generate.
type: int
default: 4096
type:
description:
- The algorithm used to generate the TLS/SSL private key.
- Note that V(ECC), V(X25519), V(X448), V(Ed25519), and V(Ed448) require the C(cryptography) backend. V(X25519) needs
cryptography 2.5 or newer, while V(X448), V(Ed25519), and V(Ed448) require cryptography 2.6 or newer. For V(ECC),
the minimal cryptography version required depends on the O(curve) option.
type: str
default: RSA
choices: [DSA, ECC, Ed25519, Ed448, RSA, X25519, X448]
curve:
description:
- Note that not all curves are supported by all versions of C(cryptography).
- For maximal interoperability, V(secp384r1) or V(secp256r1) should be used.
- We use the curve names as defined in the L(IANA registry for TLS,https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml#tls-parameters-8).
- Please note that all curves except V(secp224r1), V(secp256k1), V(secp256r1), V(secp384r1), and V(secp521r1) are discouraged
for new private keys.
type: str
choices:
- secp224r1
- secp256k1
- secp256r1
- secp384r1
- secp521r1
- secp192r1
- brainpoolP256r1
- brainpoolP384r1
- brainpoolP512r1
- sect163k1
- sect163r2
- sect233k1
- sect233r1
- sect283k1
- sect283r1
- sect409k1
- sect409r1
- sect571k1
- sect571r1
passphrase:
description:
- The passphrase for the private key.
type: str
cipher:
description:
- The cipher to encrypt the private key. This is only used when O(passphrase) is provided.
- Must be V(auto).
type: str
default: auto
select_crypto_backend:
description:
- Determines which crypto backend to use.
- The default choice is V(auto), which tries to use C(cryptography) if available.
- If set to V(cryptography), will try to use the L(cryptography,https://cryptography.io/) library.
type: str
default: auto
choices: [auto, cryptography]
format:
description:
- Determines which format the private key is written in. By default, PKCS1 (traditional OpenSSL format) is used for
all keys which support it. Please note that not every key can be exported in any format.
- The value V(auto) selects a format based on the key format. The value V(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 B(regenerated) by default. To change this
behavior, use the O(format_mismatch) option.
type: str
default: auto_ignore
choices: [pkcs1, pkcs8, raw, auto, auto_ignore]
format_mismatch:
description:
- Determines behavior of the module if the format of a private key does not match the expected format, but all other
parameters are as expected.
- If set to V(regenerate) (default), generates a new private key.
- If set to V(convert), the key will be converted to the new format instead.
- Only supported by the C(cryptography) backend.
type: str
default: regenerate
choices: [regenerate, convert]
regenerate:
description:
- Allows to configure in which situations the module is allowed to regenerate private keys. The module will always generate
a new key if the destination file does not exist.
- By default, the key will be regenerated when it does not match the module's options, except when the key cannot be
read or the passphrase does not match. Please note that this B(changed) for Ansible 2.10. For Ansible 2.9, the behavior
was as if V(full_idempotence) is specified.
- If set to V(never), the module will fail if the key cannot be read or the passphrase is not matching, and will never
regenerate an existing key.
- If set to V(fail), the module will fail if the key does not correspond to the module's options.
- If set to V(partial_idempotence), the key will be regenerated if it does not conform to the module's options. The
key is B(not) regenerated if it cannot be read (broken file), the key is protected by an unknown passphrase, or when
they key is not protected by a passphrase, but a passphrase is specified.
- If set to V(full_idempotence), the key will be regenerated if it does not conform to the module's options. This is
also the case if the key cannot be read (broken file), the key is protected by an unknown passphrase, or when they
key is not protected by a passphrase, but a passphrase is specified. Make sure you have a B(backup) when using this
option!
- If set to V(always), the module will always regenerate the key. This is equivalent to setting O(force) to V(true).
- Note that if O(format_mismatch) is set to V(convert) and everything matches except the format, the key will always
be converted, except if O(regenerate) is set to V(always).
type: str
choices:
- never
- fail
- partial_idempotence
- full_idempotence
- always
default: full_idempotence
seealso:
- module: community.crypto.x509_certificate
- module: community.crypto.x509_certificate_pipe
- module: community.crypto.openssl_csr
- module: community.crypto.openssl_csr_pipe
- module: community.crypto.openssl_dhparam
- module: community.crypto.openssl_pkcs12
- module: community.crypto.openssl_publickey
'''
- module: community.crypto.x509_certificate
- module: community.crypto.x509_certificate_pipe
- module: community.crypto.openssl_csr
- module: community.crypto.openssl_csr_pipe
- module: community.crypto.openssl_dhparam
- module: community.crypto.openssl_pkcs12
- module: community.crypto.openssl_publickey
"""