a-c-m
/
community.crypto
mirror of https://github.com/ansible-collections/community.crypto.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Documentation: fix modules formatting (#161) 

* Documentation: fix modules formatting

* Apply suggestions from code review

* Fix sanity

Co-authored-by: Felix Fontein <felix@fontein.de>
pull/164/head
Andrew Klychkov 2020-12-19 19:15:10 +03:00 committed by GitHub
parent b10e86a4ba
commit b2e13d3c03
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
9 changed files with 58 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
plugins/modules/openssh_keypair.py
View File

@ -12,7 +12,7 @@ DOCUMENTATION = '''
---
module: openssh_keypair
author: "David Kainz (@lolcube)"
short_description: Generate OpenSSH private and public keys.
short_description: Generate OpenSSH private and public keys
description:
- "This module allows one to (re)generate OpenSSH private and public keys. It uses
ssh-keygen to generate keys. One can generate C(rsa), C(dsa), C(rsa1), C(ed25519)
@ -59,7 +59,7 @@ options:
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 doesn't match the module's options,
- 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 C(full_idempotence)
is specified.
@ -91,6 +91,7 @@ options:
notes:
- In case the ssh key is broken or password protected, the module will fail.
Set the I(force) option to C(yes) if you want to regenerate the keypair.
- Supports C(check_mode).
extends_documentation_fragment: files
'''
@ -118,17 +119,17 @@ EXAMPLES = '''
RETURN = '''
size:
description: Size (in bits) of the SSH private key
description: Size (in bits) of the SSH private key.
returned: changed or success
type: int
sample: 4096
type:
description: Algorithm used to generate the SSH private key
description: Algorithm used to generate the SSH private key.
returned: changed or success
type: str
sample: rsa
filename:
description: Path to the generated SSH private key file
description: Path to the generated SSH private key file.
returned: changed or success
type: str
sample: /tmp/id_ssh_rsa
@ -138,12 +139,12 @@ fingerprint:
type: str
sample: SHA256:r4YCZxihVjedH2OlfjVGI6Y5xAYtdCwk8VxKyzVyYfM
public_key:
description: The public key of the generated SSH private key
description: The public key of the generated SSH private key.
returned: changed or success
type: str
sample: ssh-rsa AAAAB3Nza(...omitted...)veL4E3Xcw== test_key
comment:
description: The comment of the generated key
description: The comment of the generated key.
returned: changed or success
type: str
sample: test@comment

4
plugins/modules/openssl_dhparam.py
View File

@ -15,7 +15,7 @@ short_description: Generate OpenSSL Diffie-Hellman Parameters
description:
- This module allows one to (re)generate OpenSSL DH-params.
- This module uses file common arguments to specify generated file permissions.
- "Please note that the module regenerates existing DH params if they don't
- "Please note that the module regenerates existing DH params if they do not
match the module's options. If you are concerned that this could overwrite
your existing DH params, consider using the I(backup) option."
- The module can use the cryptography Python library, or the C(openssl) executable.
@ -71,6 +71,8 @@ options:
type: bool
default: no
version_added: "1.0.0"
notes:
- Supports C(check_mode).
extends_documentation_fragment:
- files
seealso:

13
plugins/modules/openssl_privatekey_info.py
View File

@ -65,6 +65,9 @@ options:
default: auto
choices: [ auto, cryptography, pyopenssl ]
notes:
- Supports C(check_mode).
seealso:
- module: community.crypto.openssl_privatekey
- module: community.crypto.openssl_privatekey_pipe
@ -81,28 +84,28 @@ EXAMPLES = r'''
register: result
- name: Dump information
debug:
ansible.builtin.debug:
var: result
'''
RETURN = r'''
can_load_key:
description: Whether the module was able to load the private key from disk
description: Whether the module was able to load the private key from disk.
returned: always
type: bool
can_parse_key:
description: Whether the module was able to parse the private key
description: Whether the module was able to parse the private key.
returned: always
type: bool
key_is_consistent:
description:
- Whether the key is consistent. Can also return C(none) next to C(yes) and
C(no), to indicate that consistency couldn't be checked.
C(no), to indicate that consistency could not be checked.
- In case the check returns C(no), the module will fail.
returned: always
type: bool
public_key:
description: Private key's public key in PEM format
description: Private key's public key in PEM format.
returned: success
type: str
sample: "-----BEGIN PUBLIC KEY-----\nMIICIjANBgkqhkiG9w0BAQEFAAOCAg8A..."

5
plugins/modules/openssl_signature_info.py
View File

@ -14,7 +14,7 @@ module: openssl_signature_info
version_added: 1.1.0
short_description: Verify signatures with openssl
description:
- This module allows one to verify a signature for a file via a certificate.
- This module allows one to verify a signature for a file by a certificate.
- 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
overridden with the I(select_crypto_backend) option. Please note that the PyOpenSSL backend
@ -61,6 +61,7 @@ notes:
RSA keys: C(cryptography) >= 1.4
DSA and ECDSA keys: C(cryptography) >= 1.5
ed448 and ed25519 keys: C(cryptography) >= 2.6
- Supports C(check_mode).
seealso:
- module: community.crypto.openssl_signature
- module: community.crypto.x509_certificate
@ -88,7 +89,7 @@ EXAMPLES = r'''
RETURN = r'''
valid:
description: C(true) means the signature was valid for the given file, C(false) means it wasn't.
description: C(true) means the signature was valid for the given file, C(false) means it was not.
returned: success
type: bool
'''

