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

Use semantic markup (#626)

Browse Source 
* Enable semantic markup.

* Use semantic markup.

* Break long lines.

* Add ignores.

* Use real option, not alias.
This commit is contained in:
Felix Fontein
2023-06-24 10:00:56 +02:00
committed by GitHub
parent c78536dfeb
commit 99d1521266
51 changed files with 1016 additions and 899 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
changelogs/fragments/semantic-markup.yml Normal file
View File

@@ -0,0 +1,5 @@
known_issues:
- Ansible markup will show up in raw form on ansible-doc text output for ansible-core
before 2.15. If you have trouble deciphering the documentation markup, please
upgrade to ansible-core 2.15 (or newer), or read the HTML documentation on
https://docs.ansible.com/ansible/devel/collections/community/crypto/.

8
docs/docsite/rst/guide_selfsigned.rst
View File

@@ -10,7 +10,7 @@ How to create self-signed certificates
The `community.crypto collection <https://galaxy.ansible.com/community/crypto>`_ offers multiple modules that create private keys, certificate signing requests, and certificates. This guide shows how to create self-signed certificates.
For creating any kind of certificate, you always have to start with a private key. You can use the :ref:`community.crypto.openssl_privatekey module <ansible_collections.community.crypto.openssl_privatekey_module>` to create a private key. If you only specify ``path``, the default parameters will be used. This will result in a 4096 bit RSA private key:
For creating any kind of certificate, you always have to start with a private key. You can use the :ref:`community.crypto.openssl_privatekey module <ansible_collections.community.crypto.openssl_privatekey_module>` to create a private key. If you only specify :ansopt:`community.crypto.openssl_privatekey#module:path`, the default parameters will be used. This will result in a 4096 bit RSA private key:
.. code-block:: yaml+jinja
@@ -18,7 +18,7 @@ For creating any kind of certificate, you always have to start with a private ke
community.crypto.openssl_privatekey:
path: /path/to/certificate.key
You can specify ``type`` to select another key type, ``size`` to select a different key size (only available for RSA and DSA keys), or ``passphrase`` if you want to store the key password-protected:
You can specify :ansopt:`community.crypto.openssl_privatekey#module:type` to select another key type, :ansopt:`community.crypto.openssl_privatekey#module:size` to select a different key size (only available for RSA and DSA keys), or :ansopt:`community.crypto.openssl_privatekey#module:passphrase` if you want to store the key password-protected:
.. code-block:: yaml+jinja
@@ -38,9 +38,9 @@ To create a very simple self-signed certificate with no specific information, yo
privatekey_path: /path/to/certificate.key
provider: selfsigned
(If you used ``passphrase`` for the private key, you have to provide ``privatekey_passphrase``.)
(If you used :ansopt:`community.crypto.openssl_privatekey#module:passphrase` for the private key, you have to provide :ansopt:`community.crypto.x509_certificate#module:privatekey_passphrase`.)
You can use ``selfsigned_not_after`` to define when the certificate expires (default: in roughly 10 years), and ``selfsigned_not_before`` to define from when the certificate is valid (default: now).
You can use :ansopt:`community.crypto.x509_certificate#module:selfsigned_not_after` to define when the certificate expires (default: in roughly 10 years), and :ansopt:`community.crypto.x509_certificate#module:selfsigned_not_before` to define from when the certificate is valid (default: now).
To define further properties of the certificate, like the subject, Subject Alternative Names (SANs), key usages, name constraints, etc., you need to first create a Certificate Signing Request (CSR) and provide it to the :ref:`community.crypto.x509_certificate module <ansible_collections.community.crypto.x509_certificate_module>`. If you do not need the CSR file, you can use the :ref:`community.crypto.openssl_csr_pipe module <ansible_collections.community.crypto.openssl_csr_pipe_module>` as in the example below. (To store it to disk, use the :ref:`community.crypto.openssl_csr module <ansible_collections.community.crypto.openssl_csr_module>` instead.)

26
plugins/doc_fragments/acme.py
View File

@@ -16,10 +16,10 @@ 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 C(select_crypto_backend) option. Note that using
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
C(account_key_content))."
O(account_key_content))."
- "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
@@ -47,15 +47,15 @@ options:
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."
- "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 C(account_key_src)."
- "Required if C(account_key_src) is not used."
- "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,
@@ -81,9 +81,9 @@ options:
acme_version:
description:
- "The ACME version of the endpoint."
- "Must be C(1) for the classic Let's Encrypt and Buypass ACME endpoints,
or C(2) for standardized ACME v2 endpoints."
- "The value C(1) is deprecated since community.crypto 2.0.0 and will be
- "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
@@ -114,17 +114,17 @@ options:
validate_certs:
description:
- Whether calls to the ACME directory will validate TLS certificates.
- "B(Warning:) Should B(only ever) be set to C(false) for testing purposes,
- "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 C(auto), which tries to use C(cryptography) if available, and falls back to
- The default choice is V(auto), which tries to use C(cryptography) if available, and falls back to
C(openssl).
- If set to C(openssl), will try to use the C(openssl) binary.
- If set to C(cryptography), will try to use the
- 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

168
plugins/doc_fragments/module_certificate.py
View File

