mirror of
https://github.com/ansible-collections/community.crypto.git
synced 2026-05-07 22:03:01 +00:00
Reformat documentation with 'andebox yaml-doc' (#828)
* Reformat documentation with 'andebox yaml-doc'. * Fix/improve. * Remaining fixes. * One more.
This commit is contained in:
Felix Fontein
GitHub
@@ -9,79 +9,76 @@ from __future__ import absolute_import, division, print_function
|
||||
__metaclass__ = type
|
||||
|
||||
|
||||
DOCUMENTATION = r'''
|
||||
---
|
||||
DOCUMENTATION = r"""
|
||||
module: openssl_privatekey
|
||||
short_description: Generate OpenSSL private keys
|
||||
description:
|
||||
- This module allows one to (re)generate OpenSSL private keys.
|
||||
- The default mode for the private key file will be V(0600) if O(mode) is not explicitly set.
|
||||
- "Please note that the module regenerates private keys if they do not 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 B(overwrite your private key),
|
||||
consider using the O(backup) option."
|
||||
- This module allows one to (re)generate OpenSSL private keys.
|
||||
- The default mode for the private key file will be V(0600) if O(mode) is not explicitly set.
|
||||
- Please note that the module regenerates private keys if they do not 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 B(overwrite your private key), consider using the O(backup) option.
|
||||
author:
|
||||
- Yanis Guenane (@Spredzy)
|
||||
- Felix Fontein (@felixfontein)
|
||||
- Yanis Guenane (@Spredzy)
|
||||
- Felix Fontein (@felixfontein)
|
||||
extends_documentation_fragment:
|
||||
- ansible.builtin.files
|
||||
- community.crypto.attributes
|
||||
- community.crypto.attributes.files
|
||||
- community.crypto.module_privatekey
|
||||
- ansible.builtin.files
|
||||
- community.crypto.attributes
|
||||
- community.crypto.attributes.files
|
||||
- community.crypto.module_privatekey
|
||||
attributes:
|
||||
check_mode:
|
||||
support: full
|
||||
diff_mode:
|
||||
support: full
|
||||
safe_file_operations:
|
||||
support: full
|
||||
check_mode:
|
||||
support: full
|
||||
diff_mode:
|
||||
support: full
|
||||
safe_file_operations:
|
||||
support: full
|
||||
options:
|
||||
state:
|
||||
description:
|
||||
- Whether the private key should exist or not, taking action if the state is different from what is stated.
|
||||
type: str
|
||||
default: present
|
||||
choices: [ absent, present ]
|
||||
force:
|
||||
description:
|
||||
- Should the key be regenerated even if it already exists.
|
||||
type: bool
|
||||
default: false
|
||||
path:
|
||||
description:
|
||||
- Name of the file in which the generated TLS/SSL private key will be written. It will have V(0600) mode
|
||||
if O(mode) is not explicitly set.
|
||||
type: path
|
||||
required: true
|
||||
format:
|
||||
version_added: '1.0.0'
|
||||
format_mismatch:
|
||||
version_added: '1.0.0'
|
||||
backup:
|
||||
description:
|
||||
- Create a backup file including a timestamp so you can get
|
||||
the original private key back if you overwrote it with a new one by accident.
|
||||
type: bool
|
||||
default: false
|
||||
return_content:
|
||||
description:
|
||||
- If set to V(true), will return the (current or generated) private key's content as RV(privatekey).
|
||||
- Note that especially if the private key is not encrypted, you have to make sure that the returned
|
||||
value is treated appropriately and not accidentally written to logs etc.! Use with care!
|
||||
- Use Ansible's C(no_log) task option to avoid the output being shown. See also
|
||||
U(https://docs.ansible.com/ansible/latest/reference_appendices/faq.html#how-do-i-keep-secret-data-in-my-playbook).
|
||||
type: bool
|
||||
default: false
|
||||
version_added: '1.0.0'
|
||||
regenerate:
|
||||
version_added: '1.0.0'
|
||||
state:
|
||||
description:
|
||||
- Whether the private key should exist or not, taking action if the state is different from what is stated.
|
||||
type: str
|
||||
default: present
|
||||
choices: [absent, present]
|
||||
force:
|
||||
description:
|
||||
- Should the key be regenerated even if it already exists.
|
||||
type: bool
|
||||
default: false
|
||||
path:
|
||||
description:
|
||||
- Name of the file in which the generated TLS/SSL private key will be written. It will have V(0600) mode if O(mode)
|
||||
is not explicitly set.
|
||||
type: path
|
||||
required: true
|
||||
format:
|
||||
version_added: '1.0.0'
|
||||
format_mismatch:
|
||||
version_added: '1.0.0'
|
||||
backup:
|
||||
description:
|
||||
- Create a backup file including a timestamp so you can get the original private key back if you overwrote it with a
|
||||
new one by accident.
|
||||
type: bool
|
||||
default: false
|
||||
return_content:
|
||||
description:
|
||||
- If set to V(true), will return the (current or generated) private key's content as RV(privatekey).
|
||||
- Note that especially if the private key is not encrypted, you have to make sure that the returned value is treated
|
||||
appropriately and not accidentally written to logs etc.! Use with care!
|
||||
- Use Ansible's C(no_log) task option to avoid the output being shown. See also
|
||||
U(https://docs.ansible.com/ansible/latest/reference_appendices/faq.html#how-do-i-keep-secret-data-in-my-playbook).
|
||||
type: bool
|
||||
default: false
|
||||
version_added: '1.0.0'
|
||||
regenerate:
|
||||
version_added: '1.0.0'
|
||||
seealso:
|
||||
- module: community.crypto.openssl_privatekey_pipe
|
||||
- module: community.crypto.openssl_privatekey_info
|
||||
'''
|
||||
- module: community.crypto.openssl_privatekey_pipe
|
||||
- module: community.crypto.openssl_privatekey_info
|
||||
"""
|
||||
|
||||
EXAMPLES = r'''
|
||||
EXAMPLES = r"""
|
||||
- name: Generate an OpenSSL private key with the default values (4096 bits, RSA)
|
||||
community.crypto.openssl_privatekey:
|
||||
path: /etc/ssl/private/ansible.com.pem
|
||||
@@ -112,54 +109,54 @@ EXAMPLES = r'''
|
||||
path: /etc/ssl/private/ansible.com.pem
|
||||
type: ECC
|
||||
curve: secp256r1
|
||||
'''
|
||||
"""
|
||||
|
||||
RETURN = r'''
|
||||
RETURN = r"""
|
||||
size:
|
||||
description: Size (in bits) of the TLS/SSL private key.
|
||||
returned: changed or success
|
||||
type: int
|
||||
sample: 4096
|
||||
description: Size (in bits) of the TLS/SSL private key.
|
||||
returned: changed or success
|
||||
type: int
|
||||
sample: 4096
|
||||
type:
|
||||
description: Algorithm used to generate the TLS/SSL private key.
|
||||
returned: changed or success
|
||||
type: str
|
||||
sample: RSA
|
||||
description: Algorithm used to generate the TLS/SSL private key.
|
||||
returned: changed or success
|
||||
type: str
|
||||
sample: RSA
|
||||
curve:
|
||||
description: Elliptic curve used to generate the TLS/SSL private key.
|
||||
returned: changed or success, and O(type) is V(ECC)
|
||||
type: str
|
||||
sample: secp256r1
|
||||
description: Elliptic curve used to generate the TLS/SSL private key.
|
||||
returned: changed or success, and O(type) is V(ECC)
|
||||
type: str
|
||||
sample: secp256r1
|
||||
filename:
|
||||
description: Path to the generated TLS/SSL private key file.
|
||||
returned: changed or success
|
||||
type: str
|
||||
sample: /etc/ssl/private/ansible.com.pem
|
||||
description: Path to the generated TLS/SSL private key file.
|
||||
returned: changed or success
|
||||
type: str
|
||||
sample: /etc/ssl/private/ansible.com.pem
|
||||
fingerprint:
|
||||
description:
|
||||
description:
|
||||
- The fingerprint of the public key. Fingerprint will be generated for each C(hashlib.algorithms) available.
|
||||
returned: changed or success
|
||||
type: dict
|
||||
sample:
|
||||
md5: "84:75:71:72:8d:04:b5:6c:4d:37:6d:66:83:f5:4c:29"
|
||||
sha1: "51:cc:7c:68:5d:eb:41:43:88:7e:1a:ae:c7:f8:24:72:ee:71:f6:10"
|
||||
sha224: "b1:19:a6:6c:14:ac:33:1d:ed:18:50:d3:06:5c:b2:32:91:f1:f1:52:8c:cb:d5:75:e9:f5:9b:46"
|
||||
sha256: "41:ab:c7:cb:d5:5f:30:60:46:99:ac:d4:00:70:cf:a1:76:4f:24:5d:10:24:57:5d:51:6e:09:97:df:2f:de:c7"
|
||||
sha384: "85:39:50:4e:de:d9:19:33:40:70:ae:10:ab:59:24:19:51:c3:a2:e4:0b:1c:b1:6e:dd:b3:0c:d9:9e:6a:46:af:da:18:f8:ef:ae:2e:c0:9a:75:2c:9b:b3:0f:3a:5f:3d"
|
||||
sha512: "fd:ed:5e:39:48:5f:9f:fe:7f:25:06:3f:79:08:cd:ee:a5:e7:b3:3d:13:82:87:1f:84:e1:f5:c7:28:77:53:94:86:56:38:69:f0:d9:35:22:01:1e:a6:60:...:0f:9b"
|
||||
returned: changed or success
|
||||
type: dict
|
||||
sample:
|
||||
md5: "84:75:71:72:8d:04:b5:6c:4d:37:6d:66:83:f5:4c:29"
|
||||
sha1: "51:cc:7c:68:5d:eb:41:43:88:7e:1a:ae:c7:f8:24:72:ee:71:f6:10"
|
||||
sha224: "b1:19:a6:6c:14:ac:33:1d:ed:18:50:d3:06:5c:b2:32:91:f1:f1:52:8c:cb:d5:75:e9:f5:9b:46"
|
||||
sha256: "41:ab:c7:cb:d5:5f:30:60:46:99:ac:d4:00:70:cf:a1:76:4f:24:5d:10:24:57:5d:51:6e:09:97:df:2f:de:c7"
|
||||
sha384: "85:39:50:4e:de:d9:19:33:40:70:ae:10:ab:59:24:19:51:c3:a2:e4:0b:1c:b1:6e:dd:b3:0c:d9:9e:6a:46:af:da:18:f8:ef:ae:2e:c0:9a:75:2c:9b:b3:0f:3a:5f:3d"
|
||||
sha512: "fd:ed:5e:39:48:5f:9f:fe:7f:25:06:3f:79:08:cd:ee:a5:e7:b3:3d:13:82:87:1f:84:e1:f5:c7:28:77:53:94:86:56:38:69:f0:d9:35:22:01:1e:a6:60:...:0f:9b"
|
||||
backup_file:
|
||||
description: Name of backup file created.
|
||||
returned: changed and if O(backup) is V(true)
|
||||
type: str
|
||||
sample: /path/to/privatekey.pem.2019-03-09@11:22~
|
||||
description: Name of backup file created.
|
||||
returned: changed and if O(backup) is V(true)
|
||||
type: str
|
||||
sample: /path/to/privatekey.pem.2019-03-09@11:22~
|
||||
privatekey:
|
||||
description:
|
||||
- The (current or generated) private key's content.
|
||||
- Will be Base64-encoded if the key is in raw format.
|
||||
returned: if O(state) is V(present) and O(return_content) is V(true)
|
||||
type: str
|
||||
version_added: '1.0.0'
|
||||
'''
|
||||
description:
|
||||
- The (current or generated) private key's content.
|
||||
- Will be Base64-encoded if the key is in raw format.
|
||||
returned: if O(state) is V(present) and O(return_content) is V(true)
|
||||
type: str
|
||||
version_added: '1.0.0'
|
||||
"""
|
||||
|
||||
import os
|
||||
|
||||
|
||||
Reference in New Issue
Block a user