18
plugins/modules/x509_certificate.py
View File

@ -16,7 +16,7 @@ short_description: Generate and/or check OpenSSL certificates
description:
- It implements a notion of provider (ie. C(selfsigned), C(ownca), C(acme), C(assertonly), C(entrust))
for your certificate.
- "Please note that the module regenerates existing certificate if it doesn't match the module's
- "Please note that the module regenerates existing certificate if it does not match the module's
options, or if it seems to be corrupt. If you are concerned that this could overwrite
your existing certificate, consider using the I(backup) option."
- Note that this module was called C(openssl_certificate) when included directly in Ansible up to version 2.9.
@ -86,6 +86,9 @@ options:
ownca_privatekey_content:
version_added: '1.0.0'
notes:
- Supports C(check_mode).
seealso:
- module: community.crypto.x509_certificate_pipe
@ -150,8 +153,8 @@ EXAMPLES = r'''
# The following example shows one assertonly usage using all existing options for
# assertonly, and shows how to emulate the behavior with the x509_certificate_info,
# openssl_csr_info, openssl_privatekey_info and assert modules:
- community.crypto.x509_certificate:
- name: Usage of assertonly with all existing options
community.crypto.x509_certificate:
provider: assertonly
path: /etc/ssl/crt/ansible.com.crt
csr_path: /etc/ssl/csr/ansible.com.csr
@ -182,7 +185,8 @@ EXAMPLES = r'''
invalid_at: 20200331202428Z
valid_in: 10 # in ten seconds
- community.crypto.x509_certificate_info:
- name: Get certificate information
community.crypto.x509_certificate_info:
path: /etc/ssl/crt/ansible.com.crt
# for valid_at, invalid_at and valid_in
valid_at:
@ -191,12 +195,14 @@ EXAMPLES = r'''
ten_seconds: "+10"
register: result
- community.crypto.openssl_csr_info:
- name: Get CSR information
community.crypto.openssl_csr_info:
# Verifies that the CSR signature is valid; module will fail if not
path: /etc/ssl/csr/ansible.com.csr
register: result_csr
- community.crypto.openssl_privatekey_info:
- name: Get private key information
community.crypto.openssl_privatekey_info:
path: /etc/ssl/csr/ansible.com.key
register: result_privatekey

19
plugins/modules/x509_certificate_info.py
View File

@ -54,7 +54,7 @@ options:
- Time can be specified either as relative time or as absolute timestamp.
- Time will always be interpreted as UTC.
- Valid format is C([+-]timespec | ASN.1 TIME) where timespec can be an integer
+ C([w | d | h | m | s]) (e.g. C(+32w1d2h), and ASN.1 TIME (i.e. pattern C(YYYYMMDDHHMMSSZ)).
+ C([w | d | h | m | s]) (e.g. C(+32w1d2h), and ASN.1 TIME (in other words, pattern C(YYYYMMDDHHMMSSZ)).
Note that all timestamps will be treated as being in UTC.
type: dict
select_crypto_backend:
@ -70,8 +70,9 @@ options:
choices: [ auto, cryptography, pyopenssl ]
notes:
- All timestamp values are provided in ASN.1 TIME format, i.e. following the C(YYYYMMDDHHMMSSZ) pattern.
- All timestamp values are provided in ASN.1 TIME format, in other words, following the C(YYYYMMDDHHMMSSZ) pattern.
They are all in UTC.
- Supports C(check_mode).
seealso:
- module: community.crypto.x509_certificate
- module: community.crypto.x509_certificate_pipe
@ -94,7 +95,7 @@ EXAMPLES = r'''
register: result
- name: Dump information
debug:
ansible.builtin.debug:
var: result
@ -120,7 +121,7 @@ EXAMPLES = r'''
RETURN = r'''
expired:
description: Whether the certificate is expired (i.e. C(notAfter) is in the past)
description: Whether the certificate is expired (in other words, C(notAfter) is in the past).
returned: success
type: bool
basic_constraints:
@ -144,7 +145,7 @@ extended_key_usage_critical:
returned: success
type: bool
extensions_by_oid:
description: Returns a dictionary for every extension OID
description: Returns a dictionary for every extension OID.
returned: success
type: dict
contains:
@ -153,7 +154,7 @@ extensions_by_oid:
returned: success
type: bool
value:
description: The Base64 encoded value (in DER format) of the extension
description: The Base64 encoded value (in DER format) of the extension.
returned: success
type: str
sample: "MAMCAQU="
@ -212,17 +213,17 @@ subject_ordered:
elements: list
sample: '[["commonName", "www.example.com"], ["emailAddress": "test@example.com"]]'
not_after:
description: C(notAfter) date as ASN.1 TIME
description: C(notAfter) date as ASN.1 TIME.
returned: success
type: str
sample: 20190413202428Z
not_before:
description: C(notBefore) date as ASN.1 TIME
description: C(notBefore) date as ASN.1 TIME.
returned: success
type: str
sample: 20190331202428Z
public_key:
description: Certificate's public key in PEM format
description: Certificate's public key in PEM format.
returned: success
type: str
sample: "-----BEGIN PUBLIC KEY-----\nMIICIjANBgkqhkiG9w0BAQEFAAOCAg8A..."