@@ -17,7 +17,7 @@ description:
- This module allows one to (re)generate OpenSSL certificates.
- It uses the cryptography python library to interact with OpenSSL.
requirements:
- cryptography >= 1.6 (if using C(selfsigned) or C(ownca) provider)
- cryptography >= 1.6 (if using V(selfsigned) or V(ownca) provider)
options:
force:
description:
@@ -28,35 +28,35 @@ options:
csr_path:
description:
- Path to the Certificate Signing Request (CSR) used to generate this certificate.
- This is mutually exclusive with I(csr_content).
- This is mutually exclusive with O(csr_content).
type: path
csr_content:
description:
- Content of the Certificate Signing Request (CSR) used to generate this certificate.
- This is mutually exclusive with I(csr_path).
- This is mutually exclusive with O(csr_path).
type: str
privatekey_path:
description:
- Path to the private key to use when signing the certificate.
- This is mutually exclusive with I(privatekey_content).
- This is mutually exclusive with O(privatekey_content).
type: path
privatekey_content:
description:
- Content of the private key to use when signing the certificate.
- This is mutually exclusive with I(privatekey_path).
- This is mutually exclusive with O(privatekey_path).
type: str
privatekey_passphrase:
description:
- The passphrase for the I(privatekey_path) resp. I(privatekey_content).
- The passphrase for the O(privatekey_path) resp. O(privatekey_content).
- This is required if the private key is password protected.
type: str
ignore_timestamps:
description:
- Whether the "not before" and "not after" timestamps should be ignored for idempotency checks.
- It is better to keep the default value C(true) when using relative timestamps (like C(+0s) for now).
- It is better to keep the default value V(true) when using relative timestamps (like V(+0s) for now).
type: bool
default: true
version_added: 2.0.0
@@ -64,8 +64,8 @@ options:
select_crypto_backend:
description:
- Determines which crypto backend to use.
- The default choice is C(auto), which tries to use C(cryptography) if available.
- If set to C(cryptography), will try to use the L(cryptography,https://cryptography.io/) library.
- 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 ]
@@ -73,7 +73,7 @@ options:
notes:
- All ASN.1 TIME values should be specified following the YYYYMMDDHHMMSSZ pattern.
- Date specified should be UTC. Minutes and seconds are mandatory.
- For security reason, when you use C(ownca) provider, you should NOT run
- For security reason, when you use V(ownca) provider, you should NOT run
M(community.crypto.x509_certificate) on a target machine, but on a dedicated CA machine. It
is recommended not to store the CA private key on the target machine. Once signed, the
certificate can be moved to the target machine.
@@ -91,26 +91,26 @@ seealso:
description:
- This module allows one to (re)generate OpenSSL certificates.
requirements:
- acme-tiny >= 4.0.0 (if using the C(acme) provider)
- acme-tiny >= 4.0.0 (if using the V(acme) provider)
options:
acme_accountkey_path:
description:
- The path to the accountkey for the C(acme) provider.
- This is only used by the C(acme) provider.
- The path to the accountkey for the V(acme) provider.
- This is only used by the V(acme) provider.
type: path
acme_challenge_path:
description:
- The path to the ACME challenge directory that is served on U(http://<HOST>:80/.well-known/acme-challenge/)
- This is only used by the C(acme) provider.
- This is only used by the V(acme) provider.
type: path
acme_chain:
description:
- Include the intermediate certificate to the generated certificate
- This is only used by the C(acme) provider.
- This is only used by the V(acme) provider.
- Note that this is only available for older versions of C(acme-tiny).
New versions include the chain automatically, and setting I(acme_chain) to C(true) results in an error.
New versions include the chain automatically, and setting O(acme_chain) to V(true) results in an error.
type: bool
default: false
@@ -127,7 +127,7 @@ options:
entrust_cert_type:
description:
- Specify the type of certificate requested.
- This is only used by the C(entrust) provider.
- This is only used by the V(entrust) provider.
type: str
default: STANDARD_SSL
choices: [ 'STANDARD_SSL', 'ADVANTAGE_SSL', 'UC_SSL', 'EV_SSL', 'WILDCARD_SSL', 'PRIVATE_SSL', 'PD_SSL', 'CDS_ENT_LITE', 'CDS_ENT_PRO', 'SMIME_ENT' ]
@@ -135,66 +135,66 @@ options:
entrust_requester_email:
description:
- The email of the requester of the certificate (for tracking purposes).
- This is only used by the C(entrust) provider.
- This is required if the provider is C(entrust).
- This is only used by the V(entrust) provider.
- This is required if the provider is V(entrust).
type: str
entrust_requester_name:
description:
- The name of the requester of the certificate (for tracking purposes).
- This is only used by the C(entrust) provider.
- This is required if the provider is C(entrust).
- This is only used by the V(entrust) provider.
- This is required if the provider is V(entrust).
type: str
entrust_requester_phone:
description:
- The phone number of the requester of the certificate (for tracking purposes).
- This is only used by the C(entrust) provider.
- This is required if the provider is C(entrust).
- This is only used by the V(entrust) provider.
- This is required if the provider is V(entrust).
type: str
entrust_api_user:
description:
- The username for authentication to the Entrust Certificate Services (ECS) API.
- This is only used by the C(entrust) provider.
- This is required if the provider is C(entrust).
- This is only used by the V(entrust) provider.
- This is required if the provider is V(entrust).
type: str
entrust_api_key:
description:
- The key (password) for authentication to the Entrust Certificate Services (ECS) API.
- This is only used by the C(entrust) provider.
- This is required if the provider is C(entrust).
- This is only used by the V(entrust) provider.
- This is required if the provider is V(entrust).
type: str
entrust_api_client_cert_path:
description:
- The path to the client certificate used to authenticate to the Entrust Certificate Services (ECS) API.
- This is only used by the C(entrust) provider.
- This is required if the provider is C(entrust).
- This is only used by the V(entrust) provider.
- This is required if the provider is V(entrust).
type: path
entrust_api_client_cert_key_path:
description:
- The path to the private key of the client certificate used to authenticate to the Entrust Certificate Services (ECS) API.
- This is only used by the C(entrust) provider.
- This is required if the provider is C(entrust).
- This is only used by the V(entrust) provider.
- This is required if the provider is V(entrust).
type: path
entrust_not_after:
description:
- The point in time at which the certificate stops being valid.
- Time can be specified either as relative time or as an absolute timestamp.
- A valid absolute time format is C(ASN.1 TIME) such as C(2019-06-18).
- A valid relative time format is C([+-]timespec) where timespec can be an integer + C([w | d | h | m | s]), such as C(+365d) or C(+32w1d2h)).
- A valid absolute time format is C(ASN.1 TIME) such as V(2019-06-18).
- A valid relative time format is V([+-]timespec) where timespec can be an integer + C([w | d | h | m | s]), such as V(+365d) or V(+32w1d2h)).
- Time will always be interpreted as UTC.
- Note that only the date (day, month, year) is supported for specifying the expiry date of the issued certificate.
- The full date-time is adjusted to EST (GMT -5:00) before issuance, which may result in a certificate with an expiration date one day
earlier than expected if a relative time is used.
- The minimum certificate lifetime is 90 days, and maximum is three years.
- If this value is not specified, the certificate will stop being valid 365 days the date of issue.
- This is only used by the C(entrust) provider.
- Please note that this value is B(not) covered by the I(ignore_timestamps) option.
- This is only used by the V(entrust) provider.
- Please note that this value is B(not) covered by the O(ignore_timestamps) option.
type: str
default: +365d
@@ -202,60 +202,60 @@ options:
description:
- The path to the specification file defining the Entrust Certificate Services (ECS) API configuration.
- You can use this to keep a local copy of the specification to avoid downloading it every time the module is used.
- This is only used by the C(entrust) provider.
- This is only used by the V(entrust) provider.
type: path
default: https://cloud.entrust.net/EntrustCloud/documentation/cms-api-2.1.0.yaml
'''
BACKEND_OWNCA_DOCUMENTATION = r'''
description:
- The C(ownca) provider is intended for generating an OpenSSL certificate signed with your own
- The V(ownca) provider is intended for generating an OpenSSL certificate signed with your own
CA (Certificate Authority) certificate (self-signed certificate).
options:
ownca_path:
description:
- Remote absolute path of the CA (Certificate Authority) certificate.
- This is only used by the C(ownca) provider.
- This is mutually exclusive with I(ownca_content).
- This is only used by the V(ownca) provider.
- This is mutually exclusive with O(ownca_content).
type: path
ownca_content:
description:
- Content of the CA (Certificate Authority) certificate.
- This is only used by the C(ownca) provider.
- This is mutually exclusive with I(ownca_path).
- This is only used by the V(ownca) provider.
- This is mutually exclusive with O(ownca_path).
type: str
ownca_privatekey_path:
description:
- Path to the CA (Certificate Authority) private key to use when signing the certificate.
- This is only used by the C(ownca) provider.
- This is mutually exclusive with I(ownca_privatekey_content).
- This is only used by the V(ownca) provider.
- This is mutually exclusive with O(ownca_privatekey_content).
type: path
ownca_privatekey_content:
description:
- Content of the CA (Certificate Authority) private key to use when signing the certificate.
- This is only used by the C(ownca) provider.
- This is mutually exclusive with I(ownca_privatekey_path).
- This is only used by the V(ownca) provider.
- This is mutually exclusive with O(ownca_privatekey_path).
type: str
ownca_privatekey_passphrase:
description:
- The passphrase for the I(ownca_privatekey_path) resp. I(ownca_privatekey_content).
- This is only used by the C(ownca) provider.
- The passphrase for the O(ownca_privatekey_path) resp. O(ownca_privatekey_content).
- This is only used by the V(ownca) provider.
type: str
ownca_digest:
description:
- The digest algorithm to be used for the C(ownca) certificate.
- This is only used by the C(ownca) provider.
- The digest algorithm to be used for the V(ownca) certificate.
- This is only used by the V(ownca) provider.
type: str
default: sha256
ownca_version:
description:
- The version of the C(ownca) certificate.
- Nowadays it should almost always be C(3).
- This is only used by the C(ownca) provider.
- The version of the V(ownca) certificate.
- Nowadays it should almost always be V(3).
- This is only used by the V(ownca) provider.
type: int
default: 3
@@ -265,12 +265,12 @@ 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]) (for example C(+32w1d2h)).
+ C([w | d | h | m | s]) (for example V(+32w1d2h)).
- If this value is not specified, the certificate will start being valid from now.
- Note that this value is B(not used to determine whether an existing certificate should be regenerated).
This can be changed by setting the I(ignore_timestamps) option to C(false). Please note that you should
avoid relative timestamps when setting I(ignore_timestamps=false).
- This is only used by the C(ownca) provider.
This can be changed by setting the O(ignore_timestamps) option to V(false). Please note that you should
avoid relative timestamps when setting O(ignore_timestamps=false).
- This is only used by the V(ownca) provider.
type: str
default: +0s
@@ -280,12 +280,12 @@ 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]) (for example C(+32w1d2h)).
+ C([w | d | h | m | s]) (for example V(+32w1d2h)).
- If this value is not specified, the certificate will stop being valid 10 years from now.
- Note that this value is B(not used to determine whether an existing certificate should be regenerated).
This can be changed by setting the I(ignore_timestamps) option to C(false). Please note that you should
avoid relative timestamps when setting I(ignore_timestamps=false).
- This is only used by the C(ownca) provider.
This can be changed by setting the O(ignore_timestamps) option to V(false). Please note that you should
avoid relative timestamps when setting O(ignore_timestamps=false).
- This is only used by the V(ownca) provider.
- On macOS 10.15 and onwards, TLS server certificates must have a validity period of 825 days or fewer.
Please see U(https://support.apple.com/en-us/HT210176) for more details.
type: str
@@ -294,12 +294,12 @@ options:
ownca_create_subject_key_identifier:
description:
- Whether to create the Subject Key Identifier (SKI) from the public key.
- A value of C(create_if_not_provided) (default) only creates a SKI when the CSR does not
- A value of V(create_if_not_provided) (default) only creates a SKI when the CSR does not
provide one.
- A value of C(always_create) always creates a SKI. If the CSR provides one, that one is
- A value of V(always_create) always creates a SKI. If the CSR provides one, that one is
ignored.
- A value of C(never_create) never creates a SKI. If the CSR provides one, that one is used.
- This is only used by the C(ownca) provider.
- A value of V(never_create) never creates a SKI. If the CSR provides one, that one is used.
- This is only used by the V(ownca) provider.
- Note that this is only supported if the C(cryptography) backend is used!
type: str
choices: [create_if_not_provided, always_create, never_create]
@@ -311,7 +311,7 @@ options:
a authority key identifier, it is ignored.
- The Authority Key Identifier is generated from the CA certificate's Subject Key Identifier,
if available. If it is not available, the CA certificate's public key will be used.
- This is only used by the C(ownca) provider.
- This is only used by the V(ownca) provider.
- Note that this is only supported if the C(cryptography) backend is used!
type: bool
default: true
@@ -319,7 +319,7 @@ options:
BACKEND_SELFSIGNED_DOCUMENTATION = r'''
notes:
- For the C(selfsigned) provider, I(csr_path) and I(csr_content) are optional. If not provided, a
- For the V(selfsigned) provider, O(csr_path) and O(csr_content) are optional. If not provided, a
certificate without any information (Subject, Subject Alternative Names, Key Usage, etc.) is created.
options:
@@ -329,28 +329,28 @@ options:
# csr_path:
# description:
# - This is optional for the C(selfsigned) provider. If not provided, a certificate
# - This is optional for the V(selfsigned) provider. If not provided, a certificate
# without any information (Subject, Subject Alternative Names, Key Usage, etc.) is
# created.
# csr_content:
# description:
# - This is optional for the C(selfsigned) provider. If not provided, a certificate
# - This is optional for the V(selfsigned) provider. If not provided, a certificate
# without any information (Subject, Subject Alternative Names, Key Usage, etc.) is
# created.
selfsigned_version:
description:
- Version of the C(selfsigned) certificate.
- Nowadays it should almost always be C(3).
- This is only used by the C(selfsigned) provider.
- Version of the V(selfsigned) certificate.
- Nowadays it should almost always be V(3).
- This is only used by the V(selfsigned) provider.
type: int
default: 3
selfsigned_digest:
description:
- Digest algorithm to be used when self-signing the certificate.
- This is only used by the C(selfsigned) provider.
- This is only used by the V(selfsigned) provider.
type: str
default: sha256
@@ -360,12 +360,12 @@ 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]) (for example C(+32w1d2h)).
+ C([w | d | h | m | s]) (for example V(+32w1d2h)).
- If this value is not specified, the certificate will start being valid from now.
- Note that this value is B(not used to determine whether an existing certificate should be regenerated).
This can be changed by setting the I(ignore_timestamps) option to C(false). Please note that you should
avoid relative timestamps when setting I(ignore_timestamps=false).
- This is only used by the C(selfsigned) provider.
This can be changed by setting the O(ignore_timestamps) option to V(false). Please note that you should
avoid relative timestamps when setting O(ignore_timestamps=false).
- This is only used by the V(selfsigned) provider.
type: str
default: +0s
aliases: [ selfsigned_notBefore ]
@@ -376,12 +376,12 @@ 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]) (for example C(+32w1d2h)).
+ C([w | d | h | m | s]) (for example V(+32w1d2h)).
- If this value is not specified, the certificate will stop being valid 10 years from now.
- Note that this value is B(not used to determine whether an existing certificate should be regenerated).
This can be changed by setting the I(ignore_timestamps) option to C(false). Please note that you should
avoid relative timestamps when setting I(ignore_timestamps=false).
- This is only used by the C(selfsigned) provider.
This can be changed by setting the O(ignore_timestamps) option to V(false). Please note that you should
avoid relative timestamps when setting O(ignore_timestamps=false).
- This is only used by the V(selfsigned) provider.
- On macOS 10.15 and onwards, TLS server certificates must have a validity period of 825 days or fewer.
Please see U(https://support.apple.com/en-us/HT210176) for more details.
type: str
@@ -391,12 +391,12 @@ options:
selfsigned_create_subject_key_identifier:
description:
- Whether to create the Subject Key Identifier (SKI) from the public key.
- A value of C(create_if_not_provided) (default) only creates a SKI when the CSR does not
- A value of V(create_if_not_provided) (default) only creates a SKI when the CSR does not
provide one.
- A value of C(always_create) always creates a SKI. If the CSR provides one, that one is
- A value of V(always_create) always creates a SKI. If the CSR provides one, that one is
ignored.
- A value of C(never_create) never creates a SKI. If the CSR provides one, that one is used.
- This is only used by the C(selfsigned) provider.
- A value of V(never_create) never creates a SKI. If the CSR provides one, that one is used.
- This is only used by the V(selfsigned) provider.
- Note that this is only supported if the C(cryptography) backend is used!
type: str
choices: [create_if_not_provided, always_create, never_create]

70
plugins/doc_fragments/module_csr.py
View File

@@ -27,12 +27,12 @@ options:
privatekey_path:
description:
- The path to the private key to use when signing the certificate signing request.
- Either I(privatekey_path) or I(privatekey_content) must be specified if I(state) is C(present), but not both.
- Either O(privatekey_path) or O(privatekey_content) must be specified if O(state) is V(present), but not both.
type: path
privatekey_content:
description:
- The content of the private key to use when signing the certificate signing request.
- Either I(privatekey_path) or I(privatekey_content) must be specified if I(state) is C(present), but not both.
- Either O(privatekey_path) or O(privatekey_content) must be specified if O(state) is V(present), but not both.
type: str
privatekey_passphrase:
description:
@@ -53,17 +53,17 @@ options:
description:
- Key/value pairs that will be present in the subject name field of the certificate signing request.
- If you need to specify more than one value with the same key, use a list as value.
- If the order of the components is important, use I(subject_ordered).
- Mutually exclusive with I(subject_ordered).
- If the order of the components is important, use O(subject_ordered).
- Mutually exclusive with O(subject_ordered).
type: dict
subject_ordered:
description:
- A list of dictionaries, where every dictionary must contain one key/value pair. This key/value pair
will be present in the subject name field of the certificate signing request.
- If you want to specify more than one value with the same key in a row, you can use a list as value.
- Mutually exclusive with I(subject), and any other subject field option, such as I(country_name),
I(state_or_province_name), I(locality_name), I(organization_name), I(organizational_unit_name),
I(common_name), or I(email_address).
- Mutually exclusive with O(subject), and any other subject field option, such as O(country_name),
O(state_or_province_name), O(locality_name), O(organization_name), O(organizational_unit_name),
O(common_name), or O(email_address).
type: list
elements: dict
version_added: 2.0.0
@@ -108,8 +108,8 @@ options:
- Values must be prefixed by their options. (These are C(email), C(URI), C(DNS), C(RID), C(IP), C(dirName),
C(otherName), and the ones specific to your CA).
- Note that if no SAN is specified, but a common name, the common
name will be added as a SAN except if C(useCommonNameForSAN) is
set to I(false).
name will be added as a SAN except if O(use_common_name_for_san) is
set to V(false).
- More at U(https://tools.ietf.org/html/rfc5280#section-4.2.1.6).
type: list
elements: str
@@ -122,8 +122,8 @@ options:
aliases: [ subjectAltName_critical ]
use_common_name_for_san:
description:
- If set to C(true), the module will fill the common name in for
C(subject_alt_name) with C(DNS:) prefix if no SAN is specified.
- If set to V(true), the module will fill the common name in for
O(subject_alt_name) with C(DNS:) prefix if no SAN is specified.
type: bool
default: true
aliases: [ useCommonNameForSAN ]
@@ -186,16 +186,16 @@ options:
description:
- For CA certificates, this specifies a list of identifiers which describe
subtrees of names that this CA is 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).
- Values must be prefixed by their options. (That is, C(email), C(URI), C(DNS), C(RID), C(IP), C(dirName),
C(otherName), and the ones specific to your CA).
type: list
elements: str
name_constraints_excluded:
description:
- For CA certificates, this specifies a list of identifiers which describe
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).
- Values must be prefixed by their options. (That is, C(email), C(URI), C(DNS), C(RID), C(IP), C(dirName),
C(otherName), and the ones specific to your CA).
type: list
elements: str
name_constraints_critical:
@@ -206,8 +206,8 @@ options:
select_crypto_backend:
description:
- Determines which crypto backend to use.
- The default choice is C(auto), which tries to use C(cryptography) if available.
- If set to C(cryptography), will try to use the L(cryptography,https://cryptography.io/) library.
- 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 ]
@@ -223,49 +223,49 @@ options:
subject_key_identifier:
description:
- The subject key identifier as a hex string, where two bytes are separated by colons.
- "Example: C(00:11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee:ff:00:11:22:33)"
- "Example: V(00:11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee:ff:00:11:22:33)"
- "Please note that commercial CAs ignore this value, respectively use a value of their
own choice. Specifying this option is mostly useful for self-signed certificates
or for own CAs."
- Note that this option can only be used if I(create_subject_key_identifier) is C(false).
- Note that this option can only be used if O(create_subject_key_identifier) is V(false).
- Note that this is only supported if the C(cryptography) backend is used!
type: str
authority_key_identifier:
description:
- The authority key identifier as a hex string, where two bytes are separated by colons.
- "Example: C(00:11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee:ff:00:11:22:33)"
- "Example: V(00:11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee:ff:00:11:22:33)"
- "Please note that commercial CAs ignore this value, respectively use a value of their
own choice. Specifying this option is mostly useful for self-signed certificates
or for own CAs."
- Note that this is only supported if the C(cryptography) backend is used!
- The C(AuthorityKeyIdentifier) extension will only be added if at least one of I(authority_key_identifier),
I(authority_cert_issuer) and I(authority_cert_serial_number) is specified.
- The C(AuthorityKeyIdentifier) extension will only be added if at least one of O(authority_key_identifier),
O(authority_cert_issuer) and O(authority_cert_serial_number) is specified.
type: str
authority_cert_issuer:
description:
- Names that will be present in the authority cert issuer field of the certificate signing request.
- 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)
- "Example: C(DNS:ca.example.org)"
- If specified, I(authority_cert_serial_number) must also be specified.
- Values must be prefixed by their options. (That is, C(email), C(URI), C(DNS), C(RID), C(IP), C(dirName),
C(otherName), and the ones specific to your CA)
- "Example: V(DNS:ca.example.org)"
- If specified, O(authority_cert_serial_number) must also be specified.
- "Please note that commercial CAs ignore this value, respectively use a value of their
own choice. Specifying this option is mostly useful for self-signed certificates
or for own CAs."
- Note that this is only supported if the C(cryptography) backend is used!
- The C(AuthorityKeyIdentifier) extension will only be added if at least one of I(authority_key_identifier),
I(authority_cert_issuer) and I(authority_cert_serial_number) is specified.
- The C(AuthorityKeyIdentifier) extension will only be added if at least one of O(authority_key_identifier),
O(authority_cert_issuer) and O(authority_cert_serial_number) is specified.
type: list
elements: str
authority_cert_serial_number:
description:
- The authority cert serial number.
- If specified, I(authority_cert_issuer) must also be specified.
- If specified, O(authority_cert_issuer) must also be specified.
- Note that this is only supported if the C(cryptography) backend is used!
- "Please note that commercial CAs ignore this value, respectively use a value of their
own choice. Specifying this option is mostly useful for self-signed certificates
or for own CAs."
- The C(AuthorityKeyIdentifier) extension will only be added if at least one of I(authority_key_identifier),
I(authority_cert_issuer) and I(authority_cert_serial_number) is specified.
- The C(AuthorityKeyIdentifier) extension will only be added if at least one of O(authority_key_identifier),
O(authority_cert_issuer) and O(authority_cert_serial_number) is specified.
type: int
crl_distribution_points:
description:
@@ -277,15 +277,15 @@ options:
full_name:
description:
- Describes how the CRL can be retrieved.
- Mutually exclusive with I(relative_name).
- "Example: C(URI:https://ca.example.com/revocations.crl)."
- Mutually exclusive with O(crl_distribution_points[].relative_name).
- "Example: V(URI:https://ca.example.com/revocations.crl)."
type: list
elements: str
relative_name:
description:
- Describes how the CRL can be retrieved relative to the CRL issuer.
- Mutually exclusive with I(full_name).
- "Example: C(/CN=example.com)."
- Mutually exclusive with O(crl_distribution_points[].full_name).
- "Example: V(/CN=example.com)."
- Can only be used when cryptography >= 1.6 is installed.
type: list
elements: str

49
plugins/doc_fragments/module_privatekey.py
View File

@@ -18,11 +18,6 @@ description:
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.
- "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 I(backup) option."
requirements:
- cryptography >= 1.2.3 (older versions might work as well)
options:
@@ -34,20 +29,20 @@ options:
type:
description:
- The algorithm used to generate the TLS/SSL private key.
- Note that C(ECC), C(X25519), C(X448), C(Ed25519) and C(Ed448) require the C(cryptography) backend.
C(X25519) needs cryptography 2.5 or newer, while C(X448), C(Ed25519) and C(Ed448) require
cryptography 2.6 or newer. For C(ECC), the minimal cryptography version required depends on the
I(curve) option.
- 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, C(secp384r1) or C(secp256r1) should be used.
- 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 C(secp224r1), C(secp256k1), C(secp256r1), C(secp384r1) and C(secp521r1)
- 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:
@@ -76,13 +71,13 @@ options:
type: str
cipher:
description:
- The cipher to encrypt the private key. Must be C(auto).
- The cipher to encrypt the private key. Must be V(auto).
type: str
select_crypto_backend:
description:
- Determines which crypto backend to use.
- The default choice is C(auto), which tries to use C(cryptography) if available.
- If set to C(cryptography), will try to use the L(cryptography,https://cryptography.io/) library.
- 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 ]
@@ -90,11 +85,11 @@ options:
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 C(auto) selects a format based on the key format. The value C(auto_ignore) does the same,
- 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 I(format_mismatch) option.
To change this behavior, use the O(format_mismatch) option.
type: str
default: auto_ignore
choices: [ pkcs1, pkcs8, raw, auto, auto_ignore ]
@@ -102,8 +97,8 @@ options:
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 C(regenerate) (default), generates a new private key.
- If set to C(convert), the key will be converted to the new format instead.
- 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
@@ -114,24 +109,24 @@ options:
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 C(full_idempotence)
this B(changed) for Ansible 2.10. For Ansible 2.9, the behavior was as if V(full_idempotence)
is specified.
- If set to C(never), the module will fail if the key cannot be read or the passphrase
- 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 C(fail), the module will fail if the key does not correspond to the module's
- If set to V(fail), the module will fail if the key does not correspond to the module's
options.
- If set to C(partial_idempotence), the key will be regenerated if it does not conform to
- 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 C(full_idempotence), the key will be regenerated if it does not conform to the
- 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 C(always), the module will always regenerate the key. This is equivalent to
setting I(force) to C(true).
- Note that if I(format_mismatch) is set to C(convert) and everything matches except the
format, the key will always be converted, except if I(regenerate) is set to C(always).
- 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

4
plugins/doc_fragments/module_privatekey_convert.py
View File

@@ -18,12 +18,12 @@ options:
src_path:
description:
- Name of the file containing the OpenSSL private key to convert.
- Exactly one of I(src_path) or I(src_content) must be specified.
- Exactly one of O(src_path) or O(src_content) must be specified.
type: path
src_content:
description:
- The content of the file containing the OpenSSL private key to convert.
- Exactly one of I(src_path) or I(src_content) must be specified.
- Exactly one of O(src_path) or O(src_content) must be specified.
type: str
src_passphrase:
description:

10
plugins/doc_fragments/name_encoding.py
View File

@@ -14,12 +14,12 @@ options:
name_encoding:
description:
- How to encode names (DNS names, URIs, email addresses) in return values.
- C(ignore) will use the encoding returned by the backend.
- C(idna) will convert all labels of domain names to IDNA encoding.
- V(ignore) will use the encoding returned by the backend.
- V(idna) will convert all labels of domain names to IDNA encoding.
IDNA2008 will be preferred, and IDNA2003 will be used if IDNA2008 encoding fails.
- C(unicode) will convert all labels of domain names to Unicode.
- V(unicode) will convert all labels of domain names to Unicode.
IDNA2008 will be preferred, and IDNA2003 will be used if IDNA2008 decoding fails.
- B(Note) that C(idna) and C(unicode) require the L(idna Python library,https://pypi.org/project/idna/) to be installed.
- B(Note) that V(idna) and V(unicode) require the L(idna Python library,https://pypi.org/project/idna/) to be installed.
type: str
default: ignore
choices:
@@ -27,5 +27,5 @@ options:
- idna
- unicode
requirements:
- If I(name_encoding) is set to another value than C(ignore), the L(idna Python library,https://pypi.org/project/idna/) needs to be installed.
- If O(name_encoding) is set to another value than V(ignore), the L(idna Python library,https://pypi.org/project/idna/) needs to be installed.
'''

61
plugins/filter/openssl_csr_info.py
View File

@@ -49,11 +49,11 @@ _value:
signature_valid:
description:
- Whether the CSR's signature is valid.
- In case the check returns C(false), the module will fail.
- In case the check returns V(false), the module will fail.
returned: success
type: bool
basic_constraints:
description: Entries in the C(basic_constraints) extension, or C(none) if extension is not present.
description: Entries in the C(basic_constraints) extension, or V(none) if extension is not present.
returned: success
type: list
elements: str
@@ -63,7 +63,7 @@ _value:
returned: success
type: bool
extended_key_usage:
description: Entries in the C(extended_key_usage) extension, or C(none) if extension is not present.
description: Entries in the C(extended_key_usage) extension, or V(none) if extension is not present.
returned: success
type: list
elements: str
@@ -94,7 +94,7 @@ _value:
sample: "MAMCAQU="
sample: {"1.3.6.1.5.5.7.1.24": { "critical": false, "value": "MAMCAQU="}}
key_usage:
description: Entries in the C(key_usage) extension, or C(none) if extension is not present.
description: Entries in the C(key_usage) extension, or V(none) if extension is not present.
returned: success
type: str
sample: [Key Agreement, Data Encipherment]
@@ -104,8 +104,8 @@ _value:
type: bool
subject_alt_name:
description:
- Entries in the C(subject_alt_name) extension, or C(none) if extension is not present.
- See I(name_encoding) for how IDNs are handled.
- Entries in the C(subject_alt_name) extension, or V(none) if extension is not present.
- See O(name_encoding) for how IDNs are handled.
returned: success
type: list
elements: str
@@ -115,7 +115,7 @@ _value:
returned: success
type: bool
ocsp_must_staple:
description: C(true) if the OCSP Must Staple extension is present, C(none) otherwise.
description: V(true) if the OCSP Must Staple extension is present, V(none) otherwise.
returned: success
type: bool
ocsp_must_staple_critical:
@@ -131,8 +131,8 @@ _value:
name_constraints_excluded:
description:
- List of excluded subtrees the CA cannot sign certificates for.
- Is C(none) if extension is not present.
- See I(name_encoding) for how IDNs are handled.
- Is V(none) if extension is not present.
- See O(name_encoding) for how IDNs are handled.
returned: success
type: list
elements: str
@@ -140,7 +140,7 @@ _value:
name_constraints_critical:
description:
- Whether the C(name_constraints) extension is critical.
- Is C(none) if extension is not present.
- Is V(none) if extension is not present.
returned: success
type: bool
subject:
@@ -164,7 +164,7 @@ _value:
public_key_type:
description:
- The CSR's public key's type.
- One of C(RSA), C(DSA), C(ECC), C(Ed25519), C(X25519), C(Ed448), or C(X448).
- One of V(RSA), V(DSA), V(ECC), V(Ed25519), V(X25519), V(Ed448), or V(X448).
- Will start with C(unknown) if the key type cannot be determined.
returned: success
type: str
@@ -179,57 +179,58 @@ _value:
description:
- Bit size of modulus (RSA) or prime number (DSA).
type: int
returned: When C(public_key_type=RSA) or C(public_key_type=DSA)
returned: When RV(_value.public_key_type=RSA) or RV(_value.public_key_type=DSA)
modulus:
description:
- The RSA key's modulus.
type: int
returned: When C(public_key_type=RSA)
returned: When RV(_value.public_key_type=RSA)
exponent:
description:
- The RSA key's public exponent.
type: int
returned: When C(public_key_type=RSA)
returned: When RV(_value.public_key_type=RSA)
p:
description:
- The C(p) value for DSA.
- This is the prime modulus upon which arithmetic takes place.
type: int
returned: When C(public_key_type=DSA)
returned: When RV(_value.public_key_type=DSA)
q:
description:
- The C(q) value for DSA.
- This is a prime that divides C(p - 1), and at the same time the order of the subgroup of the
multiplicative group of the prime field used.
type: int
returned: When C(public_key_type=DSA)
returned: When RV(_value.public_key_type=DSA)
g:
description:
- The C(g) value for DSA.
- This is the element spanning the subgroup of the multiplicative group of the prime field used.
type: int
returned: When C(public_key_type=DSA)
returned: When RV(_value.public_key_type=DSA)
curve:
description:
- The curve's name for ECC.
type: str
returned: When C(public_key_type=ECC)
returned: When RV(_value.public_key_type=ECC)
exponent_size:
description:
- The maximum number of bits of a private key. This is basically the bit size of the subgroup used.
type: int
returned: When C(public_key_type=ECC)
returned: When RV(_value.public_key_type=ECC)
x:
description:
- The C(x) coordinate for the public point on the elliptic curve.
type: int
returned: When C(public_key_type=ECC)
returned: When RV(_value.public_key_type=ECC)
y:
description:
- For C(public_key_type=ECC), this is the C(y) coordinate for the public point on the elliptic curve.
- For C(public_key_type=DSA), this is the publicly known group element whose discrete logarithm w.r.t. C(g) is the private key.
- For RV(_value.public_key_type=ECC), this is the C(y) coordinate for the public point on the elliptic curve.
- For RV(_value.public_key_type=DSA), this is the publicly known group element whose discrete logarithm with
respect to C(g) is the private key.
type: int
returned: When C(public_key_type=DSA) or C(public_key_type=ECC)
returned: When RV(_value.public_key_type=DSA) or RV(_value.public_key_type=ECC)
public_key_fingerprints:
description:
- Fingerprints of CSR's public key.
@@ -241,24 +242,24 @@ _value:
subject_key_identifier:
description:
- The CSR's subject key identifier.
- The identifier is returned in hexadecimal, with C(:) used to separate bytes.
- Is C(none) if the C(SubjectKeyIdentifier) extension is not present.
- The identifier is returned in hexadecimal, with V(:) used to separate bytes.
- Is V(none) if the C(SubjectKeyIdentifier) extension is not present.
returned: success
type: str
sample: '00:11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee:ff:00:11:22:33'
authority_key_identifier:
description:
- The CSR's authority key identifier.
- The identifier is returned in hexadecimal, with C(:) used to separate bytes.
- Is C(none) if the C(AuthorityKeyIdentifier) extension is not present.
- The identifier is returned in hexadecimal, with V(:) used to separate bytes.
- Is V(none) if the C(AuthorityKeyIdentifier) extension is not present.
returned: success
type: str
sample: '00:11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee:ff:00:11:22:33'
authority_cert_issuer:
description:
- The CSR's authority cert issuer as a list of general names.
- Is C(none) if the C(AuthorityKeyIdentifier) extension is not present.
- See I(name_encoding) for how IDNs are handled.
- Is V(none) if the C(AuthorityKeyIdentifier) extension is not present.
- See O(name_encoding) for how IDNs are handled.
returned: success
type: list
elements: str
@@ -266,7 +267,7 @@ _value:
authority_cert_serial_number:
description:
- The CSR's authority cert serial number.
- Is C(none) if the C(AuthorityKeyIdentifier) extension is not present.
- Is V(none) if the C(AuthorityKeyIdentifier) extension is not present.
returned: success
type: int
sample: 12345

33
plugins/filter/openssl_privatekey_info.py
View File

@@ -29,7 +29,7 @@ options:
return_private_key_data:
description:
- Whether to return private key data.
- Only set this to C(true) when you want private information about this key to
- Only set this to V(true) when you want private information about this key to
be extracted.
- "B(WARNING:) you have to make sure that private key data is not accidentally logged!"
type: bool
@@ -74,8 +74,8 @@ _value:
type:
description:
- The key's type.
- One of C(RSA), C(DSA), C(ECC), C(Ed25519), C(X25519), C(Ed448), or C(X448).
- Will start with C(unknown) if the key type cannot be determined.
- One of V(RSA), V(DSA), V(ECC), V(Ed25519), V(X25519), V(Ed448), or V(X448).
- Will start with V(unknown) if the key type cannot be determined.
returned: success
type: str
sample: RSA
@@ -89,61 +89,62 @@ _value:
description:
- Bit size of modulus (RSA) or prime number (DSA).
type: int
returned: When C(type=RSA) or C(type=DSA)
returned: When RV(_value.type=RSA) or RV(_value.type=DSA)
modulus:
description:
- The RSA key's modulus.
type: int
returned: When C(type=RSA)
returned: When RV(_value.type=RSA)
exponent:
description:
- The RSA key's public exponent.
type: int
returned: When C(type=RSA)
returned: When RV(_value.type=RSA)
p:
description:
- The C(p) value for DSA.
- This is the prime modulus upon which arithmetic takes place.
type: int
returned: When C(type=DSA)
returned: When RV(_value.type=DSA)
q:
description:
- The C(q) value for DSA.
- This is a prime that divides C(p - 1), and at the same time the order of the subgroup of the
multiplicative group of the prime field used.
type: int
returned: When C(type=DSA)
returned: When RV(_value.type=DSA)
g:
description:
- The C(g) value for DSA.
- This is the element spanning the subgroup of the multiplicative group of the prime field used.
type: int
returned: When C(type=DSA)
returned: When RV(_value.type=DSA)
curve:
description:
- The curve's name for ECC.
type: str
returned: When C(type=ECC)
returned: When RV(_value.type=ECC)
exponent_size:
description:
- The maximum number of bits of a private key. This is basically the bit size of the subgroup used.
type: int
returned: When C(type=ECC)
returned: When RV(_value.type=ECC)
x:
description:
- The C(x) coordinate for the public point on the elliptic curve.
type: int
returned: When C(type=ECC)
returned: When RV(_value.type=ECC)
y:
description:
- For C(type=ECC), this is the C(y) coordinate for the public point on the elliptic curve.
- For C(type=DSA), this is the publicly known group element whose discrete logarithm w.r.t. C(g) is the private key.
- For RV(_value.type=ECC), this is the C(y) coordinate for the public point on the elliptic curve.
- For RV(_value.type=DSA), this is the publicly known group element whose discrete logarithm with
respect to C(g) is the private key.
type: int
returned: When C(type=DSA) or C(type=ECC)
returned: When RV(_value.type=DSA) or RV(_value.type=ECC)
private_data:
description:
- Private key data. Depends on key type.
returned: success and when I(return_private_key_data) is set to C(true)
returned: success and when O(return_private_key_data) is set to V(true)
type: dict
'''

29
plugins/filter/openssl_publickey_info.py
View File

@@ -55,8 +55,8 @@ _value:
type:
description:
- The key's type.
- One of C(RSA), C(DSA), C(ECC), C(Ed25519), C(X25519), C(Ed448), or C(X448).
- Will start with C(unknown) if the key type cannot be determined.
- One of V(RSA), V(DSA), V(ECC), V(Ed25519), V(X25519), V(Ed448), or V(X448).
- Will start with V(unknown) if the key type cannot be determined.
returned: success
type: str
sample: RSA
@@ -70,57 +70,58 @@ _value:
description:
- Bit size of modulus (RSA) or prime number (DSA).
type: int
returned: When C(type=RSA) or C(type=DSA)
returned: When RV(_value.type=RSA) or RV(_value.type=DSA)
modulus:
description:
- The RSA key's modulus.
type: int
returned: When C(type=RSA)
returned: When RV(_value.type=RSA)
exponent:
description:
- The RSA key's public exponent.
type: int
returned: When C(type=RSA)
returned: When RV(_value.type=RSA)
p:
description:
- The C(p) value for DSA.
- This is the prime modulus upon which arithmetic takes place.
type: int
returned: When C(type=DSA)
returned: When RV(_value.type=DSA)
q:
description:
- The C(q) value for DSA.
- This is a prime that divides C(p - 1), and at the same time the order of the subgroup of the
multiplicative group of the prime field used.
type: int
returned: When C(type=DSA)
returned: When RV(_value.type=DSA)
g:
description:
- The C(g) value for DSA.
- This is the element spanning the subgroup of the multiplicative group of the prime field used.
type: int
returned: When C(type=DSA)
returned: When RV(_value.type=DSA)
curve:
description:
- The curve's name for ECC.
type: str
returned: When C(type=ECC)
returned: When RV(_value.type=ECC)
exponent_size:
description:
- The maximum number of bits of a private key. This is basically the bit size of the subgroup used.
type: int
returned: When C(type=ECC)
returned: When RV(_value.type=ECC)
x:
description:
- The C(x) coordinate for the public point on the elliptic curve.
type: int
returned: When C(type=ECC)
returned: When RV(_value.type=ECC)
y:
description:
- For C(type=ECC), this is the C(y) coordinate for the public point on the elliptic curve.
- For C(type=DSA), this is the publicly known group element whose discrete logarithm w.r.t. C(g) is the private key.
- For RV(_value.type=ECC), this is the C(y) coordinate for the public point on the elliptic curve.
- For RV(_value.type=DSA), this is the publicly known group element whose discrete logarithm with
respect to C(g) is the private key.
type: int
returned: When C(type=DSA) or C(type=ECC)
returned: When RV(_value.type=DSA) or RV(_value.type=ECC)
'''
from ansible.errors import AnsibleFilterError

59
plugins/filter/x509_certificate_info.py
View File

@@ -51,7 +51,7 @@ _value:
returned: success
type: bool
basic_constraints:
description: Entries in the C(basic_constraints) extension, or C(none) if extension is not present.
description: Entries in the C(basic_constraints) extension, or V(none) if extension is not present.
returned: success
type: list
elements: str
@@ -61,7 +61,7 @@ _value:
returned: success
type: bool
extended_key_usage:
description: Entries in the C(extended_key_usage) extension, or C(none) if extension is not present.
description: Entries in the C(extended_key_usage) extension, or V(none) if extension is not present.
returned: success
type: list
elements: str
@@ -92,7 +92,7 @@ _value:
sample: "MAMCAQU="
sample: {"1.3.6.1.5.5.7.1.24": { "critical": false, "value": "MAMCAQU="}}
key_usage:
description: Entries in the C(key_usage) extension, or C(none) if extension is not present.
description: Entries in the C(key_usage) extension, or V(none) if extension is not present.
returned: success
type: str
sample: [Key Agreement, Data Encipherment]
@@ -102,8 +102,8 @@ _value:
type: bool
subject_alt_name:
description:
- Entries in the C(subject_alt_name) extension, or C(none) if extension is not present.
- See I(name_encoding) for how IDNs are handled.
- Entries in the C(subject_alt_name) extension, or V(none) if extension is not present.
- See O(name_encoding) for how IDNs are handled.
returned: success
type: list
elements: str
@@ -113,7 +113,7 @@ _value:
returned: success
type: bool
ocsp_must_staple:
description: C(true) if the OCSP Must Staple extension is present, C(none) otherwise.
description: V(true) if the OCSP Must Staple extension is present, V(none) otherwise.
returned: success
type: bool
ocsp_must_staple_critical:
@@ -164,8 +164,8 @@ _value:
public_key_type:
description:
- The certificate's public key's type.
- One of C(RSA), C(DSA), C(ECC), C(Ed25519), C(X25519), C(Ed448), or C(X448).
- Will start with C(unknown) if the key type cannot be determined.
- One of V(RSA), V(DSA), V(ECC), V(Ed25519), V(X25519), V(Ed448), or V(X448).
- Will start with V(unknown) if the key type cannot be determined.
returned: success
type: str
sample: RSA
@@ -179,57 +179,58 @@ _value:
description:
- Bit size of modulus (RSA) or prime number (DSA).
type: int
returned: When C(public_key_type=RSA) or C(public_key_type=DSA)
returned: When RV(_value.public_key_type=RSA) or RV(_value.public_key_type=DSA)
modulus:
description:
- The RSA key's modulus.
type: int
returned: When C(public_key_type=RSA)
returned: When RV(_value.public_key_type=RSA)
exponent:
description:
- The RSA key's public exponent.
type: int
returned: When C(public_key_type=RSA)
returned: When RV(_value.public_key_type=RSA)
p:
description:
- The C(p) value for DSA.
- This is the prime modulus upon which arithmetic takes place.
type: int
returned: When C(public_key_type=DSA)
returned: When RV(_value.public_key_type=DSA)
q:
description:
- The C(q) value for DSA.
- This is a prime that divides C(p - 1), and at the same time the order of the subgroup of the
multiplicative group of the prime field used.
type: int
returned: When C(public_key_type=DSA)
returned: When RV(_value.public_key_type=DSA)
g:
description:
- The C(g) value for DSA.
- This is the element spanning the subgroup of the multiplicative group of the prime field used.
type: int
returned: When C(public_key_type=DSA)
returned: When RV(_value.public_key_type=DSA)
curve:
description:
- The curve's name for ECC.
type: str
returned: When C(public_key_type=ECC)
returned: When RV(_value.public_key_type=ECC)
exponent_size:
description:
- The maximum number of bits of a private key. This is basically the bit size of the subgroup used.
type: int
returned: When C(public_key_type=ECC)
returned: When RV(_value.public_key_type=ECC)
x:
description:
- The C(x) coordinate for the public point on the elliptic curve.
type: int
returned: When C(public_key_type=ECC)
returned: When RV(_value.public_key_type=ECC)
y:
description:
- For C(public_key_type=ECC), this is the C(y) coordinate for the public point on the elliptic curve.
- For C(public_key_type=DSA), this is the publicly known group element whose discrete logarithm w.r.t. C(g) is the private key.
- For RV(_value.public_key_type=ECC), this is the C(y) coordinate for the public point on the elliptic curve.
- For RV(_value.public_key_type=DSA), this is the publicly known group element whose discrete logarithm with
respect to C(g) is the private key.
type: int
returned: When C(public_key_type=DSA) or C(public_key_type=ECC)
returned: When RV(_value.public_key_type=DSA) or RV(_value.public_key_type=ECC)
public_key_fingerprints:
description:
- Fingerprints of certificate's public key.
@@ -264,24 +265,24 @@ _value:
subject_key_identifier:
description:
- The certificate's subject key identifier.
- The identifier is returned in hexadecimal, with C(:) used to separate bytes.
- Is C(none) if the C(SubjectKeyIdentifier) extension is not present.
- The identifier is returned in hexadecimal, with V(:) used to separate bytes.
- Is V(none) if the C(SubjectKeyIdentifier) extension is not present.
returned: success
type: str
sample: '00:11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee:ff:00:11:22:33'
authority_key_identifier:
description:
- The certificate's authority key identifier.
- The identifier is returned in hexadecimal, with C(:) used to separate bytes.
- Is C(none) if the C(AuthorityKeyIdentifier) extension is not present.
- The identifier is returned in hexadecimal, with V(:) used to separate bytes.
- Is V(none) if the C(AuthorityKeyIdentifier) extension is not present.
returned: success
type: str
sample: '00:11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee:ff:00:11:22:33'
authority_cert_issuer:
description:
- The certificate's authority cert issuer as a list of general names.
- Is C(none) if the C(AuthorityKeyIdentifier) extension is not present.
- See I(name_encoding) for how IDNs are handled.
- Is V(none) if the C(AuthorityKeyIdentifier) extension is not present.
- See O(name_encoding) for how IDNs are handled.
returned: success
type: list
elements: str
@@ -289,18 +290,18 @@ _value:
authority_cert_serial_number:
description:
- The certificate's authority cert serial number.
- Is C(none) if the C(AuthorityKeyIdentifier) extension is not present.
- Is V(none) if the C(AuthorityKeyIdentifier) extension is not present.
returned: success
type: int
sample: 12345
ocsp_uri:
description: The OCSP responder URI, if included in the certificate. Will be
C(none) if no OCSP responder URI is included.
V(none) if no OCSP responder URI is included.
returned: success
type: str
issuer_uri:
description: The Issuer URI, if included in the certificate. Will be
C(none) if no issuer URI is included.
V(none) if no issuer URI is included.
returned: success
type: str
'''

27
plugins/filter/x509_crl_info.py
View File

@@ -24,7 +24,7 @@ options:
required: true
list_revoked_certificates:
description:
- If set to C(false), the list of revoked certificates is not included in the result.
- If set to V(false), the list of revoked certificates is not included in the result.
- This is useful when retrieving information on large CRL files. Enumerating all revoked
certificates can take some time, including serializing the result as JSON, sending it to
the Ansible controller, and decoding it again.
@@ -57,15 +57,18 @@ _value:
contains:
format:
description:
- Whether the CRL is in PEM format (C(pem)) or in DER format (C(der)).
- Whether the CRL is in PEM format (V(pem)) or in DER format (V(der)).
returned: success
type: str
sample: pem
choices:
- pem
- der
issuer:
description:
- The CRL's issuer.
- Note that for repeated values, only the last one will be returned.
- See I(name_encoding) for how IDNs are handled.
- See O(name_encoding) for how IDNs are handled.
returned: success
type: dict
sample: {"organizationName": "Ansible", "commonName": "ca.example.com"}
@@ -92,7 +95,7 @@ _value:
sample: sha256WithRSAEncryption
revoked_certificates:
description: List of certificates to be revoked.
returned: success if I(list_revoked_certificates=true)
returned: success if O(list_revoked_certificates=true)
type: list
elements: dict
contains:
@@ -107,7 +110,7 @@ _value:
issuer:
description:
- The certificate's issuer.
- See I(name_encoding) for how IDNs are handled.
- See O(name_encoding) for how IDNs are handled.
type: list
elements: str
sample: ["DNS:ca.example.org"]
@@ -118,11 +121,19 @@ _value:
reason:
description:
- The value for the revocation reason extension.
- One of C(unspecified), C(key_compromise), C(ca_compromise), C(affiliation_changed), C(superseded),
C(cessation_of_operation), C(certificate_hold), C(privilege_withdrawn), C(aa_compromise), and
C(remove_from_crl).
type: str
sample: key_compromise
choices:
- unspecified
- key_compromise
- ca_compromise
- affiliation_changed
- superseded
- cessation_of_operation
- certificate_hold
- privilege_withdrawn
- aa_compromise
- remove_from_crl
reason_critical:
description: Whether the revocation reason extension is critical.
type: bool

30
plugins/modules/acme_account.py
View File

@@ -22,7 +22,7 @@ description:
notes:
- "The M(community.crypto.acme_certificate) module also allows to do basic account management.
When using both modules, it is recommended to disable account management
for M(community.crypto.acme_certificate). For that, use the C(modify_account) option of
for M(community.crypto.acme_certificate). For that, use the O(community.crypto.acme_certificate#module:modify_account) option of
M(community.crypto.acme_certificate)."
seealso:
- name: Automatic Certificate Management Environment (ACME)
@@ -49,9 +49,9 @@ options:
state:
description:
- "The state of the account, to be identified by its account key."
- "If the state is C(absent), the account will either not exist or be
- "If the state is V(absent), the account will either not exist or be
deactivated."
- "If the state is C(changed_key), the account must exist. The account
- "If the state is V(changed_key), the account must exist. The account
key will be changed; no other information will be touched."
type: str
required: true
@@ -61,7 +61,7 @@ options:
- changed_key
allow_creation:
description:
- "Whether account creation is allowed (when state is C(present))."
- "Whether account creation is allowed (when state is V(present))."
type: bool
default: true
contact:
@@ -70,30 +70,30 @@ options:
- "Email addresses must be prefixed with C(mailto:)."
- "See U(https://tools.ietf.org/html/rfc8555#section-7.3)
for what is allowed."
- "Must be specified when state is C(present). Will be ignored
if state is C(absent) or C(changed_key)."
- "Must be specified when state is V(present). Will be ignored
if state is V(absent) or V(changed_key)."
type: list
elements: str
default: []
terms_agreed:
description:
- "Boolean indicating whether you agree to the terms of service document."
- "ACME servers can require this to be true."
- "ACME servers can require this to be V(true)."
type: bool
default: false
new_account_key_src:
description:
- "Path to a file containing the ACME account RSA or Elliptic Curve key to change to."
- "Same restrictions apply as to C(account_key_src)."
- "Mutually exclusive with C(new_account_key_content)."
- "Required if C(new_account_key_content) is not used and state is C(changed_key)."
- "Same restrictions apply as to O(account_key_src)."
- "Mutually exclusive with O(new_account_key_content)."
- "Required if O(new_account_key_content) is not used and O(state) is V(changed_key)."
type: path
new_account_key_content:
description:
- "Content of the ACME account RSA or Elliptic Curve key to change to."
- "Same restrictions apply as to C(account_key_content)."
- "Mutually exclusive with C(new_account_key_src)."
- "Required if C(new_account_key_src) is not used and state is C(changed_key)."
- "Same restrictions apply as to O(account_key_content)."
- "Mutually exclusive with O(new_account_key_src)."
- "Required if O(new_account_key_src) is not used and O(state) is V(changed_key)."
type: str
new_account_key_passphrase:
description:
@@ -117,14 +117,14 @@ options:
alg:
description:
- The MAC algorithm provided by the CA.
- If not specified by the CA, this is probably C(HS256).
- If not specified by the CA, this is probably V(HS256).
type: str
required: true
choices: [ HS256, HS384, HS512 ]
key:
description:
- Base64 URL encoded value of the MAC key provided by the CA.
- Padding (C(=) symbols at the end) can be omitted.
- Padding (V(=) symbols at the end) can be omitted.
type: str
required: true
version_added: 1.1.0

31
plugins/modules/acme_account_info.py
View File

@@ -34,11 +34,11 @@ options:
description:
- "Whether to retrieve the list of order URLs or order objects, if provided
by the ACME server."
- "A value of C(ignore) will not fetch the list of orders."
- "If the value is not C(ignore) and the ACME server supports orders, the C(order_uris)
return value is always populated. The C(orders) return value is only returned
if this option is set to C(object_list)."
- "Currently, Let's Encrypt does not return orders, so the C(orders) result
- "A value of V(ignore) will not fetch the list of orders."
- "If the value is not V(ignore) and the ACME server supports orders, the RV(order_uris)
return value is always populated. The RV(orders) return value is only returned
if this option is set to V(object_list)."
- "Currently, Let's Encrypt does not return orders, so the RV(orders) result
will always be empty."
type: str
choices:
@@ -113,7 +113,7 @@ account:
orders:
description:
- A URL where a list of orders can be retrieved for this account.
- Use the I(retrieve_orders) option to query this URL and retrieve the
- Use the O(retrieve_orders) option to query this URL and retrieve the
complete list of orders.
returned: always
type: str
@@ -129,7 +129,7 @@ orders:
- "The list of orders."
type: list
elements: dict
returned: if account exists, I(retrieve_orders) is C(object_list), and server supports order listing
returned: if account exists, O(retrieve_orders) is V(object_list), and server supports order listing
contains:
status:
description: The order's status.
@@ -144,7 +144,7 @@ orders:
description:
- When the order expires.
- Timestamp should be formatted as described in RFC3339.
- Only required to be included in result when I(status) is C(pending) or C(valid).
- Only required to be included in result when RV(orders[].status) is V(pending) or V(valid).
type: str
returned: when server gives expiry date
identifiers:
@@ -154,14 +154,17 @@ orders:
elements: dict
contains:
type:
description: Type of identifier. C(dns) or C(ip).
description: Type of identifier.
type: str
choices:
- dns
- ip
value:
description: Name of identifier. Hostname or IP address.
type: str
wildcard:
description: "Whether I(value) is actually a wildcard. The wildcard
prefix C(*.) is not included in I(value) if this is C(true)."
description: "Whether RV(orders[].identifiers[].value) is actually a wildcard. The wildcard
prefix C(*.) is not included in RV(orders[].identifiers[].value) if this is V(true)."
type: bool
returned: required to be included if the identifier is wildcarded
notBefore:
@@ -202,11 +205,11 @@ orders:
order_uris:
description:
- "The list of orders."
- "If I(retrieve_orders) is C(url_list), this will be a list of URLs."
- "If I(retrieve_orders) is C(object_list), this will be a list of objects."
- "If O(retrieve_orders) is V(url_list), this will be a list of URLs."
- "If O(retrieve_orders) is V(object_list), this will be a list of objects."
type: list
elements: str
returned: if account exists, I(retrieve_orders) is not C(ignore), and server supports order listing
returned: if account exists, O(retrieve_orders) is not V(ignore), and server supports order listing
version_added: 1.5.0
'''

100
plugins/modules/acme_certificate.py
View File

@@ -19,15 +19,15 @@ description:
L(ACME protocol,https://tools.ietf.org/html/rfc8555),
such as L(Let's Encrypt,https://letsencrypt.org/) or
L(Buypass,https://www.buypass.com/). The current implementation
supports the C(http-01), C(dns-01) and C(tls-alpn-01) challenges."
supports the V(http-01), V(dns-01) and V(tls-alpn-01) challenges."
- "To use this module, it has to be executed twice. Either as two
different tasks in the same run or during two runs. Note that the output
of the first run needs to be recorded and passed to the second run as the
module argument C(data)."
module argument O(data)."
- "Between these two tasks you have to fulfill the required steps for the
chosen challenge by whatever means necessary. For C(http-01) that means
chosen challenge by whatever means necessary. For V(http-01) that means
creating the necessary challenge file on the destination webserver. For
C(dns-01) the necessary dns record has to be created. For C(tls-alpn-01)
V(dns-01) the necessary dns record has to be created. For V(tls-alpn-01)
the necessary certificate has to be created and served.
It is I(not) the responsibility of this module to perform these steps."
- "For details on how to fulfill these challenges, you might have to read through
@@ -37,11 +37,11 @@ description:
- "The module includes experimental support for IP identifiers according to
the L(RFC 8738,https://www.rfc-editor.org/rfc/rfc8738.html)."
notes:
- "At least one of C(dest) and C(fullchain_dest) must be specified."
- "At least one of O(dest) and O(fullchain_dest) must be specified."
- "This module includes basic account management functionality.
If you want to have more control over your ACME account, use the
M(community.crypto.acme_account) module and disable account management
for this module using the C(modify_account) option."
for this module using the O(modify_account) option."
- "This module was called C(letsencrypt) before Ansible 2.6. The usage
did not change."
seealso:
@@ -57,10 +57,10 @@ seealso:
description: The specification of the ACME protocol (RFC 8555).
link: https://tools.ietf.org/html/rfc8555
- name: ACME TLS ALPN Challenge Extension
description: The specification of the C(tls-alpn-01) challenge (RFC 8737).
description: The specification of the V(tls-alpn-01) challenge (RFC 8737).
link: https://www.rfc-editor.org/rfc/rfc8737.html-05
- module: community.crypto.acme_challenge_cert_helper
description: Helps preparing C(tls-alpn-01) challenges.
description: Helps preparing V(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
@@ -94,7 +94,7 @@ options:
description:
- "The email address associated with this account."
- "It will be used for certificate expiration warnings."
- "Note that when C(modify_account) is not set to C(false) and you also
- "Note that when O(modify_account) is not set to V(false) and you also
used the M(community.crypto.acme_account) module to specify more than one contact
for your account, this module will update your account and restrict
it to the (at most one) contact email address specified here."
@@ -102,31 +102,31 @@ options:
agreement:
description:
- "URI to a terms of service document you agree to when using the
ACME v1 service at C(acme_directory)."
- Default is latest gathered from C(acme_directory) URL.
- This option will only be used when C(acme_version) is 1.
ACME v1 service at O(acme_directory)."
- Default is latest gathered from O(acme_directory) URL.
- This option will only be used when O(acme_version) is 1.
type: str
terms_agreed:
description:
- "Boolean indicating whether you agree to the terms of service document."
- "ACME servers can require this to be true."
- This option will only be used when C(acme_version) is not 1.
- This option will only be used when O(acme_version) is not 1.
type: bool
default: false
modify_account:
description:
- "Boolean indicating whether the module should create the account if
necessary, and update its contact data."
- "Set to C(false) if you want to use the M(community.crypto.acme_account) module to manage
- "Set to V(false) if you want to use the M(community.crypto.acme_account) module to manage
your account instead, and to avoid accidental creation of a new account
using an old key if you changed the account key with M(community.crypto.acme_account)."
- "If set to C(false), C(terms_agreed) and C(account_email) are ignored."
- "If set to V(false), O(terms_agreed) and O(account_email) are ignored."
type: bool
default: true
challenge:
description:
- The challenge to be performed.
- If set to C(no challenge), no challenge will be used. This is necessary for some private
- If set to V(no challenge), no challenge will be used. This is necessary for some private
CAs which use External Account Binding and other means of validating certificate assurance.
For example, an account could be allowed to issue certificates for C(foo.example.com)
without any further validation for a certain period of time.
@@ -148,7 +148,7 @@ options:
account key. This is a bad idea from a security point of view, and
the CA should not accept the CSR. The ACME server should return an
error in this case."
- Precisely one of I(csr) or I(csr_content) must be specified.
- Precisely one of O(csr) or O(csr_content) must be specified.
type: path
aliases: ['src']
csr_content:
@@ -162,7 +162,7 @@ options:
account key. This is a bad idea from a security point of view, and
the CA should not accept the CSR. The ACME server should return an
error in this case."
- Precisely one of I(csr) or I(csr_content) must be specified.
- Precisely one of O(csr) or O(csr_content) must be specified.
type: str
version_added: 1.2.0
data:
@@ -171,27 +171,27 @@ options:
the second run of the module only."
- "The value that must be used here will be provided by a previous use
of this module. See the examples for more details."
- "Note that for ACME v2, only the C(order_uri) entry of C(data) will
be used. For ACME v1, C(data) must be non-empty to indicate the
- "Note that for ACME v2, only the C(order_uri) entry of O(data) will
be used. For ACME v1, O(data) must be non-empty to indicate the
second stage is active; all needed data will be taken from the
CSR."
- "I(Note): the C(data) option was marked as C(no_log) up to
- "I(Note): the O(data) option was marked as C(no_log) up to
Ansible 2.5. From Ansible 2.6 on, it is no longer marked this way
as it causes error messages to be come unusable, and C(data) does
as it causes error messages to be come unusable, and O(data) does
not contain any information which can be used without having
access to the account key or which are not public anyway."
type: dict
dest:
description:
- "The destination file for the certificate."
- "Required if C(fullchain_dest) is not specified."
- "Required if O(fullchain_dest) is not specified."
type: path
aliases: ['cert']
fullchain_dest:
description:
- "The destination file for the full chain (that is, a certificate followed
by chain of intermediate certificates)."
- "Required if C(dest) is not specified."
- "Required if O(dest) is not specified."
type: path
aliases: ['fullchain']
chain_dest:
@@ -202,11 +202,11 @@ options:
remaining_days:
description:
- "The number of days the certificate must have left being valid.
If C(cert_days < remaining_days), then it will be renewed.
If RV(cert_days) < O(remaining_days), then it will be renewed.
If the certificate is not renewed, module return values will not
include C(challenge_data)."
include RV(challenge_data)."
- "To make sure that the certificate is renewed in any case, you can
use the C(force) option."
use the O(force) option."
type: int
default: 10
deactivate_authzs:
@@ -222,16 +222,16 @@ options:
force:
description:
- Enforces the execution of the challenge and validation, even if an
existing certificate is still valid for more than C(remaining_days).
existing certificate is still valid for more than O(remaining_days).
- This is especially helpful when having an updated CSR, for example with
additional domains for which a new certificate is desired.
type: bool
default: false
retrieve_all_alternates:
description:
- "When set to C(true), will retrieve all alternate trust chains offered by the ACME CA.
- "When set to V(true), will retrieve all alternate trust chains offered by the ACME CA.
These will not be written to disk, but will be returned together with the main
chain as C(all_chains). See the documentation for the C(all_chains) return
chain as RV(all_chains). See the documentation for the RV(all_chains) return
value for details."
type: bool
default: false
@@ -244,8 +244,8 @@ options:
- "If a criterium matches multiple chains, the first one matching will be
returned. The order is determined by the ordering of the C(Link) headers
returned by the ACME server and might not be deterministic."
- "Every criterium can consist of multiple different conditions, like I(issuer)
and I(subject). For the criterium to match a chain, all conditions must apply
- "Every criterium can consist of multiple different conditions, like O(select_chain[].issuer)
and O(select_chain[].subject). For the criterium to match a chain, all conditions must apply
to the same certificate in the chain."
- "This option can only be used with the C(cryptography) backend."
type: list
@@ -255,11 +255,11 @@ options:
test_certificates:
description:
- "Determines which certificates in the chain will be tested."
- "I(all) tests all certificates in the chain (excluding the leaf, which is
- "V(all) tests all certificates in the chain (excluding the leaf, which is
identical in all chains)."
- "I(first) only tests the first certificate in the chain, that is the one which
- "V(first) only tests the first certificate in the chain, that is the one which
signed the leaf."
- "I(last) only tests the last certificate in the chain, that is the one furthest
- "V(last) only tests the last certificate in the chain, that is the one furthest
away from the leaf. Its issuer is the root certificate of this chain."
type: str
default: all
@@ -268,29 +268,29 @@ options:
description:
- "Allows to specify parts of the issuer of a certificate in the chain must
have to be selected."
- "If I(issuer) is empty, any certificate will match."
- 'An example value would be C({"commonName": "My Preferred CA Root"}).'
- "If O(select_chain[].issuer) is empty, any certificate will match."
- 'An example value would be V({"commonName": "My Preferred CA Root"}).'
type: dict
subject:
description:
- "Allows to specify parts of the subject of a certificate in the chain must
have to be selected."
- "If I(subject) is empty, any certificate will match."
- 'An example value would be C({"CN": "My Preferred CA Intermediate"})'
- "If O(select_chain[].subject) is empty, any certificate will match."
- 'An example value would be V({"CN": "My Preferred CA Intermediate"})'
type: dict
subject_key_identifier:
description:
- "Checks for the SubjectKeyIdentifier extension. This is an identifier based
on the private key of the intermediate certificate."
- "The identifier must be of the form
C(A8:4A:6A:63:04:7D:DD:BA:E6:D1:39:B7:A6:45:65:EF:F3:A8:EC:A1)."
V(A8:4A:6A:63:04:7D:DD:BA:E6:D1:39:B7:A6:45:65:EF:F3:A8:EC:A1)."
type: str
authority_key_identifier:
description:
- "Checks for the AuthorityKeyIdentifier extension. This is an identifier based
on the private key of the issuer of the intermediate certificate."
- "The identifier must be of the form
C(C4:A7:B1:A4:7B:2C:71:FA:DB:E1:4B:90:75:FF:C4:15:60:85:89:10)."
V(C4:A7:B1:A4:7B:2C:71:FA:DB:E1:4B:90:75:FF:C4:15:60:85:89:10)."
type: str
'''
@@ -455,32 +455,32 @@ challenge_data:
sample: .well-known/acme-challenge/evaGxfADs6pSRb2LAv9IZf17Dt3juxGJ-PCt92wr-oA
resource_original:
description:
- The original challenge resource including type identifier for C(tls-alpn-01)
- The original challenge resource including type identifier for V(tls-alpn-01)
challenges.
returned: changed and challenge is C(tls-alpn-01)
returned: changed and O(challenge) is V(tls-alpn-01)
type: str
sample: DNS:example.com
resource_value:
description:
- The value the resource has to produce for the validation.
- For C(http-01) and C(dns-01) challenges, the value can be used as-is.
- "For C(tls-alpn-01) challenges, note that this return value contains a
- For V(http-01) and V(dns-01) challenges, the value can be used as-is.
- "For V(tls-alpn-01) challenges, note that this return value contains a
Base64 encoded version of the correct binary blob which has to be put
into the acmeValidation x509 extension; see
U(https://www.rfc-editor.org/rfc/rfc8737.html#section-3)
for details. To do this, you might need the C(b64decode) Jinja filter
for details. To do this, you might need the P(ansible.builtin.b64decode#filter) Jinja filter
to extract the binary blob from this return value."
returned: changed
type: str
sample: IlirfxKKXA...17Dt3juxGJ-PCt92wr-oA
record:
description: The full DNS record's name for the challenge.
returned: changed and challenge is C(dns-01)
returned: changed and challenge is V(dns-01)
type: str
sample: _acme-challenge.example.com
challenge_data_dns:
description:
- List of TXT values per DNS record, in case challenge is C(dns-01).
- List of TXT values per DNS record, in case challenge is V(dns-01).
- Since Ansible 2.8.5, only challenges which are not yet valid are returned.
returned: changed
type: dict
@@ -518,11 +518,11 @@ account_uri:
type: str
all_chains:
description:
- When I(retrieve_all_alternates) is set to C(true), the module will query the ACME server
- When O(retrieve_all_alternates) is set to V(true), the module will query the ACME server
for alternate chains. This return value will contain a list of all chains returned,
the first entry being the main chain returned by the server.
- See L(Section 7.4.2 of RFC8555,https://tools.ietf.org/html/rfc8555#section-7.4.2) for details.
returned: when certificate was retrieved and I(retrieve_all_alternates) is set to C(true)
returned: when certificate was retrieved and O(retrieve_all_alternates) is set to V(true)
type: list
elements: dict
contains:

30
plugins/modules/acme_certificate_revoke.py
View File

@@ -19,8 +19,8 @@ description:
L(ACME protocol,https://tools.ietf.org/html/rfc8555),
such as L(Let's Encrypt,https://letsencrypt.org/)."
notes:
- "Exactly one of C(account_key_src), C(account_key_content),
C(private_key_src) or C(private_key_content) must be specified."
- "Exactly one of O(account_key_src), O(account_key_content),
O(private_key_src), or O(private_key_content) must be specified."
- "Trying to revoke an already revoked certificate
should result in an unchanged status, even if the revocation reason
was different than the one specified here. Also, depending on the
@@ -58,13 +58,13 @@ options:
- "RSA keys can be created with C(openssl rsa ...). 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."
- "Mutually exclusive with O(account_key_content)."
- "Required if O(account_key_content) is not used."
account_key_content:
description:
- "Content of the ACME account RSA or Elliptic Curve key."
- "Note that exactly one of C(account_key_src), C(account_key_content),
C(private_key_src) or C(private_key_content) must be specified."
- "Note that exactly one of O(account_key_src), O(account_key_content),
O(private_key_src), or O(private_key_content) must be specified."
- "I(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,
@@ -77,14 +77,14 @@ options:
private_key_src:
description:
- "Path to the certificate's private key."
- "Note that exactly one of C(account_key_src), C(account_key_content),
C(private_key_src) or C(private_key_content) must be specified."
- "Note that exactly one of O(account_key_src), O(account_key_content),
O(private_key_src), or O(private_key_content) must be specified."
type: path
private_key_content:
description:
- "Content of the certificate's private key."
- "Note that exactly one of C(account_key_src), C(account_key_content),
C(private_key_src) or C(private_key_content) must be specified."
- "Note that exactly one of O(account_key_src), O(account_key_content),
O(private_key_src), or O(private_key_content) must be specified."
- "I(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,
@@ -105,11 +105,11 @@ options:
description:
- "One of the revocation reasonCodes defined in
L(Section 5.3.1 of RFC5280,https://tools.ietf.org/html/rfc5280#section-5.3.1)."
- "Possible values are C(0) (unspecified), C(1) (keyCompromise),
C(2) (cACompromise), C(3) (affiliationChanged), C(4) (superseded),
C(5) (cessationOfOperation), C(6) (certificateHold),
C(8) (removeFromCRL), C(9) (privilegeWithdrawn),
C(10) (aACompromise)."
- "Possible values are V(0) (unspecified), V(1) (keyCompromise),
V(2) (cACompromise), V(3) (affiliationChanged), V(4) (superseded),
V(5) (cessationOfOperation), V(6) (certificateHold),
V(8) (removeFromCRL), V(9) (privilegeWithdrawn),
V(10) (aACompromise)."
type: int
'''

16
plugins/modules/acme_challenge_cert_helper.py
View File

@@ -49,7 +49,7 @@ options:
- tls-alpn-01
challenge_data:
description:
- "The C(challenge_data) entry provided by M(community.crypto.acme_certificate) for the
- "The RV(community.crypto.acme_certificate#module:challenge_data) entry provided by M(community.crypto.acme_certificate) for the
challenge."
type: dict
required: true
@@ -57,12 +57,12 @@ options:
description:
- "Path to a file containing the private key file to use for this challenge
certificate."
- "Mutually exclusive with C(private_key_content)."
- "Mutually exclusive with O(private_key_content)."
type: path
private_key_content:
description:
- "Content of the private key to use for this challenge certificate."
- "Mutually exclusive with C(private_key_src)."
- "Mutually exclusive with O(private_key_src)."
type: str
private_key_passphrase:
description:
@@ -122,14 +122,16 @@ domain:
type: str
identifier_type:
description:
- "The identifier type for the actual resource identifier. Will be C(dns)
or C(ip)."
- "The identifier type for the actual resource identifier."
returned: always
type: str
choices:
- dns
- ip
identifier:
description:
- "The identifier for the actual resource. Will be a domain name if the
type is C(dns), or an IP address if the type is C(ip)."
- "The identifier for the actual resource. Will be a domain name if
RV(identifier_type=dns), or an IP address if RV(identifier_type=ip)."
returned: always
type: str
challenge_certificate:

20
plugins/modules/acme_inspect.py
View File

@@ -24,7 +24,7 @@ description:
- "The module can also be used to directly access features of an ACME servers
which are not yet supported by the Ansible ACME modules."
notes:
- "The I(account_uri) option must be specified for properly authenticated
- "The O(account_uri) option must be specified for properly authenticated
ACME v2 requests (except a C(new-account) request)."
- "Using the C(ansible) tool, M(community.crypto.acme_inspect) can be used to directly execute
ACME requests without the need of writing a playbook. For example, the
@@ -54,16 +54,16 @@ options:
url:
description:
- "The URL to send the request to."
- "Must be specified if I(method) is not C(directory-only)."
- "Must be specified if O(method) is not V(directory-only)."
type: str
method:
description:
- "The method to use to access the given URL on the ACME server."
- "The value C(post) executes an authenticated POST request. The content
must be specified in the I(content) option."
- "The value C(get) executes an authenticated POST-as-GET request for ACME v2,
- "The value V(post) executes an authenticated POST request. The content
must be specified in the O(content) option."
- "The value V(get) executes an authenticated POST-as-GET request for ACME v2,
and a regular GET request for ACME v1."
- "The value C(directory-only) only retrieves the directory, without doing
- "The value V(directory-only) only retrieves the directory, without doing
a request."
type: str
default: get
@@ -73,13 +73,13 @@ options:
- directory-only
content:
description:
- "An encoded JSON object which will be sent as the content if I(method)
is C(post)."
- "Required when I(method) is C(post), and not allowed otherwise."
- "An encoded JSON object which will be sent as the content if O(method)
is V(post)."
- "Required when O(method) is V(post), and not allowed otherwise."
type: str
fail_on_acme_error:
description:
- "If I(method) is C(post) or C(get), make the module fail in case an ACME
- "If O(method) is V(post) or V(get), make the module fail in case an ACME
error is returned."
type: bool
default: true

6
plugins/modules/crypto_info.py
View File

@@ -45,12 +45,12 @@ python_cryptography_installed:
python_cryptography_import_error:
description: Import error when trying to import the L(Python cryptography library, https://cryptography.io/).
returned: when I(python_cryptography_installed=false)
returned: when RV(python_cryptography_installed=false)
type: str
python_cryptography_capabilities:
description: Information on the installed L(Python cryptography library, https://cryptography.io/).
returned: when I(python_cryptography_installed=true)
returned: when RV(python_cryptography_installed=true)
type: dict
contains:
version:
@@ -136,7 +136,7 @@ openssl_present:
openssl:
description: Information on the installed OpenSSL binary.
returned: when I(openssl_present=true)
returned: when RV(openssl_present=true)
type: dict
contains:
path:

154
plugins/modules/ecs_certificate.py
View File

@@ -21,7 +21,7 @@ description:
- In order to request a certificate, the domain and organization used in the certificate signing request must be already
validated in the ECS system. It is I(not) the responsibility of this module to perform those steps.
notes:
- C(path) must be specified as the output location of the certificate.
- O(path) must be specified as the output location of the certificate.
requirements:
- cryptography >= 1.6
extends_documentation_fragment:
@@ -32,7 +32,7 @@ attributes:
check_mode:
support: partial
details:
- Check mode is only supported if I(request_type=new).
- Check mode is only supported if O(request_type=new).
diff_mode:
support: none
safe_file_operations:
@@ -40,14 +40,14 @@ attributes:
options:
backup:
description:
- Whether a backup should be made for the certificate in I(path).
- Whether a backup should be made for the certificate in O(path).
type: bool
default: false
force:
description:
- If force is used, a certificate is requested regardless of whether I(path) points to an existing valid certificate.
- If C(request_type=renew), a forced renew will fail if the certificate being renewed has been issued within the past 30 days, regardless of the
value of I(remaining_days) or the return value of I(cert_days) - the ECS API does not support the "renew" operation for certificates that are not
- If force is used, a certificate is requested regardless of whether O(path) points to an existing valid certificate.
- If O(request_type=renew), a forced renew will fail if the certificate being renewed has been issued within the past 30 days, regardless of the
value of O(remaining_days) or the return value of RV(cert_days) - the ECS API does not support the "renew" operation for certificates that are not
at least 30 days old.
type: bool
default: false
@@ -56,9 +56,9 @@ options:
- The destination path for the generated certificate as a PEM encoded cert.
- If the certificate at this location is not an Entrust issued certificate, a new certificate will always be requested even if the current
certificate is technically valid.
- If there is already an Entrust certificate at this location, whether it is replaced is depends on the I(remaining_days) calculation.
- If an existing certificate is being replaced (see I(remaining_days), I(force), and I(tracking_id)), whether a new certificate is requested
or the existing certificate is renewed or reissued is based on I(request_type).
- If there is already an Entrust certificate at this location, whether it is replaced is depends on the O(remaining_days) calculation.
- If an existing certificate is being replaced (see O(remaining_days), O(force), and O(tracking_id)), whether a new certificate is requested
or the existing certificate is renewed or reissued is based on O(request_type).
type: path
required: true
full_chain_path:
@@ -67,54 +67,54 @@ options:
type: path
csr:
description:
- Base-64 encoded Certificate Signing Request (CSR). I(csr) is accepted with or without PEM formatting around the Base-64 string.
- If no I(csr) is provided when C(request_type=reissue) or C(request_type=renew), the certificate will be generated with the same public key as
- Base-64 encoded Certificate Signing Request (CSR). O(csr) is accepted with or without PEM formatting around the Base-64 string.
- If no O(csr) is provided when O(request_type=reissue) or O(request_type=renew), the certificate will be generated with the same public key as
the certificate being renewed or reissued.
- If I(subject_alt_name) is specified, it will override the subject alternate names in the CSR.
- If I(eku) is specified, it will override the extended key usage in the CSR.
- If I(ou) is specified, it will override the organizational units "ou=" present in the subject distinguished name of the CSR, if any.
- The organization "O=" field from the CSR will not be used. It will be replaced in the issued certificate by I(org) if present, and if not present,
the organization tied to I(client_id).
- If O(subject_alt_name) is specified, it will override the subject alternate names in the CSR.
- If O(eku) is specified, it will override the extended key usage in the CSR.
- If O(ou) is specified, it will override the organizational units "ou=" present in the subject distinguished name of the CSR, if any.
- The organization "O=" field from the CSR will not be used. It will be replaced in the issued certificate by O(org) if present, and if not present,
the organization tied to O(client_id).
type: str
tracking_id:
description:
- The tracking ID of the certificate to reissue or renew.
- I(tracking_id) is invalid if C(request_type=new) or C(request_type=validate_only).
- If there is a certificate present in I(path) and it is an ECS certificate, I(tracking_id) will be ignored.
- If there is no certificate present in I(path) or there is but it is from another provider, the certificate represented by I(tracking_id) will
be renewed or reissued and saved to I(path).
- If there is no certificate present in I(path) and the I(force) and I(remaining_days) parameters do not indicate a new certificate is needed,
the certificate referenced by I(tracking_id) certificate will be saved to I(path).
- O(tracking_id) is invalid if O(request_type=new) or O(request_type=validate_only).
- If there is a certificate present in O(path) and it is an ECS certificate, O(tracking_id) will be ignored.
- If there is no certificate present in O(path) or there is but it is from another provider, the certificate represented by O(tracking_id) will
be renewed or reissued and saved to O(path).
- If there is no certificate present in O(path) and the O(force) and O(remaining_days) parameters do not indicate a new certificate is needed,
the certificate referenced by O(tracking_id) certificate will be saved to O(path).
- This can be used when a known certificate is not currently present on a server, but you want to renew or reissue it to be managed by an ansible
playbook. For example, if you specify C(request_type=renew), I(tracking_id) of an issued certificate, and I(path) to a file that does not exist,
the first run of a task will download the certificate specified by I(tracking_id) (assuming it is still valid). Future runs of the task will
(if applicable - see I(force) and I(remaining_days)) renew the certificate now present in I(path).
playbook. For example, if you specify O(request_type=renew), O(tracking_id) of an issued certificate, and O(path) to a file that does not exist,
the first run of a task will download the certificate specified by O(tracking_id) (assuming it is still valid). Future runs of the task will
(if applicable - see O(force) and O(remaining_days)) renew the certificate now present in O(path).
type: int
remaining_days:
description:
- The number of days the certificate must have left being valid. If C(cert_days < remaining_days) then a new certificate will be
obtained using I(request_type).
- If C(request_type=renew), a renewal will fail if the certificate being renewed has been issued within the past 30 days, so do not set a
I(remaining_days) value that is within 30 days of the full lifetime of the certificate being acted upon.
- For exmaple, if you are requesting Certificates with a 90 day lifetime, do not set I(remaining_days) to a value C(60) or higher).
- The I(force) option may be used to ensure that a new certificate is always obtained.
- The number of days the certificate must have left being valid. If RV(cert_days) < O(remaining_days) then a new certificate will be
obtained using O(request_type).
- If O(request_type=renew), a renewal will fail if the certificate being renewed has been issued within the past 30 days, so do not set a
O(remaining_days) value that is within 30 days of the full lifetime of the certificate being acted upon.
- For exmaple, if you are requesting Certificates with a 90 day lifetime, do not set O(remaining_days) to a value V(60) or higher).
- The O(force) option may be used to ensure that a new certificate is always obtained.
type: int
default: 30
request_type:
description:
- The operation performed if I(tracking_id) references a valid certificate to reissue, or there is already a certificate present in I(path) but
either I(force) is specified or C(cert_days < remaining_days).
- Specifying C(request_type=validate_only) means the request will be validated against the ECS API, but no certificate will be issued.
- Specifying C(request_type=new) means a certificate request will always be submitted and a new certificate issued.
- Specifying C(request_type=renew) means that an existing certificate (specified by I(tracking_id) if present, otherwise I(path)) will be renewed.
- The operation performed if O(tracking_id) references a valid certificate to reissue, or there is already a certificate present in O(path) but
either O(force) is specified or RV(cert_days) < O(remaining_days).
- Specifying O(request_type=validate_only) means the request will be validated against the ECS API, but no certificate will be issued.
- Specifying O(request_type=new) means a certificate request will always be submitted and a new certificate issued.
- Specifying O(request_type=renew) means that an existing certificate (specified by O(tracking_id) if present, otherwise O(path)) will be renewed.
If there is no certificate to renew, a new certificate is requested.
- Specifying C(request_type=reissue) means that an existing certificate (specified by I(tracking_id) if present, otherwise I(path)) will be
- Specifying O(request_type=reissue) means that an existing certificate (specified by O(tracking_id) if present, otherwise O(path)) will be
reissued.
If there is no certificate to reissue, a new certificate is requested.
- If a certificate was issued within the past 30 days, the C(renew) operation is not a valid operation and will fail.
- Note that C(reissue) is an operation that will result in the revocation of the certificate that is reissued, be cautious with its use.
- I(check_mode) is only supported if C(request_type=new)
- For example, setting C(request_type=renew) and C(remaining_days=30) and pointing to the same certificate on multiple playbook runs means that on
- If a certificate was issued within the past 30 days, the V(renew) operation is not a valid operation and will fail.
- Note that V(reissue) is an operation that will result in the revocation of the certificate that is reissued, be cautious with its use.
- I(check_mode) is only supported if O(request_type=new)
- For example, setting O(request_type=renew) and O(remaining_days=30) and pointing to the same certificate on multiple playbook runs means that on
the first run new certificate will be requested. It will then be left along on future runs until it is within 30 days of expiry, then the
ECS "renew" operation will be performed.
type: str
@@ -123,57 +123,57 @@ options:
cert_type:
description:
- Specify the type of certificate requested.
- If a certificate is being reissued or renewed, this parameter is ignored, and the C(cert_type) of the initial certificate is used.
- If a certificate is being reissued or renewed, this parameter is ignored, and the O(cert_type) of the initial certificate is used.
type: str
choices: [ 'STANDARD_SSL', 'ADVANTAGE_SSL', 'UC_SSL', 'EV_SSL', 'WILDCARD_SSL', 'PRIVATE_SSL', 'PD_SSL', 'CODE_SIGNING', 'EV_CODE_SIGNING',
'CDS_INDIVIDUAL', 'CDS_GROUP', 'CDS_ENT_LITE', 'CDS_ENT_PRO', 'SMIME_ENT' ]
subject_alt_name:
description:
- The subject alternative name identifiers, as an array of values (applies to I(cert_type) with a value of C(STANDARD_SSL), C(ADVANTAGE_SSL),
C(UC_SSL), C(EV_SSL), C(WILDCARD_SSL), C(PRIVATE_SSL), and C(PD_SSL)).
- If you are requesting a new SSL certificate, and you pass a I(subject_alt_name) parameter, any SAN names in the CSR are ignored.
- The subject alternative name identifiers, as an array of values (applies to O(cert_type) with a value of V(STANDARD_SSL), V(ADVANTAGE_SSL),
V(UC_SSL), V(EV_SSL), V(WILDCARD_SSL), V(PRIVATE_SSL), and V(PD_SSL)).
- If you are requesting a new SSL certificate, and you pass a O(subject_alt_name) parameter, any SAN names in the CSR are ignored.
If no subjectAltName parameter is passed, the SAN names in the CSR are used.
- See I(request_type) to understand more about SANs during reissues and renewals.
- In the case of certificates of type C(STANDARD_SSL) certificates, if the CN of the certificate is <domain>.<tld> only the www.<domain>.<tld> value
- See O(request_type) to understand more about SANs during reissues and renewals.
- In the case of certificates of type V(STANDARD_SSL) certificates, if the CN of the certificate is <domain>.<tld> only the www.<domain>.<tld> value
is accepted. If the CN of the certificate is www.<domain>.<tld> only the <domain>.<tld> value is accepted.
type: list
elements: str
eku:
description:
- If specified, overrides the key usage in the I(csr).
- If specified, overrides the key usage in the O(csr).
type: str
choices: [ SERVER_AUTH, CLIENT_AUTH, SERVER_AND_CLIENT_AUTH ]
ct_log:
description:
- In compliance with browser requirements, this certificate may be posted to the Certificate Transparency (CT) logs. This is a best practice
technique that helps domain owners monitor certificates issued to their domains. Note that not all certificates are eligible for CT logging.
- If I(ct_log) is not specified, the certificate uses the account default.
- If I(ct_log) is specified and the account settings allow it, I(ct_log) overrides the account default.
- If I(ct_log) is set to C(false), but the account settings are set to "always log", the certificate generation will fail.
- If O(ct_log) is not specified, the certificate uses the account default.
- If O(ct_log) is specified and the account settings allow it, O(ct_log) overrides the account default.
- If O(ct_log) is set to V(false), but the account settings are set to "always log", the certificate generation will fail.
type: bool
client_id:
description:
- The client ID to submit the Certificate Signing Request under.
- If no client ID is specified, the certificate will be submitted under the primary client with ID of 1.
- When using a client other than the primary client, the I(org) parameter cannot be specified.
- When using a client other than the primary client, the O(org) parameter cannot be specified.
- The issued certificate will have an organization value in the subject distinguished name represented by the client.
type: int
default: 1
org:
description:
- Organization "O=" to include in the certificate.
- If I(org) is not specified, the organization from the client represented by I(client_id) is used.
- Unless the I(cert_type) is C(PD_SSL), this field may not be specified if the value of I(client_id) is not "1" (the primary client).
- If O(org) is not specified, the organization from the client represented by O(client_id) is used.
- Unless the O(cert_type) is V(PD_SSL), this field may not be specified if the value of O(client_id) is not "1" (the primary client).
non-primary clients, certificates may only be issued with the organization of that client.
type: str
ou:
description:
- Organizational unit "OU=" to include in the certificate.
- I(ou) behavior is dependent on whether organizational units are enabled for your account. If organizational unit support is disabled for your
account, organizational units from the I(csr) and the I(ou) parameter are ignored.
- If both I(csr) and I(ou) are specified, the value in I(ou) will override the OU fields present in the subject distinguished name in the I(csr)
- If neither I(csr) nor I(ou) are specified for a renew or reissue operation, the OU fields in the initial certificate are reused.
- An invalid OU from I(csr) is ignored, but any invalid organizational units in I(ou) will result in an error indicating "Unapproved OU". The I(ou)
- O(ou) behavior is dependent on whether organizational units are enabled for your account. If organizational unit support is disabled for your
account, organizational units from the O(csr) and the O(ou) parameter are ignored.
- If both O(csr) and O(ou) are specified, the value in O(ou) will override the OU fields present in the subject distinguished name in the O(csr)
- If neither O(csr) nor O(ou) are specified for a renew or reissue operation, the OU fields in the initial certificate are reused.
- An invalid OU from O(csr) is ignored, but any invalid organizational units in O(ou) will result in an error indicating "Unapproved OU". The O(ou)
parameter can be used to force failure if an unapproved organizational unit is provided.
- A maximum of one OU may be specified for current products. Multiple OUs are reserved for future products.
type: list
@@ -181,10 +181,10 @@ options:
end_user_key_storage_agreement:
description:
- The end user of the Code Signing certificate must generate and store the private key for this request on cryptographically secure
hardware to be compliant with the Entrust CSP and Subscription agreement. If requesting a certificate of type C(CODE_SIGNING) or
C(EV_CODE_SIGNING), you must set I(end_user_key_storage_agreement) to true if and only if you acknowledge that you will inform the user of this
hardware to be compliant with the Entrust CSP and Subscription agreement. If requesting a certificate of type V(CODE_SIGNING) or
V(EV_CODE_SIGNING), you must set O(end_user_key_storage_agreement) to true if and only if you acknowledge that you will inform the user of this
requirement.
- Applicable only to I(cert_type) of values C(CODE_SIGNING) and C(EV_CODE_SIGNING).
- Applicable only to O(cert_type) of values V(CODE_SIGNING) and V(EV_CODE_SIGNING).
type: bool
tracking_info:
description: Free form tracking information to attach to the record for the certificate.
@@ -320,29 +320,29 @@ options:
cert_expiry:
description:
- The date the certificate should be set to expire, in RFC3339 compliant date or date-time format. For example,
C(2020-02-23), C(2020-02-23T15:00:00.05Z).
- I(cert_expiry) is only supported for requests of C(request_type=new) or C(request_type=renew). If C(request_type=reissue),
I(cert_expiry) will be used for the first certificate issuance, but subsequent issuances will have the same expiry as the initial
V(2020-02-23), V(2020-02-23T15:00:00.05Z).
- O(cert_expiry) is only supported for requests of O(request_type=new) or O(request_type=renew). If O(request_type=reissue),
O(cert_expiry) will be used for the first certificate issuance, but subsequent issuances will have the same expiry as the initial
certificate.
- A reissued certificate will always have the same expiry as the original certificate.
- Note that only the date (day, month, year) is supported for specifying the expiry date. If you choose to specify an expiry time with the expiry
date, the time will be adjusted to Eastern Standard Time (EST). This could have the unintended effect of moving your expiry date to the previous
day.
- Applies only to accounts with a pooling inventory model.
- Only one of I(cert_expiry) or I(cert_lifetime) may be specified.
- Only one of O(cert_expiry) or O(cert_lifetime) may be specified.
type: str
cert_lifetime:
description:
- The lifetime of the certificate.
- Applies to all certificates for accounts with a non-pooling inventory model.
- I(cert_lifetime) is only supported for requests of C(request_type=new) or C(request_type=renew). If C(request_type=reissue), I(cert_lifetime) will
- O(cert_lifetime) is only supported for requests of O(request_type=new) or O(request_type=renew). If O(request_type=reissue), O(cert_lifetime) will
be used for the first certificate issuance, but subsequent issuances will have the same expiry as the initial certificate.
- Applies to certificates of I(cert_type)=C(CDS_INDIVIDUAL, CDS_GROUP, CDS_ENT_LITE, CDS_ENT_PRO, SMIME_ENT) for accounts with a pooling inventory
model.
- C(P1Y) is a certificate with a 1 year lifetime.
- C(P2Y) is a certificate with a 2 year lifetime.
- C(P3Y) is a certificate with a 3 year lifetime.
- Only one of I(cert_expiry) or I(cert_lifetime) may be specified.
- Applies to certificates of O(cert_type=CDS_INDIVIDUAL), V(CDS_GROUP), V(CDS_ENT_LITE), V(CDS_ENT_PRO), or V(SMIME_ENT)
for accounts with a pooling inventory model.
- V(P1Y) is a certificate with a 1 year lifetime.
- V(P2Y) is a certificate with a 2 year lifetime.
- V(P3Y) is a certificate with a 3 year lifetime.
- Only one of O(cert_expiry) or O(cert_lifetime) may be specified.
type: str
choices: [ P1Y, P2Y, P3Y ]
seealso:
@@ -476,12 +476,12 @@ filename:
sample: /etc/ssl/crt/www.ansible.com.crt
backup_file:
description: Name of backup file created for the certificate.
returned: changed and if I(backup) is C(true)
returned: changed and if O(backup) is V(true)
type: str
sample: /path/to/www.ansible.com.crt.2019-03-09@11:22~
backup_full_chain_file:
description: Name of the backup file created for the certificate chain.
returned: changed and if I(backup) is C(true) and I(full_chain_path) is set.
returned: changed and if O(backup) is V(true) and O(full_chain_path) is set.
type: str
sample: /path/to/ca.chain.crt.2019-03-09@11:22~
tracking_id:
@@ -502,8 +502,8 @@ cert_days:
cert_status:
description:
- The certificate status in ECS.
- 'Current possible values (which may be expanded in the future) are: C(ACTIVE), C(APPROVED), C(DEACTIVATED), C(DECLINED), C(EXPIRED), C(NA),
C(PENDING), C(PENDING_QUORUM), C(READY), C(REISSUED), C(REISSUING), C(RENEWED), C(RENEWING), C(REVOKED), C(SUSPENDED)'
- 'Current possible values (which may be expanded in the future) are: V(ACTIVE), V(APPROVED), V(DEACTIVATED), V(DECLINED), V(EXPIRED), V(NA),
V(PENDING), V(PENDING_QUORUM), V(READY), V(REISSUED), V(REISSUING), V(RENEWED), V(RENEWING), V(REVOKED), V(SUSPENDED)'
returned: success
type: str
sample: ACTIVE

96
plugins/modules/ecs_domain.py
View File

@@ -20,19 +20,19 @@ description:
- Request validation or re-validation of a domain with the Entrust Certificate Services (ECS) API.
- Requires credentials for the L(Entrust Certificate Services,https://www.entrustdatacard.com/products/categories/ssl-certificates) (ECS) API.
- If the domain is already in the validation process, no new validation will be requested, but the validation data (if applicable) will be returned.
- If the domain is already in the validation process but the I(verification_method) specified is different than the current I(verification_method),
the I(verification_method) will be updated and validation data (if applicable) will be returned.
- If the domain is an active, validated domain, the return value of I(changed) will be false, unless C(domain_status=EXPIRED), in which case a re-validation
will be performed.
- If C(verification_method=dns), details about the required DNS entry will be specified in the return parameters I(dns_contents), I(dns_location), and
I(dns_resource_type).
- If C(verification_method=web_server), details about the required file details will be specified in the return parameters I(file_contents) and
I(file_location).
- If C(verification_method=email), the email address(es) that the validation email(s) were sent to will be in the return parameter I(emails). This is
- If the domain is already in the validation process but the O(verification_method) specified is different than the current O(verification_method),
the O(verification_method) will be updated and validation data (if applicable) will be returned.
- If the domain is an active, validated domain, the return value of C(changed) will be false, unless RV(domain_status=EXPIRED), in which case a
re-validation will be performed.
- If O(verification_method=dns), details about the required DNS entry will be specified in the return parameters RV(dns_contents), RV(dns_location), and
RV(dns_resource_type).
- If O(verification_method=web_server), details about the required file details will be specified in the return parameters RV(file_contents) and
RV(file_location).
- If O(verification_method=email), the email address(es) that the validation email(s) were sent to will be in the return parameter RV(emails). This is
purely informational. For domains requested using this module, this will always be a list of size 1.
notes:
- There is a small delay (typically about 5 seconds, but can be as long as 60 seconds) before obtaining the random values when requesting a validation
while C(verification_method=dns) or C(verification_method=web_server). Be aware of that if doing many domain validation requests.
while O(verification_method=dns) or O(verification_method=web_server). Be aware of that if doing many domain validation requests.
extends_documentation_fragment:
- community.crypto.attributes
- community.crypto.ecs_credential
@@ -56,35 +56,35 @@ options:
verification_method:
description:
- The verification method to be used to prove control of the domain.
- If C(verification_method=email) and the value I(verification_email) is specified, that value is used for the email validation. If
I(verification_email) is not provided, the first value present in WHOIS data will be used. An email will be sent to the address in
I(verification_email) with instructions on how to verify control of the domain.
- If C(verification_method=dns), the value I(dns_contents) must be stored in location I(dns_location), with a DNS record type of
I(verification_dns_record_type). To prove domain ownership, update your DNS records so the text string returned by I(dns_contents) is available at
I(dns_location).
- If C(verification_method=web_server), the contents of return value I(file_contents) must be made available on a web server accessible at location
I(file_location).
- If C(verification_method=manual), the domain will be validated with a manual process. This is not recommended.
- If O(verification_method=email) and the value O(verification_email) is specified, that value is used for the email validation. If
O(verification_email) is not provided, the first value present in WHOIS data will be used. An email will be sent to the address in
O(verification_email) with instructions on how to verify control of the domain.
- If O(verification_method=dns), the value RV(dns_contents) must be stored in location RV(dns_location), with a DNS record type of
RV(dns_resource_type). To prove domain ownership, update your DNS records so the text string returned by RV(dns_contents) is available at
RV(dns_location).
- If O(verification_method=web_server), the contents of return value RV(file_contents) must be made available on a web server accessible at location
RV(file_location).
- If O(verification_method=manual), the domain will be validated with a manual process. This is not recommended.
type: str
choices: [ 'dns', 'email', 'manual', 'web_server']
required: true
verification_email:
description:
- Email address to be used to verify domain ownership.
- 'Email address must be either an email address present in the WHOIS data for I(domain_name), or one of the following constructed emails:
admin@I(domain_name), administrator@I(domain_name), webmaster@I(domain_name), hostmaster@I(domain_name), postmaster@I(domain_name).'
- 'Note that if I(domain_name) includes subdomains, the top level domain should be used. For example, if requesting validation of
- 'Email address must be either an email address present in the WHOIS data for O(domain_name), or one of the following constructed emails:
admin@O(domain_name), administrator@O(domain_name), webmaster@O(domain_name), hostmaster@O(domain_name), postmaster@O(domain_name).'
- 'Note that if O(domain_name) includes subdomains, the top level domain should be used. For example, if requesting validation of
example1.ansible.com, or test.example2.ansible.com, and you want to use the "admin" preconstructed name, the email address should be
admin@ansible.com.'
- If using the email values from the WHOIS data for the domain or its top level namespace, they must be exact matches.
- If C(verification_method=email) but I(verification_email) is not provided, the first email address found in WHOIS data for the domain will be
- If O(verification_method=email) but O(verification_email) is not provided, the first email address found in WHOIS data for the domain will be
used.
- To verify domain ownership, domain owner must follow the instructions in the email they receive.
- Only allowed if C(verification_method=email)
- Only allowed if O(verification_method=email)
type: str
seealso:
- module: community.crypto.x509_certificate
description: Can be used to request certificates from ECS, with C(provider=entrust).
description: Can be used to request certificates from ECS, with O(community.crypto.x509_certificate#module:provider=entrust).
- module: community.crypto.ecs_certificate
description: Can be used to request a Certificate from ECS using a verified domain.
'''
@@ -133,72 +133,72 @@ EXAMPLES = r'''
RETURN = '''
domain_status:
description: Status of the current domain. Will be one of C(APPROVED), C(DECLINED), C(CANCELLED), C(INITIAL_VERIFICATION), C(DECLINED), C(CANCELLED),
C(RE_VERIFICATION), C(EXPIRED), C(EXPIRING)
description: Status of the current domain. Will be one of V(APPROVED), V(DECLINED), V(CANCELLED), V(INITIAL_VERIFICATION), V(DECLINED), V(CANCELLED),
V(RE_VERIFICATION), V(EXPIRED), V(EXPIRING)
returned: changed or success
type: str
sample: APPROVED
verification_method:
description: Verification method used to request the domain validation. If C(changed) will be the same as I(verification_method) input parameter.
description: Verification method used to request the domain validation. If C(changed) will be the same as O(verification_method) input parameter.
returned: changed or success
type: str
sample: dns
file_location:
description: The location that ECS will be expecting to be able to find the file for domain verification, containing the contents of I(file_contents).
returned: I(verification_method) is C(web_server)
description: The location that ECS will be expecting to be able to find the file for domain verification, containing the contents of RV(file_contents).
returned: O(verification_method) is V(web_server)
type: str
sample: http://ansible.com/.well-known/pki-validation/abcd.txt
file_contents:
description: The contents of the file that ECS will be expecting to find at C(file_location).
returned: I(verification_method) is C(web_server)
description: The contents of the file that ECS will be expecting to find at RV(file_location).
returned: O(verification_method) is V(web_server)
type: str
sample: AB23CD41432522FF2526920393982FAB
emails:
description:
- The list of emails used to request validation of this domain.
- Domains requested using this module will only have a list of size 1.
returned: I(verification_method) is C(email)
returned: O(verification_method) is V(email)
type: list
sample: [ admin@ansible.com, administrator@ansible.com ]
dns_location:
description: The location that ECS will be expecting to be able to find the DNS entry for domain verification, containing the contents of I(dns_contents).
returned: changed and if I(verification_method) is C(dns)
description: The location that ECS will be expecting to be able to find the DNS entry for domain verification, containing the contents of RV(dns_contents).
returned: changed and if O(verification_method) is V(dns)
type: str
sample: _pki-validation.ansible.com
dns_contents:
description: The value that ECS will be expecting to find in the DNS record located at I(dns_location).
returned: changed and if I(verification_method) is C(dns)
description: The value that ECS will be expecting to find in the DNS record located at RV(dns_location).
returned: changed and if O(verification_method) is V(dns)
type: str
sample: AB23CD41432522FF2526920393982FAB
dns_resource_type:
description: The type of resource record that ECS will be expecting for the DNS record located at I(dns_location).
returned: changed and if I(verification_method) is C(dns)
description: The type of resource record that ECS will be expecting for the DNS record located at RV(dns_location).
returned: changed and if O(verification_method) is V(dns)
type: str
sample: TXT
client_id:
description: Client ID that the domain belongs to. If the input value I(client_id) is specified, this will always be the same as I(client_id)
description: Client ID that the domain belongs to. If the input value O(client_id) is specified, this will always be the same as O(client_id)
returned: changed or success
type: int
sample: 1
ov_eligible:
description: Whether the domain is eligible for submission of "OV" certificates. Will never be C(false) if I(ov_eligible) is C(true)
returned: success and I(domain_status) is C(APPROVED), C(RE_VERIFICATION), C(EXPIRING), or C(EXPIRED).
description: Whether the domain is eligible for submission of "OV" certificates. Will never be V(false) if RV(ev_eligible) is V(true)
returned: success and RV(domain_status) is V(APPROVED), V(RE_VERIFICATION), V(EXPIRING), or V(EXPIRED).
type: bool
sample: true
ov_days_remaining:
description: The number of days the domain remains eligible for submission of "OV" certificates. Will never be less than the value of I(ev_days_remaining)
returned: success and I(ov_eligible) is C(true) and I(domain_status) is C(APPROVED), C(RE_VERIFICATION) or C(EXPIRING).
description: The number of days the domain remains eligible for submission of "OV" certificates. Will never be less than the value of RV(ev_days_remaining)
returned: success and RV(ov_eligible) is V(true) and RV(domain_status) is V(APPROVED), V(RE_VERIFICATION) or V(EXPIRING).
type: int
sample: 129
ev_eligible:
description: Whether the domain is eligible for submission of "EV" certificates. Will never be C(true) if I(ov_eligible) is C(false)
returned: success and I(domain_status) is C(APPROVED), C(RE_VERIFICATION) or C(EXPIRING), or C(EXPIRED).
description: Whether the domain is eligible for submission of "EV" certificates. Will never be V(true) if RV(ov_eligible) is V(false)
returned: success and RV(domain_status) is V(APPROVED), V(RE_VERIFICATION) or V(EXPIRING), or V(EXPIRED).
type: bool
sample: true
ev_days_remaining:
description: The number of days the domain remains eligible for submission of "EV" certificates. Will never be greater than the value of
I(ov_days_remaining)
returned: success and I(ev_eligible) is C(true) and I(domain_status) is C(APPROVED), C(RE_VERIFICATION) or C(EXPIRING).
RV(ov_days_remaining)
returned: success and RV(ev_eligible) is V(true) and RV(domain_status) is V(APPROVED), V(RE_VERIFICATION) or V(EXPIRING).
type: int
sample: 94

18
plugins/modules/get_certificate.py
View File

@@ -63,7 +63,7 @@ options:
starttls:
description:
- Requests a secure connection for protocols which require clients to initiate encryption.
- Only available for C(mysql) currently.
- Only available for V(mysql) currently.
type: str
choices:
- mysql
@@ -76,15 +76,15 @@ options:
select_crypto_backend:
description:
- Determines which crypto backend to use.
- The default choice is C(auto), which tries to use C(cryptography) if available.
- If set to C(cryptography), will try to use the L(cryptography,https://cryptography.io/) library.
- 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 ]
ciphers:
description:
- SSL/TLS Ciphers to use for the request.
- 'When a list is provided, all ciphers are joined in order with C(:).'
- 'When a list is provided, all ciphers are joined in order with V(:).'
- See the L(OpenSSL Cipher List Format,https://www.openssl.org/docs/manmaster/man1/openssl-ciphers.html#CIPHER-LIST-FORMAT)
for more details.
- The available ciphers is dependent on the Python and OpenSSL/LibreSSL versions.
@@ -93,10 +93,10 @@ options:
version_added: 2.11.0
asn1_base64:
description:
- Whether to encode the ASN.1 values in the C(extensions) return value with Base64 or not.
- Whether to encode the ASN.1 values in the RV(extensions) return value with Base64 or not.
- The documentation claimed for a long time that the values are Base64 encoded, but they
never were. For compatibility this option is set to C(false), but that value will eventually
be deprecated and changed to C(true).
never were. For compatibility this option is set to V(false), but that value will eventually
be deprecated and changed to V(true).
type: bool
default: false
version_added: 2.12.0
@@ -105,7 +105,7 @@ notes:
- When using ca_cert on OS X it has been reported that in some conditions the validate will always succeed.
requirements:
- "python >= 2.7 when using C(proxy_host)"
- "python >= 2.7 when using O(proxy_host)"
- "cryptography >= 1.6"
'''
@@ -133,7 +133,7 @@ extensions:
type: str
description:
- The ASN.1 content of the extension.
- If I(asn1_base64=true) this will be Base64 encoded, otherwise the raw
- If O(asn1_base64=true) this will be Base64 encoded, otherwise the raw
binary value will be returned.
- Please note that the raw binary value might not survive JSON serialization
to the Ansible controller, and also might cause failures when displaying it.

82
plugins/modules/luks_device.py
View File

@@ -30,52 +30,52 @@ attributes:
options:
device:
description:
- "Device to work with (for example C(/dev/sda1)). Needed in most cases.
Can be omitted only when I(state=closed) together with I(name)
- "Device to work with (for example V(/dev/sda1)). Needed in most cases.
Can be omitted only when O(state=closed) together with O(name)
is provided."
type: str
state:
description:
- "Desired state of the LUKS container. Based on its value creates,
destroys, opens or closes the LUKS container on a given device."
- "I(present) will create LUKS container unless already present.
Requires I(device) and either I(keyfile) or I(passphrase) options
- "V(present) will create LUKS container unless already present.
Requires O(device) and either O(keyfile) or O(passphrase) options
to be provided."
- "I(absent) will remove existing LUKS container if it exists.
Requires I(device) or I(name) to be specified."
- "I(opened) will unlock the LUKS container. If it does not exist
- "V(absent) will remove existing LUKS container if it exists.
Requires O(device) or O(name) to be specified."
- "V(opened) will unlock the LUKS container. If it does not exist
it will be created first.
Requires I(device) and either I(keyfile) or I(passphrase)
to be specified. Use the I(name) option to set the name of
Requires O(device) and either O(keyfile) or O(passphrase)
to be specified. Use the O(name) option to set the name of
the opened container. Otherwise the name will be
generated automatically and returned as a part of the
result."
- "I(closed) will lock the LUKS container. However if the container
- "V(closed) will lock the LUKS container. However if the container
does not exist it will be created.
Requires I(device) and either I(keyfile) or I(passphrase)
Requires O(device) and either O(keyfile) or O(passphrase)
options to be provided. If container does already exist
I(device) or I(name) will suffice."
O(device) or O(name) will suffice."
type: str
default: present
choices: [present, absent, opened, closed]
name:
description:
- "Sets container name when I(state=opened). Can be used
instead of I(device) when closing the existing container
(that is, when I(state=closed))."
- "Sets container name when O(state=opened). Can be used
instead of O(device) when closing the existing container
(that is, when O(state=closed))."
type: str
keyfile:
description:
- "Used to unlock the container. Either a I(keyfile) or a
I(passphrase) is needed for most of the operations. Parameter
- "Used to unlock the container. Either a O(keyfile) or a
O(passphrase) is needed for most of the operations. Parameter
value is the path to the keyfile with the passphrase."
- "BEWARE that working with keyfiles in plaintext is dangerous.
Make sure that they are protected."
type: path
passphrase:
description:
- "Used to unlock the container. Either a I(passphrase) or a
I(keyfile) is needed for most of the operations. Parameter
- "Used to unlock the container. Either a O(passphrase) or a
O(keyfile) is needed for most of the operations. Parameter
value is a string with the passphrase."
type: str
version_added: '1.0.0'
@@ -86,8 +86,8 @@ options:
version_added: '1.0.0'
new_keyfile:
description:
- "Adds additional key to given container on I(device).
Needs I(keyfile) or I(passphrase) option for authorization.
- "Adds additional key to given container on O(device).
Needs O(keyfile) or O(passphrase) option for authorization.
LUKS container supports up to 8 keyslots. Parameter value
is the path to the keyfile with the passphrase."
- "NOTE that adding additional keys is idempotent only since
@@ -99,8 +99,8 @@ options:
type: path
new_passphrase:
description:
- "Adds additional passphrase to given container on I(device).
Needs I(keyfile) or I(passphrase) option for authorization. LUKS
- "Adds additional passphrase to given container on O(device).
Needs O(keyfile) or O(passphrase) option for authorization. LUKS
container supports up to 8 keyslots. Parameter value is a string
with the new passphrase."
- "NOTE that adding additional passphrase is idempotent only since
@@ -110,32 +110,32 @@ options:
version_added: '1.0.0'
remove_keyfile:
description:
- "Removes given key from the container on I(device). Does not
- "Removes given key from the container on O(device). Does not
remove the keyfile from filesystem.
Parameter value is the path to the keyfile with the passphrase."
- "NOTE that removing keys is idempotent only since
community.crypto 1.4.0. For older versions, trying to remove
a key which no longer exists results in an error."
- "NOTE that to remove the last key from a LUKS container, the
I(force_remove_last_key) option must be set to C(true)."
O(force_remove_last_key) option must be set to V(true)."
- "BEWARE that working with keyfiles in plaintext is dangerous.
Make sure that they are protected."
type: path
remove_passphrase:
description:
- "Removes given passphrase from the container on I(device).
- "Removes given passphrase from the container on O(device).
Parameter value is a string with the passphrase to remove."
- "NOTE that removing passphrases is idempotent only since
community.crypto 1.4.0. For older versions, trying to remove
a passphrase which no longer exists results in an error."
- "NOTE that to remove the last keyslot from a LUKS
container, the I(force_remove_last_key) option must be set
to C(true)."
container, the O(force_remove_last_key) option must be set
to V(true)."
type: str
version_added: '1.0.0'
force_remove_last_key:
description:
- "If set to C(true), allows removing the last key from a container."
- "If set to V(true), allows removing the last key from a container."
- "BEWARE that when the last key has been removed from a container,
the container can no longer be opened!"
type: bool
@@ -145,21 +145,21 @@ options:
- "This option allow the user to create a LUKS2 format container
with label support, respectively to identify the container by
label on later usages."
- "Will only be used on container creation, or when I(device) is
- "Will only be used on container creation, or when O(device) is
not specified."
- "This cannot be specified if I(type) is set to C(luks1)."
- "This cannot be specified if O(type) is set to V(luks1)."
type: str
version_added: '1.0.0'
uuid:
description:
- "With this option user can identify the LUKS container by UUID."
- "Will only be used when I(device) and I(label) are not specified."
- "Will only be used when O(device) and O(label) are not specified."
type: str
version_added: '1.0.0'
type:
description:
- "This option allow the user explicit define the format of LUKS
container that wants to work with. Options are C(luks1) or C(luks2)"
container that wants to work with. Options are V(luks1) or V(luks2)"
type: str
choices: [luks1, luks2]
version_added: '1.0.0'
@@ -168,8 +168,8 @@ options:
- "This option allows the user to define the cipher specification
string for the LUKS container."
- "Will only be used on container creation."
- "For pre-2.6.10 kernels, use C(aes-plain) as they do not understand
the new cipher spec strings. To use ESSIV, use C(aes-cbc-essiv:sha256)."
- "For pre-2.6.10 kernels, use V(aes-plain) as they do not understand
the new cipher spec strings. To use ESSIV, use V(aes-cbc-essiv:sha256)."
type: str
version_added: '1.1.0'
hash:
@@ -193,12 +193,12 @@ options:
- Specify the iteration time used for the PBKDF.
- Note that this is in B(seconds), not in milliseconds as on the
command line.
- Mutually exclusive with I(iteration_count).
- Mutually exclusive with O(pbkdf.iteration_count).
type: float
iteration_count:
description:
- Specify the iteration count used for the PBKDF.
- Mutually exclusive with I(iteration_time).
- Mutually exclusive with O(pbkdf.iteration_time).
type: int
algorithm:
description:
@@ -261,7 +261,7 @@ options:
persistent:
description:
- "Allows the user to store options into container's metadata persistently and automatically use them next time.
Only I(perf_same_cpu_crypt), I(perf_submit_from_crypt_cpus), I(perf_no_read_workqueue), and I(perf_no_write_workqueue)
Only O(perf_same_cpu_crypt), O(perf_submit_from_crypt_cpus), O(perf_no_read_workqueue), and O(perf_no_write_workqueue)
can be stored persistently."
- "Will only work with LUKS2 containers."
- "Will only be used when opening containers."
@@ -271,9 +271,9 @@ options:
requirements:
- "cryptsetup"
- "wipefs (when I(state) is C(absent))"
- "wipefs (when O(state) is V(absent))"
- "lsblk"
- "blkid (when I(label) or I(uuid) options are used)"
- "blkid (when O(label) or O(uuid) options are used)"
author: Jan Pokorny (@japokorn)
'''
@@ -382,7 +382,7 @@ EXAMPLES = '''
RETURN = '''
name:
description:
When I(state=opened) returns (generated or given) name
When O(state=opened) returns (generated or given) name
of LUKS container. Returns None if no name is supplied.
returned: success
type: str

80
plugins/modules/openssh_cert.py
View File

@@ -40,13 +40,13 @@ options:
type:
description:
- Whether the module should generate a host or a user certificate.
- Required if I(state) is C(present).
- Required if O(state) is V(present).
type: str
choices: ['host', 'user']
force:
description:
- Should the certificate be regenerated even if it already exists and is valid.
- Equivalent to I(regenerate=always).
- Equivalent to O(regenerate=always).
type: bool
default: false
path:
@@ -56,16 +56,16 @@ options:
required: true
regenerate:
description:
- When C(never) the task will fail if a certificate already exists at I(path) and is unreadable
- When V(never) the task will fail if a certificate already exists at O(path) and is unreadable
otherwise a new certificate will only be generated if there is no existing certificate.
- When C(fail) the task will fail if a certificate already exists at I(path) and does not
- When V(fail) the task will fail if a certificate already exists at O(path) and does not
match the module's options.
- When C(partial_idempotence) an existing certificate will be regenerated based on
I(serial), I(signature_algorithm), I(type), I(valid_from), I(valid_to), I(valid_at), and I(principals).
I(valid_from) and I(valid_to) can be excluded by I(ignore_timestamps=true).
- When C(full_idempotence) I(identifier), I(options), I(public_key), and I(signing_key)
- When V(partial_idempotence) an existing certificate will be regenerated based on
O(serial_number), O(signature_algorithm), O(type), O(valid_from), O(valid_to), O(valid_at), and O(principals).
O(valid_from) and O(valid_to) can be excluded by O(ignore_timestamps=true).
- When V(full_idempotence) O(identifier), O(options), O(public_key), and O(signing_key)
are also considered when compared against an existing certificate.
- C(always) is equivalent to I(force=true).
- V(always) is equivalent to O(force=true).
type: str
choices:
- never
@@ -78,14 +78,14 @@ options:
signature_algorithm:
description:
- As of OpenSSH 8.2 the SHA-1 signature algorithm for RSA keys has been disabled and C(ssh) will refuse
host certificates signed with the SHA-1 algorithm. OpenSSH 8.1 made C(rsa-sha2-512) the default algorithm
host certificates signed with the SHA-1 algorithm. OpenSSH 8.1 made V(rsa-sha2-512) the default algorithm
when acting as a CA and signing certificates with a RSA key. However, for OpenSSH versions less than 8.1
the SHA-2 signature algorithms, C(rsa-sha2-256) or C(rsa-sha2-512), must be specified using this option
the SHA-2 signature algorithms, V(rsa-sha2-256) or V(rsa-sha2-512), must be specified using this option
if compatibility with newer C(ssh) clients is required. Conversely if hosts using OpenSSH version 8.2
or greater must remain compatible with C(ssh) clients using OpenSSH less than 7.2, then C(ssh-rsa)
can be used when generating host certificates (a corresponding change to the sshd_config to add C(ssh-rsa)
or greater must remain compatible with C(ssh) clients using OpenSSH less than 7.2, then V(ssh-rsa)
can be used when generating host certificates (a corresponding change to the sshd_config to add V(ssh-rsa)
to the C(CASignatureAlgorithms) keyword is also required).
- Using any value for this option with a non-RSA I(signing_key) will cause this module to fail.
- Using any value for this option with a non-RSA O(signing_key) will cause this module to fail.
- "Note: OpenSSH versions prior to 7.2 do not support SHA-2 signature algorithms for RSA keys and OpenSSH
versions prior to 7.3 do not support SHA-2 signature algorithms for certificates."
- See U(https://www.openssh.com/txt/release-8.2) for more information.
@@ -98,14 +98,14 @@ options:
signing_key:
description:
- The path to the private openssh key that is used for signing the public key in order to generate the certificate.
- If the private key is on a PKCS#11 token (I(pkcs11_provider)), set this to the path to the public key instead.
- Required if I(state) is C(present).
- If the private key is on a PKCS#11 token (O(pkcs11_provider)), set this to the path to the public key instead.
- Required if O(state) is V(present).
type: path
pkcs11_provider:
description:
- To use a signing key that resides on a PKCS#11 token, set this to the name (or full path) of the shared library to use with the token.
Usually C(libpkcs11.so).
- If this is set, I(signing_key) needs to point to a file containing the public key of the CA.
- If this is set, O(signing_key) needs to point to a file containing the public key of the CA.
type: str
version_added: 1.1.0
use_agent:
@@ -117,37 +117,37 @@ options:
public_key:
description:
- The path to the public key that will be signed with the signing key in order to generate the certificate.
- Required if I(state) is C(present).
- Required if O(state) is V(present).
type: path
valid_from:
description:
- "The point in time the certificate is valid from. Time can be specified either as relative time or as absolute timestamp.
Time will always be interpreted as UTC. Valid formats are: C([+-]timespec | YYYY-MM-DD | YYYY-MM-DDTHH:MM:SS | YYYY-MM-DD HH:MM:SS | always)
where timespec can be an integer + C([w | d | h | m | s]) (for example C(+32w1d2h)).
where timespec can be an integer + C([w | d | h | m | s]) (for example V(+32w1d2h)).
Note that if using relative time this module is NOT idempotent."
- "The value C(always) is only supported for OpenSSH 7.7 and greater, however, the value C(1970-01-01T00:00:01)
- "The value V(always) is only supported for OpenSSH 7.7 and greater, however, the value V(1970-01-01T00:00:01)
can be used with earlier versions as an equivalent expression."
- "To ignore this value during comparison with an existing certificate set I(ignore_timestamps=true)."
- Required if I(state) is C(present).
- "To ignore this value during comparison with an existing certificate set O(ignore_timestamps=true)."
- Required if O(state) is V(present).
type: str
valid_to:
description:
- "The point in time the certificate is valid to. Time can be specified either as relative time or as absolute timestamp.
Time will always be interpreted as UTC. Valid formats are: C([+-]timespec | YYYY-MM-DD | YYYY-MM-DDTHH:MM:SS | YYYY-MM-DD HH:MM:SS | forever)
where timespec can be an integer + C([w | d | h | m | s]) (for example C(+32w1d2h)).
where timespec can be an integer + C([w | d | h | m | s]) (for example V(+32w1d2h)).
Note that if using relative time this module is NOT idempotent."
- "To ignore this value during comparison with an existing certificate set I(ignore_timestamps=true)."
- Required if I(state) is C(present).
- "To ignore this value during comparison with an existing certificate set O(ignore_timestamps=true)."
- Required if O(state) is V(present).
type: str
valid_at:
description:
- "Check if the certificate is valid at a certain point in time. If it is not the certificate will be regenerated.
Time will always be interpreted as UTC. Mainly to be used with relative timespec for I(valid_from) and / or I(valid_to).
Time will always be interpreted as UTC. Mainly to be used with relative timespec for O(valid_from) and / or O(valid_to).
Note that if using relative time this module is NOT idempotent."
type: str
ignore_timestamps:
description:
- "Whether the I(valid_from) and I(valid_to) timestamps should be ignored for idempotency checks."
- "Whether the O(valid_from) and O(valid_to) timestamps should be ignored for idempotency checks."
- "However, the values will still be applied to a new certificate if it meets any other necessary conditions for generation/regeneration."
type: bool
default: false
@@ -161,20 +161,20 @@ options:
options:
description:
- "Specify certificate options when signing a key. The option that are valid for user certificates are:"
- "C(clear): Clear all enabled permissions. This is useful for clearing the default set of permissions so permissions may be added individually."
- "C(force-command=command): Forces the execution of command instead of any shell or
- "V(clear): Clear all enabled permissions. This is useful for clearing the default set of permissions so permissions may be added individually."
- "V(force-command=command): Forces the execution of command instead of any shell or
command specified by the user when the certificate is used for authentication."
- "C(no-agent-forwarding): Disable ssh-agent forwarding (permitted by default)."
- "C(no-port-forwarding): Disable port forwarding (permitted by default)."
- "C(no-pty): Disable PTY allocation (permitted by default)."
- "C(no-user-rc): Disable execution of C(~/.ssh/rc) by sshd (permitted by default)."
- "C(no-x11-forwarding): Disable X11 forwarding (permitted by default)"
- "C(permit-agent-forwarding): Allows ssh-agent forwarding."
- "C(permit-port-forwarding): Allows port forwarding."
- "C(permit-pty): Allows PTY allocation."
- "C(permit-user-rc): Allows execution of C(~/.ssh/rc) by sshd."
- "C(permit-x11-forwarding): Allows X11 forwarding."
- "C(source-address=address_list): Restrict the source addresses from which the certificate is considered valid.
- "V(no-agent-forwarding): Disable ssh-agent forwarding (permitted by default)."
- "V(no-port-forwarding): Disable port forwarding (permitted by default)."
- "V(no-pty): Disable PTY allocation (permitted by default)."
- "V(no-user-rc): Disable execution of C(~/.ssh/rc) by sshd (permitted by default)."
- "V(no-x11-forwarding): Disable X11 forwarding (permitted by default)"
- "V(permit-agent-forwarding): Allows ssh-agent forwarding."
- "V(permit-port-forwarding): Allows port forwarding."
- "V(permit-pty): Allows PTY allocation."
- "V(permit-user-rc): Allows execution of C(~/.ssh/rc) by sshd."
- "V(permit-x11-forwarding): Allows X11 forwarding."
- "V(source-address=address_list): Restrict the source addresses from which the certificate is considered valid.
The C(address_list) is a comma-separated list of one or more address/netmask pairs in CIDR format."
- "At present, no options are valid for host keys."
type: list

50
plugins/modules/openssh_keypair.py
View File

@@ -15,12 +15,12 @@ author: "David Kainz (@lolcube)"
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)
or C(ecdsa) private keys."
ssh-keygen to generate keys. One can generate V(rsa), V(dsa), V(rsa1), V(ed25519)
or V(ecdsa) private keys."
requirements:
- ssh-keygen (if I(backend=openssh))
- cryptography >= 2.6 (if I(backend=cryptography) and OpenSSH < 7.8 is installed)
- cryptography >= 3.0 (if I(backend=cryptography) and OpenSSH >= 7.8 is installed)
- ssh-keygen (if O(backend=openssh))
- cryptography >= 2.6 (if O(backend=cryptography) and OpenSSH < 7.8 is installed)
- cryptography >= 3.0 (if O(backend=cryptography) and OpenSSH >= 7.8 is installed)
extends_documentation_fragment:
- ansible.builtin.files
- community.crypto.attributes
@@ -49,8 +49,8 @@ options:
type: int
type:
description:
- "The algorithm used to generate the SSH private key. C(rsa1) is for protocol version 1.
C(rsa1) is deprecated and may not be supported by every version of ssh-keygen."
- "The algorithm used to generate the SSH private key. V(rsa1) is for protocol version 1.
V(rsa1) is deprecated and may not be supported by every version of ssh-keygen."
type: str
default: rsa
choices: ['rsa', 'dsa', 'rsa1', 'ecdsa', 'ed25519']
@@ -71,18 +71,18 @@ options:
passphrase:
description:
- Passphrase used to decrypt an existing private key or encrypt a newly generated private key.
- Passphrases are not supported for I(type=rsa1).
- Can only be used when I(backend=cryptography), or when I(backend=auto) and a required C(cryptography) version is installed.
- Passphrases are not supported for O(type=rsa1).
- Can only be used when O(backend=cryptography), or when O(backend=auto) and a required C(cryptography) version is installed.
type: str
version_added: 1.7.0
private_key_format:
description:
- Used when I(backend=cryptography) to select a format for the private key at the provided I(path).
- When set to C(auto) this module will match the key format of the installed OpenSSH version.
- Used when O(backend=cryptography) to select a format for the private key at the provided O(path).
- When set to V(auto) this module will match the key format of the installed OpenSSH version.
- For OpenSSH < 7.8 private keys will be in PKCS1 format except ed25519 keys which will be in OpenSSH format.
- For OpenSSH >= 7.8 all private key types will be in the OpenSSH format.
- Using this option when I(regenerate=partial_idempotence) or I(regenerate=full_idempotence) will cause
a new keypair to be generated if the private key's format does not match the value of I(private_key_format).
- Using this option when O(regenerate=partial_idempotence) or O(regenerate=full_idempotence) will cause
a new keypair to be generated if the private key's format does not match the value of O(private_key_format).
This module will not however convert existing private keys between formats.
type: str
default: auto
@@ -94,8 +94,8 @@ options:
version_added: 1.7.0
backend:
description:
- Selects between the C(cryptography) library or the OpenSSH binary C(opensshbin).
- C(auto) will default to C(opensshbin) unless the OpenSSH binary is not installed or when using I(passphrase).
- Selects between the V(cryptography) library or the OpenSSH binary V(opensshbin).
- V(auto) will default to V(opensshbin) unless the OpenSSH binary is not installed or when using O(passphrase).
type: str
default: auto
choices:
@@ -109,24 +109,24 @@ options:
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 C(full_idempotence)
this B(changed) for Ansible 2.10. For Ansible 2.9, the behavior was as if V(full_idempotence)
is specified.
- If set to C(never), the module will fail if the key cannot be read or the passphrase
- 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 C(fail), the module will fail if the key does not correspond to the module's
- If set to V(fail), the module will fail if the key does not correspond to the module's
options.
- If set to C(partial_idempotence), the key will be regenerated if it does not conform to
- 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 C(full_idempotence), the key will be regenerated if it does not conform to the
- 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 C(always), the module will always regenerate the key. This is equivalent to
setting I(force) to C(true).
- If set to V(always), the module will always regenerate the key. This is equivalent to
setting O(force) to V(true).
- Note that adjusting the comment and the permissions can be changed without regeneration.
Therefore, even for C(never), the task can result in changed.
Therefore, even for V(never), the task can result in changed.
type: str
choices:
- never
@@ -138,8 +138,8 @@ options:
version_added: '1.0.0'
notes:
- In case the ssh key is broken or password protected, the module will fail.
Set the I(force) option to C(true) if you want to regenerate the keypair.
- In the case a custom C(mode), C(group), C(owner), or other file attribute is provided it will be applied to both key files.
Set the O(force) option to V(true) if you want to regenerate the keypair.
- In the case a custom O(mode), O(group), O(owner), or other file attribute is provided it will be applied to both key files.
'''
EXAMPLES = '''

10
plugins/modules/openssl_csr.py
View File

@@ -17,7 +17,7 @@ short_description: Generate OpenSSL Certificate Signing Request (CSR)
description:
- "Please note that the module regenerates an existing CSR 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 CSR, consider using the I(backup) option."
your existing CSR, consider using the O(backup) option."
author:
- Yanis Guenane (@Spredzy)
- Felix Fontein (@felixfontein)
@@ -58,7 +58,7 @@ options:
default: false
return_content:
description:
- If set to C(true), will return the (current or generated) CSR's content as I(csr).
- If set to V(true), will return the (current or generated) CSR's content as RV(csr).
type: bool
default: false
version_added: "1.0.0"
@@ -173,7 +173,7 @@ RETURN = r'''
privatekey:
description:
- Path to the TLS/SSL private key the CSR was generated for
- Will be C(none) if the private key has been provided in I(privatekey_content).
- Will be V(none) if the private key has been provided in O(privatekey_content).
returned: changed or success
type: str
sample: /etc/ssl/private/ansible.com.pem
@@ -234,12 +234,12 @@ name_constraints_excluded:
version_added: 1.1.0
backup_file:
description: Name of backup file created.
returned: changed and if I(backup) is C(true)
returned: changed and if O(backup) is V(true)
type: str
sample: /path/to/www.ansible.com.csr.2019-03-09@11:22~
csr:
description: The (current or generated) CSR's content.
returned: if I(state) is C(present) and I(return_content) is C(true)
returned: if O(state) is V(present) and O(return_content) is V(true)
type: str
version_added: "1.0.0"
'''

75
plugins/modules/openssl_csr_info.py
View File

@@ -32,19 +32,19 @@ options:
path:
description:
- Remote absolute path where the CSR file is loaded from.
- Either I(path) or I(content) must be specified, but not both.
- Either O(path) or O(content) must be specified, but not both.
type: path
content:
description:
- Content of the CSR file.
- Either I(path) or I(content) must be specified, but not both.
- Either O(path) or O(content) must be specified, but not both.
type: str
version_added: "1.0.0"
select_crypto_backend:
description:
- Determines which crypto backend to use.
- The default choice is C(auto), which tries to use C(cryptography) if available.
- If set to C(cryptography), will try to use the L(cryptography,https://cryptography.io/) library.
- 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 ]
@@ -52,9 +52,8 @@ options:
seealso:
- module: community.crypto.openssl_csr
- module: community.crypto.openssl_csr_pipe
- ref: community.crypto.openssl_csr_info filter <ansible_collections.community.crypto.openssl_csr_info_filter>
# - plugin: community.crypto.openssl_csr_info
# plugin_type: filter
- plugin: community.crypto.openssl_csr_info
plugin_type: filter
description: A filter variant of this module.
'''
@@ -79,11 +78,11 @@ RETURN = r'''
signature_valid:
description:
- Whether the CSR's signature is valid.
- In case the check returns C(false), the module will fail.
- In case the check returns V(false), the module will fail.
returned: success
type: bool
basic_constraints:
description: Entries in the C(basic_constraints) extension, or C(none) if extension is not present.
description: Entries in the C(basic_constraints) extension, or V(none) if extension is not present.
returned: success
type: list
elements: str
@@ -93,7 +92,7 @@ basic_constraints_critical:
returned: success
type: bool
extended_key_usage:
description: Entries in the C(extended_key_usage) extension, or C(none) if extension is not present.
description: Entries in the C(extended_key_usage) extension, or V(none) if extension is not present.
returned: success
type: list
elements: str
@@ -124,7 +123,7 @@ extensions_by_oid:
sample: "MAMCAQU="
sample: {"1.3.6.1.5.5.7.1.24": { "critical": false, "value": "MAMCAQU="}}
key_usage:
description: Entries in the C(key_usage) extension, or C(none) if extension is not present.
description: Entries in the C(key_usage) extension, or V(none) if extension is not present.
returned: success
type: str
sample: [Key Agreement, Data Encipherment]
@@ -134,8 +133,8 @@ key_usage_critical:
type: bool
subject_alt_name:
description:
- Entries in the C(subject_alt_name) extension, or C(none) if extension is not present.
- See I(name_encoding) for how IDNs are handled.
- Entries in the C(subject_alt_name) extension, or V(none) if extension is not present.
- See O(name_encoding) for how IDNs are handled.
returned: success
type: list
elements: str
@@ -145,7 +144,7 @@ subject_alt_name_critical:
returned: success
type: bool
ocsp_must_staple:
description: C(true) if the OCSP Must Staple extension is present, C(none) otherwise.
description: V(true) if the OCSP Must Staple extension is present, V(none) otherwise.
returned: success
type: bool
ocsp_must_staple_critical:
@@ -162,8 +161,8 @@ name_constraints_permitted:
name_constraints_excluded:
description:
- List of excluded subtrees the CA cannot sign certificates for.
- Is C(none) if extension is not present.
- See I(name_encoding) for how IDNs are handled.
- Is V(none) if extension is not present.
- See O(name_encoding) for how IDNs are handled.
returned: success
type: list
elements: str
@@ -172,7 +171,7 @@ name_constraints_excluded:
name_constraints_critical:
description:
- Whether the C(name_constraints) extension is critical.
- Is C(none) if extension is not present.
- Is V(none) if extension is not present.
returned: success
type: bool
version_added: 1.1.0
@@ -197,8 +196,8 @@ public_key:
public_key_type:
description:
- The CSR's public key's type.
- One of C(RSA), C(DSA), C(ECC), C(Ed25519), C(X25519), C(Ed448), or C(X448).
- Will start with C(unknown) if the key type cannot be determined.
- One of V(RSA), V(DSA), V(ECC), V(Ed25519), V(X25519), V(Ed448), or V(X448).
- Will start with V(unknown) if the key type cannot be determined.
returned: success
type: str
version_added: 1.7.0
@@ -214,57 +213,57 @@ public_key_data:
description:
- Bit size of modulus (RSA) or prime number (DSA).
type: int
returned: When C(public_key_type=RSA) or C(public_key_type=DSA)
returned: When RV(public_key_type=RSA) or RV(public_key_type=DSA)
modulus:
description:
- The RSA key's modulus.
type: int
returned: When C(public_key_type=RSA)
returned: When RV(public_key_type=RSA)
exponent:
description:
- The RSA key's public exponent.
type: int
returned: When C(public_key_type=RSA)
returned: When RV(public_key_type=RSA)
p:
description:
- The C(p) value for DSA.
- This is the prime modulus upon which arithmetic takes place.
type: int
returned: When C(public_key_type=DSA)
returned: When RV(public_key_type=DSA)
q:
description:
- The C(q) value for DSA.
- This is a prime that divides C(p - 1), and at the same time the order of the subgroup of the
multiplicative group of the prime field used.
type: int
returned: When C(public_key_type=DSA)
returned: When RV(public_key_type=DSA)
g:
description:
- The C(g) value for DSA.
- This is the element spanning the subgroup of the multiplicative group of the prime field used.
type: int
returned: When C(public_key_type=DSA)
returned: When RV(public_key_type=DSA)
curve:
description:
- The curve's name for ECC.
type: str
returned: When C(public_key_type=ECC)
returned: When RV(public_key_type=ECC)
exponent_size:
description:
- The maximum number of bits of a private key. This is basically the bit size of the subgroup used.
type: int
returned: When C(public_key_type=ECC)
returned: When RV(public_key_type=ECC)
x:
description:
- The C(x) coordinate for the public point on the elliptic curve.
type: int
returned: When C(public_key_type=ECC)
returned: When RV(public_key_type=ECC)
y:
description:
- For C(public_key_type=ECC), this is the C(y) coordinate for the public point on the elliptic curve.
- For C(public_key_type=DSA), this is the publicly known group element whose discrete logarithm w.r.t. C(g) is the private key.
- For RV(public_key_type=ECC), this is the C(y) coordinate for the public point on the elliptic curve.
- For RV(public_key_type=DSA), this is the publicly known group element whose discrete logarithm w.r.t. C(g) is the private key.
type: int
returned: When C(public_key_type=DSA) or C(public_key_type=ECC)
returned: When RV(public_key_type=DSA) or RV(public_key_type=ECC)
public_key_fingerprints:
description:
- Fingerprints of CSR's public key.
@@ -276,24 +275,24 @@ public_key_fingerprints:
subject_key_identifier:
description:
- The CSR's subject key identifier.
- The identifier is returned in hexadecimal, with C(:) used to separate bytes.
- Is C(none) if the C(SubjectKeyIdentifier) extension is not present.
- The identifier is returned in hexadecimal, with V(:) used to separate bytes.
- Is V(none) if the C(SubjectKeyIdentifier) extension is not present.
returned: success
type: str
sample: '00:11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee:ff:00:11:22:33'
authority_key_identifier:
description:
- The CSR's authority key identifier.
- The identifier is returned in hexadecimal, with C(:) used to separate bytes.
- Is C(none) if the C(AuthorityKeyIdentifier) extension is not present.
- The identifier is returned in hexadecimal, with V(:) used to separate bytes.
- Is V(none) if the C(AuthorityKeyIdentifier) extension is not present.
returned: success
type: str
sample: '00:11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee:ff:00:11:22:33'
authority_cert_issuer:
description:
- The CSR's authority cert issuer as a list of general names.
- Is C(none) if the C(AuthorityKeyIdentifier) extension is not present.
- See I(name_encoding) for how IDNs are handled.
- Is V(none) if the C(AuthorityKeyIdentifier) extension is not present.
- See O(name_encoding) for how IDNs are handled.
returned: success
type: list
elements: str
@@ -301,7 +300,7 @@ authority_cert_issuer:
authority_cert_serial_number:
description:
- The CSR's authority cert serial number.
- Is C(none) if the C(AuthorityKeyIdentifier) extension is not present.
- Is V(none) if the C(AuthorityKeyIdentifier) extension is not present.
returned: success
type: int
sample: 12345

10
plugins/modules/openssl_csr_pipe.py
View File

@@ -34,6 +34,14 @@ options:
description:
- The existing CSR.
type: str
privatekey_path:
description:
- The path to the private key to use when signing the certificate signing request.
- Either O(privatekey_path) or O(privatekey_content) must be specified, but not both.
privatekey_content:
description:
- The content of the private key to use when signing the certificate signing request.
- Either O(privatekey_path) or O(privatekey_content) must be specified, but not both.
seealso:
- module: community.crypto.openssl_csr
'''
@@ -65,7 +73,7 @@ RETURN = r'''
privatekey:
description:
- Path to the TLS/SSL private key the CSR was generated for
- Will be C(none) if the private key has been provided in I(privatekey_content).
- Will be V(none) if the private key has been provided in O(privatekey_content).
returned: changed or success
type: str
sample: /etc/ssl/private/ansible.com.pem

16
plugins/modules/openssl_dhparam.py
View File

@@ -18,10 +18,10 @@ description:
- This module uses file common arguments to specify generated file permissions.
- "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."
your existing DH params, consider using the O(backup) option."
- The module can use the cryptography Python library, or the C(openssl) executable.
By default, it tries to detect which one is available. This can be overridden
with the I(select_crypto_backend) option.
with the O(select_crypto_backend) option.
requirements:
- Either cryptography >= 2.0
- Or OpenSSL binary C(openssl)
@@ -70,16 +70,16 @@ options:
select_crypto_backend:
description:
- Determines which crypto backend to use.
- The default choice is C(auto), which tries to use C(cryptography) if available, and falls back to C(openssl).
- If set to C(openssl), will try to use the OpenSSL C(openssl) executable.
- If set to C(cryptography), will try to use the L(cryptography,https://cryptography.io/) library.
- 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 OpenSSL C(openssl) executable.
- If set to V(cryptography), will try to use the L(cryptography,https://cryptography.io/) library.
type: str
default: auto
choices: [ auto, cryptography, openssl ]
version_added: "1.0.0"
return_content:
description:
- If set to C(true), will return the (current or generated) DH parameter's content as I(dhparams).
- If set to V(true), will return the (current or generated) DH parameter's content as RV(dhparams).
type: bool
default: false
version_added: "1.0.0"
@@ -120,12 +120,12 @@ filename:
sample: /etc/ssl/dhparams.pem
backup_file:
description: Name of backup file created.
returned: changed and if I(backup) is C(true)
returned: changed and if O(backup) is V(true)
type: str
sample: /path/to/dhparams.pem.2019-03-09@11:22~
dhparams:
description: The (current or generated) DH params' content.
returned: if I(state) is C(present) and I(return_content) is C(true)
returned: if O(state) is V(present) and O(return_content) is V(true)
type: str
version_added: "1.0.0"
'''

44
plugins/modules/openssl_pkcs12.py
View File

@@ -19,8 +19,8 @@ description:
- This module allows one to (re-)generate PKCS#12.
- The module can use the cryptography Python library, or the pyOpenSSL Python
library. By default, it tries to detect which one is available, assuming none of the
I(iter_size) and I(maciter_size) options are used. This can be overridden with the
I(select_crypto_backend) option.
O(iter_size) and O(maciter_size) options are used. This can be overridden with the
O(select_crypto_backend) option.
# Please note that the C(pyopenssl) backend has been deprecated in community.crypto x.y.0,
# and will be removed in community.crypto (x+1).0.0.
requirements:
@@ -39,21 +39,21 @@ attributes:
options:
action:
description:
- C(export) or C(parse) a PKCS#12.
- V(export) or V(parse) a PKCS#12.
type: str
default: export
choices: [ export, parse ]
other_certificates:
description:
- List of other certificates to include. Pre Ansible 2.8 this parameter was called I(ca_certificates).
- List of other certificates to include. Pre Ansible 2.8 this parameter was called O(ca_certificates).
- Assumes there is one PEM-encoded certificate per file. If a file contains multiple PEM certificates,
set I(other_certificates_parse_all) to C(true).
set O(other_certificates_parse_all) to V(true).
type: list
elements: path
aliases: [ ca_certificates ]
other_certificates_parse_all:
description:
- If set to C(true), assumes that the files mentioned in I(other_certificates) can contain more than one
- If set to V(true), assumes that the files mentioned in O(other_certificates) can contain more than one
certificate per file (or even none per file).
type: bool
default: false
@@ -77,21 +77,21 @@ options:
description:
- Number of times to repeat the encryption step.
- This is B(not considered during idempotency checks).
- This is only used by the C(pyopenssl) backend, or when I(encryption_level=compatibility2022).
- When using it, the default is C(2048) for C(pyopenssl) and C(50000) for C(cryptography).
- This is only used by the C(pyopenssl) backend, or when O(encryption_level=compatibility2022).
- When using it, the default is V(2048) for C(pyopenssl) and V(50000) for C(cryptography).
type: int
maciter_size:
description:
- Number of times to repeat the MAC step.
- This is B(not considered during idempotency checks).
- This is only used by the C(pyopenssl) backend. When using it, the default is C(1).
- This is only used by the C(pyopenssl) backend. When using it, the default is V(1).
type: int
encryption_level:
description:
- Determines the encryption level used.
- C(auto) uses the default of the selected backend. For C(cryptography), this is what the
- V(auto) uses the default of the selected backend. For C(cryptography), this is what the
cryptography library's specific version considers the best available encryption.
- C(compatibility2022) uses compatibility settings for older software in 2022.
- V(compatibility2022) uses compatibility settings for older software in 2022.
This is only supported by the C(cryptography) backend if cryptography >= 38.0.0 is available.
- B(Note) that this option is B(not used for idempotency).
choices:
@@ -119,18 +119,18 @@ options:
privatekey_path:
description:
- File to read private key from.
- Mutually exclusive with I(privatekey_content).
- Mutually exclusive with O(privatekey_content).
type: path
privatekey_content:
description:
- Content of the private key file.
- Mutually exclusive with I(privatekey_path).
- Mutually exclusive with O(privatekey_path).
type: str
version_added: "2.3.0"
state:
description:
- Whether the file should exist or not.
All parameters except C(path) are ignored when state is C(absent).
All parameters except O(path) are ignored when state is V(absent).
choices: [ absent, present ]
default: present
type: str
@@ -146,18 +146,18 @@ options:
default: false
return_content:
description:
- If set to C(true), will return the (current or generated) PKCS#12's content as I(pkcs12).
- If set to V(true), will return the (current or generated) PKCS#12's content as RV(pkcs12).
type: bool
default: false
version_added: "1.0.0"
select_crypto_backend:
description:
- Determines which crypto backend to use.
- The default choice is C(auto), which tries to use C(cryptography) if available, and falls back to C(pyopenssl).
If I(iter_size) is used together with I(encryption_level != compatibility2022), or if I(maciter_size) is used,
C(auto) will always result in C(pyopenssl) to be chosen for backwards compatibility.
- If set to C(pyopenssl), will try to use the L(pyOpenSSL,https://pypi.org/project/pyOpenSSL/) library.
- If set to C(cryptography), will try to use the L(cryptography,https://cryptography.io/) library.
- The default choice is V(auto), which tries to use C(cryptography) if available, and falls back to C(pyopenssl).
If O(iter_size) is used together with O(encryption_level) is not V(compatibility2022), or if O(maciter_size) is used,
V(auto) will always result in C(pyopenssl) to be chosen for backwards compatibility.
- If set to V(pyopenssl), will try to use the L(pyOpenSSL,https://pypi.org/project/pyOpenSSL/) library.
- If set to V(cryptography), will try to use the L(cryptography,https://cryptography.io/) library.
# - Please note that the C(pyopenssl) backend has been deprecated in community.crypto x.y.0, and will be
# removed in community.crypto (x+1).0.0.
# From that point on, only the C(cryptography) backend will be available.
@@ -255,12 +255,12 @@ privatekey:
sample: /etc/ssl/private/ansible.com.pem
backup_file:
description: Name of backup file created.
returned: changed and if I(backup) is C(true)
returned: changed and if O(backup) is V(true)
type: str
sample: /path/to/ansible.com.pem.2019-03-09@11:22~
pkcs12:
description: The (current or generated) PKCS#12's content Base64 encoded.
returned: if I(state) is C(present) and I(return_content) is C(true)
returned: if O(state) is V(present) and O(return_content) is V(true)
type: str
version_added: "1.0.0"
'''

21
plugins/modules/openssl_privatekey.py
View File

@@ -15,7 +15,12 @@ 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 C(0600) if I(mode) is not explicitly set.
- 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)
@@ -45,8 +50,8 @@ options:
default: false
path:
description:
- Name of the file in which the generated TLS/SSL private key will be written. It will have C(0600) mode
if I(mode) is not explicitly set.
- 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:
@@ -61,10 +66,10 @@ options:
default: false
return_content:
description:
- If set to C(true), will return the (current or generated) private key's content as I(privatekey).
- 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 I(no_log) task option to avoid the output being shown. See also
- 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
@@ -116,7 +121,7 @@ type:
sample: RSA
curve:
description: Elliptic curve used to generate the TLS/SSL private key.
returned: changed or success, and I(type) is C(ECC)
returned: changed or success, and O(type) is V(ECC)
type: str
sample: secp256r1
filename:
@@ -138,14 +143,14 @@ fingerprint:
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 I(backup) is C(true)
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 I(state) is C(present) and I(return_content) is C(true)
returned: if O(state) is V(present) and O(return_content) is V(true)
type: str
version_added: '1.0.0'
'''

8
plugins/modules/openssl_privatekey_convert.py
View File

@@ -16,7 +16,7 @@ short_description: Convert OpenSSL private keys
version_added: 2.1.0
description:
- This module allows one to convert OpenSSL private keys.
- The default mode for the private key file will be C(0600) if I(mode) is not explicitly set.
- The default mode for the private key file will be V(0600) if O(mode) is not explicitly set.
author:
- Felix Fontein (@felixfontein)
extends_documentation_fragment:
@@ -34,8 +34,8 @@ attributes:
options:
dest_path:
description:
- Name of the file in which the generated TLS/SSL private key will be written. It will have C(0600) mode
if I(mode) is not explicitly set.
- 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
backup:
@@ -59,7 +59,7 @@ EXAMPLES = r'''
RETURN = r'''
backup_file:
description: Name of backup file created.
returned: changed and if I(backup) is C(true)
returned: changed and if O(backup) is V(true)
type: str
sample: /path/to/privatekey.pem.2019-03-09@11:22~
'''

55
plugins/modules/openssl_privatekey_info.py
View File

@@ -18,8 +18,8 @@ description:
- This module allows one to query information on OpenSSL private keys.
- In case the key consistency checks fail, the module will fail as this indicates a faked
private key. In this case, all return variables are still returned. Note that key consistency
checks are not available all key types; if none is available, C(none) is returned for
C(key_is_consistent).
checks are not available all key types; if none is available, V(none) is returned for
RV(key_is_consistent).
- It uses the cryptography python library to interact with OpenSSL.
requirements:
- cryptography >= 1.2.3
@@ -37,7 +37,7 @@ options:
content:
description:
- Content of the private key file.
- Either I(path) or I(content) must be specified, but not both.
- Either O(path) or O(content) must be specified, but not both.
type: str
version_added: '1.0.0'
passphrase:
@@ -47,7 +47,7 @@ options:
return_private_key_data:
description:
- Whether to return private key data.
- Only set this to C(true) when you want private information about this key to
- Only set this to V(true) when you want private information about this key to
leave the remote machine.
- "B(WARNING:) you have to make sure that private key data is not accidentally logged!"
type: bool
@@ -67,8 +67,8 @@ options:
select_crypto_backend:
description:
- Determines which crypto backend to use.
- The default choice is C(auto), which tries to use C(cryptography) if available.
- If set to C(cryptography), will try to use the L(cryptography,https://cryptography.io/) library.
- 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 ]
@@ -76,9 +76,8 @@ options:
seealso:
- module: community.crypto.openssl_privatekey
- module: community.crypto.openssl_privatekey_pipe
- ref: community.crypto.openssl_privatekey_info filter <ansible_collections.community.crypto.openssl_privatekey_info_filter>
# - plugin: community.crypto.openssl_privatekey_info
# plugin_type: filter
- plugin: community.crypto.openssl_privatekey_info
plugin_type: filter
description: A filter variant of this module.
'''
@@ -108,10 +107,10 @@ can_parse_key:
type: bool
key_is_consistent:
description:
- Whether the key is consistent. Can also return C(none) next to C(true) and
C(false), to indicate that consistency could not be checked.
- In case the check returns C(false), the module will fail.
returned: when I(check_consistency=true)
- Whether the key is consistent. Can also return V(none) next to V(true) and
V(false), to indicate that consistency could not be checked.
- In case the check returns V(false), the module will fail.
returned: when O(check_consistency=true)
type: bool
public_key:
description: Private key's public key in PEM format.
@@ -129,8 +128,8 @@ public_key_fingerprints:
type:
description:
- The key's type.
- One of C(RSA), C(DSA), C(ECC), C(Ed25519), C(X25519), C(Ed448), or C(X448).
- Will start with C(unknown) if the key type cannot be determined.
- One of V(RSA), V(DSA), V(ECC), V(Ed25519), V(X25519), V(Ed448), or V(X448).
- Will start with V(unknown) if the key type cannot be determined.
returned: success
type: str
sample: RSA
@@ -144,61 +143,61 @@ public_data:
description:
- Bit size of modulus (RSA) or prime number (DSA).
type: int
returned: When C(type=RSA) or C(type=DSA)
returned: When RV(type=RSA) or RV(type=DSA)
modulus:
description:
- The RSA key's modulus.
type: int
returned: When C(type=RSA)
returned: When RV(type=RSA)
exponent:
description:
- The RSA key's public exponent.
type: int
returned: When C(type=RSA)
returned: When RV(type=RSA)
p:
description:
- The C(p) value for DSA.
- This is the prime modulus upon which arithmetic takes place.
type: int
returned: When C(type=DSA)
returned: When RV(type=DSA)
q:
description:
- The C(q) value for DSA.
- This is a prime that divides C(p - 1), and at the same time the order of the subgroup of the
multiplicative group of the prime field used.
type: int
returned: When C(type=DSA)
returned: When RV(type=DSA)
g:
description:
- The C(g) value for DSA.
- This is the element spanning the subgroup of the multiplicative group of the prime field used.
type: int
returned: When C(type=DSA)
returned: When RV(type=DSA)
curve:
description:
- The curve's name for ECC.
type: str
returned: When C(type=ECC)
returned: When RV(type=ECC)
exponent_size:
description:
- The maximum number of bits of a private key. This is basically the bit size of the subgroup used.
type: int
returned: When C(type=ECC)
returned: When RV(type=ECC)
x:
description:
- The C(x) coordinate for the public point on the elliptic curve.
type: int
returned: When C(type=ECC)
returned: When RV(type=ECC)
y:
description:
- For C(type=ECC), this is the C(y) coordinate for the public point on the elliptic curve.
- For C(type=DSA), this is the publicly known group element whose discrete logarithm w.r.t. C(g) is the private key.
- For RV(type=ECC), this is the C(y) coordinate for the public point on the elliptic curve.
- For RV(type=DSA), this is the publicly known group element whose discrete logarithm w.r.t. C(g) is the private key.
type: int
returned: When C(type=DSA) or C(type=ECC)
returned: When RV(type=DSA) or RV(type=ECC)
private_data:
description:
- Private key data. Depends on key type.
returned: success and when I(return_private_key_data) is set to C(true)
returned: success and when O(return_private_key_data) is set to V(true)
type: dict
'''

37
plugins/modules/openssl_privatekey_pipe.py
View File

@@ -17,7 +17,7 @@ version_added: 1.3.0
description:
- This module allows one to (re)generate OpenSSL private keys without disk access.
- This allows to read and write keys to vaults without having to write intermediate versions to disk.
- Make sure to not write the result of this module into logs or to the console, as it contains private key data! Use the I(no_log) task option to be sure.
- Make sure to not write the result of this module into logs or to the console, as it contains private key data! Use the C(no_log) task option to be sure.
- Note that this module is implemented as an L(action plugin,https://docs.ansible.com/ansible/latest/plugins/action.html)
and will always be executed on the controller.
author:
@@ -47,16 +47,39 @@ options:
type: str
content_base64:
description:
- Set to C(true) if the content is base64 encoded.
- Set to V(true) if the content is base64 encoded.
type: bool
default: false
return_current_key:
description:
- Set to C(true) to return the current private key when the module did not generate a new one.
- Note that in case of check mode, when this option is not set to C(true), the module always returns the
- Set to V(true) to return the current private key when the module did not generate a new one.
- Note that in case of check mode, when this option is not set to V(true), the module always returns the
current key (if it was provided) and Ansible will replace it by C(VALUE_SPECIFIED_IN_NO_LOG_PARAMETER).
type: bool
default: false
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.
- 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).
seealso:
- module: community.crypto.openssl_privatekey
- module: community.crypto.openssl_privatekey_info
@@ -106,7 +129,7 @@ type:
sample: RSA
curve:
description: Elliptic curve used to generate the TLS/SSL private key.
returned: changed or success, and I(type) is C(ECC)
returned: changed or success, and O(type) is V(ECC)
type: str
sample: secp256r1
fingerprint:
@@ -125,8 +148,8 @@ privatekey:
description:
- The generated private key's content.
- Please note that if the result is not changed, the current private key will only be returned
if the I(return_current_key) option is set to C(true).
if the O(return_current_key) option is set to V(true).
- Will be Base64-encoded if the key is in raw format.
returned: changed, or I(return_current_key) is C(true)
returned: changed, or O(return_current_key) is V(true)
type: str
'''

22
plugins/modules/openssl_publickey.py
View File

@@ -20,7 +20,7 @@ description:
- The module uses the cryptography Python library.
requirements:
- cryptography >= 1.2.3 (older versions might work as well)
- Needs cryptography >= 1.4 if I(format) is C(OpenSSH)
- Needs cryptography >= 1.4 if O(format) is C(OpenSSH)
author:
- Yanis Guenane (@Spredzy)
- Felix Fontein (@felixfontein)
@@ -61,14 +61,14 @@ options:
privatekey_path:
description:
- Path to the TLS/SSL private key from which to generate the public key.
- Either I(privatekey_path) or I(privatekey_content) must be specified, but not both.
If I(state) is C(present), one of them is required.
- Either O(privatekey_path) or O(privatekey_content) must be specified, but not both.
If O(state) is V(present), one of them is required.
type: path
privatekey_content:
description:
- The content of the TLS/SSL private key from which to generate the public key.
- Either I(privatekey_path) or I(privatekey_content) must be specified, but not both.
If I(state) is C(present), one of them is required.
- Either O(privatekey_path) or O(privatekey_content) must be specified, but not both.
If O(state) is V(present), one of them is required.
type: str
version_added: '1.0.0'
privatekey_passphrase:
@@ -84,14 +84,14 @@ options:
select_crypto_backend:
description:
- Determines which crypto backend to use.
- The default choice is C(auto), which tries to use C(cryptography) if available.
- If set to C(cryptography), will try to use the L(cryptography,https://cryptography.io/) library.
- 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 ]
return_content:
description:
- If set to C(true), will return the (current or generated) public key's content as I(publickey).
- If set to V(true), will return the (current or generated) public key's content as RV(publickey).
type: bool
default: false
version_added: '1.0.0'
@@ -145,7 +145,7 @@ RETURN = r'''
privatekey:
description:
- Path to the TLS/SSL private key the public key was generated from.
- Will be C(none) if the private key has been provided in I(privatekey_content).
- Will be V(none) if the private key has been provided in O(privatekey_content).
returned: changed or success
type: str
sample: /etc/ssl/private/ansible.com.pem
@@ -173,12 +173,12 @@ fingerprint:
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 I(backup) is C(true)
returned: changed and if O(backup) is V(true)
type: str
sample: /path/to/publickey.pem.2019-03-09@11:22~
publickey:
description: The (current or generated) public key's content.
returned: if I(state) is C(present) and I(return_content) is C(true)
returned: if O(state) is V(present) and O(return_content) is V(true)
type: str
version_added: '1.0.0'
'''

39
plugins/modules/openssl_publickey_info.py
View File

@@ -32,14 +32,14 @@ options:
content:
description:
- Content of the public key file.
- Either I(path) or I(content) must be specified, but not both.
- Either O(path) or O(content) must be specified, but not both.
type: str
select_crypto_backend:
description:
- Determines which crypto backend to use.
- The default choice is C(auto), which tries to use C(cryptography) if available.
- If set to C(cryptography), will try to use the L(cryptography,https://cryptography.io/) library.
- 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 ]
@@ -47,9 +47,8 @@ options:
seealso:
- module: community.crypto.openssl_publickey
- module: community.crypto.openssl_privatekey_info
- ref: community.crypto.openssl_publickey_info filter <ansible_collections.community.crypto.openssl_publickey_info_filter>
# - plugin: community.crypto.openssl_publickey_info
# plugin_type: filter
- plugin: community.crypto.openssl_publickey_info
plugin_type: filter
description: A filter variant of this module.
'''
@@ -85,8 +84,8 @@ fingerprints:
type:
description:
- The key's type.
- One of C(RSA), C(DSA), C(ECC), C(Ed25519), C(X25519), C(Ed448), or C(X448).
- Will start with C(unknown) if the key type cannot be determined.
- One of V(RSA), V(DSA), V(ECC), V(Ed25519), V(X25519), V(Ed448), or V(X448).
- Will start with V(unknown) if the key type cannot be determined.
returned: success
type: str
sample: RSA
@@ -100,57 +99,57 @@ public_data:
description:
- Bit size of modulus (RSA) or prime number (DSA).
type: int
returned: When C(type=RSA) or C(type=DSA)
returned: When RV(type=RSA) or RV(type=DSA)
modulus:
description:
- The RSA key's modulus.
type: int
returned: When C(type=RSA)
returned: When RV(type=RSA)
exponent:
description:
- The RSA key's public exponent.
type: int
returned: When C(type=RSA)
returned: When RV(type=RSA)
p:
description:
- The C(p) value for DSA.
- This is the prime modulus upon which arithmetic takes place.
type: int
returned: When C(type=DSA)
returned: When RV(type=DSA)
q:
description:
- The C(q) value for DSA.
- This is a prime that divides C(p - 1), and at the same time the order of the subgroup of the
multiplicative group of the prime field used.
type: int
returned: When C(type=DSA)
returned: When RV(type=DSA)
g:
description:
- The C(g) value for DSA.
- This is the element spanning the subgroup of the multiplicative group of the prime field used.
type: int
returned: When C(type=DSA)
returned: When RV(type=DSA)
curve:
description:
- The curve's name for ECC.
type: str
returned: When C(type=ECC)
returned: When RV(type=ECC)
exponent_size:
description:
- The maximum number of bits of a private key. This is basically the bit size of the subgroup used.
type: int
returned: When C(type=ECC)
returned: When RV(type=ECC)
x:
description:
- The C(x) coordinate for the public point on the elliptic curve.
type: int
returned: When C(type=ECC)
returned: When RV(type=ECC)
y:
description:
- For C(type=ECC), this is the C(y) coordinate for the public point on the elliptic curve.
- For C(type=DSA), this is the publicly known group element whose discrete logarithm w.r.t. C(g) is the private key.
- For RV(type=ECC), this is the C(y) coordinate for the public point on the elliptic curve.
- For RV(type=DSA), this is the publicly known group element whose discrete logarithm w.r.t. C(g) is the private key.
type: int
returned: When C(type=DSA) or C(type=ECC)
returned: When RV(type=DSA) or RV(type=ECC)
'''

8
plugins/modules/openssl_signature.py
View File

@@ -35,12 +35,12 @@ options:
privatekey_path:
description:
- The path to the private key to use when signing.
- Either I(privatekey_path) or I(privatekey_content) must be specified, but not both.
- Either O(privatekey_path) or O(privatekey_content) must be specified, but not both.
type: path
privatekey_content:
description:
- The content of the private key to use when signing the certificate signing request.
- Either I(privatekey_path) or I(privatekey_content) must be specified, but not both.
- Either O(privatekey_path) or O(privatekey_content) must be specified, but not both.
type: str
privatekey_passphrase:
description:
@@ -56,8 +56,8 @@ options:
select_crypto_backend:
description:
- Determines which crypto backend to use.
- The default choice is C(auto), which tries to use C(cryptography) if available.
- If set to C(cryptography), will try to use the L(cryptography,https://cryptography.io/) library.
- 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 ]

10
plugins/modules/openssl_signature_info.py
View File

@@ -35,12 +35,12 @@ options:
certificate_path:
description:
- The path to the certificate used to verify the signature.
- Either I(certificate_path) or I(certificate_content) must be specified, but not both.
- Either O(certificate_path) or O(certificate_content) must be specified, but not both.
type: path
certificate_content:
description:
- The content of the certificate used to verify the signature.
- Either I(certificate_path) or I(certificate_content) must be specified, but not both.
- Either O(certificate_path) or O(certificate_content) must be specified, but not both.
type: str
signature:
description: Base64 encoded signature.
@@ -49,8 +49,8 @@ options:
select_crypto_backend:
description:
- Determines which crypto backend to use.
- The default choice is C(auto), which tries to use C(cryptography) if available.
- If set to C(cryptography), will try to use the L(cryptography,https://cryptography.io/) library.
- 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 ]
@@ -87,7 +87,7 @@ EXAMPLES = r'''
RETURN = r'''
valid:
description: C(true) means the signature was valid for the given file, C(false) means it was not.
description: V(true) means the signature was valid for the given file, V(false) means it was not.
returned: success
type: bool
'''

16
plugins/modules/x509_certificate.py
View File

@@ -15,16 +15,16 @@ DOCUMENTATION = r'''
module: x509_certificate
short_description: Generate and/or check OpenSSL certificates
description:
- It implements a notion of provider (one of C(selfsigned), C(ownca), C(acme), and C(entrust))
- It implements a notion of provider (one of V(selfsigned), V(ownca), V(acme), and V(entrust))
for your certificate.
- "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."
your existing certificate, consider using the O(backup) option."
- Note that this module was called C(openssl_certificate) when included directly in Ansible up to version 2.9.
When moved to the collection C(community.crypto), it was renamed to
M(community.crypto.x509_certificate). From Ansible 2.10 on, it can still be used by the
old short name (or by C(ansible.builtin.openssl_certificate)), which redirects to
C(community.crypto.x509_certificate). When using FQCNs or when using the
M(community.crypto.x509_certificate). When using FQCNs or when using the
L(collections,https://docs.ansible.com/ansible/latest/user_guide/collections_using.html#using-collections-in-a-playbook)
keyword, the new name M(community.crypto.x509_certificate) should be used to avoid
a deprecation warning.
@@ -67,15 +67,15 @@ options:
Please see the examples on how to emulate it with
M(community.crypto.x509_certificate_info), M(community.crypto.openssl_csr_info),
M(community.crypto.openssl_privatekey_info) and M(ansible.builtin.assert).
- "The C(entrust) provider was added for Ansible 2.9 and requires credentials for the
- "The V(entrust) provider was added for Ansible 2.9 and requires credentials for the
L(Entrust Certificate Services,https://www.entrustdatacard.com/products/categories/ssl-certificates) (ECS) API."
- Required if I(state) is C(present).
- Required if O(state) is V(present).
type: str
choices: [ acme, entrust, ownca, selfsigned ]
return_content:
description:
- If set to C(true), will return the (current or generated) certificate's content as I(certificate).
- If set to V(true), will return the (current or generated) certificate's content as RV(certificate).
type: bool
default: false
version_added: '1.0.0'
@@ -222,12 +222,12 @@ filename:
sample: /etc/ssl/crt/www.ansible.com.crt
backup_file:
description: Name of backup file created.
returned: changed and if I(backup) is C(true)
returned: changed and if O(backup) is V(true)
type: str
sample: /path/to/www.ansible.com.crt.2019-03-09@11:22~
certificate:
description: The (current or generated) certificate's content.
returned: if I(state) is C(present) and I(return_content) is C(true)
returned: if O(state) is V(present) and O(return_content) is V(true)
type: str
version_added: '1.0.0'
'''

79
plugins/modules/x509_certificate_info.py
View File

@@ -21,7 +21,7 @@ description:
up to version 2.9. When moved to the collection C(community.crypto), it was renamed to
M(community.crypto.x509_certificate_info). From Ansible 2.10 on, it can still be used by the
old short name (or by C(ansible.builtin.openssl_certificate_info)), which redirects to
C(community.crypto.x509_certificate_info). When using FQCNs or when using the
M(community.crypto.x509_certificate_info). When using FQCNs or when using the
L(collections,https://docs.ansible.com/ansible/latest/user_guide/collections_using.html#using-collections-in-a-playbook)
keyword, the new name M(community.crypto.x509_certificate_info) should be used to avoid
a deprecation warning.
@@ -39,31 +39,31 @@ options:
path:
description:
- Remote absolute path where the certificate file is loaded from.
- Either I(path) or I(content) must be specified, but not both.
- Either O(path) or O(content) must be specified, but not both.
- PEM and DER formats are supported.
type: path
content:
description:
- Content of the X.509 certificate in PEM format.
- Either I(path) or I(content) must be specified, but not both.
- Either O(path) or O(content) must be specified, but not both.
type: str
version_added: '1.0.0'
valid_at:
description:
- A dict of names mapping to time specifications. Every time specified here
will be checked whether the certificate is valid at this point. See the
C(valid_at) return value for informations on the result.
RV(valid_at) return value for informations on the result.
- 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]) (for example C(+32w1d2h)), and ASN.1 TIME (in other words, pattern C(YYYYMMDDHHMMSSZ)).
+ C([w | d | h | m | s]) (for example V(+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:
description:
- Determines which crypto backend to use.
- The default choice is C(auto), which tries to use C(cryptography) if available.
- If set to C(cryptography), will try to use the L(cryptography,https://cryptography.io/) library.
- 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 ]
@@ -74,9 +74,8 @@ notes:
seealso:
- module: community.crypto.x509_certificate
- module: community.crypto.x509_certificate_pipe
- ref: community.crypto.x509_certificate_info filter <ansible_collections.community.crypto.x509_certificate_info_filter>
# - plugin: community.crypto.x509_certificate_info
# plugin_type: filter
- plugin: community.crypto.x509_certificate_info
plugin_type: filter
description: A filter variant of this module.
'''
@@ -127,7 +126,7 @@ expired:
returned: success
type: bool
basic_constraints:
description: Entries in the C(basic_constraints) extension, or C(none) if extension is not present.
description: Entries in the C(basic_constraints) extension, or V(none) if extension is not present.
returned: success
type: list
elements: str
@@ -137,7 +136,7 @@ basic_constraints_critical:
returned: success
type: bool
extended_key_usage:
description: Entries in the C(extended_key_usage) extension, or C(none) if extension is not present.
description: Entries in the C(extended_key_usage) extension, or V(none) if extension is not present.
returned: success
type: list
elements: str
@@ -168,7 +167,7 @@ extensions_by_oid:
sample: "MAMCAQU="
sample: {"1.3.6.1.5.5.7.1.24": { "critical": false, "value": "MAMCAQU="}}
key_usage:
description: Entries in the C(key_usage) extension, or C(none) if extension is not present.
description: Entries in the C(key_usage) extension, or V(none) if extension is not present.
returned: success
type: str
sample: [Key Agreement, Data Encipherment]
@@ -178,8 +177,8 @@ key_usage_critical:
type: bool
subject_alt_name:
description:
- Entries in the C(subject_alt_name) extension, or C(none) if extension is not present.
- See I(name_encoding) for how IDNs are handled.
- Entries in the C(subject_alt_name) extension, or V(none) if extension is not present.
- See O(name_encoding) for how IDNs are handled.
returned: success
type: list
elements: str
@@ -189,7 +188,7 @@ subject_alt_name_critical:
returned: success
type: bool
ocsp_must_staple:
description: C(true) if the OCSP Must Staple extension is present, C(none) otherwise.
description: V(true) if the OCSP Must Staple extension is present, V(none) otherwise.
returned: success
type: bool
ocsp_must_staple_critical:
@@ -240,8 +239,8 @@ public_key:
public_key_type:
description:
- The certificate's public key's type.
- One of C(RSA), C(DSA), C(ECC), C(Ed25519), C(X25519), C(Ed448), or C(X448).
- Will start with C(unknown) if the key type cannot be determined.
- One of V(RSA), V(DSA), V(ECC), V(Ed25519), V(X25519), V(Ed448), or V(X448).
- Will start with V(unknown) if the key type cannot be determined.
returned: success
type: str
version_added: 1.7.0
@@ -257,57 +256,57 @@ public_key_data:
description:
- Bit size of modulus (RSA) or prime number (DSA).
type: int
returned: When C(public_key_type=RSA) or C(public_key_type=DSA)
returned: When RV(public_key_type=RSA) or RV(public_key_type=DSA)
modulus:
description:
- The RSA key's modulus.
type: int
returned: When C(public_key_type=RSA)
returned: When RV(public_key_type=RSA)
exponent:
description:
- The RSA key's public exponent.
type: int
returned: When C(public_key_type=RSA)
returned: When RV(public_key_type=RSA)
p:
description:
- The C(p) value for DSA.
- This is the prime modulus upon which arithmetic takes place.
type: int
returned: When C(public_key_type=DSA)
returned: When RV(public_key_type=DSA)
q:
description:
- The C(q) value for DSA.
- This is a prime that divides C(p - 1), and at the same time the order of the subgroup of the
multiplicative group of the prime field used.
type: int
returned: When C(public_key_type=DSA)
returned: When RV(public_key_type=DSA)
g:
description:
- The C(g) value for DSA.
- This is the element spanning the subgroup of the multiplicative group of the prime field used.
type: int
returned: When C(public_key_type=DSA)
returned: When RV(public_key_type=DSA)
curve:
description:
- The curve's name for ECC.
type: str
returned: When C(public_key_type=ECC)
returned: When RV(public_key_type=ECC)
exponent_size:
description:
- The maximum number of bits of a private key. This is basically the bit size of the subgroup used.
type: int
returned: When C(public_key_type=ECC)
returned: When RV(public_key_type=ECC)
x:
description:
- The C(x) coordinate for the public point on the elliptic curve.
type: int
returned: When C(public_key_type=ECC)
returned: When RV(public_key_type=ECC)
y:
description:
- For C(public_key_type=ECC), this is the C(y) coordinate for the public point on the elliptic curve.
- For C(public_key_type=DSA), this is the publicly known group element whose discrete logarithm w.r.t. C(g) is the private key.
- For RV(public_key_type=ECC), this is the C(y) coordinate for the public point on the elliptic curve.
- For RV(public_key_type=DSA), this is the publicly known group element whose discrete logarithm w.r.t. C(g) is the private key.
type: int
returned: When C(public_key_type=DSA) or C(public_key_type=ECC)
returned: When RV(public_key_type=DSA) or RV(public_key_type=ECC)
public_key_fingerprints:
description:
- Fingerprints of certificate's public key.
@@ -341,7 +340,7 @@ version:
type: int
sample: 3
valid_at:
description: For every time stamp provided in the I(valid_at) option, a
description: For every time stamp provided in the O(valid_at) option, a
boolean whether the certificate is valid at that point in time
or not.
returned: success
@@ -349,24 +348,24 @@ valid_at:
subject_key_identifier:
description:
- The certificate's subject key identifier.
- The identifier is returned in hexadecimal, with C(:) used to separate bytes.
- Is C(none) if the C(SubjectKeyIdentifier) extension is not present.
- The identifier is returned in hexadecimal, with V(:) used to separate bytes.
- Is V(none) if the C(SubjectKeyIdentifier) extension is not present.
returned: success
type: str
sample: '00:11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee:ff:00:11:22:33'
authority_key_identifier:
description:
- The certificate's authority key identifier.
- The identifier is returned in hexadecimal, with C(:) used to separate bytes.
- Is C(none) if the C(AuthorityKeyIdentifier) extension is not present.
- The identifier is returned in hexadecimal, with V(:) used to separate bytes.
- Is V(none) if the C(AuthorityKeyIdentifier) extension is not present.
returned: success
type: str
sample: '00:11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee:ff:00:11:22:33'
authority_cert_issuer:
description:
- The certificate's authority cert issuer as a list of general names.
- Is C(none) if the C(AuthorityKeyIdentifier) extension is not present.
- See I(name_encoding) for how IDNs are handled.
- Is V(none) if the C(AuthorityKeyIdentifier) extension is not present.
- See O(name_encoding) for how IDNs are handled.
returned: success
type: list
elements: str
@@ -374,18 +373,18 @@ authority_cert_issuer:
authority_cert_serial_number:
description:
- The certificate's authority cert serial number.
- Is C(none) if the C(AuthorityKeyIdentifier) extension is not present.
- Is V(none) if the C(AuthorityKeyIdentifier) extension is not present.
returned: success
type: int
sample: 12345
ocsp_uri:
description: The OCSP responder URI, if included in the certificate. Will be
C(none) if no OCSP responder URI is included.
V(none) if no OCSP responder URI is included.
returned: success
type: str
issuer_uri:
description: The Issuer URI, if included in the certificate. Will be
C(none) if no issuer URI is included.
V(none) if no issuer URI is included.
returned: success
type: str
version_added: 2.9.0

7
plugins/modules/x509_certificate_pipe.py
View File

@@ -17,11 +17,8 @@ module: x509_certificate_pipe
short_description: Generate and/or check OpenSSL certificates
version_added: 1.3.0
description:
- It implements a notion of provider (ie. C(selfsigned), C(ownca), C(entrust))
- It implements a notion of provider (one of V(selfsigned), V(ownca), V(entrust))
for your certificate.
- "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:
- Yanis Guenane (@Spredzy)
- Markus Teufelberger (@MarkusTeufelberger)
@@ -41,7 +38,7 @@ options:
provider:
description:
- Name of the provider to use to generate/retrieve the OpenSSL certificate.
- "The C(entrust) provider requires credentials for the
- "The V(entrust) provider requires credentials for the
L(Entrust Certificate Services,https://www.entrustdatacard.com/products/categories/ssl-certificates) (ECS) API."
type: str
choices: [ entrust, ownca, selfsigned ]

114
plugins/modules/x509_crl.py
View File

@@ -45,24 +45,24 @@ options:
crl_mode:
description:
- Defines how to process entries of existing CRLs.
- If set to C(generate), makes sure that the CRL has the exact set of revoked certificates
as specified in I(revoked_certificates).
- If set to C(update), makes sure that the CRL contains the revoked certificates from
I(revoked_certificates), but can also contain other revoked certificates. If the CRL file
- If set to V(generate), makes sure that the CRL has the exact set of revoked certificates
as specified in O(revoked_certificates).
- If set to V(update), makes sure that the CRL contains the revoked certificates from
O(revoked_certificates), but can also contain other revoked certificates. If the CRL file
already exists, all entries from the existing CRL will also be included in the new CRL.
When using C(update), you might be interested in setting I(ignore_timestamps) to C(true).
- The default value is C(generate).
- This parameter was called I(mode) before community.crypto 2.13.0. It has been renamed to avoid
a collision with the common I(mode) parameter for setting the CRL file's access mode.
When using V(update), you might be interested in setting O(ignore_timestamps) to V(true).
- The default value is V(generate).
- This parameter was called O(mode) before community.crypto 2.13.0. It has been renamed to avoid
a collision with the common O(mode) parameter for setting the CRL file's access mode.
type: str
# default: generate
choices: [ generate, update ]
version_added: 2.13.0
mode:
description:
- This parameter has been renamed to I(crl_mode). The old name I(mode) is now deprecated and will
be removed in community.crypto 3.0.0. Replace usage of this parameter with I(crl_mode).
- Note that from community.crypto 3.0.0 on, I(mode) will be used for the CRL file's mode.
- This parameter has been renamed to O(crl_mode). The old name O(mode) is now deprecated and will
be removed in community.crypto 3.0.0. Replace usage of this parameter with O(crl_mode).
- Note that from community.crypto 3.0.0 on, O(mode) will be used for the CRL file's mode.
type: str
# default: generate
choices: [ generate, update ]
@@ -89,7 +89,7 @@ options:
format:
description:
- Whether the CRL file should be in PEM or DER format.
- If an existing CRL file does match everything but I(format), it will be converted to the correct format
- If an existing CRL file does match everything but O(format), it will be converted to the correct format
instead of regenerated.
type: str
choices: [pem, der]
@@ -98,18 +98,18 @@ options:
privatekey_path:
description:
- Path to the CA's private key to use when signing the CRL.
- Either I(privatekey_path) or I(privatekey_content) must be specified if I(state) is C(present), but not both.
- Either O(privatekey_path) or O(privatekey_content) must be specified if O(state) is V(present), but not both.
type: path
privatekey_content:
description:
- The content of the CA's private key to use when signing the CRL.
- Either I(privatekey_path) or I(privatekey_content) must be specified if I(state) is C(present), but not both.
- Either O(privatekey_path) or O(privatekey_content) must be specified if O(state) is V(present), but not both.
type: str
privatekey_passphrase:
description:
- The passphrase for the I(privatekey_path).
- The passphrase for the O(privatekey_path).
- This is required if the private key is password protected.
type: str
@@ -117,9 +117,9 @@ options:
description:
- Key/value pairs that will be present in the issuer name field of the CRL.
- If you need to specify more than one value with the same key, use a list as value.
- If the order of the components is important, use I(issuer_ordered).
- One of I(issuer) and I(issuer_ordered) is required if I(state) is C(present).
- Mutually exclusive with I(issuer_ordered).
- If the order of the components is important, use O(issuer_ordered).
- One of O(issuer) and O(issuer_ordered) is required if O(state) is V(present).
- Mutually exclusive with O(issuer_ordered).
type: dict
issuer_ordered:
description:
@@ -127,8 +127,8 @@ options:
This key/value pair will be present in the issuer name field of the CRL.
- If you want to specify more than one value with the same key in a row, you can
use a list as value.
- One of I(issuer) and I(issuer_ordered) is required if I(state) is C(present).
- Mutually exclusive with I(issuer).
- One of O(issuer) and O(issuer_ordered) is required if O(state) is V(present).
- Mutually exclusive with O(issuer).
type: list
elements: dict
version_added: 2.0.0
@@ -139,23 +139,23 @@ 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]) (for example C(+32w1d2h)).
+ C([w | d | h | m | s]) (for example V(+32w1d2h)).
- Note that if using relative time this module is NOT idempotent, except when
I(ignore_timestamps) is set to C(true).
O(ignore_timestamps) is set to V(true).
type: str
default: "+0s"
next_update:
description:
- "The absolute latest point in time by which this I(issuer) is expected to have issued
another CRL. Many clients will treat a CRL as expired once I(next_update) occurs."
- "The absolute latest point in time by which this O(issuer) is expected to have issued
another CRL. Many clients will treat a CRL as expired once O(next_update) occurs."
- 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]) (for example C(+32w1d2h)).
+ C([w | d | h | m | s]) (for example V(+32w1d2h)).
- Note that if using relative time this module is NOT idempotent, except when
I(ignore_timestamps) is set to C(true).
- Required if I(state) is C(present).
O(ignore_timestamps) is set to V(true).
- Required if O(state) is V(present).
type: str
digest:
@@ -167,7 +167,7 @@ options:
revoked_certificates:
description:
- List of certificates to be revoked.
- Required if I(state) is C(present).
- Required if O(state) is V(present).
type: list
elements: dict
suboptions:
@@ -175,20 +175,23 @@ options:
description:
- Path to a certificate in PEM format.
- The serial number and issuer will be extracted from the certificate.
- Mutually exclusive with I(content) and I(serial_number). One of these three options
- Mutually exclusive with O(revoked_certificates[].content) and
O(revoked_certificates[].serial_number). One of these three options
must be specified.
type: path
content:
description:
- Content of a certificate in PEM format.
- The serial number and issuer will be extracted from the certificate.
- Mutually exclusive with I(path) and I(serial_number). One of these three options
- Mutually exclusive with O(revoked_certificates[].path) and
O(revoked_certificates[].serial_number). One of these three options
must be specified.
type: str
serial_number:
description:
- Serial number of the certificate.
- Mutually exclusive with I(path) and I(content). One of these three options must
- Mutually exclusive with O(revoked_certificates[].path) and
O(revoked_certificates[].content). One of these three options must
be specified.
type: int
revocation_date:
@@ -197,15 +200,15 @@ 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]) (for example C(+32w1d2h)).
+ C([w | d | h | m | s]) (for example V(+32w1d2h)).
- Note that if using relative time this module is NOT idempotent, except when
I(ignore_timestamps) is set to C(true).
O(ignore_timestamps) is set to V(true).
type: str
default: "+0s"
issuer:
description:
- The certificate's issuer.
- "Example: C(DNS:ca.example.org)"
- "Example: V(DNS:ca.example.org)"
type: list
elements: str
issuer_critical:
@@ -240,9 +243,9 @@ 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]) (for example C(+32w1d2h)).
+ C([w | d | h | m | s]) (for example V(+32w1d2h)).
- Note that if using relative time this module is NOT idempotent. This will NOT
change when I(ignore_timestamps) is set to C(true).
change when O(ignore_timestamps) is set to V(true).
type: str
invalidity_date_critical:
description:
@@ -252,16 +255,16 @@ options:
ignore_timestamps:
description:
- Whether the timestamps I(last_update), I(next_update) and I(revocation_date) (in
I(revoked_certificates)) should be ignored for idempotency checks. The timestamp
I(invalidity_date) in I(revoked_certificates) will never be ignored.
- Whether the timestamps O(last_update), O(next_update) and
O(revoked_certificates[].revocation_date) should be ignored for idempotency checks.
The timestamp O(revoked_certificates[].invalidity_date) will never be ignored.
- Use this in combination with relative timestamps for these values to get idempotency.
type: bool
default: false
return_content:
description:
- If set to C(true), will return the (current or generated) CRL's content as I(crl).
- If set to V(true), will return the (current or generated) CRL's content as RV(crl).
type: bool
default: false
@@ -300,7 +303,7 @@ filename:
sample: /path/to/my-ca.crl
backup_file:
description: Name of backup file created.
returned: changed and if I(backup) is C(true)
returned: changed and if O(backup) is V(true)
type: str
sample: /path/to/my-ca.crl.2019-03-09@11:22~
privatekey:
@@ -310,15 +313,18 @@ privatekey:
sample: /path/to/my-ca.pem
format:
description:
- Whether the CRL is in PEM format (C(pem)) or in DER format (C(der)).
- Whether the CRL is in PEM format (V(pem)) or in DER format (V(der)).
returned: success
type: str
sample: pem
choices:
- pem
- der
issuer:
description:
- The CRL's issuer.
- Note that for repeated values, only the last one will be returned.
- See I(name_encoding) for how IDNs are handled.
- See O(name_encoding) for how IDNs are handled.
returned: success
type: dict
sample: {"organizationName": "Ansible", "commonName": "ca.example.com"}
@@ -360,7 +366,7 @@ revoked_certificates:
issuer:
description:
- The certificate's issuer.
- See I(name_encoding) for how IDNs are handled.
- See O(name_encoding) for how IDNs are handled.
type: list
elements: str
sample: ["DNS:ca.example.org"]
@@ -371,11 +377,19 @@ revoked_certificates:
reason:
description:
- The value for the revocation reason extension.
- One of C(unspecified), C(key_compromise), C(ca_compromise), C(affiliation_changed), C(superseded),
C(cessation_of_operation), C(certificate_hold), C(privilege_withdrawn), C(aa_compromise), and
C(remove_from_crl).
type: str
sample: key_compromise
choices:
- unspecified
- key_compromise
- ca_compromise
- affiliation_changed
- superseded
- cessation_of_operation
- certificate_hold
- privilege_withdrawn
- aa_compromise
- remove_from_crl
reason_critical:
description: Whether the revocation reason extension is critical.
type: bool
@@ -393,9 +407,9 @@ revoked_certificates:
crl:
description:
- The (current or generated) CRL's content.
- Will be the CRL itself if I(format) is C(pem), and Base64 of the
CRL if I(format) is C(der).
returned: if I(state) is C(present) and I(return_content) is C(true)
- Will be the CRL itself if O(format) is V(pem), and Base64 of the
CRL if O(format) is V(der).
returned: if O(state) is V(present) and O(return_content) is V(true)
type: str
'''

36
plugins/modules/x509_crl_info.py
View File

@@ -28,16 +28,16 @@ options:
path:
description:
- Remote absolute path where the generated CRL file should be created or is already located.
- Either I(path) or I(content) must be specified, but not both.
- Either O(path) or O(content) must be specified, but not both.
type: path
content:
description:
- Content of the X.509 CRL in PEM format, or Base64-encoded X.509 CRL.
- Either I(path) or I(content) must be specified, but not both.
- Either O(path) or O(content) must be specified, but not both.
type: str
list_revoked_certificates:
description:
- If set to C(false), the list of revoked certificates is not included in the result.
- If set to V(false), the list of revoked certificates is not included in the result.
- This is useful when retrieving information on large CRL files. Enumerating all revoked
certificates can take some time, including serializing the result as JSON, sending it to
the Ansible controller, and decoding it again.
@@ -50,9 +50,8 @@ notes:
They are all in UTC.
seealso:
- module: community.crypto.x509_crl
- ref: community.crypto.x509_crl_info filter <ansible_collections.community.crypto.x509_crl_info_filter>
# - plugin: community.crypto.x509_crl_info
# plugin_type: filter
- plugin: community.crypto.x509_crl_info
plugin_type: filter
description: A filter variant of this module.
'''
@@ -76,15 +75,18 @@ EXAMPLES = r'''
RETURN = r'''
format:
description:
- Whether the CRL is in PEM format (C(pem)) or in DER format (C(der)).
- Whether the CRL is in PEM format (V(pem)) or in DER format (V(der)).
returned: success
type: str
sample: pem
choices:
- pem
- der
issuer:
description:
- The CRL's issuer.
- Note that for repeated values, only the last one will be returned.
- See I(name_encoding) for how IDNs are handled.
- See O(name_encoding) for how IDNs are handled.
returned: success
type: dict
sample: {"organizationName": "Ansible", "commonName": "ca.example.com"}
@@ -111,7 +113,7 @@ digest:
sample: sha256WithRSAEncryption
revoked_certificates:
description: List of certificates to be revoked.
returned: success if I(list_revoked_certificates=true)
returned: success if O(list_revoked_certificates=true)
type: list
elements: dict
contains:
@@ -126,7 +128,7 @@ revoked_certificates:
issuer:
description:
- The certificate's issuer.
- See I(name_encoding) for how IDNs are handled.
- See O(name_encoding) for how IDNs are handled.
type: list
elements: str
sample: ["DNS:ca.example.org"]
@@ -137,11 +139,19 @@ revoked_certificates:
reason:
description:
- The value for the revocation reason extension.
- One of C(unspecified), C(key_compromise), C(ca_compromise), C(affiliation_changed), C(superseded),
C(cessation_of_operation), C(certificate_hold), C(privilege_withdrawn), C(aa_compromise), and
C(remove_from_crl).
type: str
sample: key_compromise
choices:
- unspecified
- key_compromise
- ca_compromise
- affiliation_changed
- superseded
- cessation_of_operation
- certificate_hold
- privilege_withdrawn
- aa_compromise
- remove_from_crl
reason_critical:
description: Whether the revocation reason extension is critical.
type: bool

2
tests/sanity/extra/extra-docs.py
View File

@@ -17,7 +17,7 @@ def main():
suffix = ':{env}'.format(env=env["ANSIBLE_COLLECTIONS_PATH"]) if 'ANSIBLE_COLLECTIONS_PATH' in env else ''
env['ANSIBLE_COLLECTIONS_PATH'] = '{root}{suffix}'.format(root=os.path.dirname(os.path.dirname(os.path.dirname(os.getcwd()))), suffix=suffix)
p = subprocess.run(
['antsibull-docs', 'lint-collection-docs', '--plugin-docs', '--disallow-semantic-markup', '--skip-rstcheck', '.'],
['antsibull-docs', 'lint-collection-docs', '--plugin-docs', '--skip-rstcheck', '.'],
env=env,
check=False,
)

9
tests/sanity/ignore-2.10.txt
View File

@@ -4,6 +4,15 @@
.azure-pipelines/scripts/publish-codecov.py compile-3.5!skip # Uses Python 3.6+ syntax
.azure-pipelines/scripts/publish-codecov.py future-import-boilerplate
.azure-pipelines/scripts/publish-codecov.py metaclass-boilerplate
docs/docsite/rst/guide_selfsigned.rst rstcheck
plugins/modules/acme_account_info.py validate-modules:return-syntax-error
plugins/modules/acme_challenge_cert_helper.py validate-modules:return-syntax-error
plugins/modules/openssl_csr_info.py validate-modules:invalid-documentation
plugins/modules/openssl_privatekey_info.py validate-modules:invalid-documentation
plugins/modules/openssl_publickey_info.py validate-modules:invalid-documentation
plugins/modules/x509_certificate_info.py validate-modules:invalid-documentation
plugins/modules/x509_crl.py validate-modules:return-syntax-error
plugins/modules/x509_crl_info.py validate-modules:invalid-documentation
plugins/modules/x509_crl_info.py validate-modules:return-syntax-error
tests/ee/roles/smoke/library/smoke_ipaddress.py shebang
tests/ee/roles/smoke/library/smoke_pyyaml.py shebang

8
tests/sanity/ignore-2.11.txt
View File

@@ -5,5 +5,13 @@
.azure-pipelines/scripts/publish-codecov.py future-import-boilerplate
.azure-pipelines/scripts/publish-codecov.py metaclass-boilerplate
plugins/modules/acme_account_info.py validate-modules:return-syntax-error
plugins/modules/acme_challenge_cert_helper.py validate-modules:return-syntax-error
plugins/modules/openssl_csr_info.py validate-modules:invalid-documentation
plugins/modules/openssl_privatekey_info.py validate-modules:invalid-documentation
plugins/modules/openssl_publickey_info.py validate-modules:invalid-documentation
plugins/modules/x509_certificate_info.py validate-modules:invalid-documentation
plugins/modules/x509_crl.py validate-modules:return-syntax-error
plugins/modules/x509_crl_info.py validate-modules:invalid-documentation
plugins/modules/x509_crl_info.py validate-modules:return-syntax-error
tests/ee/roles/smoke/library/smoke_ipaddress.py shebang
tests/ee/roles/smoke/library/smoke_pyyaml.py shebang

8
tests/sanity/ignore-2.12.txt
View File

@@ -1,4 +1,12 @@
.azure-pipelines/scripts/publish-codecov.py replace-urlopen
plugins/modules/acme_account_info.py validate-modules:return-syntax-error
plugins/modules/acme_challenge_cert_helper.py validate-modules:return-syntax-error
plugins/modules/openssl_csr_info.py validate-modules:invalid-documentation
plugins/modules/openssl_privatekey_info.py validate-modules:invalid-documentation
plugins/modules/openssl_publickey_info.py validate-modules:invalid-documentation
plugins/modules/x509_certificate_info.py validate-modules:invalid-documentation
plugins/modules/x509_crl.py validate-modules:return-syntax-error
plugins/modules/x509_crl_info.py validate-modules:invalid-documentation
plugins/modules/x509_crl_info.py validate-modules:return-syntax-error
tests/ee/roles/smoke/library/smoke_ipaddress.py shebang
tests/ee/roles/smoke/library/smoke_pyyaml.py shebang

5
tests/sanity/ignore-2.13.txt
View File

@@ -1,3 +1,8 @@
.azure-pipelines/scripts/publish-codecov.py replace-urlopen
plugins/modules/openssl_csr_info.py validate-modules:invalid-documentation
plugins/modules/openssl_privatekey_info.py validate-modules:invalid-documentation
plugins/modules/openssl_publickey_info.py validate-modules:invalid-documentation
plugins/modules/x509_certificate_info.py validate-modules:invalid-documentation
plugins/modules/x509_crl_info.py validate-modules:invalid-documentation
tests/ee/roles/smoke/library/smoke_ipaddress.py shebang
tests/ee/roles/smoke/library/smoke_pyyaml.py shebang

5
tests/sanity/ignore-2.14.txt
View File

@@ -1,3 +1,8 @@
.azure-pipelines/scripts/publish-codecov.py replace-urlopen
plugins/modules/openssl_csr_info.py validate-modules:invalid-documentation
plugins/modules/openssl_privatekey_info.py validate-modules:invalid-documentation
plugins/modules/openssl_publickey_info.py validate-modules:invalid-documentation
plugins/modules/x509_certificate_info.py validate-modules:invalid-documentation
plugins/modules/x509_crl_info.py validate-modules:invalid-documentation
tests/ee/roles/smoke/library/smoke_ipaddress.py shebang
tests/ee/roles/smoke/library/smoke_pyyaml.py shebang

9
tests/sanity/ignore-2.9.txt
View File

@@ -4,5 +4,14 @@
.azure-pipelines/scripts/publish-codecov.py compile-3.5!skip # Uses Python 3.6+ syntax
.azure-pipelines/scripts/publish-codecov.py future-import-boilerplate
.azure-pipelines/scripts/publish-codecov.py metaclass-boilerplate
docs/docsite/rst/guide_selfsigned.rst rstcheck
plugins/modules/acme_challenge_cert_helper.py validate-modules:return-syntax-error
plugins/modules/openssl_csr_info.py validate-modules:invalid-documentation
plugins/modules/openssl_privatekey_info.py validate-modules:invalid-documentation
plugins/modules/openssl_publickey_info.py validate-modules:invalid-documentation
plugins/modules/x509_certificate_info.py validate-modules:invalid-documentation
plugins/modules/x509_crl.py validate-modules:return-syntax-error
plugins/modules/x509_crl_info.py validate-modules:invalid-documentation
plugins/modules/x509_crl_info.py validate-modules:return-syntax-error
tests/ee/roles/smoke/library/smoke_ipaddress.py shebang
tests/ee/roles/smoke/library/smoke_pyyaml.py shebang