8
plugins/modules/x509_certificate_pipe.py
View File

@ -18,7 +18,7 @@ version_added: 1.3.0
description:
- It implements a notion of provider (ie. C(selfsigned), C(ownca), C(entrust))
for your certificate.
- "Please note that the module regenerates an existing certificate if it doesn't match the module's
- "Please note that the module regenerates an existing certificate if it does not match the module's
options, or if it seems to be corrupt. If you are concerned that this could overwrite
your existing certificate, consider using the I(backup) option."
author:
@ -43,6 +43,9 @@ options:
seealso:
- module: community.crypto.x509_certificate
notes:
- Supports C(check_mode).
extends_documentation_fragment:
- community.crypto.module_certificate
- community.crypto.module_certificate.backend_entrust_documentation
@ -57,7 +60,8 @@ EXAMPLES = r'''
privatekey_path: /etc/ssl/private/ansible.com.pem
csr_path: /etc/ssl/csr/ansible.com.csr
register: result
- ansible.builtin.debug:
- name: Print the certificate
ansible.builtin.debug:
var: result.certificate
# In the following example, both CSR and certificate file are stored on the

7
plugins/modules/x509_crl.py
View File

@ -15,7 +15,7 @@ version_added: '1.0.0'
short_description: Generate Certificate Revocation Lists (CRLs)
description:
- This module allows one to (re)generate or update Certificate Revocation Lists (CRLs).
- Certificates on the revocation list can be either specified via serial number and (optionally) their issuer,
- Certificates on the revocation list can be either specified by serial number and (optionally) their issuer,
or as a path to a certificate file in PEM format.
requirements:
- cryptography >= 1.2
@ -233,6 +233,7 @@ extends_documentation_fragment:
notes:
- All ASN.1 TIME values should be specified following the YYYYMMDDHHMMSSZ pattern.
- Date specified should be UTC. Minutes and seconds are mandatory.
- Supports C(check_mode).
'''
EXAMPLES = r'''
@ -259,7 +260,7 @@ EXAMPLES = r'''
RETURN = r'''
filename:
description: Path to the generated CRL
description: Path to the generated CRL.
returned: changed or success
type: str
sample: /path/to/my-ca.crl
@ -269,7 +270,7 @@ backup_file:
type: str
sample: /path/to/my-ca.crl.2019-03-09@11:22~
privatekey:
description: Path to the private CA key
description: Path to the private CA key.
returned: changed or success
type: str
sample: /path/to/my-ca.pem

6
plugins/modules/x509_crl_info.py
View File

@ -32,8 +32,9 @@ options:
type: str
notes:
- All timestamp values are provided in ASN.1 TIME format, i.e. following the C(YYYYMMDDHHMMSSZ) pattern.
- All timestamp values are provided in ASN.1 TIME format, in other words, following the C(YYYYMMDDHHMMSSZ) pattern.
They are all in UTC.
- Supports C(check_mode).
seealso:
- module: community.crypto.x509_crl
'''
@ -44,7 +45,8 @@ EXAMPLES = r'''
path: /etc/ssl/my-ca.crl
register: result
- debug:
- name: Print the information
ansible.builtin.debug:
msg: "{{ result }}"
'''