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

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

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

* Fix/improve.

* Remaining fixes.

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

302
plugins/doc_fragments/acme.py
View File

@@ -14,124 +14,94 @@ class ModuleDocFragment(object):
#
# NOTE: This document fragment is DEPRECATED and will be removed from community.crypto 3.0.0.
# Use both the BASIC and ACCOUNT fragments as a replacement.
DOCUMENTATION = r'''
DOCUMENTATION = r"""
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 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
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
L(Buypass Go SSL,https://www.buypass.com/ssl/products/acme)."
- "So far, the ACME modules have only been tested by the developers against
Let's Encrypt (staging and production), Buypass (staging and production), ZeroSSL (production),
and L(Pebble testing server,https://github.com/letsencrypt/Pebble). We have got
community feedback that they also work with Sectigo ACME Service for InCommon.
If you experience problems with another ACME server, please
L(create an issue,https://github.com/ansible-collections/community.crypto/issues/new/choose)
to help us supporting it. Feedback that an ACME server not mentioned does work
is also appreciated."
- 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 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
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 L(Buypass Go SSL,https://www.buypass.com/ssl/products/acme).
- So far, the ACME modules have only been tested by the developers against Let's Encrypt (staging and production), Buypass
(staging and production), ZeroSSL (production), and L(Pebble testing server,https://github.com/letsencrypt/Pebble). We
have got community feedback that they also work with Sectigo ACME Service for InCommon. If you experience problems with
another ACME server, please L(create an issue,https://github.com/ansible-collections/community.crypto/issues/new/choose)
to help us supporting it. Feedback that an ACME server not mentioned does work is also appreciated.
requirements:
- either openssl or L(cryptography,https://cryptography.io/) >= 1.5
- ipaddress
options:
account_key_src:
description:
- "Path to a file containing the ACME account RSA or Elliptic Curve
key."
- "Private keys can be created with the
M(community.crypto.openssl_privatekey) or M(community.crypto.openssl_privatekey_pipe)
modules. If the requisite (cryptography) is not available,
keys can also be created directly with the C(openssl) command line tool:
RSA keys can be created with C(openssl genrsa ...). Elliptic curve keys
can be created with C(openssl ecparam -genkey ...). Any other tool creating
private keys in PEM format can be used as well."
- "Mutually exclusive with O(account_key_content)."
- "Required if O(account_key_content) is not used."
- Path to a file containing the ACME account RSA or Elliptic Curve key.
- 'Private keys can be created with the M(community.crypto.openssl_privatekey) or M(community.crypto.openssl_privatekey_pipe)
modules. If the requisite (cryptography) is not available, keys can also be created directly with the C(openssl) command
line tool: RSA keys can be created with C(openssl genrsa ...). Elliptic curve keys can be created with C(openssl ecparam
-genkey ...). Any other tool creating private keys in PEM format can be used as well.'
- Mutually exclusive with O(account_key_content).
- Required if O(account_key_content) is not used.
type: path
aliases: [ account_key ]
aliases: [account_key]
account_key_content:
description:
- "Content of the ACME account RSA or Elliptic Curve key."
- "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,
or to revoke your certificates without knowing their private keys
—, this might not be acceptable."
- "In case C(cryptography) is used, the content is not written into a
temporary file. It can still happen that it is written to disk by
Ansible in the process of moving the module with its argument to
the node where it is executed."
- Content of the ACME account RSA or Elliptic Curve key.
- 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, or to revoke your certificates
without knowing their private keys —, this might not be acceptable.
- In case C(cryptography) is used, the content is not written into a temporary file. It can still happen that it is
written to disk by Ansible in the process of moving the module with its argument to the node where it is executed.
type: str
account_key_passphrase:
description:
- Phassphrase to use to decode the account key.
- "B(Note:) this is not supported by the C(openssl) backend, only by the C(cryptography) backend."
- B(Note:) this is not supported by the C(openssl) backend, only by the C(cryptography) backend.
type: str
version_added: 1.6.0
account_uri:
description:
- "If specified, assumes that the account URI is as given. If the
account key does not match this account, or an account with this
URI does not exist, the module fails."
- If specified, assumes that the account URI is as given. If the account key does not match this account, or an account
with this URI does not exist, the module fails.
type: str
acme_version:
description:
- "The ACME version of the endpoint."
- "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."
- The ACME version of the endpoint.
- 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
choices: [ 1, 2 ]
choices: [1, 2]
acme_directory:
description:
- "The ACME directory to use. This is the entry point URL to access
the ACME CA server API."
- "For safety reasons the default is set to the Let's Encrypt staging
server (for the ACME v1 protocol). This will create technically correct,
but untrusted certificates."
- "For Let's Encrypt, all staging endpoints can be found here:
U(https://letsencrypt.org/docs/staging-environment/). For Buypass, all
endpoints can be found here:
U(https://community.buypass.com/t/63d4ay/buypass-go-ssl-endpoints)"
- "For B(Let's Encrypt), the production directory URL for ACME v2 is
U(https://acme-v02.api.letsencrypt.org/directory)."
- "For B(Buypass), the production directory URL for ACME v2 and v1 is
U(https://api.buypass.com/acme/directory)."
- "For B(ZeroSSL), the production directory URL for ACME v2 is
U(https://acme.zerossl.com/v2/DV90)."
- "For B(Sectigo), the production directory URL for ACME v2 is
U(https://acme-qa.secure.trust-provider.com/v2/DV)."
- The notes for this module contain a list of ACME services this module has
been tested against.
- The ACME directory to use. This is the entry point URL to access the ACME CA server API.
- For safety reasons the default is set to the Let's Encrypt staging server (for the ACME v1 protocol). This will create
technically correct, but untrusted certificates.
- "For Let's Encrypt, all staging endpoints can be found here: U(https://letsencrypt.org/docs/staging-environment/).
For Buypass, all endpoints can be found here: U(https://community.buypass.com/t/63d4ay/buypass-go-ssl-endpoints)."
- For B(Let's Encrypt), the production directory URL for ACME v2 is U(https://acme-v02.api.letsencrypt.org/directory).
- For B(Buypass), the production directory URL for ACME v2 and v1 is U(https://api.buypass.com/acme/directory).
- For B(ZeroSSL), the production directory URL for ACME v2 is U(https://acme.zerossl.com/v2/DV90).
- For B(Sectigo), the production directory URL for ACME v2 is U(https://acme-qa.secure.trust-provider.com/v2/DV).
- The notes for this module contain a list of ACME services this module has been tested against.
required: true
type: str
validate_certs:
description:
- Whether calls to the ACME directory will validate TLS certificates.
- "B(Warning:) Should B(only ever) be set to V(false) for testing purposes,
for example when testing against a local Pebble server."
- 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 V(auto), which tries to use C(cryptography) if available, and falls back to
C(openssl).
- 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 C(openssl) binary.
- If set to V(cryptography), will try to use the
L(cryptography,https://cryptography.io/) library.
- If set to V(cryptography), will try to use the L(cryptography,https://cryptography.io/) library.
type: str
default: auto
choices: [ auto, cryptography, openssl ]
choices: [auto, cryptography, openssl]
request_timeout:
description:
- The time Ansible should wait for a response from the ACME API.
@@ -139,78 +109,60 @@ options:
type: int
default: 10
version_added: 2.3.0
'''
"""
# Basic documentation fragment without account data
BASIC = r'''
BASIC = r"""
notes:
- "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
L(Buypass Go SSL,https://www.buypass.com/ssl/products/acme)."
- "So far, the ACME modules have only been tested by the developers against
Let's Encrypt (staging and production), Buypass (staging and production), ZeroSSL (production),
and L(Pebble testing server,https://github.com/letsencrypt/Pebble). We have got
community feedback that they also work with Sectigo ACME Service for InCommon.
If you experience problems with another ACME server, please
L(create an issue,https://github.com/ansible-collections/community.crypto/issues/new/choose)
to help us supporting it. Feedback that an ACME server not mentioned does work
is also appreciated."
- 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 L(Buypass Go SSL,https://www.buypass.com/ssl/products/acme).
- So far, the ACME modules have only been tested by the developers against Let's Encrypt (staging and production), Buypass
(staging and production), ZeroSSL (production), and L(Pebble testing server,https://github.com/letsencrypt/Pebble). We
have got community feedback that they also work with Sectigo ACME Service for InCommon. If you experience problems with
another ACME server, please L(create an issue,https://github.com/ansible-collections/community.crypto/issues/new/choose)
to help us supporting it. Feedback that an ACME server not mentioned does work is also appreciated.
requirements:
- either openssl or L(cryptography,https://cryptography.io/) >= 1.5
- ipaddress
options:
acme_version:
description:
- "The ACME version of the endpoint."
- "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."
- The ACME version of the endpoint.
- 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
choices: [ 1, 2 ]
choices: [1, 2]
acme_directory:
description:
- "The ACME directory to use. This is the entry point URL to access
the ACME CA server API."
- "For safety reasons the default is set to the Let's Encrypt staging
server (for the ACME v1 protocol). This will create technically correct,
but untrusted certificates."
- "For Let's Encrypt, all staging endpoints can be found here:
U(https://letsencrypt.org/docs/staging-environment/). For Buypass, all
endpoints can be found here:
U(https://community.buypass.com/t/63d4ay/buypass-go-ssl-endpoints)"
- "For B(Let's Encrypt), the production directory URL for ACME v2 is
U(https://acme-v02.api.letsencrypt.org/directory)."
- "For B(Buypass), the production directory URL for ACME v2 and v1 is
U(https://api.buypass.com/acme/directory)."
- "For B(ZeroSSL), the production directory URL for ACME v2 is
U(https://acme.zerossl.com/v2/DV90)."
- "For B(Sectigo), the production directory URL for ACME v2 is
U(https://acme-qa.secure.trust-provider.com/v2/DV)."
- The notes for this module contain a list of ACME services this module has
been tested against.
- The ACME directory to use. This is the entry point URL to access the ACME CA server API.
- For safety reasons the default is set to the Let's Encrypt staging server (for the ACME v1 protocol). This will create
technically correct, but untrusted certificates.
- "For Let's Encrypt, all staging endpoints can be found here: U(https://letsencrypt.org/docs/staging-environment/).
For Buypass, all endpoints can be found here: U(https://community.buypass.com/t/63d4ay/buypass-go-ssl-endpoints)."
- For B(Let's Encrypt), the production directory URL for ACME v2 is U(https://acme-v02.api.letsencrypt.org/directory).
- For B(Buypass), the production directory URL for ACME v2 and v1 is U(https://api.buypass.com/acme/directory).
- For B(ZeroSSL), the production directory URL for ACME v2 is U(https://acme.zerossl.com/v2/DV90).
- For B(Sectigo), the production directory URL for ACME v2 is U(https://acme-qa.secure.trust-provider.com/v2/DV).
- The notes for this module contain a list of ACME services this module has been tested against.
required: true
type: str
validate_certs:
description:
- Whether calls to the ACME directory will validate TLS certificates.
- "B(Warning:) Should B(only ever) be set to V(false) for testing purposes,
for example when testing against a local Pebble server."
- 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 V(auto), which tries to use C(cryptography) if available, and falls back to
C(openssl).
- 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 C(openssl) binary.
- If set to V(cryptography), will try to use the
L(cryptography,https://cryptography.io/) library.
- If set to V(cryptography), will try to use the L(cryptography,https://cryptography.io/) library.
type: str
default: auto
choices: [ auto, cryptography, openssl ]
choices: [auto, cryptography, openssl]
request_timeout:
description:
- The time Ansible should wait for a response from the ACME API.
@@ -218,62 +170,50 @@ options:
type: int
default: 10
version_added: 2.3.0
'''
"""
# Account data documentation fragment
ACCOUNT = r'''
ACCOUNT = r"""
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 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
O(account_key_content))."
- 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 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
O(account_key_content)).
options:
account_key_src:
description:
- "Path to a file containing the ACME account RSA or Elliptic Curve
key."
- "Private keys can be created with the
M(community.crypto.openssl_privatekey) or M(community.crypto.openssl_privatekey_pipe)
modules. If the requisite (cryptography) is not available,
keys can also be created directly with the C(openssl) command line tool:
RSA keys can be created with C(openssl genrsa ...). Elliptic curve keys
can be created with C(openssl ecparam -genkey ...). Any other tool creating
private keys in PEM format can be used as well."
- "Mutually exclusive with O(account_key_content)."
- "Required if O(account_key_content) is not used."
- Path to a file containing the ACME account RSA or Elliptic Curve key.
- 'Private keys can be created with the M(community.crypto.openssl_privatekey) or M(community.crypto.openssl_privatekey_pipe)
modules. If the requisite (cryptography) is not available, keys can also be created directly with the C(openssl) command
line tool: RSA keys can be created with C(openssl genrsa ...). Elliptic curve keys can be created with C(openssl ecparam
-genkey ...). Any other tool creating private keys in PEM format can be used as well.'
- Mutually exclusive with O(account_key_content).
- Required if O(account_key_content) is not used.
type: path
aliases: [ account_key ]
aliases: [account_key]
account_key_content:
description:
- "Content of the ACME account RSA or Elliptic Curve key."
- "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,
or to revoke your certificates without knowing their private keys
—, this might not be acceptable."
- "In case C(cryptography) is used, the content is not written into a
temporary file. It can still happen that it is written to disk by
Ansible in the process of moving the module with its argument to
the node where it is executed."
- Content of the ACME account RSA or Elliptic Curve key.
- 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, or to revoke your certificates
without knowing their private keys —, this might not be acceptable.
- In case C(cryptography) is used, the content is not written into a temporary file. It can still happen that it is
written to disk by Ansible in the process of moving the module with its argument to the node where it is executed.
type: str
account_key_passphrase:
description:
- Phassphrase to use to decode the account key.
- "B(Note:) this is not supported by the C(openssl) backend, only by the C(cryptography) backend."
- B(Note:) this is not supported by the C(openssl) backend, only by the C(cryptography) backend.
type: str
version_added: 1.6.0
account_uri:
description:
- "If specified, assumes that the account URI is as given. If the
account key does not match this account, or an account with this
URI does not exist, the module fails."
- If specified, assumes that the account URI is as given. If the account key does not match this account, or an account
with this URI does not exist, the module fails.
type: str
'''
"""
# No account data documentation fragment
NO_ACCOUNT = r'''
@@ -286,32 +226,26 @@ notes:
options: {}
'''
CERTIFICATE = r'''
CERTIFICATE = r"""
options:
csr:
description:
- "File containing the CSR for the new certificate."
- "Can be created with M(community.crypto.openssl_csr)."
- "The CSR may contain multiple Subject Alternate Names, but each one
will lead to an individual challenge that must be fulfilled for the
CSR to be signed."
- "B(Note): the private key used to create the CSR B(must not) be the
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."
- File containing the CSR for the new certificate.
- Can be created with M(community.crypto.openssl_csr).
- The CSR may contain multiple Subject Alternate Names, but each one will lead to an individual challenge that must
be fulfilled for the CSR to be signed.
- 'B(Note): the private key used to create the CSR B(must not) be the 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 O(csr) or O(csr_content) must be specified.
type: path
csr_content:
description:
- "Content of the CSR for the new certificate."
- "Can be created with M(community.crypto.openssl_csr_pipe)."
- "The CSR may contain multiple Subject Alternate Names, but each one
will lead to an individual challenge that must be fulfilled for the
CSR to be signed."
- "B(Note): the private key used to create the CSR B(must not) be the
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."
- Content of the CSR for the new certificate.
- Can be created with M(community.crypto.openssl_csr_pipe).
- The CSR may contain multiple Subject Alternate Names, but each one will lead to an individual challenge that must
be fulfilled for the CSR to be signed.
- 'B(Note): the private key used to create the CSR B(must not) be the 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 O(csr) or O(csr_content) must be specified.
type: str
'''
"""

40
plugins/doc_fragments/attributes.py
View File

@@ -11,14 +11,14 @@ __metaclass__ = type
class ModuleDocFragment(object):
# Standard documentation fragment
DOCUMENTATION = r'''
DOCUMENTATION = r"""
options: {}
attributes:
check_mode:
description: Can run in C(check_mode) and return changed status prediction without modifying target.
diff_mode:
description: Will return details on what has changed (or possibly needs changing in C(check_mode)), when in diff mode.
'''
check_mode:
description: Can run in C(check_mode) and return changed status prediction without modifying target.
diff_mode:
description: Will return details on what has changed (or possibly needs changing in C(check_mode)), when in diff mode.
"""
# Should be used together with the standard fragment
INFO_MODULE = r'''
@@ -45,12 +45,12 @@ attributes:
- acme
'''
FACTS = r'''
FACTS = r"""
options: {}
attributes:
facts:
description: Action returns an C(ansible_facts) dictionary that will update existing host facts.
'''
facts:
description: Action returns an C(ansible_facts) dictionary that will update existing host facts.
"""
# Should be used together with the standard fragment and the FACTS fragment
FACTS_MODULE = r'''
@@ -68,18 +68,18 @@ attributes:
support: full
'''
FILES = r'''
FILES = r"""
options: {}
attributes:
safe_file_operations:
description: Uses Ansible's strict file operation functions to ensure proper permissions and avoid data corruption.
'''
safe_file_operations:
description: Uses Ansible's strict file operation functions to ensure proper permissions and avoid data corruption.
"""
FLOW = r'''
FLOW = r"""
options: {}
attributes:
action:
description: Indicates this has a corresponding action plugin so some parts of the options can be executed on the controller.
async:
description: Supports being used with the C(async) keyword.
'''
action:
description: Indicates this has a corresponding action plugin so some parts of the options can be executed on the controller.
async:
description: Supports being used with the C(async) keyword.
"""

58
plugins/doc_fragments/ecs_credential.py
View File

@@ -11,34 +11,34 @@ __metaclass__ = type
class ModuleDocFragment(object):
# Plugin options for Entrust Certificate Services (ECS) credentials
DOCUMENTATION = r'''
DOCUMENTATION = r"""
options:
entrust_api_user:
description:
- The username for authentication to the Entrust Certificate Services (ECS) API.
type: str
required: true
entrust_api_key:
description:
- The key (password) for authentication to the Entrust Certificate Services (ECS) API.
type: str
required: true
entrust_api_client_cert_path:
description:
- The path to the client certificate used to authenticate to the Entrust Certificate Services (ECS) API.
type: path
required: true
entrust_api_client_cert_key_path:
description:
- The path to the key for the client certificate used to authenticate to the Entrust Certificate Services (ECS) API.
type: path
required: true
entrust_api_specification_path:
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.
type: path
default: https://cloud.entrust.net/EntrustCloud/documentation/cms-api-2.1.0.yaml
entrust_api_user:
description:
- The username for authentication to the Entrust Certificate Services (ECS) API.
type: str
required: true
entrust_api_key:
description:
- The key (password) for authentication to the Entrust Certificate Services (ECS) API.
type: str
required: true
entrust_api_client_cert_path:
description:
- The path to the client certificate used to authenticate to the Entrust Certificate Services (ECS) API.
type: path
required: true
entrust_api_client_cert_key_path:
description:
- The path to the key for the client certificate used to authenticate to the Entrust Certificate Services (ECS) API.
type: path
required: true
entrust_api_specification_path:
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.
type: path
default: https://cloud.entrust.net/EntrustCloud/documentation/cms-api-2.1.0.yaml
requirements:
- "PyYAML >= 3.11"
'''
- "PyYAML >= 3.11"
"""

125
plugins/doc_fragments/module_certificate.py
View File

@@ -12,80 +12,79 @@ __metaclass__ = type
class ModuleDocFragment(object):
# Standard files documentation fragment
DOCUMENTATION = r'''
DOCUMENTATION = r"""
description:
- This module allows one to (re)generate OpenSSL certificates.
- It uses the cryptography python library to interact with OpenSSL.
- 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 V(selfsigned) or V(ownca) provider)
- cryptography >= 1.6 (if using V(selfsigned) or V(ownca) provider)
options:
force:
description:
- Generate the certificate, even if it already exists.
type: bool
default: false
force:
description:
- Generate the certificate, even if it already exists.
type: bool
default: false
csr_path:
description:
- Path to the Certificate Signing Request (CSR) used to generate this certificate.
- 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 O(csr_path).
type: str
csr_path:
description:
- Path to the Certificate Signing Request (CSR) used to generate this certificate.
- 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 O(csr_path).
type: str
privatekey_path:
description:
- Path to the private key to use when signing the certificate.
- 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 O(privatekey_path).
type: str
privatekey_path:
description:
- Path to the private key to use when signing the certificate.
- 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 O(privatekey_path).
type: str
privatekey_passphrase:
description:
- The passphrase for the O(privatekey_path) resp. O(privatekey_content).
- This is required if the private key is password protected.
type: str
privatekey_passphrase:
description:
- 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 V(true) when using relative timestamps (like V(+0s) for now).
type: bool
default: true
version_added: 2.0.0
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 V(true) when using relative timestamps (like V(+0s) for now).
type: bool
default: true
version_added: 2.0.0
select_crypto_backend:
description:
- Determines which crypto backend to use.
- The default choice is V(auto), which tries to use C(cryptography) if available.
- If set to V(cryptography), will try to use the L(cryptography,https://cryptography.io/) library.
type: str
default: auto
choices: [ auto, cryptography ]
select_crypto_backend:
description:
- Determines which crypto backend to use.
- The default choice is V(auto), which tries to use C(cryptography) if available.
- If set to V(cryptography), will try to use the L(cryptography,https://cryptography.io/) library.
type: str
default: auto
choices: [auto, cryptography]
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 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.
- 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 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.
seealso:
- module: community.crypto.openssl_csr
- module: community.crypto.openssl_csr_pipe
- module: community.crypto.openssl_dhparam
- module: community.crypto.openssl_pkcs12
- module: community.crypto.openssl_privatekey
- module: community.crypto.openssl_privatekey_pipe
- module: community.crypto.openssl_publickey
'''
- module: community.crypto.openssl_csr
- module: community.crypto.openssl_csr_pipe
- module: community.crypto.openssl_dhparam
- module: community.crypto.openssl_pkcs12
- module: community.crypto.openssl_privatekey
- module: community.crypto.openssl_privatekey_pipe
- module: community.crypto.openssl_publickey
"""
BACKEND_ACME_DOCUMENTATION = r'''
description:

599
plugins/doc_fragments/module_csr.py
View File

@@ -11,319 +11,306 @@ __metaclass__ = type
class ModuleDocFragment(object):
# Standard files documentation fragment
DOCUMENTATION = r'''
DOCUMENTATION = r"""
description:
- This module allows one to (re)generate OpenSSL certificate signing requests.
- This module supports the subjectAltName, keyUsage, extendedKeyUsage, basicConstraints and OCSP Must Staple
extensions.
- This module allows one to (re)generate OpenSSL certificate signing requests.
- This module supports the subjectAltName, keyUsage, extendedKeyUsage, basicConstraints and OCSP Must Staple extensions.
requirements:
- cryptography >= 1.3
- cryptography >= 1.3
options:
digest:
digest:
description:
- The digest used when signing the certificate signing request with the private key.
type: str
default: sha256
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 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 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 private key.
- This is required if the private key is password protected.
type: str
version:
description:
- The version of the certificate signing request.
- The only allowed value according to L(RFC 2986,https://tools.ietf.org/html/rfc2986#section-4.1) is 1.
- This option no longer accepts unsupported values since community.crypto 2.0.0.
type: int
default: 1
choices:
- 1
subject:
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 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 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
country_name:
description:
- The countryName field of the certificate signing request subject.
type: str
aliases: [C, countryName]
state_or_province_name:
description:
- The stateOrProvinceName field of the certificate signing request subject.
type: str
aliases: [ST, stateOrProvinceName]
locality_name:
description:
- The localityName field of the certificate signing request subject.
type: str
aliases: [L, localityName]
organization_name:
description:
- The organizationName field of the certificate signing request subject.
type: str
aliases: [O, organizationName]
organizational_unit_name:
description:
- The organizationalUnitName field of the certificate signing request subject.
type: str
aliases: [OU, organizationalUnitName]
common_name:
description:
- The commonName field of the certificate signing request subject.
type: str
aliases: [CN, commonName]
email_address:
description:
- The emailAddress field of the certificate signing request subject.
type: str
aliases: [E, emailAddress]
subject_alt_name:
description:
- Subject Alternative Name (SAN) extension to attach to the certificate signing request.
- 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 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
aliases: [subjectAltName]
subject_alt_name_critical:
description:
- Should the subjectAltName extension be considered as critical.
type: bool
default: false
aliases: [subjectAltName_critical]
use_common_name_for_san:
description:
- 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]
key_usage:
description:
- This defines the purpose (for example encipherment, signature, certificate signing) of the key contained in the certificate.
type: list
elements: str
aliases: [keyUsage]
key_usage_critical:
description:
- Should the keyUsage extension be considered as critical.
type: bool
default: false
aliases: [keyUsage_critical]
extended_key_usage:
description:
- Additional restrictions (for example client authentication, server authentication) on the allowed purposes for which
the public key may be used.
type: list
elements: str
aliases: [extKeyUsage, extendedKeyUsage]
extended_key_usage_critical:
description:
- Should the extkeyUsage extension be considered as critical.
type: bool
default: false
aliases: [extKeyUsage_critical, extendedKeyUsage_critical]
basic_constraints:
description:
- Indicates basic constraints, such as if the certificate is a CA.
type: list
elements: str
aliases: [basicConstraints]
basic_constraints_critical:
description:
- Should the basicConstraints extension be considered as critical.
type: bool
default: false
aliases: [basicConstraints_critical]
ocsp_must_staple:
description:
- Indicates that the certificate should contain the OCSP Must Staple extension (U(https://tools.ietf.org/html/rfc7633)).
type: bool
default: false
aliases: [ocspMustStaple]
ocsp_must_staple_critical:
description:
- Should the OCSP Must Staple extension be considered as critical.
- Note that according to the RFC, this extension should not be marked as critical, as old clients not knowing about
OCSP Must Staple are required to reject such certificates (see U(https://tools.ietf.org/html/rfc7633#section-4)).
type: bool
default: false
aliases: [ocspMustStaple_critical]
name_constraints_permitted:
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. (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. (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:
description:
- Should the Name Constraints extension be considered as critical.
type: bool
default: false
select_crypto_backend:
description:
- Determines which crypto backend to use.
- The default choice is V(auto), which tries to use C(cryptography) if available.
- If set to V(cryptography), will try to use the L(cryptography,https://cryptography.io/) library.
type: str
default: auto
choices: [auto, cryptography]
create_subject_key_identifier:
description:
- Create the Subject Key Identifier from the public key.
- Please note that commercial CAs can ignore the value, respectively use a value of their own choice instead. 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!
type: bool
default: false
subject_key_identifier:
description:
- The subject key identifier as a hex string, where two bytes are separated by colons.
- '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 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: 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 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. (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 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, 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 O(authority_key_identifier), O(authority_cert_issuer)
and O(authority_cert_serial_number) is specified.
- This option accepts an B(integer). If you want to provide serial numbers as colon-separated hex strings, such as C(11:22:33),
you need to convert them to an integer with P(community.crypto.parse_serial#filter).
type: int
crl_distribution_points:
description:
- Allows to specify one or multiple CRL distribution points.
- Only supported by the C(cryptography) backend.
type: list
elements: dict
suboptions:
full_name:
description:
- The digest used when signing the certificate signing request with the private key.
type: str
default: sha256
privatekey_path:
- Describes how the CRL can be retrieved.
- 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:
- 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 if O(state) is V(present), but not both.
type: path
privatekey_content:
- Describes how the CRL can be retrieved relative to the CRL issuer.
- 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
crl_issuer:
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 if O(state) is V(present), but not both.
type: str
privatekey_passphrase:
- Information about the issuer of the CRL.
type: list
elements: str
reasons:
description:
- The passphrase for the private key.
- This is required if the private key is password protected.
type: str
version:
description:
- The version of the certificate signing request.
- "The only allowed value according to L(RFC 2986,https://tools.ietf.org/html/rfc2986#section-4.1)
is 1."
- This option no longer accepts unsupported values since community.crypto 2.0.0.
type: int
default: 1
- List of reasons that this distribution point can be used for when performing revocation checks.
type: list
elements: str
choices:
- 1
subject:
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 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 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
country_name:
description:
- The countryName field of the certificate signing request subject.
type: str
aliases: [ C, countryName ]
state_or_province_name:
description:
- The stateOrProvinceName field of the certificate signing request subject.
type: str
aliases: [ ST, stateOrProvinceName ]
locality_name:
description:
- The localityName field of the certificate signing request subject.
type: str
aliases: [ L, localityName ]
organization_name:
description:
- The organizationName field of the certificate signing request subject.
type: str
aliases: [ O, organizationName ]
organizational_unit_name:
description:
- The organizationalUnitName field of the certificate signing request subject.
type: str
aliases: [ OU, organizationalUnitName ]
common_name:
description:
- The commonName field of the certificate signing request subject.
type: str
aliases: [ CN, commonName ]
email_address:
description:
- The emailAddress field of the certificate signing request subject.
type: str
aliases: [ E, emailAddress ]
subject_alt_name:
description:
- Subject Alternative Name (SAN) extension to attach to the certificate signing request.
- 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 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
aliases: [ subjectAltName ]
subject_alt_name_critical:
description:
- Should the subjectAltName extension be considered as critical.
type: bool
default: false
aliases: [ subjectAltName_critical ]
use_common_name_for_san:
description:
- 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 ]
key_usage:
description:
- This defines the purpose (for example encipherment, signature, certificate signing)
of the key contained in the certificate.
type: list
elements: str
aliases: [ keyUsage ]
key_usage_critical:
description:
- Should the keyUsage extension be considered as critical.
type: bool
default: false
aliases: [ keyUsage_critical ]
extended_key_usage:
description:
- Additional restrictions (for example client authentication, server authentication)
on the allowed purposes for which the public key may be used.
type: list
elements: str
aliases: [ extKeyUsage, extendedKeyUsage ]
extended_key_usage_critical:
description:
- Should the extkeyUsage extension be considered as critical.
type: bool
default: false
aliases: [ extKeyUsage_critical, extendedKeyUsage_critical ]
basic_constraints:
description:
- Indicates basic constraints, such as if the certificate is a CA.
type: list
elements: str
aliases: [ basicConstraints ]
basic_constraints_critical:
description:
- Should the basicConstraints extension be considered as critical.
type: bool
default: false
aliases: [ basicConstraints_critical ]
ocsp_must_staple:
description:
- Indicates that the certificate should contain the OCSP Must Staple
extension (U(https://tools.ietf.org/html/rfc7633)).
type: bool
default: false
aliases: [ ocspMustStaple ]
ocsp_must_staple_critical:
description:
- Should the OCSP Must Staple extension be considered as critical.
- Note that according to the RFC, this extension should not be marked
as critical, as old clients not knowing about OCSP Must Staple
are required to reject such certificates
(see U(https://tools.ietf.org/html/rfc7633#section-4)).
type: bool
default: false
aliases: [ ocspMustStaple_critical ]
name_constraints_permitted:
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. (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. (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:
description:
- Should the Name Constraints extension be considered as critical.
type: bool
default: false
select_crypto_backend:
description:
- Determines which crypto backend to use.
- The default choice is V(auto), which tries to use C(cryptography) if available.
- If set to V(cryptography), will try to use the L(cryptography,https://cryptography.io/) library.
type: str
default: auto
choices: [ auto, cryptography ]
create_subject_key_identifier:
description:
- Create the Subject Key Identifier from the public key.
- "Please note that commercial CAs can ignore the value, respectively use a value of
their own choice instead. 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!
type: bool
default: false
subject_key_identifier:
description:
- The subject key identifier as a hex string, where two bytes are separated by colons.
- "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 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: 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 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. (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 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, 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 O(authority_key_identifier),
O(authority_cert_issuer) and O(authority_cert_serial_number) is specified.
- This option accepts an B(integer). If you want to provide serial numbers as colon-separated hex strings,
such as C(11:22:33), you need to convert them to an integer with P(community.crypto.parse_serial#filter).
type: int
crl_distribution_points:
description:
- Allows to specify one or multiple CRL distribution points.
- Only supported by the C(cryptography) backend.
type: list
elements: dict
suboptions:
full_name:
description:
- Describes how the CRL can be retrieved.
- 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 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
crl_issuer:
description:
- Information about the issuer of the CRL.
type: list
elements: str
reasons:
description:
- List of reasons that this distribution point can be used for when performing revocation checks.
type: list
elements: str
choices:
- key_compromise
- ca_compromise
- affiliation_changed
- superseded
- cessation_of_operation
- certificate_hold
- privilege_withdrawn
- aa_compromise
version_added: 1.4.0
- key_compromise
- ca_compromise
- affiliation_changed
- superseded
- cessation_of_operation
- certificate_hold
- privilege_withdrawn
- aa_compromise
version_added: 1.4.0
notes:
- If the certificate signing request already exists it will be checked whether subjectAltName,
keyUsage, extendedKeyUsage and basicConstraints only contain the requested values, whether
OCSP Must Staple is as requested, and if the request was signed by the given private key.
- If the certificate signing request already exists it will be checked whether subjectAltName, keyUsage, extendedKeyUsage
and basicConstraints only contain the requested values, whether OCSP Must Staple is as requested, and if the request was
signed by the given private key.
seealso:
- module: community.crypto.x509_certificate
- module: community.crypto.x509_certificate_pipe
- module: community.crypto.openssl_dhparam
- module: community.crypto.openssl_pkcs12
- module: community.crypto.openssl_privatekey
- module: community.crypto.openssl_privatekey_pipe
- module: community.crypto.openssl_publickey
- module: community.crypto.openssl_csr_info
- plugin: community.crypto.parse_serial
plugin_type: filter
'''
- module: community.crypto.x509_certificate
- module: community.crypto.x509_certificate_pipe
- module: community.crypto.openssl_dhparam
- module: community.crypto.openssl_pkcs12
- module: community.crypto.openssl_privatekey
- module: community.crypto.openssl_privatekey_pipe
- module: community.crypto.openssl_publickey
- module: community.crypto.openssl_csr_info
- plugin: community.crypto.parse_serial
plugin_type: filter
"""

254
plugins/doc_fragments/module_privatekey.py
View File

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

63
plugins/doc_fragments/module_privatekey_convert.py
View File

@@ -11,38 +11,37 @@ __metaclass__ = type
class ModuleDocFragment(object):
# Standard files documentation fragment
DOCUMENTATION = r'''
DOCUMENTATION = r"""
requirements:
- cryptography >= 1.2.3 (older versions might work as well)
- cryptography >= 1.2.3 (older versions might work as well)
options:
src_path:
description:
- Name of the file containing the OpenSSL private key to convert.
- 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 O(src_path) or O(src_content) must be specified.
type: str
src_passphrase:
description:
- The passphrase for the private key to load.
type: str
dest_passphrase:
description:
- The passphrase for the private key to store.
type: str
format:
description:
- Determines which format the destination private key should be written in.
- Please note that not every key can be exported in any format, and that not every
format supports encryption.
type: str
choices: [ pkcs1, pkcs8, raw ]
required: true
src_path:
description:
- Name of the file containing the OpenSSL private key to convert.
- 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 O(src_path) or O(src_content) must be specified.
type: str
src_passphrase:
description:
- The passphrase for the private key to load.
type: str
dest_passphrase:
description:
- The passphrase for the private key to store.
type: str
format:
description:
- Determines which format the destination private key should be written in.
- Please note that not every key can be exported in any format, and that not every format supports encryption.
type: str
choices: [pkcs1, pkcs8, raw]
required: true
seealso:
- module: community.crypto.openssl_privatekey
- module: community.crypto.openssl_privatekey_pipe
- module: community.crypto.openssl_publickey
'''
- module: community.crypto.openssl_privatekey
- module: community.crypto.openssl_privatekey_pipe
- module: community.crypto.openssl_publickey
"""

37
plugins/doc_fragments/name_encoding.py
View File

@@ -9,23 +9,24 @@ __metaclass__ = type
class ModuleDocFragment(object):
DOCUMENTATION = r'''
DOCUMENTATION = r"""
options:
name_encoding:
description:
- How to encode names (DNS names, URIs, email addresses) in return values.
- 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.
- 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 V(idna) and V(unicode) require the L(idna Python library,https://pypi.org/project/idna/) to be installed.
type: str
default: ignore
choices:
- ignore
- idna
- unicode
name_encoding:
description:
- How to encode names (DNS names, URIs, email addresses) in return values.
- 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.
- 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 V(idna) and V(unicode) require the L(idna Python library,https://pypi.org/project/idna/) to be installed.
type: str
default: ignore
choices:
- ignore
- idna
- unicode
requirements:
- 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.
'''
- 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.
"""

16
plugins/filter/gpg_fingerprint.py
View File

@@ -6,13 +6,13 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = """
DOCUMENTATION = r"""
name: gpg_fingerprint
short_description: Retrieve a GPG fingerprint from a GPG public or private key
author: Felix Fontein (@felixfontein)
version_added: 2.15.0
description:
- "Takes the content of a private or public GPG key as input and returns its fingerprint."
- Takes the content of a private or public GPG key as input and returns its fingerprint.
options:
_input:
description:
@@ -26,17 +26,17 @@ seealso:
plugin_type: lookup
"""
EXAMPLES = """
EXAMPLES = r"""
- name: Show fingerprint of GPG public key
ansible.builtin.debug:
msg: "{{ lookup('file', '/path/to/public_key.gpg') | community.crypto.gpg_fingerprint }}"
"""
RETURN = """
_value:
description:
- The fingerprint of the provided public or private GPG key.
type: string
RETURN = r"""
_value:
description:
- The fingerprint of the provided public or private GPG key.
type: string
"""
from ansible.errors import AnsibleFilterError

496
plugins/filter/openssl_csr_info.py
View File

@@ -7,30 +7,30 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
DOCUMENTATION = r"""
name: openssl_csr_info
short_description: Retrieve information from OpenSSL Certificate Signing Requests (CSR)
version_added: 2.10.0
author:
- Felix Fontein (@felixfontein)
- Felix Fontein (@felixfontein)
description:
- Provided an OpenSSL Certificate Signing Requests (CSR), retrieve information.
- This is a filter version of the M(community.crypto.openssl_csr_info) module.
- Provided an OpenSSL Certificate Signing Requests (CSR), retrieve information.
- This is a filter version of the M(community.crypto.openssl_csr_info) module.
options:
_input:
description:
- The content of the OpenSSL CSR.
type: string
required: true
_input:
description:
- The content of the OpenSSL CSR.
type: string
required: true
extends_documentation_fragment:
- community.crypto.name_encoding
- community.crypto.name_encoding
seealso:
- module: community.crypto.openssl_csr_info
- plugin: community.crypto.to_serial
plugin_type: filter
'''
- module: community.crypto.openssl_csr_info
- plugin: community.crypto.to_serial
plugin_type: filter
"""
EXAMPLES = '''
EXAMPLES = r"""
- name: Show the Subject Alt Names of the CSR
ansible.builtin.debug:
msg: >-
@@ -40,242 +40,240 @@ EXAMPLES = '''
| community.crypto.openssl_csr_info
).subject_alt_name | join(', ')
}}
'''
"""
RETURN = '''
RETURN = r"""
_value:
description:
- Information on the certificate.
type: dict
contains:
signature_valid:
description:
- Whether the CSR's signature is valid.
- 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 V(none) if extension is not present.
returned: success
type: list
elements: str
sample: ['CA:TRUE', 'pathlen:1']
basic_constraints_critical:
description: Whether the C(basic_constraints) extension is critical.
returned: success
type: bool
extended_key_usage:
description: Entries in the C(extended_key_usage) extension, or V(none) if extension is not present.
returned: success
type: list
elements: str
sample: [Biometric Info, DVCS, Time Stamping]
extended_key_usage_critical:
description: Whether the C(extended_key_usage) extension is critical.
returned: success
type: bool
extensions_by_oid:
description: Returns a dictionary for every extension OID
returned: success
type: dict
contains:
critical:
description: Whether the extension is critical.
returned: success
type: bool
value:
description:
- The Base64 encoded value (in DER format) of the extension.
- B(Note) that depending on the C(cryptography) version used, it is
not possible to extract the ASN.1 content of the extension, but only
to provide the re-encoded content of the extension in case it was
parsed by C(cryptography). This should usually result in exactly the
same value, except if the original extension value was malformed.
returned: success
type: str
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 V(none) if extension is not present.
returned: success
type: str
sample: [Key Agreement, Data Encipherment]
key_usage_critical:
description: Whether the C(key_usage) extension is critical.
returned: success
type: bool
subject_alt_name:
description:
- 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
sample: ["DNS:www.ansible.com", "IP:1.2.3.4"]
subject_alt_name_critical:
description: Whether the C(subject_alt_name) extension is critical.
returned: success
type: bool
ocsp_must_staple:
description: V(true) if the OCSP Must Staple extension is present, V(none) otherwise.
returned: success
type: bool
ocsp_must_staple_critical:
description: Whether the C(ocsp_must_staple) extension is critical.
returned: success
type: bool
name_constraints_permitted:
description: List of permitted subtrees to sign certificates for.
returned: success
type: list
elements: str
sample: ['email:.somedomain.com']
name_constraints_excluded:
description:
- List of excluded subtrees the CA cannot sign certificates for.
- Is V(none) if extension is not present.
- See O(name_encoding) for how IDNs are handled.
returned: success
type: list
elements: str
sample: ['email:.com']
name_constraints_critical:
description:
- Whether the C(name_constraints) extension is critical.
- Is V(none) if extension is not present.
returned: success
type: bool
subject:
description:
- The CSR's subject as a dictionary.
- Note that for repeated values, only the last one will be returned.
returned: success
type: dict
sample: {"commonName": "www.example.com", "emailAddress": "test@example.com"}
subject_ordered:
description: The CSR's subject as an ordered list of tuples.
returned: success
type: list
elements: list
sample: [["commonName", "www.example.com"], ["emailAddress": "test@example.com"]]
public_key:
description: CSR's public key in PEM format
returned: success
type: str
sample: "-----BEGIN PUBLIC KEY-----\nMIICIjANBgkqhkiG9w0BAQEFAAOCAg8A..."
public_key_type:
description:
- The CSR's public key's type.
- 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
sample: RSA
public_key_data:
description:
- Public key data. Depends on the public key's type.
returned: success
type: dict
contains:
size:
description:
- Bit size of modulus (RSA) or prime number (DSA).
type: int
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 RV(_value.public_key_type=RSA)
exponent:
description:
- The RSA key's public exponent.
type: int
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 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 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 RV(_value.public_key_type=DSA)
curve:
description:
- The curve's name for ECC.
type: str
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 RV(_value.public_key_type=ECC)
x:
description:
- The C(x) coordinate for the public point on the elliptic curve.
type: int
returned: When RV(_value.public_key_type=ECC)
y:
description:
- 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 RV(_value.public_key_type=DSA) or RV(_value.public_key_type=ECC)
public_key_fingerprints:
description:
- Fingerprints of CSR's public key.
- For every hash algorithm available, the fingerprint is computed.
returned: success
type: dict
sample: "{'sha256': 'd4:b3:aa:6d:c8:04:ce:4e:ba:f6:29:4d:92:a3:94:b0:c2:ff:bd:bf:33:63:11:43:34:0f:51:b0:95:09:2f:63',
'sha512': 'f7:07:4a:f0:b0:f0:e6:8b:95:5f:f9:e6:61:0a:32:68:f1..."
subject_key_identifier:
description:
- The CSR's subject key identifier.
- 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 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 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
sample: ["DNS:www.ansible.com", "IP:1.2.3.4"]
authority_cert_serial_number:
description:
- The CSR's authority cert serial number.
- Is V(none) if the C(AuthorityKeyIdentifier) extension is not present.
- This return value is an B(integer). If you need the serial numbers as a colon-separated hex string,
such as C(11:22:33), you need to convert it to that form with P(community.crypto.to_serial#filter).
returned: success
type: int
sample: 12345
'''
description:
- Information on the certificate.
type: dict
contains:
signature_valid:
description:
- Whether the CSR's signature is valid.
- 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 V(none) if extension is not present.
returned: success
type: list
elements: str
sample: ['CA:TRUE', 'pathlen:1']
basic_constraints_critical:
description: Whether the C(basic_constraints) extension is critical.
returned: success
type: bool
extended_key_usage:
description: Entries in the C(extended_key_usage) extension, or V(none) if extension is not present.
returned: success
type: list
elements: str
sample: [Biometric Info, DVCS, Time Stamping]
extended_key_usage_critical:
description: Whether the C(extended_key_usage) extension is critical.
returned: success
type: bool
extensions_by_oid:
description: Returns a dictionary for every extension OID.
returned: success
type: dict
contains:
critical:
description: Whether the extension is critical.
returned: success
type: bool
value:
description:
- The Base64 encoded value (in DER format) of the extension.
- B(Note) that depending on the C(cryptography) version used, it is not possible to extract the ASN.1 content
of the extension, but only to provide the re-encoded content of the extension in case it was parsed by C(cryptography).
This should usually result in exactly the same value, except if the original extension value was malformed.
returned: success
type: str
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 V(none) if extension is not present.
returned: success
type: str
sample: [Key Agreement, Data Encipherment]
key_usage_critical:
description: Whether the C(key_usage) extension is critical.
returned: success
type: bool
subject_alt_name:
description:
- 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
sample: ["DNS:www.ansible.com", "IP:1.2.3.4"]
subject_alt_name_critical:
description: Whether the C(subject_alt_name) extension is critical.
returned: success
type: bool
ocsp_must_staple:
description: V(true) if the OCSP Must Staple extension is present, V(none) otherwise.
returned: success
type: bool
ocsp_must_staple_critical:
description: Whether the C(ocsp_must_staple) extension is critical.
returned: success
type: bool
name_constraints_permitted:
description: List of permitted subtrees to sign certificates for.
returned: success
type: list
elements: str
sample: ['email:.somedomain.com']
name_constraints_excluded:
description:
- List of excluded subtrees the CA cannot sign certificates for.
- Is V(none) if extension is not present.
- See O(name_encoding) for how IDNs are handled.
returned: success
type: list
elements: str
sample: ['email:.com']
name_constraints_critical:
description:
- Whether the C(name_constraints) extension is critical.
- Is V(none) if extension is not present.
returned: success
type: bool
subject:
description:
- The CSR's subject as a dictionary.
- Note that for repeated values, only the last one will be returned.
returned: success
type: dict
sample: {"commonName": "www.example.com", "emailAddress": "test@example.com"}
subject_ordered:
description: The CSR's subject as an ordered list of tuples.
returned: success
type: list
elements: list
sample: [["commonName", "www.example.com"], ["emailAddress": "test@example.com"]]
public_key:
description: CSR's public key in PEM format.
returned: success
type: str
sample: "-----BEGIN PUBLIC KEY-----\nMIICIjANBgkqhkiG9w0BAQEFAAOCAg8A..."
public_key_type:
description:
- The CSR's public key's type.
- 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
sample: RSA
public_key_data:
description:
- Public key data. Depends on the public key's type.
returned: success
type: dict
contains:
size:
description:
- Bit size of modulus (RSA) or prime number (DSA).
type: int
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 RV(_value.public_key_type=RSA)
exponent:
description:
- The RSA key's public exponent.
type: int
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 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 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 RV(_value.public_key_type=DSA)
curve:
description:
- The curve's name for ECC.
type: str
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 RV(_value.public_key_type=ECC)
x:
description:
- The C(x) coordinate for the public point on the elliptic curve.
type: int
returned: When RV(_value.public_key_type=ECC)
y:
description:
- 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 RV(_value.public_key_type=DSA) or RV(_value.public_key_type=ECC)
public_key_fingerprints:
description:
- Fingerprints of CSR's public key.
- For every hash algorithm available, the fingerprint is computed.
returned: success
type: dict
sample: "{'sha256': 'd4:b3:aa:6d:c8:04:ce:4e:ba:f6:29:4d:92:a3:94:b0:c2:ff:bd:bf:33:63:11:43:34:0f:51:b0:95:09:2f:63',
'sha512': 'f7:07:4a:f0:b0:f0:e6:8b:95:5f:f9:e6:61:0a:32:68:f1..."
subject_key_identifier:
description:
- The CSR's subject key identifier.
- 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 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 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
sample: ["DNS:www.ansible.com", "IP:1.2.3.4"]
authority_cert_serial_number:
description:
- The CSR's authority cert serial number.
- Is V(none) if the C(AuthorityKeyIdentifier) extension is not present.
- This return value is an B(integer). If you need the serial numbers as a colon-separated hex string, such as C(11:22:33),
you need to convert it to that form with P(community.crypto.to_serial#filter).
returned: success
type: int
sample: 12345
"""
from ansible.errors import AnsibleFilterError
from ansible.module_utils.six import string_types

239
plugins/filter/openssl_privatekey_info.py
View File

@@ -7,40 +7,39 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
DOCUMENTATION = r"""
name: openssl_privatekey_info
short_description: Retrieve information from OpenSSL private keys
version_added: 2.10.0
author:
- Felix Fontein (@felixfontein)
- Felix Fontein (@felixfontein)
description:
- Provided an OpenSSL private keys, retrieve information.
- This is a filter version of the M(community.crypto.openssl_privatekey_info) module.
- Provided an OpenSSL private keys, retrieve information.
- This is a filter version of the M(community.crypto.openssl_privatekey_info) module.
options:
_input:
description:
- The content of the OpenSSL private key.
type: string
required: true
passphrase:
description:
- The passphrase for the private key.
type: str
return_private_key_data:
description:
- Whether to return private key data.
- 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
default: false
_input:
description:
- The content of the OpenSSL private key.
type: string
required: true
passphrase:
description:
- The passphrase for the private key.
type: str
return_private_key_data:
description:
- Whether to return private key data.
- 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
default: false
extends_documentation_fragment:
- community.crypto.name_encoding
- community.crypto.name_encoding
seealso:
- module: community.crypto.openssl_privatekey_info
'''
- module: community.crypto.openssl_privatekey_info
"""
EXAMPLES = '''
EXAMPLES = r"""
- name: Show the Subject Alt Names of the CSR
ansible.builtin.debug:
msg: >-
@@ -50,103 +49,103 @@ EXAMPLES = '''
| community.crypto.openssl_privatekey_info
).subject_alt_name | join(', ')
}}
'''
"""
RETURN = '''
RETURN = r"""
_value:
description:
- Information on the certificate.
type: dict
contains:
public_key:
description: Private key's public key in PEM format.
returned: success
type: str
sample: "-----BEGIN PUBLIC KEY-----\nMIICIjANBgkqhkiG9w0BAQEFAAOCAg8A..."
public_key_fingerprints:
description:
- Fingerprints of private key's public key.
- For every hash algorithm available, the fingerprint is computed.
returned: success
type: dict
sample: "{'sha256': 'd4:b3:aa:6d:c8:04:ce:4e:ba:f6:29:4d:92:a3:94:b0:c2:ff:bd:bf:33:63:11:43:34:0f:51:b0:95:09:2f:63',
'sha512': 'f7:07:4a:f0:b0:f0:e6:8b:95:5f:f9:e6:61:0a:32:68:f1..."
type:
description:
- The key's type.
- 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
public_data:
description:
- Public key data. Depends on key type.
returned: success
type: dict
contains:
size:
description:
- Bit size of modulus (RSA) or prime number (DSA).
type: int
returned: When RV(_value.type=RSA) or RV(_value.type=DSA)
modulus:
description:
- The RSA key's modulus.
type: int
returned: When RV(_value.type=RSA)
exponent:
description:
- The RSA key's public exponent.
type: int
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 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 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 RV(_value.type=DSA)
curve:
description:
- The curve's name for ECC.
type: str
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 RV(_value.type=ECC)
x:
description:
- The C(x) coordinate for the public point on the elliptic curve.
type: int
returned: When RV(_value.type=ECC)
y:
description:
- 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 RV(_value.type=DSA) or RV(_value.type=ECC)
private_data:
description:
- Private key data. Depends on key type.
returned: success and when O(return_private_key_data) is set to V(true)
type: dict
'''
description:
- Information on the certificate.
type: dict
contains:
public_key:
description: Private key's public key in PEM format.
returned: success
type: str
sample: "-----BEGIN PUBLIC KEY-----\nMIICIjANBgkqhkiG9w0BAQEFAAOCAg8A..."
public_key_fingerprints:
description:
- Fingerprints of private key's public key.
- For every hash algorithm available, the fingerprint is computed.
returned: success
type: dict
sample: "{'sha256': 'd4:b3:aa:6d:c8:04:ce:4e:ba:f6:29:4d:92:a3:94:b0:c2:ff:bd:bf:33:63:11:43:34:0f:51:b0:95:09:2f:63',
'sha512': 'f7:07:4a:f0:b0:f0:e6:8b:95:5f:f9:e6:61:0a:32:68:f1..."
type:
description:
- The key's type.
- 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
public_data:
description:
- Public key data. Depends on key type.
returned: success
type: dict
contains:
size:
description:
- Bit size of modulus (RSA) or prime number (DSA).
type: int
returned: When RV(_value.type=RSA) or RV(_value.type=DSA)
modulus:
description:
- The RSA key's modulus.
type: int
returned: When RV(_value.type=RSA)
exponent:
description:
- The RSA key's public exponent.
type: int
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 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 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 RV(_value.type=DSA)
curve:
description:
- The curve's name for ECC.
type: str
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 RV(_value.type=ECC)
x:
description:
- The C(x) coordinate for the public point on the elliptic curve.
type: int
returned: When RV(_value.type=ECC)
y:
description:
- 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 RV(_value.type=DSA) or RV(_value.type=ECC)
private_data:
description:
- Private key data. Depends on key type.
returned: success and when O(return_private_key_data) is set to V(true)
type: dict
"""
from ansible.errors import AnsibleFilterError
from ansible.module_utils.six import string_types

194
plugins/filter/openssl_publickey_info.py
View File

@@ -7,26 +7,26 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
DOCUMENTATION = r"""
name: openssl_publickey_info
short_description: Retrieve information from OpenSSL public keys in PEM format
version_added: 2.10.0
author:
- Felix Fontein (@felixfontein)
- Felix Fontein (@felixfontein)
description:
- Provided a public key in OpenSSL PEM format, retrieve information.
- This is a filter version of the M(community.crypto.openssl_publickey_info) module.
- Provided a public key in OpenSSL PEM format, retrieve information.
- This is a filter version of the M(community.crypto.openssl_publickey_info) module.
options:
_input:
description:
- The content of the OpenSSL PEM public key.
type: string
required: true
_input:
description:
- The content of the OpenSSL PEM public key.
type: string
required: true
seealso:
- module: community.crypto.openssl_publickey_info
'''
- module: community.crypto.openssl_publickey_info
"""
EXAMPLES = '''
EXAMPLES = r"""
- name: Show the type of a public key
ansible.builtin.debug:
msg: >-
@@ -36,93 +36,93 @@ EXAMPLES = '''
| community.crypto.openssl_publickey_info
).type
}}
'''
"""
RETURN = '''
RETURN = r"""
_value:
description:
- Information on the public key.
type: dict
contains:
fingerprints:
description:
- Fingerprints of public key.
- For every hash algorithm available, the fingerprint is computed.
returned: success
type: dict
sample: "{'sha256': 'd4:b3:aa:6d:c8:04:ce:4e:ba:f6:29:4d:92:a3:94:b0:c2:ff:bd:bf:33:63:11:43:34:0f:51:b0:95:09:2f:63',
'sha512': 'f7:07:4a:f0:b0:f0:e6:8b:95:5f:f9:e6:61:0a:32:68:f1..."
type:
description:
- The key's type.
- 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
public_data:
description:
- Public key data. Depends on key type.
returned: success
type: dict
contains:
size:
description:
- Bit size of modulus (RSA) or prime number (DSA).
type: int
returned: When RV(_value.type=RSA) or RV(_value.type=DSA)
modulus:
description:
- The RSA key's modulus.
type: int
returned: When RV(_value.type=RSA)
exponent:
description:
- The RSA key's public exponent.
type: int
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 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 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 RV(_value.type=DSA)
curve:
description:
- The curve's name for ECC.
type: str
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 RV(_value.type=ECC)
x:
description:
- The C(x) coordinate for the public point on the elliptic curve.
type: int
returned: When RV(_value.type=ECC)
y:
description:
- 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 RV(_value.type=DSA) or RV(_value.type=ECC)
'''
description:
- Information on the public key.
type: dict
contains:
fingerprints:
description:
- Fingerprints of public key.
- For every hash algorithm available, the fingerprint is computed.
returned: success
type: dict
sample: "{'sha256': 'd4:b3:aa:6d:c8:04:ce:4e:ba:f6:29:4d:92:a3:94:b0:c2:ff:bd:bf:33:63:11:43:34:0f:51:b0:95:09:2f:63',
'sha512': 'f7:07:4a:f0:b0:f0:e6:8b:95:5f:f9:e6:61:0a:32:68:f1..."
type:
description:
- The key's type.
- 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
public_data:
description:
- Public key data. Depends on key type.
returned: success
type: dict
contains:
size:
description:
- Bit size of modulus (RSA) or prime number (DSA).
type: int
returned: When RV(_value.type=RSA) or RV(_value.type=DSA)
modulus:
description:
- The RSA key's modulus.
type: int
returned: When RV(_value.type=RSA)
exponent:
description:
- The RSA key's public exponent.
type: int
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 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 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 RV(_value.type=DSA)
curve:
description:
- The curve's name for ECC.
type: str
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 RV(_value.type=ECC)
x:
description:
- The C(x) coordinate for the public point on the elliptic curve.
type: int
returned: When RV(_value.type=ECC)
y:
description:
- 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 RV(_value.type=DSA) or RV(_value.type=ECC)
"""
from ansible.errors import AnsibleFilterError
from ansible.module_utils.six import string_types

20
plugins/filter/parse_serial.py
View File

@@ -6,19 +6,19 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = """
DOCUMENTATION = r"""
name: parse_serial
short_description: Convert a serial number as a colon-separated list of hex numbers to an integer
author: Felix Fontein (@felixfontein)
version_added: 2.18.0
description:
- "Parses a colon-separated list of hex numbers of the form C(00:11:22:33) and returns the corresponding integer."
- Parses a colon-separated list of hex numbers of the form C(00:11:22:33) and returns the corresponding integer.
options:
_input:
description:
- A serial number represented as a colon-separated list of hex numbers between 0 and 255.
- These numbers are interpreted as the byte presentation of an unsigned integer in network byte order.
That is, C(01:00) is interpreted as the integer 256.
- These numbers are interpreted as the byte presentation of an unsigned integer in network byte order. That is, C(01:00)
is interpreted as the integer 256.
type: string
required: true
seealso:
@@ -26,17 +26,17 @@ seealso:
plugin_type: filter
"""
EXAMPLES = """
EXAMPLES = r"""
- name: Parse serial number
ansible.builtin.debug:
msg: "{{ '11:22:33' | community.crypto.parse_serial }}"
"""
RETURN = """
_value:
description:
- The serial number as an integer.
type: int
RETURN = r"""
_value:
description:
- The serial number as an integer.
type: int
"""
from ansible.errors import AnsibleFilterError

34
plugins/filter/split_pem.py
View File

@@ -7,37 +7,37 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
DOCUMENTATION = r"""
name: split_pem
short_description: Split PEM file contents into multiple objects
version_added: 2.10.0
author:
- Felix Fontein (@felixfontein)
- Felix Fontein (@felixfontein)
description:
- Split PEM file contents into multiple PEM objects. Comments or invalid parts are ignored.
- Split PEM file contents into multiple PEM objects. Comments or invalid parts are ignored.
options:
_input:
description:
- The PEM contents to split.
type: string
required: true
'''
_input:
description:
- The PEM contents to split.
type: string
required: true
"""
EXAMPLES = '''
EXAMPLES = r"""
- name: Print all CA certificates
ansible.builtin.debug:
msg: '{{ item }}'
loop: >-
{{ lookup('ansible.builtin.file', '/path/to/ca-bundle.pem') | community.crypto.split_pem }}
'''
"""
RETURN = '''
RETURN = r"""
_value:
description:
- A list of PEM file contents.
type: list
elements: string
'''
description:
- A list of PEM file contents.
type: list
elements: string
"""
from ansible.errors import AnsibleFilterError
from ansible.module_utils.six import string_types

20
plugins/filter/to_serial.py
View File

@@ -6,13 +6,13 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = """
DOCUMENTATION = r"""
name: to_serial
short_description: Convert an integer to a colon-separated list of hex numbers
author: Felix Fontein (@felixfontein)
version_added: 2.18.0
description:
- "Converts an integer to a colon-separated list of hex numbers of the form C(00:11:22:33)."
- Converts an integer to a colon-separated list of hex numbers of the form C(00:11:22:33).
options:
_input:
description:
@@ -24,19 +24,19 @@ seealso:
plugin_type: filter
"""
EXAMPLES = """
EXAMPLES = r"""
- name: Convert integer to serial number
ansible.builtin.debug:
msg: "{{ 1234567 | community.crypto.to_serial }}"
"""
RETURN = """
_value:
description:
- A colon-separated list of hexadecimal numbers.
- Letters are upper-case, and all numbers have exactly two digits.
- The string is never empty. The representation of C(0) is C("00").
type: string
RETURN = r"""
_value:
description:
- A colon-separated list of hexadecimal numbers.
- Letters are upper-case, and all numbers have exactly two digits.
- The string is never empty. The representation of C(0) is C("00").
type: string
"""
from ansible.errors import AnsibleFilterError

566
plugins/filter/x509_certificate_info.py
View File

@@ -7,30 +7,30 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
DOCUMENTATION = r"""
name: x509_certificate_info
short_description: Retrieve information from X.509 certificates in PEM format
version_added: 2.10.0
author:
- Felix Fontein (@felixfontein)
- Felix Fontein (@felixfontein)
description:
- Provided a X.509 certificate in PEM format, retrieve information.
- This is a filter version of the M(community.crypto.x509_certificate_info) module.
- Provided a X.509 certificate in PEM format, retrieve information.
- This is a filter version of the M(community.crypto.x509_certificate_info) module.
options:
_input:
description:
- The content of the X.509 certificate in PEM format.
type: string
required: true
_input:
description:
- The content of the X.509 certificate in PEM format.
type: string
required: true
extends_documentation_fragment:
- community.crypto.name_encoding
- community.crypto.name_encoding
seealso:
- module: community.crypto.x509_certificate_info
- plugin: community.crypto.to_serial
plugin_type: filter
'''
- module: community.crypto.x509_certificate_info
- plugin: community.crypto.to_serial
plugin_type: filter
"""
EXAMPLES = '''
EXAMPLES = r"""
- name: Show the Subject Alt Names of the certificate
ansible.builtin.debug:
msg: >-
@@ -40,278 +40,274 @@ EXAMPLES = '''
| community.crypto.x509_certificate_info
).subject_alt_name | join(', ')
}}
'''
"""
RETURN = '''
RETURN = r"""
_value:
description:
- Information on the certificate.
type: dict
contains:
expired:
description: Whether the certificate is expired (in other words, C(notAfter) is in the past).
returned: success
type: bool
basic_constraints:
description: Entries in the C(basic_constraints) extension, or V(none) if extension is not present.
returned: success
type: list
elements: str
sample: ["CA:TRUE", "pathlen:1"]
basic_constraints_critical:
description: Whether the C(basic_constraints) extension is critical.
returned: success
type: bool
extended_key_usage:
description: Entries in the C(extended_key_usage) extension, or V(none) if extension is not present.
returned: success
type: list
elements: str
sample: [Biometric Info, DVCS, Time Stamping]
extended_key_usage_critical:
description: Whether the C(extended_key_usage) extension is critical.
returned: success
type: bool
extensions_by_oid:
description: Returns a dictionary for every extension OID.
returned: success
type: dict
contains:
critical:
description: Whether the extension is critical.
returned: success
type: bool
value:
description:
- The Base64 encoded value (in DER format) of the extension.
- B(Note) that depending on the C(cryptography) version used, it is
not possible to extract the ASN.1 content of the extension, but only
to provide the re-encoded content of the extension in case it was
parsed by C(cryptography). This should usually result in exactly the
same value, except if the original extension value was malformed.
returned: success
type: str
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 V(none) if extension is not present.
returned: success
type: str
sample: [Key Agreement, Data Encipherment]
key_usage_critical:
description: Whether the C(key_usage) extension is critical.
returned: success
type: bool
subject_alt_name:
description:
- 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
sample: ["DNS:www.ansible.com", "IP:1.2.3.4"]
subject_alt_name_critical:
description: Whether the C(subject_alt_name) extension is critical.
returned: success
type: bool
ocsp_must_staple:
description: V(true) if the OCSP Must Staple extension is present, V(none) otherwise.
returned: success
type: bool
ocsp_must_staple_critical:
description: Whether the C(ocsp_must_staple) extension is critical.
returned: success
type: bool
issuer:
description:
- The certificate's issuer.
- Note that for repeated values, only the last one will be returned.
returned: success
type: dict
sample: {"organizationName": "Ansible", "commonName": "ca.example.com"}
issuer_ordered:
description: The certificate's issuer as an ordered list of tuples.
returned: success
type: list
elements: list
sample: [["organizationName", "Ansible"], ["commonName": "ca.example.com"]]
subject:
description:
- The certificate's subject as a dictionary.
- Note that for repeated values, only the last one will be returned.
returned: success
type: dict
sample: {"commonName": "www.example.com", "emailAddress": "test@example.com"}
subject_ordered:
description: The certificate's subject as an ordered list of tuples.
returned: success
type: list
elements: list
sample: [["commonName", "www.example.com"], ["emailAddress": "test@example.com"]]
not_after:
description: C(notAfter) date as ASN.1 TIME.
returned: success
type: str
sample: '20190413202428Z'
not_before:
description: C(notBefore) date as ASN.1 TIME.
returned: success
type: str
sample: '20190331202428Z'
public_key:
description: Certificate's public key in PEM format.
returned: success
type: str
sample: "-----BEGIN PUBLIC KEY-----\nMIICIjANBgkqhkiG9w0BAQEFAAOCAg8A..."
public_key_type:
description:
- The certificate's public key's type.
- 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
public_key_data:
description:
- Public key data. Depends on the public key's type.
returned: success
type: dict
contains:
size:
description:
- Bit size of modulus (RSA) or prime number (DSA).
type: int
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 RV(_value.public_key_type=RSA)
exponent:
description:
- The RSA key's public exponent.
type: int
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 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 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 RV(_value.public_key_type=DSA)
curve:
description:
- The curve's name for ECC.
type: str
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 RV(_value.public_key_type=ECC)
x:
description:
- The C(x) coordinate for the public point on the elliptic curve.
type: int
returned: When RV(_value.public_key_type=ECC)
y:
description:
- 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 RV(_value.public_key_type=DSA) or RV(_value.public_key_type=ECC)
public_key_fingerprints:
description:
- Fingerprints of certificate's public key.
- For every hash algorithm available, the fingerprint is computed.
returned: success
type: dict
sample: "{'sha256': 'd4:b3:aa:6d:c8:04:ce:4e:ba:f6:29:4d:92:a3:94:b0:c2:ff:bd:bf:33:63:11:43:34:0f:51:b0:95:09:2f:63',
'sha512': 'f7:07:4a:f0:b0:f0:e6:8b:95:5f:f9:e6:61:0a:32:68:f1..."
fingerprints:
description:
- Fingerprints of the DER-encoded form of the whole certificate.
- For every hash algorithm available, the fingerprint is computed.
returned: success
type: dict
sample: "{'sha256': 'd4:b3:aa:6d:c8:04:ce:4e:ba:f6:29:4d:92:a3:94:b0:c2:ff:bd:bf:33:63:11:43:34:0f:51:b0:95:09:2f:63',
'sha512': 'f7:07:4a:f0:b0:f0:e6:8b:95:5f:f9:e6:61:0a:32:68:f1..."
signature_algorithm:
description: The signature algorithm used to sign the certificate.
returned: success
type: str
sample: sha256WithRSAEncryption
serial_number:
description:
- The certificate's serial number.
- This return value is an B(integer). If you need the serial numbers as a colon-separated hex string,
such as C(11:22:33), you need to convert it to that form with P(community.crypto.to_serial#filter).
returned: success
type: int
sample: 1234
version:
description: The certificate version.
returned: success
type: int
sample: 3
subject_key_identifier:
description:
- The certificate's subject key identifier.
- 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 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 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
sample: ["DNS:www.ansible.com", "IP:1.2.3.4"]
authority_cert_serial_number:
description:
- The certificate's authority cert serial number.
- Is V(none) if the C(AuthorityKeyIdentifier) extension is not present.
- This return value is an B(integer). If you need the serial numbers as a colon-separated hex string,
such as C(11:22:33), you need to convert it to that form with P(community.crypto.to_serial#filter).
returned: success
type: int
sample: 12345
ocsp_uri:
description: The OCSP responder URI, if included in the certificate. Will be
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
V(none) if no issuer URI is included.
returned: success
type: str
'''
description:
- Information on the certificate.
type: dict
contains:
expired:
description: Whether the certificate is expired (in other words, C(notAfter) is in the past).
returned: success
type: bool
basic_constraints:
description: Entries in the C(basic_constraints) extension, or V(none) if extension is not present.
returned: success
type: list
elements: str
sample: ["CA:TRUE", "pathlen:1"]
basic_constraints_critical:
description: Whether the C(basic_constraints) extension is critical.
returned: success
type: bool
extended_key_usage:
description: Entries in the C(extended_key_usage) extension, or V(none) if extension is not present.
returned: success
type: list
elements: str
sample: [Biometric Info, DVCS, Time Stamping]
extended_key_usage_critical:
description: Whether the C(extended_key_usage) extension is critical.
returned: success
type: bool
extensions_by_oid:
description: Returns a dictionary for every extension OID.
returned: success
type: dict
contains:
critical:
description: Whether the extension is critical.
returned: success
type: bool
value:
description:
- The Base64 encoded value (in DER format) of the extension.
- B(Note) that depending on the C(cryptography) version used, it is not possible to extract the ASN.1 content
of the extension, but only to provide the re-encoded content of the extension in case it was parsed by C(cryptography).
This should usually result in exactly the same value, except if the original extension value was malformed.
returned: success
type: str
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 V(none) if extension is not present.
returned: success
type: str
sample: [Key Agreement, Data Encipherment]
key_usage_critical:
description: Whether the C(key_usage) extension is critical.
returned: success
type: bool
subject_alt_name:
description:
- 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
sample: ["DNS:www.ansible.com", "IP:1.2.3.4"]
subject_alt_name_critical:
description: Whether the C(subject_alt_name) extension is critical.
returned: success
type: bool
ocsp_must_staple:
description: V(true) if the OCSP Must Staple extension is present, V(none) otherwise.
returned: success
type: bool
ocsp_must_staple_critical:
description: Whether the C(ocsp_must_staple) extension is critical.
returned: success
type: bool
issuer:
description:
- The certificate's issuer.
- Note that for repeated values, only the last one will be returned.
returned: success
type: dict
sample: {"organizationName": "Ansible", "commonName": "ca.example.com"}
issuer_ordered:
description: The certificate's issuer as an ordered list of tuples.
returned: success
type: list
elements: list
sample: [["organizationName", "Ansible"], ["commonName": "ca.example.com"]]
subject:
description:
- The certificate's subject as a dictionary.
- Note that for repeated values, only the last one will be returned.
returned: success
type: dict
sample: {"commonName": "www.example.com", "emailAddress": "test@example.com"}
subject_ordered:
description: The certificate's subject as an ordered list of tuples.
returned: success
type: list
elements: list
sample: [["commonName", "www.example.com"], ["emailAddress": "test@example.com"]]
not_after:
description: C(notAfter) date as ASN.1 TIME.
returned: success
type: str
sample: '20190413202428Z'
not_before:
description: C(notBefore) date as ASN.1 TIME.
returned: success
type: str
sample: '20190331202428Z'
public_key:
description: Certificate's public key in PEM format.
returned: success
type: str
sample: "-----BEGIN PUBLIC KEY-----\nMIICIjANBgkqhkiG9w0BAQEFAAOCAg8A..."
public_key_type:
description:
- The certificate's public key's type.
- 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
public_key_data:
description:
- Public key data. Depends on the public key's type.
returned: success
type: dict
contains:
size:
description:
- Bit size of modulus (RSA) or prime number (DSA).
type: int
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 RV(_value.public_key_type=RSA)
exponent:
description:
- The RSA key's public exponent.
type: int
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 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 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 RV(_value.public_key_type=DSA)
curve:
description:
- The curve's name for ECC.
type: str
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 RV(_value.public_key_type=ECC)
x:
description:
- The C(x) coordinate for the public point on the elliptic curve.
type: int
returned: When RV(_value.public_key_type=ECC)
y:
description:
- 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 RV(_value.public_key_type=DSA) or RV(_value.public_key_type=ECC)
public_key_fingerprints:
description:
- Fingerprints of certificate's public key.
- For every hash algorithm available, the fingerprint is computed.
returned: success
type: dict
sample: "{'sha256': 'd4:b3:aa:6d:c8:04:ce:4e:ba:f6:29:4d:92:a3:94:b0:c2:ff:bd:bf:33:63:11:43:34:0f:51:b0:95:09:2f:63',
'sha512': 'f7:07:4a:f0:b0:f0:e6:8b:95:5f:f9:e6:61:0a:32:68:f1..."
fingerprints:
description:
- Fingerprints of the DER-encoded form of the whole certificate.
- For every hash algorithm available, the fingerprint is computed.
returned: success
type: dict
sample: "{'sha256': 'd4:b3:aa:6d:c8:04:ce:4e:ba:f6:29:4d:92:a3:94:b0:c2:ff:bd:bf:33:63:11:43:34:0f:51:b0:95:09:2f:63',
'sha512': 'f7:07:4a:f0:b0:f0:e6:8b:95:5f:f9:e6:61:0a:32:68:f1..."
signature_algorithm:
description: The signature algorithm used to sign the certificate.
returned: success
type: str
sample: sha256WithRSAEncryption
serial_number:
description:
- The certificate's serial number.
- This return value is an B(integer). If you need the serial numbers as a colon-separated hex string, such as C(11:22:33),
you need to convert it to that form with P(community.crypto.to_serial#filter).
returned: success
type: int
sample: 1234
version:
description: The certificate version.
returned: success
type: int
sample: 3
subject_key_identifier:
description:
- The certificate's subject key identifier.
- 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 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 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
sample: ["DNS:www.ansible.com", "IP:1.2.3.4"]
authority_cert_serial_number:
description:
- The certificate's authority cert serial number.
- Is V(none) if the C(AuthorityKeyIdentifier) extension is not present.
- This return value is an B(integer). If you need the serial numbers as a colon-separated hex string, such as C(11:22:33),
you need to convert it to that form with P(community.crypto.to_serial#filter).
returned: success
type: int
sample: 12345
ocsp_uri:
description: The OCSP responder URI, if included in the certificate. Will be 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 V(none) if no issuer URI is included.
returned: success
type: str
"""
from ansible.errors import AnsibleFilterError
from ansible.module_utils.six import string_types

251
plugins/filter/x509_crl_info.py
View File

@@ -7,39 +7,38 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
DOCUMENTATION = r"""
name: x509_crl_info
short_description: Retrieve information from X.509 CRLs in PEM format
version_added: 2.10.0
author:
- Felix Fontein (@felixfontein)
- Felix Fontein (@felixfontein)
description:
- Provided a X.509 crl in PEM format, retrieve information.
- This is a filter version of the M(community.crypto.x509_crl_info) module.
- Provided a X.509 crl in PEM format, retrieve information.
- This is a filter version of the M(community.crypto.x509_crl_info) module.
options:
_input:
description:
- The content of the X.509 CRL in PEM format.
type: string
required: true
list_revoked_certificates:
description:
- 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.
type: bool
default: true
version_added: 1.7.0
_input:
description:
- The content of the X.509 CRL in PEM format.
type: string
required: true
list_revoked_certificates:
description:
- 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.
type: bool
default: true
version_added: 1.7.0
extends_documentation_fragment:
- community.crypto.name_encoding
- community.crypto.name_encoding
seealso:
- module: community.crypto.x509_crl_info
- plugin: community.crypto.to_serial
plugin_type: filter
'''
- module: community.crypto.x509_crl_info
- plugin: community.crypto.to_serial
plugin_type: filter
"""
EXAMPLES = '''
EXAMPLES = r"""
- name: Show the Organization Name of the CRL's subject
ansible.builtin.debug:
msg: >-
@@ -49,111 +48,111 @@ EXAMPLES = '''
| community.crypto.x509_crl_info
).issuer.organizationName
}}
'''
"""
RETURN = '''
RETURN = r"""
_value:
description:
- Information on the CRL.
type: dict
contains:
format:
description:
- Whether the CRL is in PEM format (V(pem)) or in DER format (V(der)).
returned: success
type: str
sample: pem
choices:
- pem
- der
description:
- Information on the CRL.
type: dict
contains:
format:
description:
- 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 O(name_encoding) for how IDNs are handled.
returned: success
type: dict
sample: {"organizationName": "Ansible", "commonName": "ca.example.com"}
issuer_ordered:
description: The CRL's issuer as an ordered list of tuples.
returned: success
type: list
elements: list
sample: [["organizationName", "Ansible"], ["commonName": "ca.example.com"]]
last_update:
description: The point in time from which this CRL can be trusted as ASN.1 TIME.
returned: success
type: str
sample: '20190413202428Z'
next_update:
description: The point in time from which a new CRL will be issued and the client has to check for it as ASN.1 TIME.
returned: success
type: str
sample: '20190413202428Z'
digest:
description: The signature algorithm used to sign the CRL.
returned: success
type: str
sample: sha256WithRSAEncryption
revoked_certificates:
description: List of certificates to be revoked.
returned: success if O(list_revoked_certificates=true)
type: list
elements: dict
contains:
serial_number:
description:
- Serial number of the certificate.
- This return value is an B(integer). If you need the serial numbers as a colon-separated hex string, such as
C(11:22:33), you need to convert it to that form with P(community.crypto.to_serial#filter).
type: int
sample: 1234
revocation_date:
description: The point in time the certificate was revoked as ASN.1 TIME.
type: str
sample: '20190413202428Z'
issuer:
description:
- The CRL's issuer.
- Note that for repeated values, only the last one will be returned.
- See O(name_encoding) for how IDNs are handled.
returned: success
type: dict
sample: {"organizationName": "Ansible", "commonName": "ca.example.com"}
issuer_ordered:
description: The CRL's issuer as an ordered list of tuples.
returned: success
type: list
elements: list
sample: [["organizationName", "Ansible"], ["commonName": "ca.example.com"]]
last_update:
description: The point in time from which this CRL can be trusted as ASN.1 TIME.
returned: success
type: str
sample: '20190413202428Z'
next_update:
description: The point in time from which a new CRL will be issued and the client has to check for it as ASN.1 TIME.
returned: success
type: str
sample: '20190413202428Z'
digest:
description: The signature algorithm used to sign the CRL.
returned: success
type: str
sample: sha256WithRSAEncryption
revoked_certificates:
description: List of certificates to be revoked.
returned: success if O(list_revoked_certificates=true)
type: list
elements: dict
contains:
serial_number:
description:
- Serial number of the certificate.
- This return value is an B(integer). If you need the serial numbers as a colon-separated hex string,
such as C(11:22:33), you need to convert it to that form with P(community.crypto.to_serial#filter).
type: int
sample: 1234
revocation_date:
description: The point in time the certificate was revoked as ASN.1 TIME.
type: str
sample: '20190413202428Z'
issuer:
description:
- The certificate's issuer.
- See O(name_encoding) for how IDNs are handled.
type: list
elements: str
sample: ["DNS:ca.example.org"]
issuer_critical:
description: Whether the certificate issuer extension is critical.
type: bool
sample: false
reason:
description:
- The value for the revocation reason extension.
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
sample: false
invalidity_date:
description: |
The point in time it was known/suspected that the private key was compromised
or that the certificate otherwise became invalid as ASN.1 TIME.
type: str
sample: '20190413202428Z'
invalidity_date_critical:
description: Whether the invalidity date extension is critical.
type: bool
sample: false
'''
description:
- The certificate's issuer.
- See O(name_encoding) for how IDNs are handled.
type: list
elements: str
sample: ["DNS:ca.example.org"]
issuer_critical:
description: Whether the certificate issuer extension is critical.
type: bool
sample: false
reason:
description:
- The value for the revocation reason extension.
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
sample: false
invalidity_date:
description: |-
The point in time it was known/suspected that the private key was compromised
or that the certificate otherwise became invalid as ASN.1 TIME.
type: str
sample: '20190413202428Z'
invalidity_date_critical:
description: Whether the invalidity date extension is critical.
type: bool
sample: false
"""
import base64
import binascii

20
plugins/lookup/gpg_fingerprint.py
View File

@@ -6,13 +6,13 @@
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = """
DOCUMENTATION = r"""
name: gpg_fingerprint
short_description: Retrieve a GPG fingerprint from a GPG public or private key file
author: Felix Fontein (@felixfontein)
version_added: 2.15.0
description:
- "Takes a list of filenames pointing to GPG public or private key files. Returns the fingerprints for each of these keys."
- Takes a list of filenames pointing to GPG public or private key files. Returns the fingerprints for each of these keys.
options:
_terms:
description:
@@ -27,19 +27,19 @@ seealso:
plugin_type: filter
"""
EXAMPLES = """
EXAMPLES = r"""
- name: Show fingerprint of GPG public key
ansible.builtin.debug:
msg: "{{ lookup('community.crypto.gpg_fingerprint', '/path/to/public_key.gpg') }}"
"""
RETURN = """
_value:
description:
- The fingerprints of the provided public or private GPG keys.
- The list has one entry for every path provided.
type: list
elements: string
RETURN = r"""
_value:
description:
- The fingerprints of the provided public or private GPG keys.
- The list has one entry for every path provided.
type: list
elements: string
"""
from ansible.plugins.lookup import LookupBase

88
plugins/modules/acme_account.py
View File

@@ -9,21 +9,18 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: acme_account
author: "Felix Fontein (@felixfontein)"
short_description: Create, modify or delete ACME accounts
description:
- "Allows to create, modify or delete accounts with a CA supporting the
L(ACME protocol,https://tools.ietf.org/html/rfc8555),
such as L(Let's Encrypt,https://letsencrypt.org/)."
- "This module only works with the ACME v2 protocol."
- Allows to create, modify or delete accounts with a CA supporting the L(ACME protocol,https://tools.ietf.org/html/rfc8555),
such as L(Let's Encrypt,https://letsencrypt.org/).
- This module only works with the ACME v2 protocol.
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 O(community.crypto.acme_certificate#module:modify_account) option of
M(community.crypto.acme_certificate)."
- 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
O(community.crypto.acme_certificate#module:modify_account) option of M(community.crypto.acme_certificate).
seealso:
- name: Automatic Certificate Management Environment (ACME)
description: The specification of the ACME protocol (RFC 8555).
@@ -49,64 +46,61 @@ attributes:
options:
state:
description:
- "The state of the account, to be identified by its account key."
- "If the state is V(absent), the account will either not exist or be
deactivated."
- "If the state is V(changed_key), the account must exist. The account
key will be changed; no other information will be touched."
- The state of the account, to be identified by its account key.
- If the state is V(absent), the account will either not exist or be deactivated.
- 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
choices:
- present
- absent
- changed_key
- present
- absent
- changed_key
allow_creation:
description:
- "Whether account creation is allowed (when state is V(present))."
- Whether account creation is allowed (when state is V(present)).
type: bool
default: true
contact:
description:
- "A list of contact URLs."
- "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 V(present). Will be ignored
if state is V(absent) or V(changed_key)."
- A list of contact URLs.
- 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 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 V(true)."
- Boolean indicating whether you agree to the terms of service document.
- 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 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)."
- Path to a file containing the ACME account RSA or Elliptic Curve key to change to.
- 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 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)."
- Content of the ACME account RSA or Elliptic Curve key to change to.
- 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:
- Phassphrase to use to decode the new account key.
- "B(Note:) this is not supported by the C(openssl) backend, only by the C(cryptography) backend."
- B(Note:) this is not supported by the C(openssl) backend, only by the C(cryptography) backend.
type: str
version_added: 1.6.0
external_account_binding:
description:
- Allows to provide external account binding data during account creation.
- This is used by CAs like Sectigo to bind a new ACME account to an existing CA-specific
account, to be able to properly identify a customer.
- This is used by CAs like Sectigo to bind a new ACME account to an existing CA-specific account, to be able to properly
identify a customer.
- Only used when creating a new account. Can not be specified for ACME v1.
type: dict
suboptions:
@@ -121,7 +115,7 @@ options:
- If not specified by the CA, this is probably V(HS256).
type: str
required: true
choices: [ HS256, HS384, HS512 ]
choices: [HS256, HS384, HS512]
key:
description:
- Base64 URL encoded value of the MAC key provided by the CA.
@@ -129,17 +123,17 @@ options:
type: str
required: true
version_added: 1.1.0
'''
"""
EXAMPLES = '''
EXAMPLES = r"""
- name: Make sure account exists and has given contacts. We agree to TOS.
community.crypto.acme_account:
account_key_src: /etc/pki/cert/private/account.key
state: present
terms_agreed: true
contact:
- mailto:me@example.com
- mailto:myself@example.org
- mailto:me@example.com
- mailto:myself@example.org
- name: Make sure account has given email address. Do not create account if it does not exist
community.crypto.acme_account:
@@ -147,7 +141,7 @@ EXAMPLES = '''
state: present
allow_creation: false
contact:
- mailto:me@example.com
- mailto:me@example.com
- name: Change account's key to the one stored in the variable new_account_key
community.crypto.acme_account:
@@ -159,14 +153,14 @@ EXAMPLES = '''
community.crypto.acme_account:
account_key_content: '{{ new_account_key }}'
state: absent
'''
"""
RETURN = '''
RETURN = r"""
account_uri:
description: ACME account URI, or None if account does not exist.
returned: always
type: str
'''
"""
import base64

61
plugins/modules/acme_account_info.py
View File

@@ -9,21 +9,17 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: acme_account_info
author: "Felix Fontein (@felixfontein)"
short_description: Retrieves information on ACME accounts
description:
- "Allows to retrieve information on accounts a CA supporting the
L(ACME protocol,https://tools.ietf.org/html/rfc8555),
such as L(Let's Encrypt,https://letsencrypt.org/)."
- "This module only works with the ACME v2 protocol."
- Allows to retrieve information on accounts a CA supporting the L(ACME protocol,https://tools.ietf.org/html/rfc8555), such
as L(Let's Encrypt,https://letsencrypt.org/).
- This module only works with the ACME v2 protocol.
notes:
- "The M(community.crypto.acme_account) module allows to modify, create and delete ACME
accounts."
- "This module was called C(acme_account_facts) before Ansible 2.8. The usage
did not change."
- The M(community.crypto.acme_account) module allows to modify, create and delete ACME accounts.
- This module was called C(acme_account_facts) before Ansible 2.8. The usage did not change.
extends_documentation_fragment:
- community.crypto.acme.basic
- community.crypto.acme.account
@@ -33,14 +29,11 @@ extends_documentation_fragment:
options:
retrieve_orders:
description:
- "Whether to retrieve the list of order URLs or order objects, if provided
by the ACME server."
- "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."
- Whether to retrieve the list of order URLs or order objects, if provided by the ACME server.
- 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:
- ignore
@@ -50,10 +43,9 @@ options:
seealso:
- module: community.crypto.acme_account
description: Allows to create, modify or delete an ACME account.
"""
'''
EXAMPLES = '''
EXAMPLES = r"""
- name: Check whether an account with the given account key exists
community.crypto.acme_account_info:
account_key_src: /etc/pki/cert/private/account.key
@@ -81,9 +73,9 @@ EXAMPLES = '''
- name: Print account contacts
ansible.builtin.debug:
var: account_data.account.contact
'''
"""
RETURN = '''
RETURN = r"""
exists:
description: Whether the account exists.
returned: always
@@ -100,13 +92,13 @@ account:
type: dict
contains:
contact:
description: the challenge resource that must be created for validation
description: The challenge resource that must be created for validation.
returned: always
type: list
elements: str
sample: ['mailto:me@example.com', 'tel:00123456789']
status:
description: the account's status
description: The account's status.
returned: always
type: str
choices: ['valid', 'deactivated', 'revoked']
@@ -114,20 +106,19 @@ account:
orders:
description:
- A URL where a list of orders can be retrieved for this account.
- Use the O(retrieve_orders) option to query this URL and retrieve the
complete list of orders.
- Use the O(retrieve_orders) option to query this URL and retrieve the complete list of orders.
returned: always
type: str
sample: https://example.ca/account/1/orders
public_account_key:
description: the public account key as a L(JSON Web Key,https://tools.ietf.org/html/rfc7517).
description: The public account key as a L(JSON Web Key,https://tools.ietf.org/html/rfc7517).
returned: always
type: str
sample: '{"kty":"EC","crv":"P-256","x":"MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4","y":"4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM"}'
orders:
description:
- "The list of orders."
- The list of orders.
type: list
elements: dict
returned: if account exists, O(retrieve_orders) is V(object_list), and server supports order listing
@@ -164,8 +155,8 @@ orders:
description: Name of identifier. Hostname or IP address.
type: str
wildcard:
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)."
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:
@@ -205,14 +196,14 @@ orders:
order_uris:
description:
- "The list of orders."
- "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."
- The list of orders.
- 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, O(retrieve_orders) is not V(ignore), and server supports order listing
version_added: 1.5.0
'''
"""
from ansible_collections.community.crypto.plugins.module_utils.acme.acme import (
create_backend,

31
plugins/modules/acme_ari_info.py
View File

@@ -9,18 +9,16 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: acme_ari_info
author: "Felix Fontein (@felixfontein)"
version_added: 2.20.0
short_description: Retrieves ACME Renewal Information (ARI) for a certificate
description:
- "Allows to retrieve renewal information on a certificate obtained with the
L(ACME protocol,https://tools.ietf.org/html/rfc8555)."
- "This module only works with the ACME v2 protocol, and requires the ACME server
to support the ARI extension (U(https://datatracker.ietf.org/doc/draft-ietf-acme-ari/)).
This module implements version 3 of the ARI draft."
- Allows to retrieve renewal information on a certificate obtained with the L(ACME protocol,https://tools.ietf.org/html/rfc8555).
- This module only works with the ACME v2 protocol, and requires the ACME server to support the ARI extension
(U(https://datatracker.ietf.org/doc/draft-ietf-acme-ari/)).
This module implements version 3 of the ARI draft.
extends_documentation_fragment:
- community.crypto.acme.basic
- community.crypto.acme.no_account
@@ -39,12 +37,12 @@ options:
type: str
seealso:
- module: community.crypto.acme_certificate
description: Allows to obtain a certificate using the ACME protocol
description: Allows to obtain a certificate using the ACME protocol.
- module: community.crypto.acme_certificate_revoke
description: Allows to revoke a certificate using the ACME protocol
'''
description: Allows to revoke a certificate using the ACME protocol.
"""
EXAMPLES = '''
EXAMPLES = r"""
- name: Retrieve renewal information for a certificate
community.crypto.acme_ari_info:
certificate_path: /etc/httpd/ssl/sample.com.crt
@@ -53,9 +51,9 @@ EXAMPLES = '''
- name: Show the certificate renewal information
ansible.builtin.debug:
var: cert_data.renewal_info
'''
"""
RETURN = '''
RETURN = r"""
renewal_info:
description: The ARI renewal info object (U(https://www.ietf.org/archive/id/draft-ietf-acme-ari-03.html#section-4.2)).
returned: success
@@ -84,9 +82,8 @@ renewal_info:
explanationURL:
description:
- A URL pointing to a page which may explain why the suggested renewal window is what it is.
- For example, it may be a page explaining the CA's dynamic load-balancing strategy, or a
page documenting which certificates are affected by a mass revocation event. Should be shown
to the user.
- For example, it may be a page explaining the CA's dynamic load-balancing strategy, or a page documenting which certificates
are affected by a mass revocation event. Should be shown to the user.
returned: depends on the ACME server
type: str
sample: https://example.com/docs/ari
@@ -96,7 +93,7 @@ renewal_info:
returned: depends on the ACME server
type: str
sample: '2024-04-29T01:17:10.236921+00:00'
'''
"""
from ansible_collections.community.crypto.plugins.module_utils.acme.acme import (
create_backend,

266
plugins/modules/acme_certificate.py
View File

@@ -9,49 +9,37 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: acme_certificate
author: "Michael Gruener (@mgruener)"
short_description: Create SSL/TLS certificates with the ACME protocol
description:
- "Create and renew SSL/TLS certificates with a CA supporting the
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 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 O(data)."
- "Between these two tasks you have to fulfill the required steps for the
chosen challenge by whatever means necessary. For V(http-01) that means
creating the necessary challenge file on the destination webserver. For
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
L(the main ACME specification,https://tools.ietf.org/html/rfc8555#section-8)
and the L(TLS-ALPN-01 specification,https://www.rfc-editor.org/rfc/rfc8737.html#section-3).
Also, consider the examples provided for this module."
- "The module includes experimental support for IP identifiers according to
the L(RFC 8738,https://www.rfc-editor.org/rfc/rfc8738.html)."
- Create and renew SSL/TLS certificates with a CA supporting the 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 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 O(data).
- Between these two tasks you have to fulfill the required steps for the chosen challenge by whatever means necessary. For
V(http-01) that means creating the necessary challenge file on the destination webserver. For 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 L(the main ACME specification,https://tools.ietf.org/html/rfc8555#section-8)
and the L(TLS-ALPN-01 specification,https://www.rfc-editor.org/rfc/rfc8737.html#section-3). Also, consider the examples
provided for this module.
- 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 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 O(modify_account) option."
- "This module was called C(letsencrypt) before Ansible 2.6. The usage
did not change."
- 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 O(modify_account)
option.
- This module was called C(letsencrypt) before Ansible 2.6. The usage did not change.
seealso:
- name: The Let's Encrypt documentation
description: Documentation for the Let's Encrypt Certification Authority.
Provides useful information for example on rate limits.
description: Documentation for the Let's Encrypt Certification Authority. Provides useful information for example on rate
limits.
link: https://letsencrypt.org/docs/
- name: Buypass Go SSL
description: Documentation for the Buypass Certification Authority.
Provides useful information for example on rate limits.
description: Documentation for the Buypass Certification Authority. Provides useful information for example on rate limits.
link: https://www.buypass.com/ssl/products/acme
- name: Automatic Certificate Management Environment (ACME)
description: The specification of the ACME protocol (RFC 8555).
@@ -96,44 +84,39 @@ attributes:
options:
account_email:
description:
- "The email address associated with this account."
- "It will be used for certificate expiration warnings."
- "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."
- The email address associated with this account.
- It will be used for certificate expiration warnings.
- 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.
type: str
agreement:
description:
- "URI to a terms of service document you agree to when using the
ACME v1 service at O(acme_directory)."
- URI to a terms of service document you agree to when using the 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."
- 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 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 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 V(false), O(terms_agreed) and O(account_email) are ignored."
- Boolean indicating whether the module should create the account if necessary, and update its contact data.
- 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 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 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.
- 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.
type: str
default: 'http-01'
choices:
@@ -147,31 +130,24 @@ options:
version_added: 1.2.0
data:
description:
- "The data to validate ongoing challenges. This must be specified for
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 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 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 O(data) does
not contain any information which can be used without having
access to the account key or which are not public anyway."
- The data to validate ongoing challenges. This must be specified for 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 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 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 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 O(fullchain_dest) is not specified."
- The destination file for the certificate.
- 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 O(dest) is not specified."
- The destination file for the full chain (that is, a certificate followed by chain of intermediate certificates).
- Required if O(dest) is not specified.
type: path
aliases: ['fullchain']
chain_dest:
@@ -181,115 +157,98 @@ options:
aliases: ['chain']
remaining_days:
description:
- "The number of days the certificate must have left being valid.
If RV(cert_days) < O(remaining_days), then it will be renewed.
If the certificate is not renewed, module return values will not
include RV(challenge_data)."
- "To make sure that the certificate is renewed in any case, you can
use the O(force) option."
- The number of days the certificate must have left being valid. If RV(cert_days) < O(remaining_days), then it will
be renewed. If the certificate is not renewed, module return values will not include RV(challenge_data).
- To make sure that the certificate is renewed in any case, you can use the O(force) option.
type: int
default: 10
deactivate_authzs:
description:
- "Deactivate authentication objects (authz) after issuing a certificate,
or when issuing the certificate failed."
- "Authentication objects are bound to an account key and remain valid
for a certain amount of time, and can be used to issue certificates
without having to re-authenticate the domain. This can be a security
concern."
- Deactivate authentication objects (authz) after issuing a certificate, or when issuing the certificate failed.
- Authentication objects are bound to an account key and remain valid for a certain amount of time, and can be used
to issue certificates without having to re-authenticate the domain. This can be a security concern.
type: bool
default: false
force:
description:
- Enforces the execution of the challenge and validation, even if an
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.
- Enforces the execution of the challenge and validation, even if an 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 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 RV(all_chains). See the documentation for the RV(all_chains) return
value for details."
- 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 RV(all_chains). See the documentation for the RV(all_chains)
return value for details.
type: bool
default: false
select_chain:
description:
- "Allows to specify criteria by which an (alternate) trust chain can be selected."
- "The list of criteria will be processed one by one until a chain is found
matching a criterium. If such a chain is found, it will be used by the
module instead of the default chain."
- "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 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."
- Allows to specify criteria by which an (alternate) trust chain can be selected.
- The list of criteria will be processed one by one until a chain is found matching a criterium. If such a chain is
found, it will be used by the module instead of the default chain.
- 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 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
elements: dict
version_added: '1.0.0'
suboptions:
test_certificates:
description:
- "Determines which certificates in the chain will be tested."
- "V(all) tests all certificates in the chain (excluding the leaf, which is
identical in all chains)."
- "V(first) only tests the first certificate in the chain, that is the one which
signed the leaf."
- "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."
- Determines which certificates in the chain will be tested.
- V(all) tests all certificates in the chain (excluding the leaf, which is identical in all chains).
- V(first) only tests the first certificate in the chain, that is the one which signed the leaf.
- 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
choices: [first, last, all]
issuer:
description:
- "Allows to specify parts of the issuer of a certificate in the chain must
have to be selected."
- "If O(select_chain[].issuer) is empty, any certificate will match."
- Allows to specify parts of the issuer of a certificate in the chain must have to be selected.
- 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 O(select_chain[].subject) is empty, any certificate will match."
- 'An example value would be V({"CN": "My Preferred CA Intermediate"})'
- Allows to specify parts of the subject of a certificate in the chain must have to be selected.
- 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
V(A8:4A:6A:63:04:7D:DD:BA:E6:D1:39:B7:A6:45:65:EF:F3:A8:EC:A1)."
- 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 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
V(C4:A7:B1:A4:7B:2C:71:FA:DB:E1:4B:90:75:FF:C4:15:60:85:89:10)."
- 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 V(C4:A7:B1:A4:7B:2C:71:FA:DB:E1:4B:90:75:FF:C4:15:60:85:89:10).
type: str
include_renewal_cert_id:
description:
- Determines whether to request renewal of an existing certificate according to
L(the ACME ARI draft 3, https://www.ietf.org/archive/id/draft-ietf-acme-ari-03.html#section-5).
- Determines whether to request renewal of an existing certificate according to L(the ACME ARI draft 3,
https://www.ietf.org/archive/id/draft-ietf-acme-ari-03.html#section-5).
- This is only used when the certificate specified in O(dest) or O(fullchain_dest) already exists.
- V(never) never sends the certificate ID of the certificate to renew. V(always) will always send it.
- V(when_ari_supported) only sends the certificate ID if the ARI endpoint is found in the ACME directory.
- Generally you should use V(when_ari_supported) if you know that the ACME service supports a compatible
draft (or final version, once it is out) of the ARI extension. V(always) should never be necessary.
If you are not sure, or if you receive strange errors on invalid C(replaces) values in order objects,
use V(never), which also happens to be the default.
- ACME servers might refuse to create new orders with C(replaces) for certificates that already have an
existing order. This can happen if this module is used to create an order, and then the playbook/role
fails in case the challenges cannot be set up. If the playbook/role does not record the order data to
continue with the existing order, but tries to create a new one on the next run, creating the new order
might fail. For this reason, this option should only be set to a value different from V(never) if the
role/playbook using it keeps track of order data accross restarts, or if it takes care to deactivate
orders whose processing is aborted. Orders can be deactivated with the
- Generally you should use V(when_ari_supported) if you know that the ACME service supports a compatible draft (or final
version, once it is out) of the ARI extension. V(always) should never be necessary. If you are not sure, or if you
receive strange errors on invalid C(replaces) values in order objects, use V(never), which also happens to be the
default.
- ACME servers might refuse to create new orders with C(replaces) for certificates that already have an existing order.
This can happen if this module is used to create an order, and then the playbook/role fails in case the challenges
cannot be set up. If the playbook/role does not record the order data to continue with the existing order, but tries
to create a new one on the next run, creating the new order might fail. For this reason, this option should only be
set to a value different from V(never) if the role/playbook using it keeps track of order data accross restarts, or
if it takes care to deactivate orders whose processing is aborted. Orders can be deactivated with the
M(community.crypto.acme_certificate_deactivate_authz) module.
type: str
choices:
@@ -298,9 +257,9 @@ options:
- always
default: never
version_added: 2.20.0
'''
"""
EXAMPLES = r'''
EXAMPLES = r"""
### Example with HTTP challenge ###
- name: Create a challenge for sample.com using a account key from a variable.
@@ -440,9 +399,9 @@ EXAMPLES = r'''
CN: DST Root CA X3
O: Digital Signature Trust Co.
when: sample_com_challenge is changed
'''
"""
RETURN = '''
RETURN = r"""
cert_days:
description: The number of days the certificate remains valid.
returned: success
@@ -478,8 +437,7 @@ challenge_data:
sample: .well-known/acme-challenge/evaGxfADs6pSRb2LAv9IZf17Dt3juxGJ-PCt92wr-oA
resource_original:
description:
- The original challenge resource including type identifier for V(tls-alpn-01)
challenges.
- The original challenge resource including type identifier for V(tls-alpn-01) challenges.
returned: changed and O(challenge) is V(tls-alpn-01)
type: str
sample: DNS:example.com
@@ -487,12 +445,10 @@ challenge_data:
description:
- The value the resource has to produce for the validation.
- 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 P(ansible.builtin.b64decode#filter) Jinja filter
to extract the binary blob from this return value."
- 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 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
@@ -541,9 +497,8 @@ account_uri:
type: str
all_chains:
description:
- 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.
- 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 O(retrieve_all_alternates) is set to V(true)
type: list
@@ -561,11 +516,10 @@ all_chains:
returned: always
full_chain:
description:
- The certificate chain, excluding the root, but including the leaf certificate,
as concatenated PEM certificates.
- The certificate chain, excluding the root, but including the leaf certificate, as concatenated PEM certificates.
type: str
returned: always
'''
"""
import os

25
plugins/modules/acme_certificate_deactivate_authz.py
View File

@@ -9,21 +9,18 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: acme_certificate_deactivate_authz
author: "Felix Fontein (@felixfontein)"
version_added: 2.20.0
short_description: Deactivate all authz for an ACME v2 order
description:
- "Deactivate all authentication objects (authz) for an ACME v2 order,
which effectively deactivates (invalidates) the order itself."
- "Authentication objects are bound to an account key and remain valid
for a certain amount of time, and can be used to issue certificates
without having to re-authenticate the domain. This can be a security
concern."
- "Another reason to use this module is to deactivate an order whose
processing failed when using O(community.crypto.acme_certificate#module:include_renewal_cert_id)."
- Deactivate all authentication objects (authz) for an ACME v2 order, which effectively deactivates (invalidates) the order
itself.
- Authentication objects are bound to an account key and remain valid for a certain amount of time, and can be used to issue
certificates without having to re-authenticate the domain. This can be a security concern.
- Another reason to use this module is to deactivate an order whose processing failed when using
O(community.crypto.acme_certificate#module:include_renewal_cert_id).
seealso:
- module: community.crypto.acme_certificate
extends_documentation_fragment:
@@ -43,16 +40,16 @@ options:
- Can be obtained from RV(community.crypto.acme_certificate#module:order_uri).
type: str
required: true
'''
"""
EXAMPLES = r'''
EXAMPLES = r"""
- name: Deactivate all authzs for an order
community.crypto.acme_certificate_deactivate_authz:
account_key_content: "{{ account_private_key }}"
order_uri: "{{ certificate_result.order_uri }}"
'''
"""
RETURN = '''#'''
RETURN = """#"""
from ansible_collections.community.crypto.plugins.module_utils.acme.acme import (
create_backend,

41
plugins/modules/acme_certificate_renewal_info.py
View File

@@ -9,16 +9,15 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: acme_certificate_renewal_info
author: "Felix Fontein (@felixfontein)"
version_added: 2.20.0
short_description: Determine whether a certificate should be renewed or not
description:
- Uses various information to determine whether a certificate should be renewed or not.
- If available, the ARI extension (ACME Renewal Information, U(https://datatracker.ietf.org/doc/draft-ietf-acme-ari/))
is used. This module implements version 3 of the ARI draft."
- If available, the ARI extension (ACME Renewal Information, U(https://datatracker.ietf.org/doc/draft-ietf-acme-ari/)) is
used. This module implements version 3 of the ARI draft.".
extends_documentation_fragment:
- community.crypto.acme.basic
- community.crypto.acme.no_account
@@ -56,14 +55,14 @@ options:
remaining_days:
description:
- The number of days the certificate must have left being valid.
- For example, if O(remaining_days=20), this check causes RV(should_renew=true) if the
certificate is valid for less than 20 days.
- For example, if O(remaining_days=20), this check causes RV(should_renew=true) if the certificate is valid for less
than 20 days.
type: int
remaining_percentage:
description:
- The percentage of the certificate's validity period that should be left.
- For example, if O(remaining_percentage=0.1), and the certificate's validity period is 90 days,
this check causes RV(should_renew=true) if the certificate is valid for less than 9 days.
- For example, if O(remaining_percentage=0.1), and the certificate's validity period is 90 days, this check causes RV(should_renew=true)
if the certificate is valid for less than 9 days.
- Must be a value between 0 and 1.
type: float
now:
@@ -71,17 +70,17 @@ options:
- Use this timestamp instead of the current timestamp to determine whether a certificate should be renewed.
- 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 V(+32w1d2h)).
- Valid format is C([+-]timespec | ASN.1 TIME) where timespec can be an integer + C([w | d | h | m | s]) (for example
V(+32w1d2h)).
type: str
seealso:
- module: community.crypto.acme_certificate
description: Allows to obtain a certificate using the ACME protocol
description: Allows to obtain a certificate using the ACME protocol.
- module: community.crypto.acme_ari_info
description: Obtain renewal information for a certificate
'''
description: Obtain renewal information for a certificate.
"""
EXAMPLES = '''
EXAMPLES = r"""
- name: Retrieve renewal information for a certificate
community.crypto.acme_certificate_renewal_info:
certificate_path: /etc/httpd/ssl/sample.com.crt
@@ -90,9 +89,9 @@ EXAMPLES = '''
- name: Should the certificate be renewed?
ansible.builtin.debug:
var: cert_data.should_renew
'''
"""
RETURN = '''
RETURN = r"""
should_renew:
description:
- Whether the certificate should be renewed.
@@ -104,16 +103,16 @@ should_renew:
msg:
description:
- Information on the reason for renewal.
- Should be shown to the user, as in case of ARI triggered renewal it can contain important
information, for example on forced revocations for misissued certificates.
- Should be shown to the user, as in case of ARI triggered renewal it can contain important information, for example on
forced revocations for misissued certificates.
type: str
returned: success
sample: The certificate does not exist.
supports_ari:
description:
- Whether ARI information was used to determine renewal. This can be used to determine whether to
specify O(community.crypto.acme_certificate#module:include_renewal_cert_id=when_ari_supported)
- Whether ARI information was used to determine renewal. This can be used to determine whether to specify
O(community.crypto.acme_certificate#module:include_renewal_cert_id=when_ari_supported)
for the M(community.crypto.acme_certificate) module.
- If O(use_ari=false), this will always be V(false).
returned: success
@@ -126,7 +125,7 @@ cert_id:
returned: success, the certificate exists, and has an Authority Key Identifier X.509 extension
type: str
sample: aYhba4dGQEHhs3uEe6CuLN4ByNQ.AIdlQyE
'''
"""
import os
import random

104
plugins/modules/acme_certificate_revoke.py
View File

@@ -9,27 +9,22 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: acme_certificate_revoke
author: "Felix Fontein (@felixfontein)"
short_description: Revoke certificates with the ACME protocol
description:
- "Allows to revoke certificates issued by a CA supporting the
L(ACME protocol,https://tools.ietf.org/html/rfc8555),
such as L(Let's Encrypt,https://letsencrypt.org/)."
- Allows to revoke certificates issued by a CA supporting the L(ACME protocol,https://tools.ietf.org/html/rfc8555), such
as L(Let's Encrypt,https://letsencrypt.org/).
notes:
- "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
server, it can happen that some other error is returned if the
certificate has already been revoked."
- 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 server, it can happen that some other error is returned
if the certificate has already been revoked.
seealso:
- name: The Let's Encrypt documentation
description: Documentation for the Let's Encrypt Certification Authority.
Provides useful information for example on rate limits.
description: Documentation for the Let's Encrypt Certification Authority. Provides useful information for example on rate
limits.
link: https://letsencrypt.org/docs/
- name: Automatic Certificate Management Environment (ACME)
description: The specification of the ACME protocol (RFC 8555).
@@ -49,72 +44,59 @@ attributes:
options:
certificate:
description:
- "Path to the certificate to revoke."
- Path to the certificate to revoke.
type: path
required: true
account_key_src:
description:
- "Path to a file containing the ACME account RSA or Elliptic Curve
key."
- "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 O(account_key_content)."
- "Required if O(account_key_content) is not used."
- Path to a file containing the ACME account RSA or Elliptic Curve key.
- 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 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 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,
or to revoke your certificates without knowing their private keys
—, this might not be acceptable."
- "In case C(cryptography) is used, the content is not written into a
temporary file. It can still happen that it is written to disk by
Ansible in the process of moving the module with its argument to
the node where it is executed."
- Content of the ACME account RSA or Elliptic Curve key.
- 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, or to revoke your certificates
without knowing their private keys —, this might not be acceptable.'
- In case C(cryptography) is used, the content is not written into a temporary file. It can still happen that it is
written to disk by Ansible in the process of moving the module with its argument to the node where it is executed.
private_key_src:
description:
- "Path to the certificate's private key."
- "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."
- Path to the certificate's private key.
- 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 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,
or to revoke your certificates without knowing their private keys
—, this might not be acceptable."
- "In case C(cryptography) is used, the content is not written into a
temporary file. It can still happen that it is written to disk by
Ansible in the process of moving the module with its argument to
the node where it is executed."
- Content of the certificate's private key.
- 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, or to revoke your certificates
without knowing their private keys —, this might not be acceptable.'
- In case C(cryptography) is used, the content is not written into a temporary file. It can still happen that it is
written to disk by Ansible in the process of moving the module with its argument to the node where it is executed.
type: str
private_key_passphrase:
description:
- Phassphrase to use to decode the certificate's private key.
- "B(Note:) this is not supported by the C(openssl) backend, only by the C(cryptography) backend."
- B(Note:) this is not supported by the C(openssl) backend, only by the C(cryptography) backend.
type: str
version_added: 1.6.0
revoke_reason:
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 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)."
- 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 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
'''
"""
EXAMPLES = '''
EXAMPLES = r"""
- name: Revoke certificate with account key
community.crypto.acme_certificate_revoke:
account_key_src: /etc/pki/cert/private/account.key
@@ -124,9 +106,9 @@ EXAMPLES = '''
community.crypto.acme_certificate_revoke:
private_key_src: /etc/httpd/ssl/sample.com.key
certificate: /etc/httpd/ssl/sample.com.crt
'''
"""
RETURN = '''#'''
RETURN = """#"""
from ansible_collections.community.crypto.plugins.module_utils.acme.acme import (
create_backend,

55
plugins/modules/acme_challenge_cert_helper.py
View File

@@ -9,16 +9,14 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: acme_challenge_cert_helper
author: "Felix Fontein (@felixfontein)"
short_description: Prepare certificates required for ACME challenges such as C(tls-alpn-01)
description:
- "Prepares certificates for ACME challenges such as C(tls-alpn-01)."
- "The raw data is provided by the M(community.crypto.acme_certificate) module, and needs to be
converted to a certificate to be used for challenge validation. This module
provides a simple way to generate the required certificates."
- Prepares certificates for ACME challenges such as C(tls-alpn-01).
- The raw data is provided by the M(community.crypto.acme_certificate) module, and needs to be converted to a certificate
to be used for challenge validation. This module provides a simple way to generate the required certificates.
seealso:
- name: Automatic Certificate Management Environment (ACME)
description: The specification of the ACME protocol (RFC 8555).
@@ -42,36 +40,35 @@ attributes:
options:
challenge:
description:
- "The challenge type."
- The challenge type.
type: str
required: true
choices:
- tls-alpn-01
- tls-alpn-01
challenge_data:
description:
- "The RV(community.crypto.acme_certificate#module:challenge_data) entry provided by M(community.crypto.acme_certificate) for the
challenge."
- The RV(community.crypto.acme_certificate#module:challenge_data) entry provided by M(community.crypto.acme_certificate)
for the challenge.
type: dict
required: true
private_key_src:
description:
- "Path to a file containing the private key file to use for this challenge
certificate."
- "Mutually exclusive with O(private_key_content)."
- Path to a file containing the private key file to use for this challenge certificate.
- 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 O(private_key_src)."
- Content of the private key to use for this challenge certificate.
- Mutually exclusive with O(private_key_src).
type: str
private_key_passphrase:
description:
- Phassphrase to use to decode the private key.
type: str
version_added: 1.6.0
'''
"""
EXAMPLES = '''
EXAMPLES = r"""
- name: Create challenges for a given CRT for sample.com
community.crypto.acme_certificate:
account_key_src: /etc/pki/cert/private/account.key
@@ -111,18 +108,18 @@ EXAMPLES = '''
csr: /etc/pki/cert/csr/sample.com.csr
dest: /etc/httpd/ssl/sample.com.crt
data: "{{ sample_com_challenge }}"
'''
"""
RETURN = '''
RETURN = r"""
domain:
description:
- "The domain the challenge is for. The certificate should be provided if
this is specified in the request's the C(Host) header."
- The domain the challenge is for. The certificate should be provided if this is specified in the request's the C(Host)
header.
returned: always
type: str
identifier_type:
description:
- "The identifier type for the actual resource identifier."
- The identifier type for the actual resource identifier.
returned: always
type: str
choices:
@@ -130,24 +127,22 @@ identifier_type:
- ip
identifier:
description:
- "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)."
- 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:
description:
- "The challenge certificate in PEM format."
- The challenge certificate in PEM format.
returned: always
type: str
regular_certificate:
description:
- "A self-signed certificate for the challenge domain."
- "If no existing certificate exists, can be used to set-up
https in the first place if that is needed for providing
the challenge."
- A self-signed certificate for the challenge domain.
- If no existing certificate exists, can be used to set-up https in the first place if that is needed for providing the
challenge.
returned: always
type: str
'''
"""
import base64
import datetime

137
plugins/modules/acme_inspect.py
View File

@@ -9,31 +9,24 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = r'''
---
DOCUMENTATION = r"""
module: acme_inspect
author: "Felix Fontein (@felixfontein)"
short_description: Send direct requests to an ACME server
description:
- "Allows to send direct requests to an ACME server with the
L(ACME protocol,https://tools.ietf.org/html/rfc8555),
which is supported by CAs such as L(Let's Encrypt,https://letsencrypt.org/)."
- "This module can be used to debug failed certificate request attempts,
for example when M(community.crypto.acme_certificate) fails or encounters a problem which
you wish to investigate."
- "The module can also be used to directly access features of an ACME servers
which are not yet supported by the Ansible ACME modules."
- Allows to send direct requests to an ACME server with the L(ACME protocol,https://tools.ietf.org/html/rfc8555), which
is supported by CAs such as L(Let's Encrypt,https://letsencrypt.org/).
- This module can be used to debug failed certificate request attempts, for example when M(community.crypto.acme_certificate)
fails or encounters a problem which you wish to investigate.
- 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 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
following command retrieves the ACME account with ID 1 from Let's Encrypt
(assuming C(/path/to/key) is the correct private account key):
C(ansible localhost -m acme_inspect -a \"account_key_src=/path/to/key
acme_directory=https://acme-v02.api.letsencrypt.org/directory acme_version=2
account_uri=https://acme-v02.api.letsencrypt.org/acme/acct/1 method=get
url=https://acme-v02.api.letsencrypt.org/acme/acct/1\")"
- 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 following command retrieves the ACME account with ID 1 from Let's Encrypt
(assuming C(/path/to/key) is the correct private account key): C(ansible localhost -m acme_inspect -a \"account_key_src=/path/to/key
acme_directory=https://acme-v02.api.letsencrypt.org/directory acme_version=2 account_uri=https://acme-v02.api.letsencrypt.org/acme/acct/1
method=get url=https://acme-v02.api.letsencrypt.org/acme/acct/1\")."
seealso:
- name: Automatic Certificate Management Environment (ACME)
description: The specification of the ACME protocol (RFC 8555).
@@ -54,39 +47,34 @@ attributes:
options:
url:
description:
- "The URL to send the request to."
- "Must be specified if O(method) is not V(directory-only)."
- The URL to send the request to.
- 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 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 V(directory-only) only retrieves the directory, without doing
a request."
- The method to use to access the given URL on the ACME server.
- 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 V(directory-only) only retrieves the directory, without doing a request.
type: str
default: get
choices:
- get
- post
- directory-only
- get
- post
- directory-only
content:
description:
- "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."
- 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 O(method) is V(post) or V(get), make the module fail in case an ACME
error is returned."
- If O(method) is V(post) or V(get), make the module fail in case an ACME error is returned.
type: bool
default: true
'''
"""
EXAMPLES = r'''
EXAMPLES = r"""
- name: Get directory
community.crypto.acme_inspect:
acme_directory: https://acme-staging-v02.api.letsencrypt.org/directory
@@ -129,7 +117,7 @@ EXAMPLES = r'''
# For valid values, see
# https://tools.ietf.org/html/rfc8555#section-7.3
contact:
- mailto:me@example.com
- mailto:me@example.com
- name: Create certificate order
community.crypto.acme_certificate:
@@ -184,69 +172,46 @@ EXAMPLES = r'''
url: "{{ http01challenge.url }}"
method: post
content: '{}'
'''
"""
RETURN = '''
RETURN = r"""
directory:
description: The ACME directory's content
description: The ACME directory's content.
returned: always
type: dict
sample:
{
"a85k3x9f91A4": "https://community.letsencrypt.org/t/adding-random-entries-to-the-directory/33417",
"keyChange": "https://acme-v02.api.letsencrypt.org/acme/key-change",
"meta": {
"caaIdentities": [
"letsencrypt.org"
],
"termsOfService": "https://letsencrypt.org/documents/LE-SA-v1.2-November-15-2017.pdf",
"website": "https://letsencrypt.org"
},
"newAccount": "https://acme-v02.api.letsencrypt.org/acme/new-acct",
"newNonce": "https://acme-v02.api.letsencrypt.org/acme/new-nonce",
"newOrder": "https://acme-v02.api.letsencrypt.org/acme/new-order",
"revokeCert": "https://acme-v02.api.letsencrypt.org/acme/revoke-cert"
}
sample: {"a85k3x9f91A4": "https://community.letsencrypt.org/t/adding-random-entries-to-the-directory/33417",
"keyChange": "https://acme-v02.api.letsencrypt.org/acme/key-change",
"meta": {"caaIdentities": ["letsencrypt.org"], "termsOfService": "https://letsencrypt.org/documents/LE-SA-v1.2-November-15-2017.pdf",
"website": "https://letsencrypt.org"},
"newAccount": "https://acme-v02.api.letsencrypt.org/acme/new-acct",
"newNonce": "https://acme-v02.api.letsencrypt.org/acme/new-nonce",
"newOrder": "https://acme-v02.api.letsencrypt.org/acme/new-order",
"revokeCert": "https://acme-v02.api.letsencrypt.org/acme/revoke-cert"}
headers:
description: The request's HTTP headers (with lowercase keys)
description: The request's HTTP headers (with lowercase keys).
returned: always
type: dict
sample:
{
"boulder-requester": "12345",
"cache-control": "max-age=0, no-cache, no-store",
"connection": "close",
"content-length": "904",
"content-type": "application/json",
"cookies": {},
"cookies_string": "",
"date": "Wed, 07 Nov 2018 12:34:56 GMT",
"expires": "Wed, 07 Nov 2018 12:44:56 GMT",
"link": '<https://letsencrypt.org/documents/LE-SA-v1.2-November-15-2017.pdf>;rel="terms-of-service"',
"msg": "OK (904 bytes)",
"pragma": "no-cache",
"replay-nonce": "1234567890abcdefghijklmnopqrstuvwxyzABCDEFGH",
"server": "nginx",
"status": 200,
"strict-transport-security": "max-age=604800",
"url": "https://acme-v02.api.letsencrypt.org/acme/acct/46161",
"x-frame-options": "DENY"
}
sample: {"boulder-requester": "12345", "cache-control": "max-age=0, no-cache, no-store", "connection": "close", "content-length": "904",
"content-type": "application/json", "cookies": {}, "cookies_string": "", "date": "Wed, 07 Nov 2018 12:34:56 GMT", "expires": "Wed,
07 Nov 2018 12:44:56 GMT", "link": '<https://letsencrypt.org/documents/LE-SA-v1.2-November-15-2017.pdf>;rel="terms-of-service"',
"msg": "OK (904 bytes)", "pragma": "no-cache", "replay-nonce": "1234567890abcdefghijklmnopqrstuvwxyzABCDEFGH", "server": "nginx",
"status": 200, "strict-transport-security": "max-age=604800", "url": "https://acme-v02.api.letsencrypt.org/acme/acct/46161",
"x-frame-options": "DENY"}
output_text:
description: The raw text output
description: The raw text output.
returned: always
type: str
sample: "{\\n \\\"id\\\": 12345,\\n \\\"key\\\": {\\n \\\"kty\\\": \\\"RSA\\\",\\n ..."
output_json:
description: The output parsed as JSON
description: The output parsed as JSON.
returned: if output can be parsed as JSON
type: dict
sample:
- id: 12345
- key:
- kty: RSA
- ...
'''
- kty: RSA
- '...'
"""
from ansible.module_utils.common.text.converters import to_native, to_bytes, to_text

146
plugins/modules/certificate_complete_chain.py
View File

@@ -9,78 +9,70 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: certificate_complete_chain
author: "Felix Fontein (@felixfontein)"
short_description: Complete certificate chain given a set of untrusted and root certificates
description:
- "This module completes a given chain of certificates in PEM format by finding
intermediate certificates from a given set of certificates, until it finds a root
certificate in another given set of certificates."
- "This can for example be used to find the root certificate for a certificate chain
returned by M(community.crypto.acme_certificate)."
- "Note that this module does I(not) check for validity of the chains. It only
checks that issuer and subject match, and that the signature is correct. It
ignores validity dates and key usage completely. If you need to verify that a
generated chain is valid, please use C(openssl verify ...)."
- This module completes a given chain of certificates in PEM format by finding intermediate certificates from a given set
of certificates, until it finds a root certificate in another given set of certificates.
- This can for example be used to find the root certificate for a certificate chain returned by M(community.crypto.acme_certificate).
- Note that this module does I(not) check for validity of the chains. It only checks that issuer and subject match, and
that the signature is correct. It ignores validity dates and key usage completely. If you need to verify that a generated
chain is valid, please use C(openssl verify ...).
requirements:
- "cryptography >= 1.5"
- "cryptography >= 1.5"
extends_documentation_fragment:
- community.crypto.attributes
- community.crypto.attributes
attributes:
check_mode:
support: full
details:
- This action does not modify state.
diff_mode:
support: N/A
details:
- This action does not modify state.
check_mode:
support: full
details:
- This action does not modify state.
diff_mode:
support: N/A
details:
- This action does not modify state.
options:
input_chain:
description:
- A concatenated set of certificates in PEM format forming a chain.
- The module will try to complete this chain.
type: str
required: true
root_certificates:
description:
- "A list of filenames or directories."
- "A filename is assumed to point to a file containing one or more certificates
in PEM format. All certificates in this file will be added to the set of
root certificates."
- "If a directory name is given, all files in the directory and its
subdirectories will be scanned and tried to be parsed as concatenated
certificates in PEM format."
- "Symbolic links will be followed."
type: list
elements: path
required: true
intermediate_certificates:
description:
- "A list of filenames or directories."
- "A filename is assumed to point to a file containing one or more certificates
in PEM format. All certificates in this file will be added to the set of
root certificates."
- "If a directory name is given, all files in the directory and its
subdirectories will be scanned and tried to be parsed as concatenated
certificates in PEM format."
- "Symbolic links will be followed."
type: list
elements: path
default: []
'''
input_chain:
description:
- A concatenated set of certificates in PEM format forming a chain.
- The module will try to complete this chain.
type: str
required: true
root_certificates:
description:
- A list of filenames or directories.
- A filename is assumed to point to a file containing one or more certificates in PEM format. All certificates in this
file will be added to the set of root certificates.
- If a directory name is given, all files in the directory and its subdirectories will be scanned and tried to be parsed
as concatenated certificates in PEM format.
- Symbolic links will be followed.
type: list
elements: path
required: true
intermediate_certificates:
description:
- A list of filenames or directories.
- A filename is assumed to point to a file containing one or more certificates in PEM format. All certificates in this
file will be added to the set of root certificates.
- If a directory name is given, all files in the directory and its subdirectories will be scanned and tried to be parsed
as concatenated certificates in PEM format.
- Symbolic links will be followed.
type: list
elements: path
default: []
"""
EXAMPLES = '''
EXAMPLES = r"""
# Given a leaf certificate for www.ansible.com and one or more intermediate
# certificates, finds the associated root certificate.
- name: Find root certificate
community.crypto.certificate_complete_chain:
input_chain: "{{ lookup('ansible.builtin.file', '/etc/ssl/csr/www.ansible.com-fullchain.pem') }}"
root_certificates:
- /etc/ca-certificates/
- /etc/ca-certificates/
register: www_ansible_com
- name: Write root certificate to disk
ansible.builtin.copy:
@@ -93,9 +85,9 @@ EXAMPLES = '''
community.crypto.certificate_complete_chain:
input_chain: "{{ lookup('ansible.builtin.file', '/etc/ssl/csr/www.ansible.com.pem') }}"
intermediate_certificates:
- /etc/ssl/csr/www.ansible.com-chain.pem
- /etc/ssl/csr/www.ansible.com-chain.pem
root_certificates:
- /etc/ca-certificates/
- /etc/ca-certificates/
register: www_ansible_com
- name: Write complete chain to disk
ansible.builtin.copy:
@@ -105,30 +97,30 @@ EXAMPLES = '''
ansible.builtin.copy:
dest: /etc/ssl/csr/www.ansible.com-rootchain.pem
content: "{{ ''.join(www_ansible_com.chain) }}"
'''
"""
RETURN = '''
RETURN = r"""
root:
description:
- "The root certificate in PEM format."
returned: success
type: str
description:
- The root certificate in PEM format.
returned: success
type: str
chain:
description:
- "The chain added to the given input chain. Includes the root certificate."
- "Returned as a list of PEM certificates."
returned: success
type: list
elements: str
description:
- The chain added to the given input chain. Includes the root certificate.
- Returned as a list of PEM certificates.
returned: success
type: list
elements: str
complete_chain:
description:
- "The completed chain, including leaf, all intermediates, and root."
- "Returned as a list of PEM certificates."
returned: success
type: list
elements: str
'''
description:
- The completed chain, including leaf, all intermediates, and root.
- Returned as a list of PEM certificates.
returned: success
type: list
elements: str
"""
import os
import traceback

13
plugins/modules/crypto_info.py
View File

@@ -9,8 +9,7 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = r'''
---
DOCUMENTATION = r"""
module: crypto_info
author: "Felix Fontein (@felixfontein)"
short_description: Retrieve cryptographic capabilities
@@ -23,9 +22,9 @@ extends_documentation_fragment:
- community.crypto.attributes
- community.crypto.attributes.info_module
options: {}
'''
"""
EXAMPLES = r'''
EXAMPLES = r"""
- name: Retrieve information
community.crypto.crypto_info:
account_key_src: /etc/pki/cert/private/account.key
@@ -34,9 +33,9 @@ EXAMPLES = r'''
- name: Show retrieved information
ansible.builtin.debug:
var: crypto_information
'''
"""
RETURN = r'''
RETURN = r"""
python_cryptography_installed:
description: Whether the L(Python cryptography library, https://cryptography.io/) is installed.
returned: always
@@ -151,7 +150,7 @@ openssl:
description: The complete output of C(openssl version).
type: str
sample: 'OpenSSL 1.1.1m 14 Dec 2021\n'
'''
"""
import traceback

781
plugins/modules/ecs_certificate.py
View File

@@ -9,355 +9,369 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: ecs_certificate
author:
- Chris Trufan (@ctrufan)
- Chris Trufan (@ctrufan)
short_description: Request SSL/TLS certificates with the Entrust Certificate Services (ECS) API
description:
- Create, reissue, and renew certificates 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.
- 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.
- Create, reissue, and renew certificates 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.
- 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:
- O(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
- cryptography >= 1.6
extends_documentation_fragment:
- community.crypto.attributes
- community.crypto.attributes.files
- community.crypto.ecs_credential
- community.crypto.attributes
- community.crypto.attributes.files
- community.crypto.ecs_credential
attributes:
check_mode:
support: partial
details:
- Check mode is only supported if O(request_type=new).
diff_mode:
support: none
safe_file_operations:
support: full
check_mode:
support: partial
details:
- Check mode is only supported if O(request_type=new).
diff_mode:
support: none
safe_file_operations:
support: full
options:
backup:
description:
- 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 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
path:
description:
- 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 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:
description:
- The destination path for the full certificate chain of the certificate, intermediates, and roots.
type: path
csr:
description:
- 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 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).
backup:
description:
- 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 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
path:
description:
- 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 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:
description:
- The destination path for the full certificate chain of the certificate, intermediates, and roots.
type: path
csr:
description:
- 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 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.
- 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 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 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 example, 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 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 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 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
choices: ['new', 'renew', 'reissue', 'validate_only']
default: new
cert_type:
description:
- Specify the type of certificate requested.
- 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 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 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 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 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 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 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.
- 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
elements: str
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
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 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.
type: str
requester_name:
description: The requester name to associate with certificate tracking information.
type: str
required: true
requester_email:
description: The requester email to associate with certificate tracking information and receive delivery and expiry notices
for the certificate.
type: str
required: true
requester_phone:
description: The requester phone number to associate with certificate tracking information.
type: str
required: true
additional_emails:
description: A list of additional email addresses to receive the delivery notice and expiry notification for the certificate.
type: list
elements: str
custom_fields:
description:
- Mapping of custom fields to associate with the certificate request and certificate.
- Only supported if custom fields are enabled for your account.
- Each custom field specified must be a custom field you have defined for your account.
type: dict
suboptions:
text1:
description: Custom text field (maximum 500 characters).
type: str
tracking_id:
description:
- The tracking ID of the certificate to reissue or renew.
- 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 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 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 example, 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 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 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 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.
text2:
description: Custom text field (maximum 500 characters).
type: str
choices: [ 'new', 'renew', 'reissue', 'validate_only']
default: new
cert_type:
description:
- Specify the type of certificate requested.
- If a certificate is being reissued or renewed, this parameter is ignored, and the O(cert_type) of the initial certificate is used.
text3:
description: Custom text field (maximum 500 characters).
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 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 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 O(csr).
text4:
description: Custom text field (maximum 500 characters).
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 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 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 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.
text5:
description: Custom text field (maximum 500 characters).
type: str
ou:
description:
- Organizational unit "OU=" to include in the certificate.
- 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
elements: str
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 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 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.
text6:
description: Custom text field (maximum 500 characters).
type: str
requester_name:
description: The requester name to associate with certificate tracking information.
text7:
description: Custom text field (maximum 500 characters).
type: str
required: true
requester_email:
description: The requester email to associate with certificate tracking information and receive delivery and expiry notices for the certificate.
text8:
description: Custom text field (maximum 500 characters).
type: str
required: true
requester_phone:
description: The requester phone number to associate with certificate tracking information.
text9:
description: Custom text field (maximum 500 characters).
type: str
required: true
additional_emails:
description: A list of additional email addresses to receive the delivery notice and expiry notification for the certificate.
type: list
elements: str
custom_fields:
description:
- Mapping of custom fields to associate with the certificate request and certificate.
- Only supported if custom fields are enabled for your account.
- Each custom field specified must be a custom field you have defined for your account.
type: dict
suboptions:
text1:
description: Custom text field (maximum 500 characters)
type: str
text2:
description: Custom text field (maximum 500 characters)
type: str
text3:
description: Custom text field (maximum 500 characters)
type: str
text4:
description: Custom text field (maximum 500 characters)
type: str
text5:
description: Custom text field (maximum 500 characters)
type: str
text6:
description: Custom text field (maximum 500 characters)
type: str
text7:
description: Custom text field (maximum 500 characters)
type: str
text8:
description: Custom text field (maximum 500 characters)
type: str
text9:
description: Custom text field (maximum 500 characters)
type: str
text10:
description: Custom text field (maximum 500 characters)
type: str
text11:
description: Custom text field (maximum 500 characters)
type: str
text12:
description: Custom text field (maximum 500 characters)
type: str
text13:
description: Custom text field (maximum 500 characters)
type: str
text14:
description: Custom text field (maximum 500 characters)
type: str
text15:
description: Custom text field (maximum 500 characters)
type: str
number1:
description: Custom number field.
type: float
number2:
description: Custom number field.
type: float
number3:
description: Custom number field.
type: float
number4:
description: Custom number field.
type: float
number5:
description: Custom number field.
type: float
date1:
description: Custom date field.
type: str
date2:
description: Custom date field.
type: str
date3:
description: Custom date field.
type: str
date4:
description: Custom date field.
type: str
date5:
description: Custom date field.
type: str
email1:
description: Custom email field.
type: str
email2:
description: Custom email field.
type: str
email3:
description: Custom email field.
type: str
email4:
description: Custom email field.
type: str
email5:
description: Custom email field.
type: str
dropdown1:
description: Custom dropdown field.
type: str
dropdown2:
description: Custom dropdown field.
type: str
dropdown3:
description: Custom dropdown field.
type: str
dropdown4:
description: Custom dropdown field.
type: str
dropdown5:
description: Custom dropdown field.
type: str
cert_expiry:
description:
- The date the certificate should be set to expire, in RFC3339 compliant date or date-time format. For example,
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 O(cert_expiry) or O(cert_lifetime) may be specified.
text10:
description: Custom text field (maximum 500 characters).
type: str
cert_lifetime:
description:
- The lifetime of the certificate.
- Applies to all certificates for accounts with a non-pooling inventory model.
- 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 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.
text11:
description: Custom text field (maximum 500 characters).
type: str
choices: [ P1Y, P2Y, P3Y ]
text12:
description: Custom text field (maximum 500 characters).
type: str
text13:
description: Custom text field (maximum 500 characters).
type: str
text14:
description: Custom text field (maximum 500 characters).
type: str
text15:
description: Custom text field (maximum 500 characters).
type: str
number1:
description: Custom number field.
type: float
number2:
description: Custom number field.
type: float
number3:
description: Custom number field.
type: float
number4:
description: Custom number field.
type: float
number5:
description: Custom number field.
type: float
date1:
description: Custom date field.
type: str
date2:
description: Custom date field.
type: str
date3:
description: Custom date field.
type: str
date4:
description: Custom date field.
type: str
date5:
description: Custom date field.
type: str
email1:
description: Custom email field.
type: str
email2:
description: Custom email field.
type: str
email3:
description: Custom email field.
type: str
email4:
description: Custom email field.
type: str
email5:
description: Custom email field.
type: str
dropdown1:
description: Custom dropdown field.
type: str
dropdown2:
description: Custom dropdown field.
type: str
dropdown3:
description: Custom dropdown field.
type: str
dropdown4:
description: Custom dropdown field.
type: str
dropdown5:
description: Custom dropdown field.
type: str
cert_expiry:
description:
- The date the certificate should be set to expire, in RFC3339 compliant date or date-time format. For example, 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 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.
- 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 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:
- module: community.crypto.openssl_privatekey
description: Can be used to create private keys (both for certificates and accounts).
- module: community.crypto.openssl_csr
description: Can be used to create a Certificate Signing Request (CSR).
- plugin: community.crypto.to_serial
plugin_type: filter
'''
- module: community.crypto.openssl_privatekey
description: Can be used to create private keys (both for certificates and accounts).
- module: community.crypto.openssl_csr
description: Can be used to create a Certificate Signing Request (CSR).
- plugin: community.crypto.to_serial
plugin_type: filter
"""
EXAMPLES = r'''
- name: Request a new certificate from Entrust with bare minimum parameters.
Will request a new certificate if current one is valid but within 30
days of expiry. If replacing an existing file in path, will back it up.
EXAMPLES = r"""
- name: Request a new certificate from Entrust with bare minimum parameters. Will request a new certificate if current one
is valid but within 30 days of expiry. If replacing an existing file in path, will back it up.
community.crypto.ecs_certificate:
backup: true
path: /etc/ssl/crt/ansible.com.crt
@@ -372,10 +386,8 @@ EXAMPLES = r'''
entrust_api_client_cert_path: /etc/ssl/entrust/ecs-client.crt
entrust_api_client_cert_key_path: /etc/ssl/entrust/ecs-client.key
- name: If there is no certificate present in path, request a new certificate
of type EV_SSL. Otherwise, if there is an Entrust managed certificate
in path and it is within 63 days of expiration, request a renew of that
certificate.
- name: If there is no certificate present in path, request a new certificate of type EV_SSL. Otherwise, if there is an
Entrust managed certificate in path and it is within 63 days of expiration, request a renew of that certificate.
community.crypto.ecs_certificate:
path: /etc/ssl/crt/ansible.com.crt
csr: /etc/ssl/csr/ansible.com.csr
@@ -391,11 +403,9 @@ EXAMPLES = r'''
entrust_api_client_cert_path: /etc/ssl/entrust/ecs-client.crt
entrust_api_client_cert_key_path: /etc/ssl/entrust/ecs-client.key
- name: If there is no certificate present in path, download certificate
specified by tracking_id if it is still valid. Otherwise, if the
certificate is within 79 days of expiration, request a renew of that
certificate and save it in path. This can be used to "migrate" a
certificate to be Ansible managed.
- name: If there is no certificate present in path, download certificate specified by tracking_id if it is still valid.
Otherwise, if the certificate is within 79 days of expiration, request a renew of that certificate and save it in path.
This can be used to "migrate" a certificate to be Ansible managed.
community.crypto.ecs_certificate:
path: /etc/ssl/crt/ansible.com.crt
csr: /etc/ssl/csr/ansible.com.csr
@@ -418,10 +428,8 @@ EXAMPLES = r'''
entrust_api_client_cert_path: /etc/ssl/entrust/ecs-client.crt
entrust_api_client_cert_key_path: /etc/ssl/entrust/ecs-client.key
- name: Request a new certificate with an alternative client. Note that the
issued certificate will have its Subject Distinguished Name use the
organization details associated with that client, rather than what is
in the CSR.
- name: Request a new certificate with an alternative client. Note that the issued certificate will have its Subject Distinguished
Name use the organization details associated with that client, rather than what is in the CSR.
community.crypto.ecs_certificate:
path: /etc/ssl/crt/ansible.com.crt
csr: /etc/ssl/csr/ansible.com.csr
@@ -434,8 +442,7 @@ EXAMPLES = r'''
entrust_api_client_cert_path: /etc/ssl/entrust/ecs-client.crt
entrust_api_client_cert_key_path: /etc/ssl/entrust/ecs-client.key
- name: Request a new certificate with a number of CSR parameters overridden
and tracking information
- name: Request a new certificate with a number of CSR parameters overridden and tracking information
community.crypto.ecs_certificate:
path: /etc/ssl/crt/ansible.com.crt
full_chain_path: /etc/ssl/crt/ansible.com.chain.crt
@@ -467,60 +474,60 @@ EXAMPLES = r'''
entrust_api_key: a^lv*32!cd9LnT
entrust_api_client_cert_path: /etc/ssl/entrust/ecs-client.crt
entrust_api_client_cert_key_path: /etc/ssl/entrust/ecs-client.key
"""
'''
RETURN = '''
RETURN = r"""
filename:
description: The destination path for the generated certificate.
returned: changed or success
type: str
sample: /etc/ssl/crt/www.ansible.com.crt
description: The destination path for the generated certificate.
returned: changed or success
type: str
sample: /etc/ssl/crt/www.ansible.com.crt
backup_file:
description: Name of backup file created for the certificate.
returned: changed and if O(backup) is V(true)
type: str
sample: /path/to/www.ansible.com.crt.2019-03-09@11:22~
description: Name of backup file created for the certificate.
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 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~
description: Name of the backup file created for the certificate chain.
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:
description: The tracking ID to reference and track the certificate in ECS.
returned: success
type: int
sample: 380079
description: The tracking ID to reference and track the certificate in ECS.
returned: success
type: int
sample: 380079
serial_number:
description:
- The serial number of the issued certificate.
- This return value is an B(integer). If you need the serial numbers as a colon-separated hex string,
such as C(11:22:33), you need to convert it to that form with P(community.crypto.to_serial#filter).
returned: success
type: int
sample: 1235262234164342
description:
- The serial number of the issued certificate.
- This return value is an B(integer). If you need the serial numbers as a colon-separated hex string, such as C(11:22:33),
you need to convert it to that form with P(community.crypto.to_serial#filter).
returned: success
type: int
sample: 1235262234164342
cert_days:
description: The number of days the certificate remains valid.
returned: success
type: int
sample: 253
description: The number of days the certificate remains valid.
returned: success
type: int
sample: 253
cert_status:
description:
- The certificate status in ECS.
- '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
description:
- The certificate status in ECS.
- '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
cert_details:
description:
- The full response JSON from the Get Certificate call of the ECS API.
- 'While the response contents are guaranteed to be forwards compatible with new ECS API releases, Entrust recommends that you do not make any
playbooks take actions based on the content of this field. However it may be useful for debugging, logging, or auditing purposes.'
returned: success
type: dict
'''
description:
- The full response JSON from the Get Certificate call of the ECS API.
- While the response contents are guaranteed to be forwards compatible with new ECS API releases, Entrust recommends that
you do not make any playbooks take actions based on the content of this field. However it may be useful for debugging,
logging, or auditing purposes.
returned: success
type: dict
"""
from ansible_collections.community.crypto.plugins.module_utils.ecs.api import (
ecs_client_argument_spec,

276
plugins/modules/ecs_domain.py
View File

@@ -9,87 +9,91 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: ecs_domain
author:
- Chris Trufan (@ctrufan)
- Chris Trufan (@ctrufan)
version_added: '1.0.0'
short_description: Request validation of a domain with the Entrust Certificate Services (ECS) API
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 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.
- 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 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 O(verification_method=dns) or O(verification_method=web_server). Be aware of that if doing many domain validation requests.
- 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 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
- community.crypto.attributes
- community.crypto.ecs_credential
attributes:
check_mode:
support: none
diff_mode:
support: none
check_mode:
support: none
diff_mode:
support: none
options:
client_id:
description:
- The client ID to request the domain be associated with.
- If no client ID is specified, the domain will be added under the primary client with ID of 1.
type: int
default: 1
domain_name:
description:
- The domain name to be verified or reverified.
type: str
required: true
verification_method:
description:
- The verification method to be used to prove control of the domain.
- 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 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 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 O(verification_method=email)
type: str
client_id:
description:
- The client ID to request the domain be associated with.
- If no client ID is specified, the domain will be added under the primary client with ID of 1.
type: int
default: 1
domain_name:
description:
- The domain name to be verified or reverified.
type: str
required: true
verification_method:
description:
- The verification method to be used to prove control of the domain.
- 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 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 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 O(verification_method=email).
type: str
seealso:
- module: community.crypto.x509_certificate
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.
'''
- module: community.crypto.x509_certificate
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.
"""
EXAMPLES = r'''
EXAMPLES = r"""
- name: Request domain validation using email validation for client ID of 2.
community.crypto.ecs_domain:
domain_name: ansible.com
@@ -101,8 +105,7 @@ EXAMPLES = r'''
entrust_api_client_cert_path: /etc/ssl/entrust/ecs-client.crt
entrust_api_client_cert_key_path: /etc/ssl/entrust/ecs-client.key
- name: Request domain validation using DNS. If domain is already valid,
request revalidation if expires within 90 days
- name: Request domain validation using DNS. If domain is already valid, request revalidation if expires within 90 days
community.crypto.ecs_domain:
domain_name: ansible.com
verification_method: dns
@@ -111,8 +114,7 @@ EXAMPLES = r'''
entrust_api_client_cert_path: /etc/ssl/entrust/ecs-client.crt
entrust_api_client_cert_key_path: /etc/ssl/entrust/ecs-client.key
- name: Request domain validation using web server validation, and revalidate
if fewer than 60 days remaining of EV eligibility.
- name: Request domain validation using web server validation, and revalidate if fewer than 60 days remaining of EV eligibility.
community.crypto.ecs_domain:
domain_name: ansible.com
verification_method: web_server
@@ -129,80 +131,86 @@ EXAMPLES = r'''
entrust_api_key: a^lv*32!cd9LnT
entrust_api_client_cert_path: /etc/ssl/entrust/ecs-client.crt
entrust_api_client_cert_key_path: /etc/ssl/entrust/ecs-client.key
'''
"""
RETURN = '''
RETURN = r"""
domain_status:
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
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 O(verification_method) input parameter.
returned: changed or success
type: str
sample: dns
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 RV(file_contents).
returned: O(verification_method) is V(web_server)
type: str
sample: http://ansible.com/.well-known/pki-validation/abcd.txt
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 RV(file_location).
returned: O(verification_method) is V(web_server)
type: str
sample: AB23CD41432522FF2526920393982FAB
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: O(verification_method) is V(email)
type: list
sample: [ admin@ansible.com, administrator@ansible.com ]
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: 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 RV(dns_contents).
returned: changed and if O(verification_method) is V(dns)
type: str
sample: _pki-validation.ansible.com
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 RV(dns_location).
returned: changed and if O(verification_method) is V(dns)
type: str
sample: AB23CD41432522FF2526920393982FAB
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 RV(dns_location).
returned: changed and if O(verification_method) is V(dns)
type: str
sample: TXT
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 O(client_id) is specified, this will always be the same as O(client_id)
returned: changed or success
type: int
sample: 1
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 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
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 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
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 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
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
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
'''
description: The number of days the domain remains eligible for submission of "EV" certificates. Will never be greater than
the value of 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
"""
import datetime
import time

64
plugins/modules/get_certificate.py
View File

@@ -9,15 +9,15 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: get_certificate
author: "John Westcott IV (@john-westcott-iv)"
short_description: Get a certificate from a host:port
description:
- Makes a secure connection and returns information about the presented certificate.
- The module uses the cryptography Python library.
- Support SNI (L(Server Name Indication,https://en.wikipedia.org/wiki/Server_Name_Indication)) only with Python 2.7 and newer.
- Support SNI (L(Server Name Indication,https://en.wikipedia.org/wiki/Server_Name_Indication)) only with Python 2.7 and
newer.
extends_documentation_fragment:
- community.crypto.attributes
attributes:
@@ -38,7 +38,8 @@ options:
ca_cert:
description:
- A PEM file containing one or more root certificates; if present, the cert will be validated against these root certs.
- Note that this only validates the certificate is signed by the chain; not that the cert is valid for the host presenting it.
- Note that this only validates the certificate is signed by the chain; not that the cert is valid for the host presenting
it.
type: path
port:
description:
@@ -47,8 +48,8 @@ options:
required: true
server_name:
description:
- Server name used for SNI (L(Server Name Indication,https://en.wikipedia.org/wiki/Server_Name_Indication)) when hostname
is an IP or is different from server name.
- Server name used for SNI (L(Server Name Indication,https://en.wikipedia.org/wiki/Server_Name_Indication)) when hostname
is an IP or is different from server name.
type: str
version_added: 1.4.0
proxy_host:
@@ -80,11 +81,11 @@ options:
- If set to V(cryptography), will try to use the L(cryptography,https://cryptography.io/) library.
type: str
default: auto
choices: [ auto, cryptography ]
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 V(:).'
- 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.
@@ -94,8 +95,8 @@ options:
asn1_base64:
description:
- 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 V(false).
- The documentation claimed for a long time that the values are Base64 encoded, but they never were. For compatibility
this option is set to V(false).
- The default value V(false) is B(deprecated) and will change to V(true) in community.crypto 3.0.0.
type: bool
version_added: 2.12.0
@@ -110,8 +111,8 @@ options:
get_certificate_chain:
description:
- If set to V(true), will obtain the certificate chain next to the certificate itself.
- The chain as returned by the server can be found in RV(unverified_chain), and the chain that passed validation
in RV(verified_chain).
- The chain as returned by the server can be found in RV(unverified_chain), and the chain that passed validation in
RV(verified_chain).
- B(Note) that this needs B(Python 3.10 or newer). Also note that only Python 3.13 or newer officially supports this.
The module uses internal APIs of Python 3.10, 3.11, and 3.12 to achieve the same. It can be that future versions of
Python 3.10, 3.11, or 3.12 break this.
@@ -121,7 +122,6 @@ options:
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 O(proxy_host), and Python >= 3.10 when O(get_certificate_chain=true)"
- "cryptography >= 1.6"
@@ -129,9 +129,9 @@ requirements:
seealso:
- plugin: community.crypto.to_serial
plugin_type: filter
'''
"""
RETURN = '''
RETURN = r"""
cert:
description: The certificate retrieved from the port.
returned: success
@@ -155,16 +155,12 @@ extensions:
type: str
description:
- The ASN.1 content of the extension.
- 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.
See U(https://github.com/ansible/ansible/issues/80258) for more information.
- B(Note) that depending on the C(cryptography) version used, it is
not possible to extract the ASN.1 content of the extension, but only
to provide the re-encoded content of the extension in case it was
parsed by C(cryptography). This should usually result in exactly the
same value, except if the original extension value was malformed.
- 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. See U(https://github.com/ansible/ansible/issues/80258) for more information.
- B(Note) that depending on the C(cryptography) version used, it is not possible to extract the ASN.1 content of the
extension, but only to provide the re-encoded content of the extension in case it was parsed by C(cryptography).
This should usually result in exactly the same value, except if the original extension value was malformed.
name:
returned: success
type: str
@@ -184,8 +180,8 @@ not_before:
serial_number:
description:
- The serial number of the cert.
- This return value is an B(integer). If you need the serial numbers as a colon-separated hex string,
such as C(11:22:33), you need to convert it to that form with P(community.crypto.to_serial#filter).
- This return value is an B(integer). If you need the serial numbers as a colon-separated hex string, such as C(11:22:33),
you need to convert it to that form with P(community.crypto.to_serial#filter).
returned: success
type: int
signature_algorithm:
@@ -204,10 +200,10 @@ verified_chain:
description:
- The verified certificate chain retrieved from the port.
- The first entry is always RV(cert).
- The last certificate the root certificate the chain is traced to. If O(ca_cert) is provided this certificate is part of that store;
otherwise it is part of the store used by default by Python.
- Note that RV(unverified_chain) generally does not contain the root certificate, and might contain other certificates that are not part
of the validated chain.
- The last certificate the root certificate the chain is traced to. If O(ca_cert) is provided this certificate is part
of that store; otherwise it is part of the store used by default by Python.
- Note that RV(unverified_chain) generally does not contain the root certificate, and might contain other certificates
that are not part of the validated chain.
returned: success and O(get_certificate_chain=true)
type: list
elements: str
@@ -220,9 +216,9 @@ unverified_chain:
type: list
elements: str
version_added: 2.21.0
'''
"""
EXAMPLES = '''
EXAMPLES = r"""
- name: Get the cert from an RDP port
community.crypto.get_certificate:
host: "1.2.3.4"
@@ -265,7 +261,7 @@ EXAMPLES = '''
delegate_to: localhost
run_once: true
register: legacy_cert
'''
"""
import atexit
import base64

547
plugins/modules/luks_device.py
View File

@@ -7,318 +7,269 @@ from __future__ import (absolute_import, division, print_function)
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: luks_device
short_description: Manage encrypted (LUKS) devices
description:
- "Module manages L(LUKS,https://en.wikipedia.org/wiki/Linux_Unified_Key_Setup)
on given device. Supports creating, destroying, opening and closing of
LUKS container and adding or removing new keys and passphrases."
- Module manages L(LUKS,https://en.wikipedia.org/wiki/Linux_Unified_Key_Setup) on given device. Supports creating, destroying,
opening and closing of LUKS container and adding or removing new keys and passphrases.
extends_documentation_fragment:
- community.crypto.attributes
- community.crypto.attributes
attributes:
check_mode:
support: full
diff_mode:
support: none
check_mode:
support: full
diff_mode:
support: none
options:
device:
device:
description:
- 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.
- V(present) will create LUKS container unless already present. Requires O(device) and either O(keyfile) or O(passphrase)
options to be provided.
- 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 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.
- V(closed) will lock the LUKS container. However if the container does not exist it will be created. Requires O(device)
and either O(keyfile) or O(passphrase) options to be provided. If container does already exist O(device) or O(name)
will suffice.
type: str
default: present
choices: [present, absent, opened, closed]
name:
description:
- 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 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 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'
keyslot:
description:
- Adds the O(keyfile) or O(passphrase) to a specific keyslot when creating a new container on O(device). Parameter value
is the number of the keyslot.
- B(Note) that a device of O(type=luks1) supports the keyslot numbers V(0)-V(7) and a device of O(type=luks2) supports
the keyslot numbers V(0)-V(31). In order to use the keyslots V(8)-V(31) when creating a new container, setting O(type)
to V(luks2) is required.
type: int
version_added: '2.16.0'
keysize:
description:
- Sets the key size only if LUKS container does not exist.
type: int
version_added: '1.0.0'
new_keyfile:
description:
- 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 community.crypto 1.4.0. For older versions, a new keyslot
will be used even if another keyslot already exists for this keyfile.
- BEWARE that working with keyfiles in plaintext is dangerous. Make sure that they are protected.
type: path
new_passphrase:
description:
- 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 community.crypto 1.4.0. For older versions, a new
keyslot will be used even if another keyslot already exists for this passphrase.
type: str
version_added: '1.0.0'
new_keyslot:
description:
- Adds the additional O(new_keyfile) or O(new_passphrase) to a specific keyslot on the given O(device). Parameter value
is the number of the keyslot.
- B(Note) that a device of O(type=luks1) supports the keyslot numbers V(0)-V(7) and a device of O(type=luks2) supports
the keyslot numbers V(0)-V(31).
type: int
version_added: '2.16.0'
remove_keyfile:
description:
- 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 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 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 O(force_remove_last_key) option must be set to V(true).
type: str
version_added: '1.0.0'
remove_keyslot:
description:
- Removes the key in the given slot on O(device). Needs O(keyfile) or O(passphrase) for authorization.
- B(Note) that a device of O(type=luks1) supports the keyslot numbers V(0)-V(7) and a device of O(type=luks2) supports
the keyslot numbers V(0)-V(31).
- B(Note) that the given O(keyfile) or O(passphrase) must not be in the slot to be removed.
type: int
version_added: '2.16.0'
force_remove_last_key:
description:
- 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
default: false
label:
description:
- 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 O(device) is not specified.
- 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 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 V(luks1)
or V(luks2).
type: str
choices: [luks1, luks2]
version_added: '1.0.0'
cipher:
description:
- 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 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:
description:
- This option allows the user to specify the hash function used in LUKS key setup scheme and volume key digest.
- Will only be used on container creation.
type: str
version_added: '1.1.0'
pbkdf:
description:
- This option allows the user to configure the Password-Based Key Derivation Function (PBKDF) used.
- Will only be used on container creation, and when adding keys to an existing container.
type: dict
version_added: '1.4.0'
suboptions:
iteration_time:
description:
- "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:
- 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 O(pbkdf.iteration_count).
type: float
iteration_count:
description:
- "Desired state of the LUKS container. Based on its value creates,
destroys, opens or closes the LUKS container on a given device."
- "V(present) will create LUKS container unless already present.
Requires O(device) and either O(keyfile) or O(passphrase) options
to be provided."
- "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 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."
- "V(closed) will lock the LUKS container. However if the container
does not exist it will be created.
Requires O(device) and either O(keyfile) or O(passphrase)
options to be provided. If container does already exist
O(device) or O(name) will suffice."
type: str
default: present
choices: [present, absent, opened, closed]
name:
description:
- "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 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 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'
keyslot:
description:
- "Adds the O(keyfile) or O(passphrase) to a specific keyslot when
creating a new container on O(device). Parameter value is the
number of the keyslot."
- "B(Note) that a device of O(type=luks1) supports the keyslot numbers
V(0)-V(7) and a device of O(type=luks2) supports the keyslot numbers
V(0)-V(31). In order to use the keyslots V(8)-V(31) when creating a new
container, setting O(type) to V(luks2) is required."
- Specify the iteration count used for the PBKDF.
- Mutually exclusive with O(pbkdf.iteration_time).
type: int
version_added: '2.16.0'
keysize:
algorithm:
description:
- "Sets the key size only if LUKS container does not exist."
- The algorithm to use.
- Only available for the LUKS 2 format.
choices:
- argon2i
- argon2id
- pbkdf2
type: str
memory:
description:
- The memory cost limit in kilobytes for the PBKDF.
- This is not used for PBKDF2, but only for the Argon PBKDFs.
type: int
version_added: '1.0.0'
new_keyfile:
parallel:
description:
- "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
community.crypto 1.4.0. For older versions, a new keyslot
will be used even if another keyslot already exists for this
keyfile."
- "BEWARE that working with keyfiles in plaintext is dangerous.
Make sure that they are protected."
type: path
new_passphrase:
description:
- "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
community.crypto 1.4.0. For older versions, a new keyslot will
be used even if another keyslot already exists for this passphrase."
type: str
version_added: '1.0.0'
new_keyslot:
description:
- "Adds the additional O(new_keyfile) or O(new_passphrase) to a
specific keyslot on the given O(device). Parameter value is the number
of the keyslot."
- "B(Note) that a device of O(type=luks1) supports the keyslot numbers
V(0)-V(7) and a device of O(type=luks2) supports the keyslot numbers
V(0)-V(31)."
- The parallel cost for the PBKDF. This is the number of threads that run in parallel.
- This is not used for PBKDF2, but only for the Argon PBKDFs.
type: int
version_added: '2.16.0'
remove_keyfile:
description:
- "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
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 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 O(force_remove_last_key) option must be set
to V(true)."
type: str
version_added: '1.0.0'
remove_keyslot:
description:
- "Removes the key in the given slot on O(device). Needs
O(keyfile) or O(passphrase) for authorization."
- "B(Note) that a device of O(type=luks1) supports the keyslot numbers
V(0)-V(7) and a device of O(type=luks2) supports the keyslot numbers
V(0)-V(31)."
- "B(Note) that the given O(keyfile) or O(passphrase) must not be
in the slot to be removed."
type: int
version_added: '2.16.0'
force_remove_last_key:
description:
- "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
default: false
label:
description:
- "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 O(device) is
not specified."
- "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 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 V(luks1) or V(luks2)"
type: str
choices: [luks1, luks2]
version_added: '1.0.0'
cipher:
description:
- "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 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:
description:
- "This option allows the user to specify the hash function used in LUKS
key setup scheme and volume key digest."
- "Will only be used on container creation."
type: str
version_added: '1.1.0'
pbkdf:
description:
- This option allows the user to configure the Password-Based Key Derivation
Function (PBKDF) used.
- Will only be used on container creation, and when adding keys to an existing
container.
type: dict
version_added: '1.4.0'
suboptions:
iteration_time:
description:
- 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 O(pbkdf.iteration_count).
type: float
iteration_count:
description:
- Specify the iteration count used for the PBKDF.
- Mutually exclusive with O(pbkdf.iteration_time).
type: int
algorithm:
description:
- The algorithm to use.
- Only available for the LUKS 2 format.
choices:
- argon2i
- argon2id
- pbkdf2
type: str
memory:
description:
- The memory cost limit in kilobytes for the PBKDF.
- This is not used for PBKDF2, but only for the Argon PBKDFs.
type: int
parallel:
description:
- The parallel cost for the PBKDF. This is the number of threads that
run in parallel.
- This is not used for PBKDF2, but only for the Argon PBKDFs.
type: int
sector_size:
description:
- "This option allows the user to specify the sector size (in bytes) used for LUKS2 containers."
- "Will only be used on container creation."
type: int
version_added: '1.5.0'
perf_same_cpu_crypt:
description:
- "Allows the user to perform encryption using the same CPU that IO was submitted on."
- "The default is to use an unbound workqueue so that encryption work is automatically balanced between available CPUs."
- "Will only be used when opening containers."
type: bool
default: false
version_added: '2.3.0'
perf_submit_from_crypt_cpus:
description:
- "Allows the user to disable offloading writes to a separate thread after encryption."
- "There are some situations where offloading block write IO operations from the encryption threads
to a single thread degrades performance significantly."
- "The default is to offload block write IO operations to the same thread."
- "Will only be used when opening containers."
type: bool
default: false
version_added: '2.3.0'
perf_no_read_workqueue:
description:
- "Allows the user to bypass dm-crypt internal workqueue and process read requests synchronously."
- "Will only be used when opening containers."
type: bool
default: false
version_added: '2.3.0'
perf_no_write_workqueue:
description:
- "Allows the user to bypass dm-crypt internal workqueue and process write requests synchronously."
- "Will only be used when opening containers."
type: bool
default: false
version_added: '2.3.0'
persistent:
description:
- "Allows the user to store options into container's metadata persistently and automatically use them next time.
Only O(perf_same_cpu_crypt), O(perf_submit_from_crypt_cpus), O(perf_no_read_workqueue), O(perf_no_write_workqueue),
and O(allow_discards) can be stored persistently."
- "Will only work with LUKS2 containers."
- "Will only be used when opening containers."
type: bool
default: false
version_added: '2.3.0'
allow_discards:
description:
- "Allow discards (also known as TRIM) requests for device."
- "Will only be used when opening containers."
type: bool
default: false
version_added: '2.17.0'
sector_size:
description:
- This option allows the user to specify the sector size (in bytes) used for LUKS2 containers.
- Will only be used on container creation.
type: int
version_added: '1.5.0'
perf_same_cpu_crypt:
description:
- Allows the user to perform encryption using the same CPU that IO was submitted on.
- The default is to use an unbound workqueue so that encryption work is automatically balanced between available CPUs.
- Will only be used when opening containers.
type: bool
default: false
version_added: '2.3.0'
perf_submit_from_crypt_cpus:
description:
- Allows the user to disable offloading writes to a separate thread after encryption.
- There are some situations where offloading block write IO operations from the encryption threads to a single thread
degrades performance significantly.
- The default is to offload block write IO operations to the same thread.
- Will only be used when opening containers.
type: bool
default: false
version_added: '2.3.0'
perf_no_read_workqueue:
description:
- Allows the user to bypass dm-crypt internal workqueue and process read requests synchronously.
- Will only be used when opening containers.
type: bool
default: false
version_added: '2.3.0'
perf_no_write_workqueue:
description:
- Allows the user to bypass dm-crypt internal workqueue and process write requests synchronously.
- Will only be used when opening containers.
type: bool
default: false
version_added: '2.3.0'
persistent:
description:
- Allows the user to store options into container's metadata persistently and automatically use them next time. Only
O(perf_same_cpu_crypt), O(perf_submit_from_crypt_cpus), O(perf_no_read_workqueue), O(perf_no_write_workqueue), and
O(allow_discards) can be stored persistently.
- Will only work with LUKS2 containers.
- Will only be used when opening containers.
type: bool
default: false
version_added: '2.3.0'
allow_discards:
description:
- Allow discards (also known as TRIM) requests for device.
- Will only be used when opening containers.
type: bool
default: false
version_added: '2.17.0'
requirements:
- "cryptsetup"
- "wipefs (when O(state) is V(absent))"
- "lsblk"
- "blkid (when O(label) or O(uuid) options are used)"
- "cryptsetup"
- "wipefs (when O(state) is V(absent))"
- "lsblk"
- "blkid (when O(label) or O(uuid) options are used)"
author: Jan Pokorny (@japokorn)
'''
EXAMPLES = '''
"""
EXAMPLES = r"""
- name: Create LUKS container (remains unchanged if it already exists)
community.crypto.luks_device:
device: "/dev/loop0"
@@ -436,17 +387,15 @@ EXAMPLES = '''
device: "/dev/loop0"
keyfile: "/vault/keyfile"
remove_keyslot: 4
'''
"""
RETURN = '''
RETURN = r"""
name:
description:
When O(state=opened) returns (generated or given) name
of LUKS container. Returns None if no name is supplied.
returned: success
type: str
sample: "luks-c1da9a58-2fde-4256-9d9f-6ab008b4dd1b"
'''
description: When O(state=opened) returns (generated or given) name of LUKS container. Returns None if no name is supplied.
returned: success
type: str
sample: "luks-c1da9a58-2fde-4256-9d9f-6ab008b4dd1b"
"""
import os
import re

398
plugins/modules/openssh_cert.py
View File

@@ -9,197 +9,193 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: openssh_cert
author: "David Kainz (@lolcube)"
short_description: Generate OpenSSH host or user certificates.
short_description: Generate OpenSSH host or user certificates
description:
- Generate and regenerate OpenSSH host or user certificates.
- Generate and regenerate OpenSSH host or user certificates.
requirements:
- "ssh-keygen"
- "ssh-keygen"
extends_documentation_fragment:
- ansible.builtin.files
- community.crypto.attributes
- community.crypto.attributes.files
- ansible.builtin.files
- community.crypto.attributes
- community.crypto.attributes.files
attributes:
check_mode:
support: full
diff_mode:
support: full
safe_file_operations:
support: full
check_mode:
support: full
diff_mode:
support: full
safe_file_operations:
support: full
options:
state:
description:
- Whether the host or user certificate should exist or not, taking action if the state is different
from what is stated.
type: str
default: "present"
choices: [ 'present', 'absent' ]
type:
description:
- Whether the module should generate a host or a user certificate.
- 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 O(regenerate=always).
type: bool
default: false
path:
description:
- Path of the file containing the certificate.
type: path
required: true
regenerate:
description:
- 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 V(fail) the task will fail if a certificate already exists at O(path) and does not
match the module's options.
- 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.
- V(always) is equivalent to O(force=true).
type: str
choices:
- never
- fail
- partial_idempotence
- full_idempotence
- always
default: partial_idempotence
version_added: 1.8.0
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 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, 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 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 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.
type: str
choices:
- ssh-rsa
- rsa-sha2-256
- rsa-sha2-512
version_added: 1.10.0
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 (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, 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:
description:
- Should the ssh-keygen use a CA key residing in a ssh-agent.
type: bool
default: false
version_added: 1.3.0
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 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 V(+32w1d2h)).
Note that if using relative time this module is NOT idempotent."
- "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 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 V(+32w1d2h)).
Note that if using relative time this module is NOT idempotent."
- "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 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 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
version_added: 2.2.0
principals:
description:
- "Certificates may be limited to be valid for a set of principal (user/host) names.
By default, generated certificates are valid for all users or hosts."
type: list
elements: str
options:
description:
- "Specify certificate options when signing a key. The option that are valid for user certificates are:"
- "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."
- "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
elements: str
identifier:
description:
- Specify the key identity when signing a public key. The identifier that is logged by the server when the certificate is used for authentication.
type: str
serial_number:
description:
- "Specify the certificate serial number.
The serial number is logged by the server when the certificate is used for authentication.
The certificate serial number may be used in a KeyRevocationList.
The serial number may be omitted for checks, but must be specified again for a new certificate.
Note: The default value set by ssh-keygen is 0."
- This option accepts an B(integer). If you want to provide serial numbers as colon-separated hex strings,
such as C(11:22:33), you need to convert them to an integer with P(community.crypto.parse_serial#filter).
type: int
state:
description:
- Whether the host or user certificate should exist or not, taking action if the state is different from what is stated.
type: str
default: "present"
choices: ['present', 'absent']
type:
description:
- Whether the module should generate a host or a user certificate.
- 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 O(regenerate=always).
type: bool
default: false
path:
description:
- Path of the file containing the certificate.
type: path
required: true
regenerate:
description:
- 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 V(fail) the task will fail if a certificate already exists at O(path) and does not match the module's options.
- 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.
- V(always) is equivalent to O(force=true).
type: str
choices:
- never
- fail
- partial_idempotence
- full_idempotence
- always
default: partial_idempotence
version_added: 1.8.0
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 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, 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 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 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.
type: str
choices:
- ssh-rsa
- rsa-sha2-256
- rsa-sha2-512
version_added: 1.10.0
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 (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, 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:
description:
- Should the ssh-keygen use a CA key residing in a ssh-agent.
type: bool
default: false
version_added: 1.3.0
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 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 V(+32w1d2h)). Note that
if using relative time this module is NOT idempotent.'
- 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 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 V(+32w1d2h)). Note that
if using relative time this module is NOT idempotent.'
- 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 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 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
version_added: 2.2.0
principals:
description:
- Certificates may be limited to be valid for a set of principal (user/host) names. By default, generated certificates
are valid for all users or hosts.
type: list
elements: str
options:
description:
- 'Specify certificate options when signing a key. The option that are valid for user certificates are:'
- '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.'
- '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
elements: str
identifier:
description:
- Specify the key identity when signing a public key. The identifier that is logged by the server when the certificate
is used for authentication.
type: str
serial_number:
description:
- 'Specify the certificate serial number. The serial number is logged by the server when the certificate is used for
authentication. The certificate serial number may be used in a KeyRevocationList. The serial number may be omitted
for checks, but must be specified again for a new certificate. Note: The default value set by ssh-keygen is 0.'
- This option accepts an B(integer). If you want to provide serial numbers as colon-separated hex strings, such as C(11:22:33),
you need to convert them to an integer with P(community.crypto.parse_serial#filter).
type: int
seealso:
- plugin: community.crypto.parse_serial
plugin_type: filter
'''
- plugin: community.crypto.parse_serial
plugin_type: filter
"""
EXAMPLES = '''
EXAMPLES = r"""
- name: Generate an OpenSSH user certificate that is valid forever and for all users
community.crypto.openssh_cert:
type: user
@@ -231,8 +227,8 @@ EXAMPLES = '''
valid_from: always
valid_to: forever
principals:
- example.com
- examplehost
- example.com
- examplehost
- name: Generate an OpenSSH host Certificate that is valid from 21.1.2001 to 21.1.2019
community.crypto.openssh_cert:
@@ -252,8 +248,8 @@ EXAMPLES = '''
valid_from: always
valid_to: forever
options:
- "clear"
- "force-command=/tmp/bla/foo"
- "clear"
- "force-command=/tmp/bla/foo"
- name: Generate an OpenSSH user certificate using a PKCS#11 token
community.crypto.openssh_cert:
@@ -264,27 +260,25 @@ EXAMPLES = '''
path: /path/to/certificate
valid_from: always
valid_to: forever
"""
'''
RETURN = '''
RETURN = r"""
type:
description: type of the certificate (host or user)
returned: changed or success
type: str
sample: host
description: Type of the certificate (host or user).
returned: changed or success
type: str
sample: host
filename:
description: path to the certificate
returned: changed or success
type: str
sample: /tmp/certificate-cert.pub
description: Path to the certificate.
returned: changed or success
type: str
sample: /tmp/certificate-cert.pub
info:
description: Information about the certificate. Output of C(ssh-keygen -L -f).
returned: change or success
type: list
elements: str
'''
description: Information about the certificate. Output of C(ssh-keygen -L -f).
returned: change or success
type: list
elements: str
"""
import os

299
plugins/modules/openssh_keypair.py
View File

@@ -8,141 +8,136 @@
from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = '''
---
DOCUMENTATION = r"""
module: openssh_keypair
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 V(rsa), V(dsa), V(rsa1), V(ed25519)
or V(ecdsa) private keys."
- This module allows one to (re)generate OpenSSH private and public keys. It uses 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 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)
- 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
- community.crypto.attributes.files
- ansible.builtin.files
- community.crypto.attributes
- community.crypto.attributes.files
attributes:
check_mode:
support: full
diff_mode:
support: full
safe_file_operations:
support: full
check_mode:
support: full
diff_mode:
support: full
safe_file_operations:
support: full
options:
state:
description:
- Whether the private and public keys should exist or not, taking action if the state is different from what is stated.
type: str
default: present
choices: [ present, absent ]
size:
description:
- "Specifies the number of bits in the private key to create. For RSA keys, the minimum size is 1024 bits and the default is 4096 bits.
Generally, 2048 bits is considered sufficient. DSA keys must be exactly 1024 bits as specified by FIPS 186-2.
For ECDSA keys, size determines the key length by selecting from one of three elliptic curve sizes: 256, 384 or 521 bits.
Attempting to use bit lengths other than these three values for ECDSA keys will cause this module to fail.
Ed25519 keys have a fixed length and the size will be ignored."
type: int
type:
description:
- "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']
force:
description:
- Should the key be regenerated even if it already exists
type: bool
default: false
path:
description:
- Name of the files containing the public and private key. The file containing the public key will have the extension C(.pub).
type: path
required: true
comment:
description:
- Provides a new comment to the public key.
type: str
passphrase:
description:
- Passphrase used to decrypt an existing private key or encrypt a newly generated private key.
- 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 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 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
choices:
- auto
- pkcs1
- pkcs8
- ssh
version_added: 1.7.0
backend:
description:
- 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:
- auto
- cryptography
- opensshbin
version_added: 1.7.0
regenerate:
description:
- Allows to configure in which situations the module is allowed to regenerate private keys.
The module will always generate a new key if the destination file does not exist.
- By default, the key will be regenerated when it does not match the module's options,
except when the key cannot be read or the passphrase does not match. Please note that
this B(changed) for Ansible 2.10. For Ansible 2.9, the behavior was as if V(full_idempotence)
is specified.
- If set to V(never), the module will fail if the key cannot be read or the passphrase
is not matching, and will never regenerate an existing key.
- If set to V(fail), the module will fail if the key does not correspond to the module's
options.
- If set to V(partial_idempotence), the key will be regenerated if it does not conform to
the module's options. The key is B(not) regenerated if it cannot be read (broken file),
the key is protected by an unknown passphrase, or when they key is not protected by a
passphrase, but a passphrase is specified.
- If set to V(full_idempotence), the key will be regenerated if it does not conform to the
module's options. This is also the case if the key cannot be read (broken file), the key
is protected by an unknown passphrase, or when they key is not protected by a passphrase,
but a passphrase is specified. Make sure you have a B(backup) when using this option!
- If set to V(always), the module will always regenerate the key. This is equivalent to
setting O(force) to V(true).
- Note that adjusting the comment and the permissions can be changed without regeneration.
Therefore, even for V(never), the task can result in changed.
type: str
choices:
- never
- fail
- partial_idempotence
- full_idempotence
- always
default: partial_idempotence
version_added: '1.0.0'
state:
description:
- Whether the private and public keys should exist or not, taking action if the state is different from what is stated.
type: str
default: present
choices: [present, absent]
size:
description:
- 'Specifies the number of bits in the private key to create. For RSA keys, the minimum size is 1024 bits and the default
is 4096 bits. Generally, 2048 bits is considered sufficient. DSA keys must be exactly 1024 bits as specified by FIPS
186-2. For ECDSA keys, size determines the key length by selecting from one of three elliptic curve sizes: 256, 384
or 521 bits. Attempting to use bit lengths other than these three values for ECDSA keys will cause this module to
fail. Ed25519 keys have a fixed length and the size will be ignored.'
type: int
type:
description:
- 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']
force:
description:
- Should the key be regenerated even if it already exists.
type: bool
default: false
path:
description:
- Name of the files containing the public and private key. The file containing the public key will have the extension
C(.pub).
type: path
required: true
comment:
description:
- Provides a new comment to the public key.
type: str
passphrase:
description:
- Passphrase used to decrypt an existing private key or encrypt a newly generated private key.
- 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 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 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
choices:
- auto
- pkcs1
- pkcs8
- ssh
version_added: 1.7.0
backend:
description:
- 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:
- auto
- cryptography
- opensshbin
version_added: 1.7.0
regenerate:
description:
- Allows to configure in which situations the module is allowed to regenerate private keys. The module will always generate
a new key if the destination file does not exist.
- By default, the key will be regenerated when it does not match the module's options, except when the key cannot be
read or the passphrase does not match. Please note that this B(changed) for Ansible 2.10. For Ansible 2.9, the behavior
was as if V(full_idempotence) is specified.
- If set to V(never), the module will fail if the key cannot be read or the passphrase is not matching, and will never
regenerate an existing key.
- If set to V(fail), the module will fail if the key does not correspond to the module's options.
- If set to V(partial_idempotence), the key will be regenerated if it does not conform to the module's options. The
key is B(not) regenerated if it cannot be read (broken file), the key is protected by an unknown passphrase, or when
they key is not protected by a passphrase, but a passphrase is specified.
- If set to V(full_idempotence), the key will be regenerated if it does not conform to the module's options. This is
also the case if the key cannot be read (broken file), the key is protected by an unknown passphrase, or when they
key is not protected by a passphrase, but a passphrase is specified. Make sure you have a B(backup) when using this
option!
- If set to V(always), the module will always regenerate the key. This is equivalent to setting O(force) to V(true).
- Note that adjusting the comment and the permissions can be changed without regeneration. Therefore, even for V(never),
the task can result in changed.
type: str
choices:
- never
- fail
- partial_idempotence
- full_idempotence
- always
default: partial_idempotence
version_added: '1.0.0'
notes:
- In case the ssh key is broken or password protected, the module will fail.
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.
'''
- In case the ssh key is broken or password protected, the module will fail. 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 = '''
EXAMPLES = r"""
- name: Generate an OpenSSH keypair with the default values (4096 bits, rsa)
community.crypto.openssh_keypair:
path: /tmp/id_ssh_rsa
@@ -166,40 +161,40 @@ EXAMPLES = '''
community.crypto.openssh_keypair:
path: /tmp/id_ssh_dsa
type: dsa
'''
"""
RETURN = '''
RETURN = r"""
size:
description: Size (in bits) of the SSH private key.
returned: changed or success
type: int
sample: 4096
description: Size (in bits) of the SSH private key.
returned: changed or success
type: int
sample: 4096
type:
description: Algorithm used to generate the SSH private key.
returned: changed or success
type: str
sample: rsa
description: Algorithm used to generate the SSH private key.
returned: changed or success
type: str
sample: rsa
filename:
description: Path to the generated SSH private key file.
returned: changed or success
type: str
sample: /tmp/id_ssh_rsa
description: Path to the generated SSH private key file.
returned: changed or success
type: str
sample: /tmp/id_ssh_rsa
fingerprint:
description: The fingerprint of the key.
returned: changed or success
type: str
sample: SHA256:r4YCZxihVjedH2OlfjVGI6Y5xAYtdCwk8VxKyzVyYfM
description: The fingerprint of the key.
returned: changed or success
type: str
sample: SHA256:r4YCZxihVjedH2OlfjVGI6Y5xAYtdCwk8VxKyzVyYfM
public_key:
description: The public key of the generated SSH private key.
returned: changed or success
type: str
sample: ssh-rsa AAAAB3Nza(...omitted...)veL4E3Xcw==
description: The public key of the generated SSH private key.
returned: changed or success
type: str
sample: ssh-rsa AAAAB3Nza(...omitted...)veL4E3Xcw==
comment:
description: The comment of the generated key.
returned: changed or success
type: str
sample: test@comment
'''
description: The comment of the generated key.
returned: changed or success
type: str
sample: test@comment
"""
from ansible.module_utils.basic import AnsibleModule

240
plugins/modules/openssl_csr.py
View File

@@ -10,71 +10,70 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = r'''
---
DOCUMENTATION = r"""
module: openssl_csr
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 O(backup) option."
- 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 O(backup) option.
author:
- Yanis Guenane (@Spredzy)
- Felix Fontein (@felixfontein)
- Yanis Guenane (@Spredzy)
- Felix Fontein (@felixfontein)
extends_documentation_fragment:
- ansible.builtin.files
- community.crypto.attributes
- community.crypto.attributes.files
- community.crypto.module_csr
- ansible.builtin.files
- community.crypto.attributes
- community.crypto.attributes.files
- community.crypto.module_csr
attributes:
check_mode:
support: full
diff_mode:
support: full
safe_file_operations:
support: full
check_mode:
support: full
diff_mode:
support: full
safe_file_operations:
support: full
options:
state:
description:
- Whether the certificate signing request should exist or not, taking action if the state is different from what is stated.
type: str
default: present
choices: [ absent, present ]
force:
description:
- Should the certificate signing request be forced regenerated by this ansible module.
type: bool
default: false
path:
description:
- The name of the file into which the generated OpenSSL certificate signing request will be written.
type: path
required: true
backup:
description:
- Create a backup file including a timestamp so you can get the original
CSR back if you overwrote it with a new one by accident.
type: bool
default: false
return_content:
description:
- If set to V(true), will return the (current or generated) CSR's content as RV(csr).
type: bool
default: false
version_added: "1.0.0"
privatekey_content:
version_added: "1.0.0"
name_constraints_permitted:
version_added: 1.1.0
name_constraints_excluded:
version_added: 1.1.0
name_constraints_critical:
version_added: 1.1.0
state:
description:
- Whether the certificate signing request should exist or not, taking action if the state is different from what is
stated.
type: str
default: present
choices: [absent, present]
force:
description:
- Should the certificate signing request be forced regenerated by this ansible module.
type: bool
default: false
path:
description:
- The name of the file into which the generated OpenSSL certificate signing request will be written.
type: path
required: true
backup:
description:
- Create a backup file including a timestamp so you can get the original CSR back if you overwrote it with a new one
by accident.
type: bool
default: false
return_content:
description:
- If set to V(true), will return the (current or generated) CSR's content as RV(csr).
type: bool
default: false
version_added: "1.0.0"
privatekey_content:
version_added: "1.0.0"
name_constraints_permitted:
version_added: 1.1.0
name_constraints_excluded:
version_added: 1.1.0
name_constraints_critical:
version_added: 1.1.0
seealso:
- module: community.crypto.openssl_csr_pipe
'''
- module: community.crypto.openssl_csr_pipe
"""
EXAMPLES = r'''
EXAMPLES = r"""
- name: Generate an OpenSSL Certificate Signing Request
community.crypto.openssl_csr:
path: /etc/ssl/csr/www.ansible.com.csr
@@ -116,8 +115,8 @@ EXAMPLES = r'''
subject_alt_name: "{{ item.value | map('regex_replace', '^', 'DNS:') | list }}"
with_dict:
dns_server:
- www.ansible.com
- m.ansible.com
- www.ansible.com
- m.ansible.com
- name: Force regenerate an OpenSSL Certificate Signing Request
community.crypto.openssl_csr:
@@ -150,7 +149,7 @@ EXAMPLES = r'''
privatekey_path: /etc/ssl/private/winrm.auth.pem
common_name: username
extended_key_usage:
- clientAuth
- clientAuth
subject_alt_name: otherName:1.3.6.1.4.1.311.20.2.3;UTF8:username@localhost
- name: Generate an OpenSSL Certificate Signing Request with a CRL distribution point
@@ -167,82 +166,81 @@ EXAMPLES = r'''
- key_compromise
- ca_compromise
- cessation_of_operation
'''
"""
RETURN = r'''
RETURN = r"""
privatekey:
description:
- Path to the TLS/SSL private key the CSR was generated for
description:
- Path to the TLS/SSL private key the CSR was generated for.
- 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
returned: changed or success
type: str
sample: /etc/ssl/private/ansible.com.pem
filename:
description: Path to the generated Certificate Signing Request
returned: changed or success
type: str
sample: /etc/ssl/csr/www.ansible.com.csr
description: Path to the generated Certificate Signing Request.
returned: changed or success
type: str
sample: /etc/ssl/csr/www.ansible.com.csr
subject:
description: A list of the subject tuples attached to the CSR
returned: changed or success
type: list
elements: list
sample: [['CN', 'www.ansible.com'], ['O', 'Ansible']]
description: A list of the subject tuples attached to the CSR.
returned: changed or success
type: list
elements: list
sample: [['CN', 'www.ansible.com'], ['O', 'Ansible']]
subjectAltName:
description: The alternative names this CSR is valid for
returned: changed or success
type: list
elements: str
sample: [ 'DNS:www.ansible.com', 'DNS:m.ansible.com' ]
description: The alternative names this CSR is valid for.
returned: changed or success
type: list
elements: str
sample: ['DNS:www.ansible.com', 'DNS:m.ansible.com']
keyUsage:
description: Purpose for which the public key may be used
returned: changed or success
type: list
elements: str
sample: [ 'digitalSignature', 'keyAgreement' ]
description: Purpose for which the public key may be used.
returned: changed or success
type: list
elements: str
sample: ['digitalSignature', 'keyAgreement']
extendedKeyUsage:
description: Additional restriction on the public key purposes
returned: changed or success
type: list
elements: str
sample: [ 'clientAuth' ]
description: Additional restriction on the public key purposes.
returned: changed or success
type: list
elements: str
sample: ['clientAuth']
basicConstraints:
description: Indicates if the certificate belongs to a CA
returned: changed or success
type: list
elements: str
sample: ['CA:TRUE', 'pathLenConstraint:0']
description: Indicates if the certificate belongs to a CA.
returned: changed or success
type: list
elements: str
sample: ['CA:TRUE', 'pathLenConstraint:0']
ocsp_must_staple:
description: Indicates whether the certificate has the OCSP
Must Staple feature enabled
returned: changed or success
type: bool
sample: false
description: Indicates whether the certificate has the OCSP Must Staple feature enabled.
returned: changed or success
type: bool
sample: false
name_constraints_permitted:
description: List of permitted subtrees to sign certificates for.
returned: changed or success
type: list
elements: str
sample: ['email:.somedomain.com']
version_added: 1.1.0
description: List of permitted subtrees to sign certificates for.
returned: changed or success
type: list
elements: str
sample: ['email:.somedomain.com']
version_added: 1.1.0
name_constraints_excluded:
description: List of excluded subtrees the CA cannot sign certificates for.
returned: changed or success
type: list
elements: str
sample: ['email:.com']
version_added: 1.1.0
description: List of excluded subtrees the CA cannot sign certificates for.
returned: changed or success
type: list
elements: str
sample: ['email:.com']
version_added: 1.1.0
backup_file:
description: Name of backup file created.
returned: changed and if O(backup) is V(true)
type: str
sample: /path/to/www.ansible.com.csr.2019-03-09@11:22~
description: Name of backup file created.
returned: changed and if O(backup) is V(true)
type: str
sample: /path/to/www.ansible.com.csr.2019-03-09@11:22~
csr:
description: The (current or generated) CSR's content.
returned: if O(state) is V(present) and O(return_content) is V(true)
type: str
version_added: "1.0.0"
'''
description: The (current or generated) CSR's content.
returned: if O(state) is V(present) and O(return_content) is V(true)
type: str
version_added: "1.0.0"
"""
import os

495
plugins/modules/openssl_csr_info.py
View File

@@ -10,56 +10,54 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = r'''
---
DOCUMENTATION = r"""
module: openssl_csr_info
short_description: Provide information of OpenSSL Certificate Signing Requests (CSR)
description:
- This module allows one to query information on OpenSSL Certificate Signing Requests (CSR).
- In case the CSR signature cannot be validated, the module will fail. In this case, all return
variables are still returned.
- It uses the cryptography python library to interact with OpenSSL.
- This module allows one to query information on OpenSSL Certificate Signing Requests (CSR).
- In case the CSR signature cannot be validated, the module will fail. In this case, all return variables are still returned.
- It uses the cryptography python library to interact with OpenSSL.
requirements:
- cryptography >= 1.3
- cryptography >= 1.3
author:
- Felix Fontein (@felixfontein)
- Yanis Guenane (@Spredzy)
- Felix Fontein (@felixfontein)
- Yanis Guenane (@Spredzy)
extends_documentation_fragment:
- community.crypto.attributes
- community.crypto.attributes.info_module
- community.crypto.name_encoding
- community.crypto.attributes
- community.crypto.attributes.info_module
- community.crypto.name_encoding
options:
path:
description:
- Remote absolute path where the CSR file is loaded from.
- Either O(path) or O(content) must be specified, but not both.
type: path
content:
description:
- Content of the CSR file.
- 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 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 ]
path:
description:
- Remote absolute path where the CSR file is loaded from.
- Either O(path) or O(content) must be specified, but not both.
type: path
content:
description:
- Content of the CSR file.
- 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 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]
seealso:
- module: community.crypto.openssl_csr
- module: community.crypto.openssl_csr_pipe
- plugin: community.crypto.openssl_csr_info
plugin_type: filter
description: A filter variant of this module.
- plugin: community.crypto.to_serial
plugin_type: filter
'''
- module: community.crypto.openssl_csr
- module: community.crypto.openssl_csr_pipe
- plugin: community.crypto.openssl_csr_info
plugin_type: filter
description: A filter variant of this module.
- plugin: community.crypto.to_serial
plugin_type: filter
"""
EXAMPLES = r'''
EXAMPLES = r"""
- name: Generate an OpenSSL Certificate Signing Request
community.crypto.openssl_csr:
path: /etc/ssl/csr/www.ansible.com.csr
@@ -74,241 +72,240 @@ EXAMPLES = r'''
- name: Dump information
ansible.builtin.debug:
var: result
'''
"""
RETURN = r'''
RETURN = r"""
signature_valid:
description:
- Whether the CSR's signature is valid.
- In case the check returns V(false), the module will fail.
returned: success
type: bool
description:
- Whether the CSR's signature is valid.
- 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 V(none) if extension is not present.
returned: success
type: list
elements: str
sample: ['CA:TRUE', 'pathlen:1']
description: Entries in the C(basic_constraints) extension, or V(none) if extension is not present.
returned: success
type: list
elements: str
sample: ['CA:TRUE', 'pathlen:1']
basic_constraints_critical:
description: Whether the C(basic_constraints) extension is critical.
returned: success
type: bool
description: Whether the C(basic_constraints) extension is critical.
returned: success
type: bool
extended_key_usage:
description: Entries in the C(extended_key_usage) extension, or V(none) if extension is not present.
returned: success
type: list
elements: str
sample: [Biometric Info, DVCS, Time Stamping]
description: Entries in the C(extended_key_usage) extension, or V(none) if extension is not present.
returned: success
type: list
elements: str
sample: [Biometric Info, DVCS, Time Stamping]
extended_key_usage_critical:
description: Whether the C(extended_key_usage) extension is critical.
returned: success
type: bool
description: Whether the C(extended_key_usage) extension is critical.
returned: success
type: bool
extensions_by_oid:
description: Returns a dictionary for every extension OID
returned: success
type: dict
contains:
critical:
description: Whether the extension is critical.
returned: success
type: bool
value:
description:
- The Base64 encoded value (in DER format) of the extension.
- B(Note) that depending on the C(cryptography) version used, it is
not possible to extract the ASN.1 content of the extension, but only
to provide the re-encoded content of the extension in case it was
parsed by C(cryptography). This should usually result in exactly the
same value, except if the original extension value was malformed.
returned: success
type: str
sample: "MAMCAQU="
sample: {"1.3.6.1.5.5.7.1.24": { "critical": false, "value": "MAMCAQU="}}
description: Returns a dictionary for every extension OID.
returned: success
type: dict
contains:
critical:
description: Whether the extension is critical.
returned: success
type: bool
value:
description:
- The Base64 encoded value (in DER format) of the extension.
- B(Note) that depending on the C(cryptography) version used, it is not possible to extract the ASN.1 content of the
extension, but only to provide the re-encoded content of the extension in case it was parsed by C(cryptography).
This should usually result in exactly the same value, except if the original extension value was malformed.
returned: success
type: str
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 V(none) if extension is not present.
returned: success
type: str
sample: [Key Agreement, Data Encipherment]
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]
key_usage_critical:
description: Whether the C(key_usage) extension is critical.
returned: success
type: bool
description: Whether the C(key_usage) extension is critical.
returned: success
type: bool
subject_alt_name:
description:
- 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
sample: ["DNS:www.ansible.com", "IP:1.2.3.4"]
description:
- 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
sample: ["DNS:www.ansible.com", "IP:1.2.3.4"]
subject_alt_name_critical:
description: Whether the C(subject_alt_name) extension is critical.
returned: success
type: bool
description: Whether the C(subject_alt_name) extension is critical.
returned: success
type: bool
ocsp_must_staple:
description: V(true) if the OCSP Must Staple extension is present, V(none) otherwise.
returned: success
type: bool
description: V(true) if the OCSP Must Staple extension is present, V(none) otherwise.
returned: success
type: bool
ocsp_must_staple_critical:
description: Whether the C(ocsp_must_staple) extension is critical.
returned: success
type: bool
description: Whether the C(ocsp_must_staple) extension is critical.
returned: success
type: bool
name_constraints_permitted:
description: List of permitted subtrees to sign certificates for.
returned: success
type: list
elements: str
sample: ['email:.somedomain.com']
version_added: 1.1.0
description: List of permitted subtrees to sign certificates for.
returned: success
type: list
elements: str
sample: ['email:.somedomain.com']
version_added: 1.1.0
name_constraints_excluded:
description:
- List of excluded subtrees the CA cannot sign certificates for.
- Is V(none) if extension is not present.
- See O(name_encoding) for how IDNs are handled.
returned: success
type: list
elements: str
sample: ['email:.com']
version_added: 1.1.0
description:
- List of excluded subtrees the CA cannot sign certificates for.
- Is V(none) if extension is not present.
- See O(name_encoding) for how IDNs are handled.
returned: success
type: list
elements: str
sample: ['email:.com']
version_added: 1.1.0
name_constraints_critical:
description:
- Whether the C(name_constraints) extension is critical.
- Is V(none) if extension is not present.
returned: success
type: bool
version_added: 1.1.0
description:
- Whether the C(name_constraints) extension is critical.
- Is V(none) if extension is not present.
returned: success
type: bool
version_added: 1.1.0
subject:
description:
- The CSR's subject as a dictionary.
- Note that for repeated values, only the last one will be returned.
returned: success
type: dict
sample: {"commonName": "www.example.com", "emailAddress": "test@example.com"}
description:
- The CSR's subject as a dictionary.
- Note that for repeated values, only the last one will be returned.
returned: success
type: dict
sample: {"commonName": "www.example.com", "emailAddress": "test@example.com"}
subject_ordered:
description: The CSR's subject as an ordered list of tuples.
returned: success
type: list
elements: list
sample: [["commonName", "www.example.com"], ["emailAddress": "test@example.com"]]
description: The CSR's subject as an ordered list of tuples.
returned: success
type: list
elements: list
sample: [["commonName", "www.example.com"], ["emailAddress": "test@example.com"]]
public_key:
description: CSR's public key in PEM format
returned: success
type: str
sample: "-----BEGIN PUBLIC KEY-----\nMIICIjANBgkqhkiG9w0BAQEFAAOCAg8A..."
description: CSR's public key in PEM format.
returned: success
type: str
sample: "-----BEGIN PUBLIC KEY-----\nMIICIjANBgkqhkiG9w0BAQEFAAOCAg8A..."
public_key_type:
description:
- The CSR's public key's type.
- 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
sample: RSA
description:
- The CSR's public key's type.
- 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
sample: RSA
public_key_data:
description:
- Public key data. Depends on the public key's type.
returned: success
type: dict
version_added: 1.7.0
contains:
size:
description:
- Bit size of modulus (RSA) or prime number (DSA).
type: int
returned: When RV(public_key_type=RSA) or RV(public_key_type=DSA)
modulus:
description:
- The RSA key's modulus.
type: int
returned: When RV(public_key_type=RSA)
exponent:
description:
- The RSA key's public exponent.
type: int
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 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 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 RV(public_key_type=DSA)
curve:
description:
- The curve's name for ECC.
type: str
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 RV(public_key_type=ECC)
x:
description:
- The C(x) coordinate for the public point on the elliptic curve.
type: int
returned: When RV(public_key_type=ECC)
y:
description:
- 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 RV(public_key_type=DSA) or RV(public_key_type=ECC)
description:
- Public key data. Depends on the public key's type.
returned: success
type: dict
version_added: 1.7.0
contains:
size:
description:
- Bit size of modulus (RSA) or prime number (DSA).
type: int
returned: When RV(public_key_type=RSA) or RV(public_key_type=DSA)
modulus:
description:
- The RSA key's modulus.
type: int
returned: When RV(public_key_type=RSA)
exponent:
description:
- The RSA key's public exponent.
type: int
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 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 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 RV(public_key_type=DSA)
curve:
description:
- The curve's name for ECC.
type: str
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 RV(public_key_type=ECC)
x:
description:
- The C(x) coordinate for the public point on the elliptic curve.
type: int
returned: When RV(public_key_type=ECC)
y:
description:
- 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 RV(public_key_type=DSA) or RV(public_key_type=ECC)
public_key_fingerprints:
description:
- Fingerprints of CSR's public key.
- For every hash algorithm available, the fingerprint is computed.
returned: success
type: dict
sample: "{'sha256': 'd4:b3:aa:6d:c8:04:ce:4e:ba:f6:29:4d:92:a3:94:b0:c2:ff:bd:bf:33:63:11:43:34:0f:51:b0:95:09:2f:63',
'sha512': 'f7:07:4a:f0:b0:f0:e6:8b:95:5f:f9:e6:61:0a:32:68:f1..."
description:
- Fingerprints of CSR's public key.
- For every hash algorithm available, the fingerprint is computed.
returned: success
type: dict
sample: "{'sha256': 'd4:b3:aa:6d:c8:04:ce:4e:ba:f6:29:4d:92:a3:94:b0:c2:ff:bd:bf:33:63:11:43:34:0f:51:b0:95:09:2f:63', 'sha512':
'f7:07:4a:f0:b0:f0:e6:8b:95:5f:f9:e6:61:0a:32:68:f1..."
subject_key_identifier:
description:
- The CSR's subject key identifier.
- 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'
description:
- The CSR's subject key identifier.
- 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 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'
description:
- The CSR's authority key identifier.
- 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 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
sample: ["DNS:www.ansible.com", "IP:1.2.3.4"]
description:
- The CSR's authority cert issuer as a list of general names.
- 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
sample: ["DNS:www.ansible.com", "IP:1.2.3.4"]
authority_cert_serial_number:
description:
- The CSR's authority cert serial number.
- Is V(none) if the C(AuthorityKeyIdentifier) extension is not present.
- This return value is an B(integer). If you need the serial numbers as a colon-separated hex string,
such as C(11:22:33), you need to convert it to that form with P(community.crypto.to_serial#filter).
returned: success
type: int
sample: 12345
'''
description:
- The CSR's authority cert serial number.
- Is V(none) if the C(AuthorityKeyIdentifier) extension is not present.
- This return value is an B(integer). If you need the serial numbers as a colon-separated hex string, such as C(11:22:33),
you need to convert it to that form with P(community.crypto.to_serial#filter).
returned: success
type: int
sample: 12345
"""
from ansible.module_utils.basic import AnsibleModule

165
plugins/modules/openssl_csr_pipe.py
View File

@@ -10,49 +10,47 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = r'''
---
DOCUMENTATION = r"""
module: openssl_csr_pipe
short_description: Generate OpenSSL Certificate Signing Request (CSR)
version_added: 1.3.0
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."
- 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.
author:
- Yanis Guenane (@Spredzy)
- Felix Fontein (@felixfontein)
- Yanis Guenane (@Spredzy)
- Felix Fontein (@felixfontein)
extends_documentation_fragment:
- community.crypto.attributes
- community.crypto.module_csr
- community.crypto.attributes
- community.crypto.module_csr
attributes:
check_mode:
support: full
details:
- Currently in check mode, private keys will not be (re-)generated, only the changed status is
set. This will change in community.crypto 3.0.0.
- From community.crypto 3.0.0 on, the module will ignore check mode and always behave as if
check mode is not active. If you think this breaks your use-case of this module, please
create an issue in the community.crypto repository.
diff_mode:
support: full
check_mode:
support: full
details:
- Currently in check mode, private keys will not be (re-)generated, only the changed status is set. This will change
in community.crypto 3.0.0.
- From community.crypto 3.0.0 on, the module will ignore check mode and always behave as if check mode is not active.
If you think this breaks your use-case of this module, please create an issue in the community.crypto repository.
diff_mode:
support: full
options:
content:
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.
content:
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
'''
- module: community.crypto.openssl_csr
"""
EXAMPLES = r'''
EXAMPLES = r"""
- name: Generate an OpenSSL Certificate Signing Request
community.crypto.openssl_csr_pipe:
privatekey_path: /etc/ssl/private/ansible.com.pem
@@ -73,69 +71,68 @@ EXAMPLES = r'''
dest: /etc/ssl/csr/www.ansible.com.csr
content: "{{ result.csr }}"
when: result is changed
'''
"""
RETURN = r'''
RETURN = r"""
privatekey:
description:
- Path to the TLS/SSL private key the CSR was generated for
description:
- Path to the TLS/SSL private key the CSR was generated for.
- 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
returned: changed or success
type: str
sample: /etc/ssl/private/ansible.com.pem
subject:
description: A list of the subject tuples attached to the CSR
returned: changed or success
type: list
elements: list
sample: [['CN', 'www.ansible.com'], ['O', 'Ansible']]
description: A list of the subject tuples attached to the CSR.
returned: changed or success
type: list
elements: list
sample: [['CN', 'www.ansible.com'], ['O', 'Ansible']]
subjectAltName:
description: The alternative names this CSR is valid for
returned: changed or success
type: list
elements: str
sample: [ 'DNS:www.ansible.com', 'DNS:m.ansible.com' ]
description: The alternative names this CSR is valid for.
returned: changed or success
type: list
elements: str
sample: ['DNS:www.ansible.com', 'DNS:m.ansible.com']
keyUsage:
description: Purpose for which the public key may be used
returned: changed or success
type: list
elements: str
sample: [ 'digitalSignature', 'keyAgreement' ]
description: Purpose for which the public key may be used.
returned: changed or success
type: list
elements: str
sample: ['digitalSignature', 'keyAgreement']
extendedKeyUsage:
description: Additional restriction on the public key purposes
returned: changed or success
type: list
elements: str
sample: [ 'clientAuth' ]
description: Additional restriction on the public key purposes.
returned: changed or success
type: list
elements: str
sample: ['clientAuth']
basicConstraints:
description: Indicates if the certificate belongs to a CA
returned: changed or success
type: list
elements: str
sample: ['CA:TRUE', 'pathLenConstraint:0']
description: Indicates if the certificate belongs to a CA.
returned: changed or success
type: list
elements: str
sample: ['CA:TRUE', 'pathLenConstraint:0']
ocsp_must_staple:
description: Indicates whether the certificate has the OCSP
Must Staple feature enabled
returned: changed or success
type: bool
sample: false
description: Indicates whether the certificate has the OCSP Must Staple feature enabled.
returned: changed or success
type: bool
sample: false
name_constraints_permitted:
description: List of permitted subtrees to sign certificates for.
returned: changed or success
type: list
elements: str
sample: ['email:.somedomain.com']
description: List of permitted subtrees to sign certificates for.
returned: changed or success
type: list
elements: str
sample: ['email:.somedomain.com']
name_constraints_excluded:
description: List of excluded subtrees the CA cannot sign certificates for.
returned: changed or success
type: list
elements: str
sample: ['email:.com']
description: List of excluded subtrees the CA cannot sign certificates for.
returned: changed or success
type: list
elements: str
sample: ['email:.com']
csr:
description: The (current or generated) CSR's content.
returned: changed or success
type: str
'''
description: The (current or generated) CSR's content.
returned: changed or success
type: str
"""
from ansible.module_utils.common.text.converters import to_native

180
plugins/modules/openssl_dhparam.py
View File

@@ -9,89 +9,85 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = r'''
---
DOCUMENTATION = r"""
module: openssl_dhparam
short_description: Generate OpenSSL Diffie-Hellman Parameters
description:
- This module allows one to (re)generate OpenSSL DH-params.
- This module uses file common arguments to specify generated file permissions.
- "Please note that the module regenerates existing DH params if they do not
match the module's options. If you are concerned that this could overwrite
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 O(select_crypto_backend) option.
- This module allows one to (re)generate OpenSSL DH-params.
- This module uses file common arguments to specify generated file permissions.
- Please note that the module regenerates existing DH params if they do not match the module's options. If you are concerned
that this could overwrite 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 O(select_crypto_backend) option.
requirements:
- Either cryptography >= 2.0
- Or OpenSSL binary C(openssl)
- Either cryptography >= 2.0
- Or OpenSSL binary C(openssl)
author:
- Thom Wiggers (@thomwiggers)
- Thom Wiggers (@thomwiggers)
extends_documentation_fragment:
- ansible.builtin.files
- community.crypto.attributes
- community.crypto.attributes.files
- ansible.builtin.files
- community.crypto.attributes
- community.crypto.attributes.files
attributes:
check_mode:
support: full
diff_mode:
support: none
safe_file_operations:
support: full
check_mode:
support: full
diff_mode:
support: none
safe_file_operations:
support: full
options:
state:
description:
- Whether the parameters should exist or not,
taking action if the state is different from what is stated.
type: str
default: present
choices: [ absent, present ]
size:
description:
- Size (in bits) of the generated DH-params.
type: int
default: 4096
force:
description:
- Should the parameters be regenerated even it it already exists.
type: bool
default: false
path:
description:
- Name of the file in which the generated parameters will be saved.
type: path
required: true
backup:
description:
- Create a backup file including a timestamp so you can get the original
DH params back if you overwrote them with new ones by accident.
type: bool
default: false
select_crypto_backend:
description:
- Determines which crypto backend to use.
- 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 V(true), will return the (current or generated) DH parameter's content as RV(dhparams).
type: bool
default: false
version_added: "1.0.0"
state:
description:
- Whether the parameters should exist or not, taking action if the state is different from what is stated.
type: str
default: present
choices: [absent, present]
size:
description:
- Size (in bits) of the generated DH-params.
type: int
default: 4096
force:
description:
- Should the parameters be regenerated even it it already exists.
type: bool
default: false
path:
description:
- Name of the file in which the generated parameters will be saved.
type: path
required: true
backup:
description:
- Create a backup file including a timestamp so you can get the original DH params back if you overwrote them with new
ones by accident.
type: bool
default: false
select_crypto_backend:
description:
- Determines which crypto backend to use.
- 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 V(true), will return the (current or generated) DH parameter's content as RV(dhparams).
type: bool
default: false
version_added: "1.0.0"
seealso:
- module: community.crypto.x509_certificate
- module: community.crypto.openssl_csr
- module: community.crypto.openssl_pkcs12
- module: community.crypto.openssl_privatekey
- module: community.crypto.openssl_publickey
'''
- module: community.crypto.x509_certificate
- module: community.crypto.openssl_csr
- module: community.crypto.openssl_pkcs12
- module: community.crypto.openssl_privatekey
- module: community.crypto.openssl_publickey
"""
EXAMPLES = r'''
EXAMPLES = r"""
- name: Generate Diffie-Hellman parameters with the default size (4096 bits)
community.crypto.openssl_dhparam:
path: /etc/ssl/dhparams.pem
@@ -105,30 +101,30 @@ EXAMPLES = r'''
community.crypto.openssl_dhparam:
path: /etc/ssl/dhparams.pem
force: true
'''
"""
RETURN = r'''
RETURN = r"""
size:
description: Size (in bits) of the Diffie-Hellman parameters.
returned: changed or success
type: int
sample: 4096
description: Size (in bits) of the Diffie-Hellman parameters.
returned: changed or success
type: int
sample: 4096
filename:
description: Path to the generated Diffie-Hellman parameters.
returned: changed or success
type: str
sample: /etc/ssl/dhparams.pem
description: Path to the generated Diffie-Hellman parameters.
returned: changed or success
type: str
sample: /etc/ssl/dhparams.pem
backup_file:
description: Name of backup file created.
returned: changed and if O(backup) is V(true)
type: str
sample: /path/to/dhparams.pem.2019-03-09@11:22~
description: Name of backup file created.
returned: changed and if O(backup) is V(true)
type: str
sample: /path/to/dhparams.pem.2019-03-09@11:22~
dhparams:
description: The (current or generated) DH params' content.
returned: if O(state) is V(present) and O(return_content) is V(true)
type: str
version_added: "1.0.0"
'''
description: The (current or generated) DH params' content.
returned: if O(state) is V(present) and O(return_content) is V(true)
type: str
version_added: "1.0.0"
"""
import abc
import os

358
plugins/modules/openssl_pkcs12.py
View File

@@ -9,173 +9,163 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = r'''
---
DOCUMENTATION = r"""
module: openssl_pkcs12
author:
- Guillaume Delpierre (@gdelpierre)
- Guillaume Delpierre (@gdelpierre)
short_description: Generate OpenSSL PKCS#12 archive
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
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.
- 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 O(iter_size) and O(maciter_size) options are used. This can be overridden with
the O(select_crypto_backend) option.
requirements:
- PyOpenSSL >= 0.15, < 23.3.0 or cryptography >= 3.0
- PyOpenSSL >= 0.15, < 23.3.0 or cryptography >= 3.0
extends_documentation_fragment:
- ansible.builtin.files
- community.crypto.attributes
- community.crypto.attributes.files
- ansible.builtin.files
- community.crypto.attributes
- community.crypto.attributes.files
attributes:
check_mode:
support: full
diff_mode:
support: none
safe_file_operations:
support: full
check_mode:
support: full
diff_mode:
support: none
safe_file_operations:
support: full
options:
action:
description:
- 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 O(ca_certificates).
- Assumes there is one PEM-encoded certificate per file. If a file contains multiple PEM certificates,
set O(other_certificates_parse_all) to V(true).
type: list
elements: path
aliases: [ ca_certificates ]
other_certificates_parse_all:
description:
- 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
version_added: 1.4.0
certificate_path:
description:
- The path to read certificates and private keys from.
- Must be in PEM format.
type: path
force:
description:
- Should the file be regenerated even if it already exists.
type: bool
default: false
friendly_name:
description:
- Specifies the friendly name for the certificate and private key.
type: str
aliases: [ name ]
iter_size:
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 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 V(1).
type: int
encryption_level:
description:
- Determines the encryption level used.
- 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.
- 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:
- auto
- compatibility2022
default: auto
type: str
version_added: 2.8.0
passphrase:
description:
- The PKCS#12 password.
- "B(Note:) PKCS12 encryption is typically not secure and should not be used as a security mechanism.
If you need to store or send a PKCS12 file safely, you should additionally encrypt it
with something else.
(L(Source,
https://cryptography.io/en/latest/hazmat/primitives/asymmetric/serialization/#cryptography.hazmat.primitives.serialization.pkcs12.serialize_key_and_certificates).)"
type: str
path:
description:
- Filename to write the PKCS#12 file to.
type: path
required: true
privatekey_passphrase:
description:
- Passphrase source to decrypt any input private keys with.
type: str
privatekey_path:
description:
- File to read private key from.
- Mutually exclusive with O(privatekey_content).
type: path
privatekey_content:
description:
- Content of the private key file.
- 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 O(path) are ignored when state is V(absent).
choices: [ absent, present ]
default: present
type: str
src:
description:
- PKCS#12 file path to parse.
type: path
backup:
description:
- Create a backup file including a timestamp so you can get the original
output file back if you overwrote it with a new one by accident.
type: bool
default: false
return_content:
description:
- If set to V(true), will return the (current or generated) 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 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.
type: str
default: auto
choices: [ auto, cryptography, pyopenssl ]
version_added: 1.7.0
action:
description:
- 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 O(ca_certificates).
- Assumes there is one PEM-encoded certificate per file. If a file contains multiple PEM certificates, set O(other_certificates_parse_all)
to V(true).
type: list
elements: path
aliases: [ca_certificates]
other_certificates_parse_all:
description:
- 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
version_added: 1.4.0
certificate_path:
description:
- The path to read certificates and private keys from.
- Must be in PEM format.
type: path
force:
description:
- Should the file be regenerated even if it already exists.
type: bool
default: false
friendly_name:
description:
- Specifies the friendly name for the certificate and private key.
type: str
aliases: [name]
iter_size:
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 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 V(1).
type: int
encryption_level:
description:
- Determines the encryption level used.
- 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.
- 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:
- auto
- compatibility2022
default: auto
type: str
version_added: 2.8.0
passphrase:
description:
- The PKCS#12 password.
- B(Note:) PKCS12 encryption is typically not secure and should not be used as a security mechanism. If you need to
store or send a PKCS12 file safely, you should additionally encrypt it with something else. (L(Source,
https://cryptography.io/en/latest/hazmat/primitives/asymmetric/serialization/#cryptography.hazmat.primitives.serialization.pkcs12.serialize_key_and_certificates)).
type: str
path:
description:
- Filename to write the PKCS#12 file to.
type: path
required: true
privatekey_passphrase:
description:
- Passphrase source to decrypt any input private keys with.
type: str
privatekey_path:
description:
- File to read private key from.
- Mutually exclusive with O(privatekey_content).
type: path
privatekey_content:
description:
- Content of the private key file.
- 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 O(path) are ignored when state is V(absent).
choices: [absent, present]
default: present
type: str
src:
description:
- PKCS#12 file path to parse.
type: path
backup:
description:
- Create a backup file including a timestamp so you can get the original output file back if you overwrote it with a
new one by accident.
type: bool
default: false
return_content:
description:
- If set to V(true), will return the (current or generated) 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 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.
type: str
default: auto
choices: [auto, cryptography, pyopenssl]
version_added: 1.7.0
seealso:
- module: community.crypto.x509_certificate
- module: community.crypto.openssl_csr
- module: community.crypto.openssl_dhparam
- module: community.crypto.openssl_privatekey
- module: community.crypto.openssl_publickey
'''
- module: community.crypto.x509_certificate
- module: community.crypto.openssl_csr
- module: community.crypto.openssl_dhparam
- module: community.crypto.openssl_privatekey
- module: community.crypto.openssl_publickey
"""
EXAMPLES = r'''
EXAMPLES = r"""
- name: Generate PKCS#12 file
community.crypto.openssl_pkcs12:
action: export
@@ -184,9 +174,9 @@ EXAMPLES = r'''
privatekey_path: /opt/certs/keys/key.pem
certificate_path: /opt/certs/cert.pem
other_certificates: /opt/certs/ca.pem
# Note that if /opt/certs/ca.pem contains multiple certificates,
# only the first one will be used. See the other_certificates_parse_all
# option for changing this behavior.
# Note that if /opt/certs/ca.pem contains multiple certificates,
# only the first one will be used. See the other_certificates_parse_all
# option for changing this behavior.
state: present
- name: Generate PKCS#12 file
@@ -199,12 +189,12 @@ EXAMPLES = r'''
other_certificates_parse_all: true
other_certificates:
- /opt/certs/ca_bundle.pem
# Since we set other_certificates_parse_all to true, all
# certificates in the CA bundle are included and not just
# the first one.
# Since we set other_certificates_parse_all to true, all
# certificates in the CA bundle are included and not just
# the first one.
- /opt/certs/intermediate.pem
# In case this file has multiple certificates in it,
# all will be included as well.
# In case this file has multiple certificates in it,
# all will be included as well.
state: present
- name: Change PKCS#12 file permission
@@ -242,30 +232,30 @@ EXAMPLES = r'''
community.crypto.openssl_pkcs12:
path: /opt/certs/ansible.p12
state: absent
'''
"""
RETURN = r'''
RETURN = r"""
filename:
description: Path to the generate PKCS#12 file.
returned: changed or success
type: str
sample: /opt/certs/ansible.p12
description: Path to the generate PKCS#12 file.
returned: changed or success
type: str
sample: /opt/certs/ansible.p12
privatekey:
description: Path to the TLS/SSL private key the public key was generated from.
returned: changed or success
type: str
sample: /etc/ssl/private/ansible.com.pem
description: Path to the TLS/SSL private key the public key was generated from.
returned: changed or success
type: str
sample: /etc/ssl/private/ansible.com.pem
backup_file:
description: Name of backup file created.
returned: changed and if O(backup) is V(true)
type: str
sample: /path/to/ansible.com.pem.2019-03-09@11:22~
description: Name of backup file created.
returned: changed and if O(backup) is V(true)
type: str
sample: /path/to/ansible.com.pem.2019-03-09@11:22~
pkcs12:
description: The (current or generated) PKCS#12's content Base64 encoded.
returned: if O(state) is V(present) and O(return_content) is V(true)
type: str
version_added: "1.0.0"
'''
description: The (current or generated) PKCS#12's content Base64 encoded.
returned: if O(state) is V(present) and O(return_content) is V(true)
type: str
version_added: "1.0.0"
"""
import abc
import base64

203
plugins/modules/openssl_privatekey.py
View File

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

71
plugins/modules/openssl_privatekey_convert.py
View File

@@ -9,60 +9,59 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = r'''
---
DOCUMENTATION = r"""
module: openssl_privatekey_convert
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 V(0600) if O(mode) is not explicitly set.
- This module allows one to convert OpenSSL private keys.
- The default mode for the private key file will be V(0600) if O(mode) is not explicitly set.
author:
- Felix Fontein (@felixfontein)
- Felix Fontein (@felixfontein)
extends_documentation_fragment:
- ansible.builtin.files
- community.crypto.attributes
- community.crypto.attributes.files
- community.crypto.module_privatekey_convert
- ansible.builtin.files
- community.crypto.attributes
- community.crypto.attributes.files
- community.crypto.module_privatekey_convert
attributes:
check_mode:
support: full
diff_mode:
support: none
safe_file_operations:
support: full
check_mode:
support: full
diff_mode:
support: none
safe_file_operations:
support: full
options:
dest_path:
description:
- Name of the file in which the generated TLS/SSL private key will be written. It will have V(0600) mode
if O(mode) is not explicitly set.
type: path
required: true
backup:
description:
- Create a backup file including a timestamp so you can get
the original private key back if you overwrote it with a new one by accident.
type: bool
default: false
dest_path:
description:
- Name of the file in which the generated TLS/SSL private key will be written. It will have V(0600) mode if O(mode)
is not explicitly set.
type: path
required: true
backup:
description:
- Create a backup file including a timestamp so you can get the original private key back if you overwrote it with a
new one by accident.
type: bool
default: false
seealso: []
'''
"""
EXAMPLES = r'''
EXAMPLES = r"""
- name: Convert private key to PKCS8 format with passphrase
community.crypto.openssl_privatekey_convert:
src_path: /etc/ssl/private/ansible.com.pem
dest_path: /etc/ssl/private/ansible.com.key
dest_passphrase: '{{ private_key_passphrase }}'
format: pkcs8
'''
"""
RETURN = r'''
RETURN = r"""
backup_file:
description: Name of backup file created.
returned: changed and if O(backup) is V(true)
type: str
sample: /path/to/privatekey.pem.2019-03-09@11:22~
'''
description: Name of backup file created.
returned: changed and if O(backup) is V(true)
type: str
sample: /path/to/privatekey.pem.2019-03-09@11:22~
"""
import os

317
plugins/modules/openssl_privatekey_info.py
View File

@@ -10,81 +10,76 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = r'''
---
DOCUMENTATION = r"""
module: openssl_privatekey_info
short_description: Provide information for OpenSSL private keys
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, V(none) is returned for
RV(key_is_consistent).
- It uses the cryptography python library to interact with OpenSSL.
- 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,
V(none) is returned for RV(key_is_consistent).
- It uses the cryptography python library to interact with OpenSSL.
requirements:
- cryptography >= 1.2.3
- cryptography >= 1.2.3
author:
- Felix Fontein (@felixfontein)
- Yanis Guenane (@Spredzy)
- Felix Fontein (@felixfontein)
- Yanis Guenane (@Spredzy)
extends_documentation_fragment:
- community.crypto.attributes
- community.crypto.attributes.info_module
- community.crypto.attributes
- community.crypto.attributes.info_module
options:
path:
description:
- Remote absolute path where the private key file is loaded from.
type: path
content:
description:
- Content of the private key file.
- Either O(path) or O(content) must be specified, but not both.
type: str
version_added: '1.0.0'
passphrase:
description:
- The passphrase for the private key.
type: str
return_private_key_data:
description:
- Whether to return private key data.
- 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
default: false
check_consistency:
description:
- Whether to check consistency of the private key.
- In community.crypto < 2.0.0, consistency was always checked.
- Since community.crypto 2.0.0, the consistency check has been disabled by default to
avoid private key material to be transported around and computed with, and only do
so when requested explicitly. This can potentially prevent
L(side-channel attacks,https://en.wikipedia.org/wiki/Side-channel_attack).
- Note that consistency checks only work for certain key types, and might depend on the
version of the cryptography library. For example, with cryptography 42.0.0 and newer
consistency of RSA keys can no longer be checked.
type: bool
default: false
version_added: 2.0.0
path:
description:
- Remote absolute path where the private key file is loaded from.
type: path
content:
description:
- Content of the private key file.
- Either O(path) or O(content) must be specified, but not both.
type: str
version_added: '1.0.0'
passphrase:
description:
- The passphrase for the private key.
type: str
return_private_key_data:
description:
- Whether to return private key data.
- 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
default: false
check_consistency:
description:
- Whether to check consistency of the private key.
- In community.crypto < 2.0.0, consistency was always checked.
- Since community.crypto 2.0.0, the consistency check has been disabled by default to avoid private key material to
be transported around and computed with, and only do so when requested explicitly. This can potentially prevent L(side-channel
attacks,https://en.wikipedia.org/wiki/Side-channel_attack).
- Note that consistency checks only work for certain key types, and might depend on the version of the cryptography
library. For example, with cryptography 42.0.0 and newer consistency of RSA keys can no longer be checked.
type: bool
default: false
version_added: 2.0.0
select_crypto_backend:
description:
- Determines which crypto backend to use.
- The default choice is V(auto), which tries to use C(cryptography) if available.
- If set to V(cryptography), will try to use the L(cryptography,https://cryptography.io/) library.
type: str
default: auto
choices: [ auto, cryptography ]
select_crypto_backend:
description:
- Determines which crypto backend to use.
- The default choice is V(auto), which tries to use C(cryptography) if available.
- If set to V(cryptography), will try to use the L(cryptography,https://cryptography.io/) library.
type: str
default: auto
choices: [auto, cryptography]
seealso:
- module: community.crypto.openssl_privatekey
- module: community.crypto.openssl_privatekey_pipe
- plugin: community.crypto.openssl_privatekey_info
plugin_type: filter
description: A filter variant of this module.
'''
- module: community.crypto.openssl_privatekey
- module: community.crypto.openssl_privatekey_pipe
- plugin: community.crypto.openssl_privatekey_info
plugin_type: filter
description: A filter variant of this module.
"""
EXAMPLES = r'''
EXAMPLES = r"""
- name: Generate an OpenSSL private key with the default values (4096 bits, RSA)
community.crypto.openssl_privatekey:
path: /etc/ssl/private/ansible.com.pem
@@ -97,112 +92,112 @@ EXAMPLES = r'''
- name: Dump information
ansible.builtin.debug:
var: result
'''
"""
RETURN = r'''
RETURN = r"""
can_load_key:
description: Whether the module was able to load the private key from disk.
returned: always
type: bool
description: Whether the module was able to load the private key from disk.
returned: always
type: bool
can_parse_key:
description: Whether the module was able to parse the private key.
returned: always
type: bool
description: Whether the module was able to parse the private key.
returned: always
type: bool
key_is_consistent:
description:
- Whether the key is consistent. Can also return 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
description:
- 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.
returned: success
type: str
sample: "-----BEGIN PUBLIC KEY-----\nMIICIjANBgkqhkiG9w0BAQEFAAOCAg8A..."
description: Private key's public key in PEM format.
returned: success
type: str
sample: "-----BEGIN PUBLIC KEY-----\nMIICIjANBgkqhkiG9w0BAQEFAAOCAg8A..."
public_key_fingerprints:
description:
- Fingerprints of private key's public key.
- For every hash algorithm available, the fingerprint is computed.
returned: success
type: dict
sample: "{'sha256': 'd4:b3:aa:6d:c8:04:ce:4e:ba:f6:29:4d:92:a3:94:b0:c2:ff:bd:bf:33:63:11:43:34:0f:51:b0:95:09:2f:63',
'sha512': 'f7:07:4a:f0:b0:f0:e6:8b:95:5f:f9:e6:61:0a:32:68:f1..."
description:
- Fingerprints of private key's public key.
- For every hash algorithm available, the fingerprint is computed.
returned: success
type: dict
sample: "{'sha256': 'd4:b3:aa:6d:c8:04:ce:4e:ba:f6:29:4d:92:a3:94:b0:c2:ff:bd:bf:33:63:11:43:34:0f:51:b0:95:09:2f:63', 'sha512':
'f7:07:4a:f0:b0:f0:e6:8b:95:5f:f9:e6:61:0a:32:68:f1..."
type:
description:
- The key's type.
- 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
description:
- The key's type.
- 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
public_data:
description:
- Public key data. Depends on key type.
returned: success
type: dict
contains:
size:
description:
- Bit size of modulus (RSA) or prime number (DSA).
type: int
returned: When RV(type=RSA) or RV(type=DSA)
modulus:
description:
- The RSA key's modulus.
type: int
returned: When RV(type=RSA)
exponent:
description:
- The RSA key's public exponent.
type: int
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 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 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 RV(type=DSA)
curve:
description:
- The curve's name for ECC.
type: str
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 RV(type=ECC)
x:
description:
- The C(x) coordinate for the public point on the elliptic curve.
type: int
returned: When RV(type=ECC)
y:
description:
- 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 RV(type=DSA) or RV(type=ECC)
description:
- Public key data. Depends on key type.
returned: success
type: dict
contains:
size:
description:
- Bit size of modulus (RSA) or prime number (DSA).
type: int
returned: When RV(type=RSA) or RV(type=DSA)
modulus:
description:
- The RSA key's modulus.
type: int
returned: When RV(type=RSA)
exponent:
description:
- The RSA key's public exponent.
type: int
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 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 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 RV(type=DSA)
curve:
description:
- The curve's name for ECC.
type: str
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 RV(type=ECC)
x:
description:
- The C(x) coordinate for the public point on the elliptic curve.
type: int
returned: When RV(type=ECC)
y:
description:
- 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 RV(type=DSA) or RV(type=ECC)
private_data:
description:
- Private key data. Depends on key type.
returned: success and when O(return_private_key_data) is set to V(true)
type: dict
'''
description:
- Private key data. Depends on key type.
returned: success and when O(return_private_key_data) is set to V(true)
type: dict
"""
from ansible.module_utils.basic import AnsibleModule

210
plugins/modules/openssl_privatekey_pipe.py
View File

@@ -9,93 +9,89 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = r'''
---
DOCUMENTATION = r"""
module: openssl_privatekey_pipe
short_description: Generate OpenSSL private keys without disk access
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 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.
- 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
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:
- Yanis Guenane (@Spredzy)
- Felix Fontein (@felixfontein)
- Yanis Guenane (@Spredzy)
- Felix Fontein (@felixfontein)
extends_documentation_fragment:
- community.crypto.attributes
- community.crypto.attributes.flow
- community.crypto.module_privatekey
- community.crypto.attributes
- community.crypto.attributes.flow
- community.crypto.module_privatekey
attributes:
action:
support: full
async:
support: none
details:
- This action runs completely on the controller.
check_mode:
support: full
details:
- Currently in check mode, private keys will not be (re-)generated, only the changed status is
set. This will change in community.crypto 3.0.0.
- From community.crypto 3.0.0 on, the module will ignore check mode and always behave as if
check mode is not active. If you think this breaks your use-case of this module, please
create an issue in the community.crypto repository.
diff_mode:
support: full
action:
support: full
async:
support: none
details:
- This action runs completely on the controller.
check_mode:
support: full
details:
- Currently in check mode, private keys will not be (re-)generated, only the changed status is set. This will change
in community.crypto 3.0.0.
- From community.crypto 3.0.0 on, the module will ignore check mode and always behave as if check mode is not active.
If you think this breaks your use-case of this module, please create an issue in the community.crypto repository.
diff_mode:
support: full
options:
content:
description:
- The current private key data.
- Needed for idempotency. If not provided, the module will always return a change, and all idempotence-related
options are ignored.
type: str
content_base64:
description:
- Set to V(true) if the content is base64 encoded.
type: bool
default: false
return_current_key:
description:
- 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).
content:
description:
- The current private key data.
- Needed for idempotency. If not provided, the module will always return a change, and all idempotence-related options
are ignored.
type: str
content_base64:
description:
- Set to V(true) if the content is base64 encoded.
type: bool
default: false
return_current_key:
description:
- 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
'''
- module: community.crypto.openssl_privatekey
- module: community.crypto.openssl_privatekey_info
"""
EXAMPLES = r'''
EXAMPLES = r"""
- name: Generate an OpenSSL private key with the default values (4096 bits, RSA)
community.crypto.openssl_privatekey_pipe:
register: output
no_log: true # make sure that private key data is not accidentally revealed in logs!
no_log: true # make sure that private key data is not accidentally revealed in logs!
- name: Show generated key
ansible.builtin.debug:
msg: "{{ output.privatekey }}"
@@ -113,7 +109,7 @@ EXAMPLES = r'''
content: "{{ lookup('community.sops.sops', 'private_key.pem.sops') }}"
size: 2048
register: output
no_log: true # make sure that private key data is not accidentally revealed in logs!
no_log: true # make sure that private key data is not accidentally revealed in logs!
- name: Update encrypted key when openssl_privatekey_pipe reported a change
community.sops.sops_encrypt:
@@ -124,42 +120,42 @@ EXAMPLES = r'''
- name: Make sure that output (which contains the private key) is overwritten
ansible.builtin.set_fact:
output: ''
'''
"""
RETURN = r'''
RETURN = r"""
size:
description: Size (in bits) of the TLS/SSL private key.
returned: changed or success
type: int
sample: 4096
description: Size (in bits) of the TLS/SSL private key.
returned: changed or success
type: int
sample: 4096
type:
description: Algorithm used to generate the TLS/SSL private key.
returned: changed or success
type: str
sample: RSA
description: Algorithm used to generate the TLS/SSL private key.
returned: changed or success
type: str
sample: RSA
curve:
description: Elliptic curve used to generate the TLS/SSL private key.
returned: changed or success, and O(type) is V(ECC)
type: str
sample: secp256r1
description: Elliptic curve used to generate the TLS/SSL private key.
returned: changed or success, and O(type) is V(ECC)
type: str
sample: secp256r1
fingerprint:
description:
description:
- The fingerprint of the public key. Fingerprint will be generated for each C(hashlib.algorithms) available.
returned: changed or success
type: dict
sample:
md5: "84:75:71:72:8d:04:b5:6c:4d:37:6d:66:83:f5:4c:29"
sha1: "51:cc:7c:68:5d:eb:41:43:88:7e:1a:ae:c7:f8:24:72:ee:71:f6:10"
sha224: "b1:19:a6:6c:14:ac:33:1d:ed:18:50:d3:06:5c:b2:32:91:f1:f1:52:8c:cb:d5:75:e9:f5:9b:46"
sha256: "41:ab:c7:cb:d5:5f:30:60:46:99:ac:d4:00:70:cf:a1:76:4f:24:5d:10:24:57:5d:51:6e:09:97:df:2f:de:c7"
sha384: "85:39:50:4e:de:d9:19:33:40:70:ae:10:ab:59:24:19:51:c3:a2:e4:0b:1c:b1:6e:dd:b3:0c:d9:9e:6a:46:af:da:18:f8:ef:ae:2e:c0:9a:75:2c:9b:b3:0f:3a:5f:3d"
sha512: "fd:ed:5e:39:48:5f:9f:fe:7f:25:06:3f:79:08:cd:ee:a5:e7:b3:3d:13:82:87:1f:84:e1:f5:c7:28:77:53:94:86:56:38:69:f0:d9:35:22:01:1e:a6:60:...:0f:9b"
returned: changed or success
type: dict
sample:
md5: "84:75:71:72:8d:04:b5:6c:4d:37:6d:66:83:f5:4c:29"
sha1: "51:cc:7c:68:5d:eb:41:43:88:7e:1a:ae:c7:f8:24:72:ee:71:f6:10"
sha224: "b1:19:a6:6c:14:ac:33:1d:ed:18:50:d3:06:5c:b2:32:91:f1:f1:52:8c:cb:d5:75:e9:f5:9b:46"
sha256: "41:ab:c7:cb:d5:5f:30:60:46:99:ac:d4:00:70:cf:a1:76:4f:24:5d:10:24:57:5d:51:6e:09:97:df:2f:de:c7"
sha384: "85:39:50:4e:de:d9:19:33:40:70:ae:10:ab:59:24:19:51:c3:a2:e4:0b:1c:b1:6e:dd:b3:0c:d9:9e:6a:46:af:da:18:f8:ef:ae:2e:c0:9a:75:2c:9b:b3:0f:3a:5f:3d"
sha512: "fd:ed:5e:39:48:5f:9f:fe:7f:25:06:3f:79:08:cd:ee:a5:e7:b3:3d:13:82:87:1f:84:e1:f5:c7:28:77:53:94:86:56:38:69:f0:d9:35:22:01:1e:a6:60:...:0f:9b"
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 O(return_current_key) option is set to V(true).
- Will be Base64-encoded if the key is in raw format.
returned: changed, or O(return_current_key) is V(true)
type: str
'''
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 O(return_current_key)
option is set to V(true).
- Will be Base64-encoded if the key is in raw format.
returned: changed, or O(return_current_key) is V(true)
type: str
"""

243
plugins/modules/openssl_publickey.py
View File

@@ -9,104 +9,103 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = r'''
---
DOCUMENTATION = r"""
module: openssl_publickey
short_description: Generate an OpenSSL public key from its private key.
short_description: Generate an OpenSSL public key from its private key
description:
- This module allows one to (re)generate public keys from their private keys.
- Public keys are generated in PEM or OpenSSH format. Private keys must be OpenSSL PEM keys.
B(OpenSSH private keys are not supported), use the M(community.crypto.openssh_keypair) module to manage these.
- The module uses the cryptography Python library.
- This module allows one to (re)generate public keys from their private keys.
- Public keys are generated in PEM or OpenSSH format. Private keys must be OpenSSL PEM keys. B(OpenSSH private keys are
not supported), use the M(community.crypto.openssh_keypair) module to manage these.
- The module uses the cryptography Python library.
requirements:
- cryptography >= 1.2.3 (older versions might work as well)
- Needs cryptography >= 1.4 if O(format) is C(OpenSSH)
- cryptography >= 1.2.3 (older versions might work as well)
- Needs cryptography >= 1.4 if O(format) is C(OpenSSH)
author:
- Yanis Guenane (@Spredzy)
- Felix Fontein (@felixfontein)
- Yanis Guenane (@Spredzy)
- Felix Fontein (@felixfontein)
extends_documentation_fragment:
- ansible.builtin.files
- community.crypto.attributes
- community.crypto.attributes.files
- ansible.builtin.files
- community.crypto.attributes
- community.crypto.attributes.files
attributes:
check_mode:
support: full
diff_mode:
support: full
safe_file_operations:
support: full
check_mode:
support: full
diff_mode:
support: full
safe_file_operations:
support: full
options:
state:
description:
- Whether the public key should exist or not, taking action if the state is different from what is stated.
type: str
default: present
choices: [ absent, present ]
force:
description:
- Should the key be regenerated even it it already exists.
type: bool
default: false
format:
description:
- The format of the public key.
type: str
default: PEM
choices: [ OpenSSH, PEM ]
path:
description:
- Name of the file in which the generated TLS/SSL public key will be written.
type: path
required: true
privatekey_path:
description:
- Path to the TLS/SSL private key from which to generate the public key.
- 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 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:
description:
- The passphrase for the private key.
type: str
backup:
description:
- Create a backup file including a timestamp so you can get the original
public key back if you overwrote it with a different one by accident.
type: bool
default: false
select_crypto_backend:
description:
- Determines which crypto backend to use.
- The default choice is V(auto), which tries to use C(cryptography) if available.
- If set to V(cryptography), will try to use the L(cryptography,https://cryptography.io/) library.
type: str
default: auto
choices: [ auto, cryptography ]
return_content:
description:
- 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'
state:
description:
- Whether the public key should exist or not, taking action if the state is different from what is stated.
type: str
default: present
choices: [absent, present]
force:
description:
- Should the key be regenerated even it it already exists.
type: bool
default: false
format:
description:
- The format of the public key.
type: str
default: PEM
choices: [OpenSSH, PEM]
path:
description:
- Name of the file in which the generated TLS/SSL public key will be written.
type: path
required: true
privatekey_path:
description:
- Path to the TLS/SSL private key from which to generate the public key.
- 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 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:
description:
- The passphrase for the private key.
type: str
backup:
description:
- Create a backup file including a timestamp so you can get the original public key back if you overwrote it with a
different one by accident.
type: bool
default: false
select_crypto_backend:
description:
- Determines which crypto backend to use.
- The default choice is V(auto), which tries to use C(cryptography) if available.
- If set to V(cryptography), will try to use the L(cryptography,https://cryptography.io/) library.
type: str
default: auto
choices: [auto, cryptography]
return_content:
description:
- 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'
seealso:
- module: community.crypto.x509_certificate
- module: community.crypto.x509_certificate_pipe
- module: community.crypto.openssl_csr
- module: community.crypto.openssl_csr_pipe
- module: community.crypto.openssl_dhparam
- module: community.crypto.openssl_pkcs12
- module: community.crypto.openssl_privatekey
- module: community.crypto.openssl_privatekey_pipe
'''
- module: community.crypto.x509_certificate
- module: community.crypto.x509_certificate_pipe
- module: community.crypto.openssl_csr
- module: community.crypto.openssl_csr_pipe
- module: community.crypto.openssl_dhparam
- module: community.crypto.openssl_pkcs12
- module: community.crypto.openssl_privatekey
- module: community.crypto.openssl_privatekey_pipe
"""
EXAMPLES = r'''
EXAMPLES = r"""
- name: Generate an OpenSSL public key in PEM format
community.crypto.openssl_publickey:
path: /etc/ssl/public/ansible.com.pem
@@ -139,49 +138,49 @@ EXAMPLES = r'''
community.crypto.openssl_publickey:
path: /etc/ssl/public/ansible.com.pem
state: absent
'''
"""
RETURN = r'''
RETURN = r"""
privatekey:
description:
description:
- Path to the TLS/SSL private key the public key was generated from.
- 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
returned: changed or success
type: str
sample: /etc/ssl/private/ansible.com.pem
format:
description: The format of the public key (PEM, OpenSSH, ...).
returned: changed or success
type: str
sample: PEM
description: The format of the public key (PEM, OpenSSH, ...).
returned: changed or success
type: str
sample: PEM
filename:
description: Path to the generated TLS/SSL public key file.
returned: changed or success
type: str
sample: /etc/ssl/public/ansible.com.pem
description: Path to the generated TLS/SSL public key file.
returned: changed or success
type: str
sample: /etc/ssl/public/ansible.com.pem
fingerprint:
description:
description:
- The fingerprint of the public key. Fingerprint will be generated for each hashlib.algorithms available.
returned: changed or success
type: dict
sample:
md5: "84:75:71:72:8d:04:b5:6c:4d:37:6d:66:83:f5:4c:29"
sha1: "51:cc:7c:68:5d:eb:41:43:88:7e:1a:ae:c7:f8:24:72:ee:71:f6:10"
sha224: "b1:19:a6:6c:14:ac:33:1d:ed:18:50:d3:06:5c:b2:32:91:f1:f1:52:8c:cb:d5:75:e9:f5:9b:46"
sha256: "41:ab:c7:cb:d5:5f:30:60:46:99:ac:d4:00:70:cf:a1:76:4f:24:5d:10:24:57:5d:51:6e:09:97:df:2f:de:c7"
sha384: "85:39:50:4e:de:d9:19:33:40:70:ae:10:ab:59:24:19:51:c3:a2:e4:0b:1c:b1:6e:dd:b3:0c:d9:9e:6a:46:af:da:18:f8:ef:ae:2e:c0:9a:75:2c:9b:b3:0f:3a:5f:3d"
sha512: "fd:ed:5e:39:48:5f:9f:fe:7f:25:06:3f:79:08:cd:ee:a5:e7:b3:3d:13:82:87:1f:84:e1:f5:c7:28:77:53:94:86:56:38:69:f0:d9:35:22:01:1e:a6:60:...:0f:9b"
returned: changed or success
type: dict
sample:
md5: "84:75:71:72:8d:04:b5:6c:4d:37:6d:66:83:f5:4c:29"
sha1: "51:cc:7c:68:5d:eb:41:43:88:7e:1a:ae:c7:f8:24:72:ee:71:f6:10"
sha224: "b1:19:a6:6c:14:ac:33:1d:ed:18:50:d3:06:5c:b2:32:91:f1:f1:52:8c:cb:d5:75:e9:f5:9b:46"
sha256: "41:ab:c7:cb:d5:5f:30:60:46:99:ac:d4:00:70:cf:a1:76:4f:24:5d:10:24:57:5d:51:6e:09:97:df:2f:de:c7"
sha384: "85:39:50:4e:de:d9:19:33:40:70:ae:10:ab:59:24:19:51:c3:a2:e4:0b:1c:b1:6e:dd:b3:0c:d9:9e:6a:46:af:da:18:f8:ef:ae:2e:c0:9a:75:2c:9b:b3:0f:3a:5f:3d"
sha512: "fd:ed:5e:39:48:5f:9f:fe:7f:25:06:3f:79:08:cd:ee:a5:e7:b3:3d:13:82:87:1f:84:e1:f5:c7:28:77:53:94:86:56:38:69:f0:d9:35:22:01:1e:a6:60:...:0f:9b"
backup_file:
description: Name of backup file created.
returned: changed and if O(backup) is V(true)
type: str
sample: /path/to/publickey.pem.2019-03-09@11:22~
description: Name of backup file created.
returned: changed and if O(backup) is V(true)
type: str
sample: /path/to/publickey.pem.2019-03-09@11:22~
publickey:
description: The (current or generated) public key's content.
returned: if O(state) is V(present) and O(return_content) is V(true)
type: str
version_added: '1.0.0'
'''
description: The (current or generated) public key's content.
returned: if O(state) is V(present) and O(return_content) is V(true)
type: str
version_added: '1.0.0'
"""
import os
import traceback

217
plugins/modules/openssl_publickey_info.py
View File

@@ -9,50 +9,49 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = r'''
---
DOCUMENTATION = r"""
module: openssl_publickey_info
short_description: Provide information for OpenSSL public keys
description:
- This module allows one to query information on OpenSSL public keys.
- It uses the cryptography python library to interact with OpenSSL.
- This module allows one to query information on OpenSSL public keys.
- It uses the cryptography python library to interact with OpenSSL.
version_added: 1.7.0
requirements:
- cryptography >= 1.2.3
- cryptography >= 1.2.3
author:
- Felix Fontein (@felixfontein)
- Felix Fontein (@felixfontein)
extends_documentation_fragment:
- community.crypto.attributes
- community.crypto.attributes.info_module
- community.crypto.attributes
- community.crypto.attributes.info_module
options:
path:
description:
- Remote absolute path where the public key file is loaded from.
type: path
content:
description:
- Content of the public key file.
- Either O(path) or O(content) must be specified, but not both.
type: str
path:
description:
- Remote absolute path where the public key file is loaded from.
type: path
content:
description:
- Content of the public key file.
- 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 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 ]
select_crypto_backend:
description:
- Determines which crypto backend to use.
- The default choice is V(auto), which tries to use C(cryptography) if available.
- If set to V(cryptography), will try to use the L(cryptography,https://cryptography.io/) library.
type: str
default: auto
choices: [auto, cryptography]
seealso:
- module: community.crypto.openssl_publickey
- module: community.crypto.openssl_privatekey_info
- plugin: community.crypto.openssl_publickey_info
plugin_type: filter
description: A filter variant of this module.
'''
- module: community.crypto.openssl_publickey
- module: community.crypto.openssl_privatekey_info
- plugin: community.crypto.openssl_publickey_info
plugin_type: filter
description: A filter variant of this module.
"""
EXAMPLES = r'''
EXAMPLES = r"""
- name: Generate an OpenSSL private key with the default values (4096 bits, RSA)
community.crypto.openssl_privatekey:
path: /etc/ssl/private/ansible.com.pem
@@ -70,87 +69,87 @@ EXAMPLES = r'''
- name: Dump information
ansible.builtin.debug:
var: result
'''
"""
RETURN = r'''
RETURN = r"""
fingerprints:
description:
- Fingerprints of public key.
- For every hash algorithm available, the fingerprint is computed.
returned: success
type: dict
sample: "{'sha256': 'd4:b3:aa:6d:c8:04:ce:4e:ba:f6:29:4d:92:a3:94:b0:c2:ff:bd:bf:33:63:11:43:34:0f:51:b0:95:09:2f:63',
'sha512': 'f7:07:4a:f0:b0:f0:e6:8b:95:5f:f9:e6:61:0a:32:68:f1..."
description:
- Fingerprints of public key.
- For every hash algorithm available, the fingerprint is computed.
returned: success
type: dict
sample: "{'sha256': 'd4:b3:aa:6d:c8:04:ce:4e:ba:f6:29:4d:92:a3:94:b0:c2:ff:bd:bf:33:63:11:43:34:0f:51:b0:95:09:2f:63', 'sha512':
'f7:07:4a:f0:b0:f0:e6:8b:95:5f:f9:e6:61:0a:32:68:f1..."
type:
description:
- The key's type.
- 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
description:
- The key's type.
- 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
public_data:
description:
- Public key data. Depends on key type.
returned: success
type: dict
contains:
size:
description:
- Bit size of modulus (RSA) or prime number (DSA).
type: int
returned: When RV(type=RSA) or RV(type=DSA)
modulus:
description:
- The RSA key's modulus.
type: int
returned: When RV(type=RSA)
exponent:
description:
- The RSA key's public exponent.
type: int
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 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 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 RV(type=DSA)
curve:
description:
- The curve's name for ECC.
type: str
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 RV(type=ECC)
x:
description:
- The C(x) coordinate for the public point on the elliptic curve.
type: int
returned: When RV(type=ECC)
y:
description:
- 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 RV(type=DSA) or RV(type=ECC)
'''
description:
- Public key data. Depends on key type.
returned: success
type: dict
contains:
size:
description:
- Bit size of modulus (RSA) or prime number (DSA).
type: int
returned: When RV(type=RSA) or RV(type=DSA)
modulus:
description:
- The RSA key's modulus.
type: int
returned: When RV(type=RSA)
exponent:
description:
- The RSA key's public exponent.
type: int
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 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 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 RV(type=DSA)
curve:
description:
- The curve's name for ECC.
type: str
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 RV(type=ECC)
x:
description:
- The C(x) coordinate for the public point on the elliptic curve.
type: int
returned: When RV(type=ECC)
y:
description:
- 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 RV(type=DSA) or RV(type=ECC)
"""
from ansible.module_utils.basic import AnsibleModule

113
plugins/modules/openssl_signature.py
View File

@@ -9,70 +9,67 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = r'''
---
DOCUMENTATION = r"""
module: openssl_signature
version_added: 1.1.0
short_description: Sign data with openssl
description:
- This module allows one to sign data using a private key.
- The module uses the cryptography Python library.
- This module allows one to sign data using a private key.
- The module uses the cryptography Python library.
requirements:
- cryptography >= 1.4 (some key types require newer versions)
- cryptography >= 1.4 (some key types require newer versions)
author:
- Patrick Pichler (@aveexy)
- Markus Teufelberger (@MarkusTeufelberger)
- Patrick Pichler (@aveexy)
- Markus Teufelberger (@MarkusTeufelberger)
extends_documentation_fragment:
- community.crypto.attributes
- community.crypto.attributes
attributes:
check_mode:
support: full
details:
- This action does not modify state.
diff_mode:
support: none
check_mode:
support: full
details:
- This action does not modify state.
diff_mode:
support: none
options:
privatekey_path:
description:
- The path to the private key to use when signing.
- 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 O(privatekey_path) or O(privatekey_content) must be specified, but not both.
type: str
privatekey_passphrase:
description:
- The passphrase for the private key.
- This is required if the private key is password protected.
type: str
path:
description:
- The file to sign.
- This file will only be read and not modified.
type: path
required: true
select_crypto_backend:
description:
- Determines which crypto backend to use.
- The default choice is V(auto), which tries to use C(cryptography) if available.
- If set to V(cryptography), will try to use the L(cryptography,https://cryptography.io/) library.
type: str
default: auto
choices: [ auto, cryptography ]
privatekey_path:
description:
- The path to the private key to use when signing.
- 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 O(privatekey_path) or O(privatekey_content) must be specified, but not both.
type: str
privatekey_passphrase:
description:
- The passphrase for the private key.
- This is required if the private key is password protected.
type: str
path:
description:
- The file to sign.
- This file will only be read and not modified.
type: path
required: true
select_crypto_backend:
description:
- Determines which crypto backend to use.
- The default choice is V(auto), which tries to use C(cryptography) if available.
- If set to V(cryptography), will try to use the L(cryptography,https://cryptography.io/) library.
type: str
default: auto
choices: [auto, cryptography]
notes:
- |
When using the C(cryptography) backend, the following key types require at least the following C(cryptography) version:
RSA keys: C(cryptography) >= 1.4
DSA and ECDSA keys: C(cryptography) >= 1.5
ed448 and ed25519 keys: C(cryptography) >= 2.6
- "When using the C(cryptography) backend, the following key types require at least the following C(cryptography) version:\n
RSA keys: C(cryptography) >= 1.4\nDSA and ECDSA keys: C(cryptography) >= 1.5\ned448 and ed25519 keys: C(cryptography)
>= 2.6."
seealso:
- module: community.crypto.openssl_signature_info
- module: community.crypto.openssl_privatekey
'''
- module: community.crypto.openssl_signature_info
- module: community.crypto.openssl_privatekey
"""
EXAMPLES = r'''
EXAMPLES = r"""
- name: Sign example file
community.crypto.openssl_signature:
privatekey_path: private.key
@@ -90,14 +87,14 @@ EXAMPLES = r'''
ansible.builtin.assert:
that:
- verify.valid
'''
"""
RETURN = r'''
RETURN = r"""
signature:
description: Base64 encoded signature.
returned: success
type: str
'''
description: Base64 encoded signature.
returned: success
type: str
"""
import os
import traceback

101
plugins/modules/openssl_signature_info.py
View File

@@ -9,63 +9,60 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = r'''
---
DOCUMENTATION = r"""
module: openssl_signature_info
version_added: 1.1.0
short_description: Verify signatures with openssl
description:
- This module allows one to verify a signature for a file by a certificate.
- The module uses the cryptography Python library.
- This module allows one to verify a signature for a file by a certificate.
- The module uses the cryptography Python library.
requirements:
- cryptography >= 1.4 (some key types require newer versions)
- cryptography >= 1.4 (some key types require newer versions)
author:
- Patrick Pichler (@aveexy)
- Markus Teufelberger (@MarkusTeufelberger)
- Patrick Pichler (@aveexy)
- Markus Teufelberger (@MarkusTeufelberger)
extends_documentation_fragment:
- community.crypto.attributes
- community.crypto.attributes.info_module
- community.crypto.attributes
- community.crypto.attributes.info_module
options:
path:
description:
- The signed file to verify.
- This file will only be read and not modified.
type: path
required: true
certificate_path:
description:
- The path to the certificate used to verify the signature.
- 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 O(certificate_path) or O(certificate_content) must be specified, but not both.
type: str
signature:
description: Base64 encoded signature.
type: str
required: true
select_crypto_backend:
description:
- Determines which crypto backend to use.
- The default choice is V(auto), which tries to use C(cryptography) if available.
- If set to V(cryptography), will try to use the L(cryptography,https://cryptography.io/) library.
type: str
default: auto
choices: [ auto, cryptography ]
path:
description:
- The signed file to verify.
- This file will only be read and not modified.
type: path
required: true
certificate_path:
description:
- The path to the certificate used to verify the signature.
- 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 O(certificate_path) or O(certificate_content) must be specified, but not both.
type: str
signature:
description: Base64 encoded signature.
type: str
required: true
select_crypto_backend:
description:
- Determines which crypto backend to use.
- The default choice is V(auto), which tries to use C(cryptography) if available.
- If set to V(cryptography), will try to use the L(cryptography,https://cryptography.io/) library.
type: str
default: auto
choices: [auto, cryptography]
notes:
- |
When using the C(cryptography) backend, the following key types require at least the following C(cryptography) version:
RSA keys: C(cryptography) >= 1.4
DSA and ECDSA keys: C(cryptography) >= 1.5
ed448 and ed25519 keys: C(cryptography) >= 2.6
- "When using the C(cryptography) backend, the following key types require at least the following C(cryptography) version:\n
RSA keys: C(cryptography) >= 1.4\nDSA and ECDSA keys: C(cryptography) >= 1.5\ned448 and ed25519 keys: C(cryptography)
>= 2.6."
seealso:
- module: community.crypto.openssl_signature
- module: community.crypto.x509_certificate
'''
- module: community.crypto.openssl_signature
- module: community.crypto.x509_certificate
"""
EXAMPLES = r'''
EXAMPLES = r"""
- name: Sign example file
community.crypto.openssl_signature:
privatekey_path: private.key
@@ -83,14 +80,14 @@ EXAMPLES = r'''
ansible.builtin.assert:
that:
- verify.valid
'''
"""
RETURN = r'''
RETURN = r"""
valid:
description: V(true) means the signature was valid for the given file, V(false) means it was not.
returned: success
type: bool
'''
description: V(true) means the signature was valid for the given file, V(false) means it was not.
returned: success
type: bool
"""
import os
import traceback

196
plugins/modules/x509_certificate.py
View File

@@ -10,99 +10,93 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = r'''
---
DOCUMENTATION = r"""
module: x509_certificate
short_description: Generate and/or check OpenSSL certificates
description:
- 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 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
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.
- 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 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 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.
author:
- Yanis Guenane (@Spredzy)
- Markus Teufelberger (@MarkusTeufelberger)
- Yanis Guenane (@Spredzy)
- Markus Teufelberger (@MarkusTeufelberger)
extends_documentation_fragment:
- ansible.builtin.files
- community.crypto.attributes
- community.crypto.attributes.files
- community.crypto.module_certificate
- community.crypto.module_certificate.backend_acme_documentation
- community.crypto.module_certificate.backend_entrust_documentation
- community.crypto.module_certificate.backend_ownca_documentation
- community.crypto.module_certificate.backend_selfsigned_documentation
- ansible.builtin.files
- community.crypto.attributes
- community.crypto.attributes.files
- community.crypto.module_certificate
- community.crypto.module_certificate.backend_acme_documentation
- community.crypto.module_certificate.backend_entrust_documentation
- community.crypto.module_certificate.backend_ownca_documentation
- community.crypto.module_certificate.backend_selfsigned_documentation
attributes:
check_mode:
support: full
diff_mode:
support: full
safe_file_operations:
support: full
check_mode:
support: full
diff_mode:
support: full
safe_file_operations:
support: full
options:
state:
description:
- Whether the certificate should exist or not, taking action if the state is different from what is stated.
type: str
default: present
choices: [ absent, present ]
state:
description:
- Whether the certificate should exist or not, taking action if the state is different from what is stated.
type: str
default: present
choices: [absent, present]
path:
description:
- Remote absolute path where the generated certificate file should be created or is already located.
type: path
required: true
path:
description:
- Remote absolute path where the generated certificate file should be created or is already located.
type: path
required: true
provider:
description:
- Name of the provider to use to generate/retrieve the OpenSSL certificate.
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 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 O(state) is V(present).
type: str
choices: [ acme, entrust, ownca, selfsigned ]
provider:
description:
- Name of the provider to use to generate/retrieve the OpenSSL certificate. 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 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 O(state) is V(present).
type: str
choices: [acme, entrust, ownca, selfsigned]
return_content:
description:
- 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'
return_content:
description:
- 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'
backup:
description:
- Create a backup file including a timestamp so you can get the original
certificate back if you overwrote it with a new one by accident.
type: bool
default: false
backup:
description:
- Create a backup file including a timestamp so you can get the original certificate back if you overwrote it with a
new one by accident.
type: bool
default: false
csr_content:
version_added: '1.0.0'
privatekey_content:
version_added: '1.0.0'
acme_directory:
version_added: '1.0.0'
ownca_content:
version_added: '1.0.0'
ownca_privatekey_content:
version_added: '1.0.0'
csr_content:
version_added: '1.0.0'
privatekey_content:
version_added: '1.0.0'
acme_directory:
version_added: '1.0.0'
ownca_content:
version_added: '1.0.0'
ownca_privatekey_content:
version_added: '1.0.0'
seealso:
- module: community.crypto.x509_certificate_pipe
'''
- module: community.crypto.x509_certificate_pipe
"""
EXAMPLES = r'''
EXAMPLES = r"""
- name: Generate a Self Signed OpenSSL certificate
community.crypto.x509_certificate:
path: /etc/ssl/crt/ansible.com.crt
@@ -188,49 +182,49 @@ EXAMPLES = r'''
- "result.signature_algorithm == 'sha256WithRSAEncryption' or result.signature_algorithm == 'sha512WithRSAEncryption'"
# subject and subject_strict
- "result.subject.commonName == 'ansible.com'"
- "result.subject | length == 1" # the number must be the number of entries you check for
- "result.subject | length == 1" # the number must be the number of entries you check for
# issuer and issuer_strict
- "result.issuer.commonName == 'ansible.com'"
- "result.issuer | length == 1" # the number must be the number of entries you check for
- "result.issuer | length == 1" # the number must be the number of entries you check for
# has_expired
- not result.expired
# version
- result.version == 3
# key_usage and key_usage_strict
- "'Data Encipherment' in result.key_usage"
- "result.key_usage | length == 1" # the number must be the number of entries you check for
- "result.key_usage | length == 1" # the number must be the number of entries you check for
# extended_key_usage and extended_key_usage_strict
- "'DVCS' in result.extended_key_usage"
- "result.extended_key_usage | length == 1" # the number must be the number of entries you check for
- "result.extended_key_usage | length == 1" # the number must be the number of entries you check for
# subject_alt_name and subject_alt_name_strict
- "'dns:ansible.com' in result.subject_alt_name"
- "result.subject_alt_name | length == 1" # the number must be the number of entries you check for
- "result.subject_alt_name | length == 1" # the number must be the number of entries you check for
# not_before and not_after
- "result.not_before == '20190331202428Z'"
- "result.not_after == '20190413202428Z'"
# valid_at, invalid_at and valid_in
- "result.valid_at.one_day_ten_hours" # for valid_at
- "not result.valid_at.fixed_timestamp" # for invalid_at
- "result.valid_at.ten_seconds" # for valid_in
'''
- "result.valid_at.one_day_ten_hours" # for valid_at
- "not result.valid_at.fixed_timestamp" # for invalid_at
- "result.valid_at.ten_seconds" # for valid_in
"""
RETURN = r'''
RETURN = r"""
filename:
description: Path to the generated certificate.
returned: changed or success
type: str
sample: /etc/ssl/crt/www.ansible.com.crt
description: Path to the generated certificate.
returned: changed or success
type: str
sample: /etc/ssl/crt/www.ansible.com.crt
backup_file:
description: Name of backup file created.
returned: changed and if O(backup) is V(true)
type: str
sample: /path/to/www.ansible.com.crt.2019-03-09@11:22~
description: Name of backup file created.
returned: changed and if O(backup) is V(true)
type: str
sample: /path/to/www.ansible.com.crt.2019-03-09@11:22~
certificate:
description: The (current or generated) certificate's content.
returned: if O(state) is V(present) and O(return_content) is V(true)
type: str
version_added: '1.0.0'
'''
description: The (current or generated) certificate's content.
returned: if O(state) is V(present) and O(return_content) is V(true)
type: str
version_added: '1.0.0'
"""
import os

142
plugins/modules/x509_certificate_convert.py
View File

@@ -9,96 +9,92 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = r'''
---
DOCUMENTATION = r"""
module: x509_certificate_convert
short_description: Convert X.509 certificates
version_added: 2.19.0
description:
- This module allows to convert X.509 certificates between different formats.
- This module allows to convert X.509 certificates between different formats.
author:
- Felix Fontein (@felixfontein)
- Felix Fontein (@felixfontein)
extends_documentation_fragment:
- ansible.builtin.files
- community.crypto.attributes
- community.crypto.attributes.files
- ansible.builtin.files
- community.crypto.attributes
- community.crypto.attributes.files
attributes:
check_mode:
support: full
diff_mode:
support: none
safe_file_operations:
support: full
check_mode:
support: full
diff_mode:
support: none
safe_file_operations:
support: full
options:
src_path:
description:
- Name of the file containing the X.509 certificate to convert.
- 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 X.509 certificate to convert.
- This must be text. If you are not sure that the input file is PEM, you must Base64 encode
the value and set O(src_content_base64=true). You can use the
P(ansible.builtin.b64encode#filter) filter plugin for this.
- Exactly one of O(src_path) or O(src_content) must be specified.
type: str
src_content_base64:
description:
- If set to V(true) when O(src_content) is provided, the module assumes that the value
of O(src_content) is Base64 encoded.
type: bool
default: false
format:
description:
- Determines which format the destination X.509 certificate should be written in.
- Please note that not every key can be exported in any format, and that not every
format supports encryption.
type: str
choices:
- pem
- der
required: true
strict:
description:
- If the input is a PEM file, ensure that it contains a single PEM object, that
the header and footer match, and are of type C(CERTIFICATE) or C(X509 CERTIFICATE).
type: bool
default: false
dest_path:
description:
- Name of the file in which the generated TLS/SSL X.509 certificate will be written.
type: path
required: true
backup:
description:
- Create a backup file including a timestamp so you can get
the original X.509 certificate back if you overwrote it with a new one by accident.
type: bool
default: false
src_path:
description:
- Name of the file containing the X.509 certificate to convert.
- 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 X.509 certificate to convert.
- This must be text. If you are not sure that the input file is PEM, you must Base64 encode the value and set O(src_content_base64=true).
You can use the P(ansible.builtin.b64encode#filter) filter plugin for this.
- Exactly one of O(src_path) or O(src_content) must be specified.
type: str
src_content_base64:
description:
- If set to V(true) when O(src_content) is provided, the module assumes that the value of O(src_content) is Base64 encoded.
type: bool
default: false
format:
description:
- Determines which format the destination X.509 certificate should be written in.
- Please note that not every key can be exported in any format, and that not every format supports encryption.
type: str
choices:
- pem
- der
required: true
strict:
description:
- If the input is a PEM file, ensure that it contains a single PEM object, that the header and footer match, and are
of type C(CERTIFICATE) or C(X509 CERTIFICATE).
type: bool
default: false
dest_path:
description:
- Name of the file in which the generated TLS/SSL X.509 certificate will be written.
type: path
required: true
backup:
description:
- Create a backup file including a timestamp so you can get the original X.509 certificate back if you overwrote it
with a new one by accident.
type: bool
default: false
seealso:
- plugin: ansible.builtin.b64encode
plugin_type: filter
- module: community.crypto.x509_certificate
- module: community.crypto.x509_certificate_pipe
- module: community.crypto.x509_certificate_info
'''
- plugin: ansible.builtin.b64encode
plugin_type: filter
- module: community.crypto.x509_certificate
- module: community.crypto.x509_certificate_pipe
- module: community.crypto.x509_certificate_info
"""
EXAMPLES = r'''
EXAMPLES = r"""
- name: Convert PEM X.509 certificate to DER format
community.crypto.x509_certificate_convert:
src_path: /etc/ssl/cert/ansible.com.pem
dest_path: /etc/ssl/cert/ansible.com.der
format: der
'''
"""
RETURN = r'''
RETURN = r"""
backup_file:
description: Name of backup file created.
returned: changed and if O(backup) is V(true)
type: str
sample: /path/to/cert.pem.2019-03-09@11:22~
'''
description: Name of backup file created.
returned: changed and if O(backup) is V(true)
type: str
sample: /path/to/cert.pem.2019-03-09@11:22~
"""
import base64
import os

602
plugins/modules/x509_certificate_info.py
View File

@@ -10,78 +10,74 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = r'''
---
DOCUMENTATION = r"""
module: x509_certificate_info
short_description: Provide information of OpenSSL X.509 certificates
description:
- This module allows one to query information on OpenSSL certificates.
- It uses the cryptography python library to interact with OpenSSL.
- Note that this module was called C(openssl_certificate_info) 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_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
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.
- This module allows one to query information on OpenSSL certificates.
- It uses the cryptography python library to interact with OpenSSL.
- Note that this module was called C(openssl_certificate_info) 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_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 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.
requirements:
- cryptography >= 1.6
- cryptography >= 1.6
author:
- Felix Fontein (@felixfontein)
- Yanis Guenane (@Spredzy)
- Markus Teufelberger (@MarkusTeufelberger)
- Felix Fontein (@felixfontein)
- Yanis Guenane (@Spredzy)
- Markus Teufelberger (@MarkusTeufelberger)
extends_documentation_fragment:
- community.crypto.attributes
- community.crypto.attributes.info_module
- community.crypto.name_encoding
- community.crypto.attributes
- community.crypto.attributes.info_module
- community.crypto.name_encoding
options:
path:
description:
- Remote absolute path where the certificate file is loaded from.
- 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 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
RV(valid_at) return value for information 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 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 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 ]
path:
description:
- Remote absolute path where the certificate file is loaded from.
- 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 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 RV(valid_at) return value for information 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
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 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]
notes:
- All timestamp values are provided in ASN.1 TIME format, in other words, following the C(YYYYMMDDHHMMSSZ) pattern.
They are all in UTC.
- All timestamp values are provided in ASN.1 TIME format, in other words, following the C(YYYYMMDDHHMMSSZ) pattern. They
are all in UTC.
seealso:
- module: community.crypto.x509_certificate
- module: community.crypto.x509_certificate_pipe
- plugin: community.crypto.x509_certificate_info
plugin_type: filter
description: A filter variant of this module.
- plugin: community.crypto.to_serial
plugin_type: filter
'''
- module: community.crypto.x509_certificate
- module: community.crypto.x509_certificate_pipe
- plugin: community.crypto.x509_certificate_info
plugin_type: filter
description: A filter variant of this module.
- plugin: community.crypto.to_serial
plugin_type: filter
"""
EXAMPLES = r'''
EXAMPLES = r"""
- name: Generate a Self Signed OpenSSL certificate
community.crypto.x509_certificate:
path: /etc/ssl/crt/ansible.com.crt
@@ -118,284 +114,280 @@ EXAMPLES = r'''
- name: Validate that certificate is valid tomorrow, but not in three weeks
ansible.builtin.assert:
that:
- result.valid_at.point_1 # valid in one day
- not result.valid_at.point_2 # not valid in three weeks
'''
- result.valid_at.point_1 # valid in one day
- not result.valid_at.point_2 # not valid in three weeks
"""
RETURN = r'''
RETURN = r"""
expired:
description: Whether the certificate is expired (in other words, C(notAfter) is in the past).
returned: success
type: bool
description: Whether the certificate is expired (in other words, C(notAfter) is in the past).
returned: success
type: bool
basic_constraints:
description: Entries in the C(basic_constraints) extension, or V(none) if extension is not present.
returned: success
type: list
elements: str
sample: ["CA:TRUE", "pathlen:1"]
description: Entries in the C(basic_constraints) extension, or V(none) if extension is not present.
returned: success
type: list
elements: str
sample: ["CA:TRUE", "pathlen:1"]
basic_constraints_critical:
description: Whether the C(basic_constraints) extension is critical.
returned: success
type: bool
description: Whether the C(basic_constraints) extension is critical.
returned: success
type: bool
extended_key_usage:
description: Entries in the C(extended_key_usage) extension, or V(none) if extension is not present.
returned: success
type: list
elements: str
sample: [Biometric Info, DVCS, Time Stamping]
description: Entries in the C(extended_key_usage) extension, or V(none) if extension is not present.
returned: success
type: list
elements: str
sample: [Biometric Info, DVCS, Time Stamping]
extended_key_usage_critical:
description: Whether the C(extended_key_usage) extension is critical.
returned: success
type: bool
description: Whether the C(extended_key_usage) extension is critical.
returned: success
type: bool
extensions_by_oid:
description: Returns a dictionary for every extension OID.
returned: success
type: dict
contains:
critical:
description: Whether the extension is critical.
returned: success
type: bool
value:
description:
- The Base64 encoded value (in DER format) of the extension.
- B(Note) that depending on the C(cryptography) version used, it is
not possible to extract the ASN.1 content of the extension, but only
to provide the re-encoded content of the extension in case it was
parsed by C(cryptography). This should usually result in exactly the
same value, except if the original extension value was malformed.
returned: success
type: str
sample: "MAMCAQU="
sample: {"1.3.6.1.5.5.7.1.24": { "critical": false, "value": "MAMCAQU="}}
description: Returns a dictionary for every extension OID.
returned: success
type: dict
contains:
critical:
description: Whether the extension is critical.
returned: success
type: bool
value:
description:
- The Base64 encoded value (in DER format) of the extension.
- B(Note) that depending on the C(cryptography) version used, it is not possible to extract the ASN.1 content of the
extension, but only to provide the re-encoded content of the extension in case it was parsed by C(cryptography).
This should usually result in exactly the same value, except if the original extension value was malformed.
returned: success
type: str
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 V(none) if extension is not present.
returned: success
type: str
sample: [Key Agreement, Data Encipherment]
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]
key_usage_critical:
description: Whether the C(key_usage) extension is critical.
returned: success
type: bool
description: Whether the C(key_usage) extension is critical.
returned: success
type: bool
subject_alt_name:
description:
- 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
sample: ["DNS:www.ansible.com", "IP:1.2.3.4"]
description:
- 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
sample: ["DNS:www.ansible.com", "IP:1.2.3.4"]
subject_alt_name_critical:
description: Whether the C(subject_alt_name) extension is critical.
returned: success
type: bool
description: Whether the C(subject_alt_name) extension is critical.
returned: success
type: bool
ocsp_must_staple:
description: V(true) if the OCSP Must Staple extension is present, V(none) otherwise.
returned: success
type: bool
description: V(true) if the OCSP Must Staple extension is present, V(none) otherwise.
returned: success
type: bool
ocsp_must_staple_critical:
description: Whether the C(ocsp_must_staple) extension is critical.
returned: success
type: bool
description: Whether the C(ocsp_must_staple) extension is critical.
returned: success
type: bool
issuer:
description:
- The certificate's issuer.
- Note that for repeated values, only the last one will be returned.
returned: success
type: dict
sample: {"organizationName": "Ansible", "commonName": "ca.example.com"}
description:
- The certificate's issuer.
- Note that for repeated values, only the last one will be returned.
returned: success
type: dict
sample: {"organizationName": "Ansible", "commonName": "ca.example.com"}
issuer_ordered:
description: The certificate's issuer as an ordered list of tuples.
returned: success
type: list
elements: list
sample: [["organizationName", "Ansible"], ["commonName": "ca.example.com"]]
description: The certificate's issuer as an ordered list of tuples.
returned: success
type: list
elements: list
sample: [["organizationName", "Ansible"], ["commonName": "ca.example.com"]]
subject:
description:
- The certificate's subject as a dictionary.
- Note that for repeated values, only the last one will be returned.
returned: success
type: dict
sample: {"commonName": "www.example.com", "emailAddress": "test@example.com"}
description:
- The certificate's subject as a dictionary.
- Note that for repeated values, only the last one will be returned.
returned: success
type: dict
sample: {"commonName": "www.example.com", "emailAddress": "test@example.com"}
subject_ordered:
description: The certificate's subject as an ordered list of tuples.
returned: success
type: list
elements: list
sample: [["commonName", "www.example.com"], ["emailAddress": "test@example.com"]]
description: The certificate's subject as an ordered list of tuples.
returned: success
type: list
elements: list
sample: [["commonName", "www.example.com"], ["emailAddress": "test@example.com"]]
not_after:
description: C(notAfter) date as ASN.1 TIME.
returned: success
type: str
sample: '20190413202428Z'
description: C(notAfter) date as ASN.1 TIME.
returned: success
type: str
sample: '20190413202428Z'
not_before:
description: C(notBefore) date as ASN.1 TIME.
returned: success
type: str
sample: '20190331202428Z'
description: C(notBefore) date as ASN.1 TIME.
returned: success
type: str
sample: '20190331202428Z'
public_key:
description: Certificate's public key in PEM format.
returned: success
type: str
sample: "-----BEGIN PUBLIC KEY-----\nMIICIjANBgkqhkiG9w0BAQEFAAOCAg8A..."
description: Certificate's public key in PEM format.
returned: success
type: str
sample: "-----BEGIN PUBLIC KEY-----\nMIICIjANBgkqhkiG9w0BAQEFAAOCAg8A..."
public_key_type:
description:
- The certificate's public key's type.
- 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
sample: RSA
description:
- The certificate's public key's type.
- 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
sample: RSA
public_key_data:
description:
- Public key data. Depends on the public key's type.
returned: success
type: dict
version_added: 1.7.0
contains:
size:
description:
- Bit size of modulus (RSA) or prime number (DSA).
type: int
returned: When RV(public_key_type=RSA) or RV(public_key_type=DSA)
modulus:
description:
- The RSA key's modulus.
type: int
returned: When RV(public_key_type=RSA)
exponent:
description:
- The RSA key's public exponent.
type: int
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 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 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 RV(public_key_type=DSA)
curve:
description:
- The curve's name for ECC.
type: str
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 RV(public_key_type=ECC)
x:
description:
- The C(x) coordinate for the public point on the elliptic curve.
type: int
returned: When RV(public_key_type=ECC)
y:
description:
- 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 RV(public_key_type=DSA) or RV(public_key_type=ECC)
description:
- Public key data. Depends on the public key's type.
returned: success
type: dict
version_added: 1.7.0
contains:
size:
description:
- Bit size of modulus (RSA) or prime number (DSA).
type: int
returned: When RV(public_key_type=RSA) or RV(public_key_type=DSA)
modulus:
description:
- The RSA key's modulus.
type: int
returned: When RV(public_key_type=RSA)
exponent:
description:
- The RSA key's public exponent.
type: int
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 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 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 RV(public_key_type=DSA)
curve:
description:
- The curve's name for ECC.
type: str
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 RV(public_key_type=ECC)
x:
description:
- The C(x) coordinate for the public point on the elliptic curve.
type: int
returned: When RV(public_key_type=ECC)
y:
description:
- 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 RV(public_key_type=DSA) or RV(public_key_type=ECC)
public_key_fingerprints:
description:
- Fingerprints of certificate's public key.
- For every hash algorithm available, the fingerprint is computed.
returned: success
type: dict
sample: "{'sha256': 'd4:b3:aa:6d:c8:04:ce:4e:ba:f6:29:4d:92:a3:94:b0:c2:ff:bd:bf:33:63:11:43:34:0f:51:b0:95:09:2f:63',
'sha512': 'f7:07:4a:f0:b0:f0:e6:8b:95:5f:f9:e6:61:0a:32:68:f1..."
description:
- Fingerprints of certificate's public key.
- For every hash algorithm available, the fingerprint is computed.
returned: success
type: dict
sample: "{'sha256': 'd4:b3:aa:6d:c8:04:ce:4e:ba:f6:29:4d:92:a3:94:b0:c2:ff:bd:bf:33:63:11:43:34:0f:51:b0:95:09:2f:63', 'sha512':
'f7:07:4a:f0:b0:f0:e6:8b:95:5f:f9:e6:61:0a:32:68:f1..."
fingerprints:
description:
- Fingerprints of the DER-encoded form of the whole certificate.
- For every hash algorithm available, the fingerprint is computed.
returned: success
type: dict
sample: "{'sha256': 'd4:b3:aa:6d:c8:04:ce:4e:ba:f6:29:4d:92:a3:94:b0:c2:ff:bd:bf:33:63:11:43:34:0f:51:b0:95:09:2f:63',
'sha512': 'f7:07:4a:f0:b0:f0:e6:8b:95:5f:f9:e6:61:0a:32:68:f1..."
version_added: 1.2.0
description:
- Fingerprints of the DER-encoded form of the whole certificate.
- For every hash algorithm available, the fingerprint is computed.
returned: success
type: dict
sample: "{'sha256': 'd4:b3:aa:6d:c8:04:ce:4e:ba:f6:29:4d:92:a3:94:b0:c2:ff:bd:bf:33:63:11:43:34:0f:51:b0:95:09:2f:63', 'sha512':
'f7:07:4a:f0:b0:f0:e6:8b:95:5f:f9:e6:61:0a:32:68:f1..."
version_added: 1.2.0
signature_algorithm:
description: The signature algorithm used to sign the certificate.
returned: success
type: str
sample: sha256WithRSAEncryption
description: The signature algorithm used to sign the certificate.
returned: success
type: str
sample: sha256WithRSAEncryption
serial_number:
description:
- The certificate's serial number.
- This return value is an B(integer). If you need the serial numbers as a colon-separated hex string,
such as C(11:22:33), you need to convert it to that form with P(community.crypto.to_serial#filter).
returned: success
type: int
sample: 1234
description:
- The certificate's serial number.
- This return value is an B(integer). If you need the serial numbers as a colon-separated hex string, such as C(11:22:33),
you need to convert it to that form with P(community.crypto.to_serial#filter).
returned: success
type: int
sample: 1234
version:
description: The certificate version.
returned: success
type: int
sample: 3
description: The certificate version.
returned: success
type: int
sample: 3
valid_at:
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
type: dict
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
type: dict
subject_key_identifier:
description:
- The certificate's subject key identifier.
- 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'
description:
- The certificate's subject key identifier.
- 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 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'
description:
- The certificate's authority key identifier.
- 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 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
sample: ["DNS:www.ansible.com", "IP:1.2.3.4"]
description:
- The certificate's authority cert issuer as a list of general names.
- 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
sample: ["DNS:www.ansible.com", "IP:1.2.3.4"]
authority_cert_serial_number:
description:
- The certificate's authority cert serial number.
- Is V(none) if the C(AuthorityKeyIdentifier) extension is not present.
- This return value is an B(integer). If you need the serial numbers as a colon-separated hex string,
such as C(11:22:33), you need to convert it to that form with P(community.crypto.to_serial#filter).
returned: success
type: int
sample: 12345
description:
- The certificate's authority cert serial number.
- Is V(none) if the C(AuthorityKeyIdentifier) extension is not present.
- This return value is an B(integer). If you need the serial numbers as a colon-separated hex string, such as C(11:22:33),
you need to convert it to that form with P(community.crypto.to_serial#filter).
returned: success
type: int
sample: 12345
ocsp_uri:
description: The OCSP responder URI, if included in the certificate. Will be
V(none) if no OCSP responder URI is included.
returned: success
type: str
description: The OCSP responder URI, if included in the certificate. Will be 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
V(none) if no issuer URI is included.
returned: success
type: str
version_added: 2.9.0
'''
description: The Issuer URI, if included in the certificate. Will be V(none) if no issuer URI is included.
returned: success
type: str
version_added: 2.9.0
"""
from ansible.module_utils.basic import AnsibleModule

83
plugins/modules/x509_certificate_pipe.py
View File

@@ -11,55 +11,52 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = r'''
---
DOCUMENTATION = r"""
module: x509_certificate_pipe
short_description: Generate and/or check OpenSSL certificates
version_added: 1.3.0
description:
- It implements a notion of provider (one of V(selfsigned), V(ownca), V(entrust))
for your certificate.
- It implements a notion of provider (one of V(selfsigned), V(ownca), V(entrust)) for your certificate.
author:
- Yanis Guenane (@Spredzy)
- Markus Teufelberger (@MarkusTeufelberger)
- Felix Fontein (@felixfontein)
- Yanis Guenane (@Spredzy)
- Markus Teufelberger (@MarkusTeufelberger)
- Felix Fontein (@felixfontein)
extends_documentation_fragment:
- community.crypto.attributes
- community.crypto.module_certificate
- community.crypto.module_certificate.backend_entrust_documentation
- community.crypto.module_certificate.backend_ownca_documentation
- community.crypto.module_certificate.backend_selfsigned_documentation
- community.crypto.attributes
- community.crypto.module_certificate
- community.crypto.module_certificate.backend_entrust_documentation
- community.crypto.module_certificate.backend_ownca_documentation
- community.crypto.module_certificate.backend_selfsigned_documentation
attributes:
check_mode:
support: full
details:
- Currently in check mode, private keys will not be (re-)generated, only the changed status is
set. This will change in community.crypto 3.0.0.
- From community.crypto 3.0.0 on, the module will ignore check mode and always behave as if
check mode is not active. If you think this breaks your use-case of this module, please
create an issue in the community.crypto repository.
diff_mode:
support: full
check_mode:
support: full
details:
- Currently in check mode, private keys will not be (re-)generated, only the changed status is set. This will change
in community.crypto 3.0.0.
- From community.crypto 3.0.0 on, the module will ignore check mode and always behave as if check mode is not active.
If you think this breaks your use-case of this module, please create an issue in the community.crypto repository.
diff_mode:
support: full
options:
provider:
description:
- Name of the provider to use to generate/retrieve the OpenSSL certificate.
- "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 ]
required: true
provider:
description:
- Name of the provider to use to generate/retrieve the OpenSSL certificate.
- 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]
required: true
content:
description:
- The existing certificate.
type: str
content:
description:
- The existing certificate.
type: str
seealso:
- module: community.crypto.x509_certificate
'''
- module: community.crypto.x509_certificate
"""
EXAMPLES = r'''
EXAMPLES = r"""
- name: Generate a Self Signed OpenSSL certificate
community.crypto.x509_certificate_pipe:
provider: selfsigned
@@ -119,14 +116,14 @@ EXAMPLES = r'''
dest: /etc/ssl/csr/www.ansible.com.crt
content: "{{ result.certificate }}"
when: result is changed
'''
"""
RETURN = r'''
RETURN = r"""
certificate:
description: The (current or generated) certificate's content.
returned: changed or success
type: str
'''
description: The (current or generated) certificate's content.
returned: changed or success
type: str
"""
from ansible.module_utils.common.text.converters import to_native

715
plugins/modules/x509_crl.py
View File

@@ -9,298 +9,284 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = r'''
---
DOCUMENTATION = r"""
module: x509_crl
version_added: '1.0.0'
short_description: Generate Certificate Revocation Lists (CRLs)
description:
- This module allows one to (re)generate or update Certificate Revocation Lists (CRLs).
- Certificates on the revocation list can be either specified by serial number and (optionally) their issuer,
or as a path to a certificate file in PEM format.
- This module allows one to (re)generate or update Certificate Revocation Lists (CRLs).
- Certificates on the revocation list can be either specified by serial number and (optionally) their issuer, or as a path
to a certificate file in PEM format.
requirements:
- cryptography >= 1.2
- cryptography >= 1.2
author:
- Felix Fontein (@felixfontein)
- Felix Fontein (@felixfontein)
extends_documentation_fragment:
- ansible.builtin.files
- community.crypto.attributes
- community.crypto.attributes.files
- community.crypto.name_encoding
- ansible.builtin.files
- community.crypto.attributes
- community.crypto.attributes.files
- community.crypto.name_encoding
attributes:
check_mode:
support: full
diff_mode:
support: full
safe_file_operations:
support: full
check_mode:
support: full
diff_mode:
support: full
safe_file_operations:
support: full
options:
state:
description:
- Whether the CRL file should exist or not, taking action if the state is different from what is stated.
type: str
default: present
choices: [ absent, present ]
state:
description:
- Whether the CRL file should exist or not, taking action if the state is different from what is stated.
type: str
default: present
choices: [absent, present]
crl_mode:
description:
- Defines how to process entries of existing CRLs.
- 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 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
crl_mode:
description:
- Defines how to process entries of existing CRLs.
- 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 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 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
choices: [generate, update]
version_added: 2.13.0
mode:
description:
- 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 ]
choices: [generate, update]
force:
description:
- Should the CRL be forced to be regenerated.
type: bool
default: false
force:
description:
- Should the CRL be forced to be regenerated.
type: bool
default: false
backup:
description:
- Create a backup file including a timestamp so you can get the original
CRL back if you overwrote it with a new one by accident.
type: bool
default: false
backup:
description:
- Create a backup file including a timestamp so you can get the original CRL back if you overwrote it with a new one
by accident.
type: bool
default: false
path:
path:
description:
- Remote absolute path where the generated CRL file should be created or is already located.
type: path
required: true
format:
description:
- Whether the CRL file should be in PEM or DER 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]
default: pem
privatekey_path:
description:
- Path to the CA's private key to use when signing the CRL.
- 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 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 O(privatekey_path).
- This is required if the private key is password protected.
type: str
issuer:
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 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:
- A list of dictionaries, where every dictionary must contain one key/value pair. 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 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
last_update:
description:
- The point in time from which this CRL can be trusted.
- 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
V(+32w1d2h)).
- Note that if using relative time this module is NOT idempotent, except when O(ignore_timestamps) is set to V(true).
type: str
default: "+0s"
next_update:
description:
- 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
V(+32w1d2h)).
- Note that if using relative time this module is NOT idempotent, except when O(ignore_timestamps) is set to V(true).
- Required if O(state) is V(present).
type: str
digest:
description:
- Digest algorithm to be used when signing the CRL.
type: str
default: sha256
serial_numbers:
description:
- This option determines which values will be accepted for O(revoked_certificates[].serial_number).
- If set to V(integer) (default), serial numbers are assumed to be integers, for example V(66223). (This example value
is equivalent to the hex octet string V(01:02:AF)).
- If set to V(hex-octets), serial numbers are assumed to be colon-separated hex octet strings, for example V(01:02:AF).
(This example value is equivalent to the integer V(66223)).
type: str
choices:
- integer
- hex-octets
default: integer
version_added: 2.18.0
revoked_certificates:
description:
- List of certificates to be revoked.
- Required if O(state) is V(present).
type: list
elements: dict
suboptions:
path:
description:
- Remote absolute path where the generated CRL file should be created or is already located.
- Path to a certificate in PEM format.
- The serial number and issuer will be extracted from the certificate.
- Mutually exclusive with O(revoked_certificates[].content) and O(revoked_certificates[].serial_number). One of
these three options must be specified.
type: path
required: true
format:
content:
description:
- Whether the CRL file should be in PEM or DER format.
- If an existing CRL file does match everything but O(format), it will be converted to the correct format
instead of regenerated.
- Content of a certificate in PEM format.
- The serial number and issuer will be extracted from the certificate.
- Mutually exclusive with O(revoked_certificates[].path) and O(revoked_certificates[].serial_number). One of these
three options must be specified.
type: str
choices: [pem, der]
default: pem
privatekey_path:
serial_number:
description:
- Path to the CA's private key to use when signing the CRL.
- Either O(privatekey_path) or O(privatekey_content) must be specified if O(state) is V(present), but not both.
type: path
privatekey_content:
- Serial number of the certificate.
- Mutually exclusive with O(revoked_certificates[].path) and O(revoked_certificates[].content). One of these three
options must be specified.
- This option accepts integers or hex octet strings, depending on the value of O(serial_numbers).
- If O(serial_numbers=integer), integers such as V(66223) must be provided.
- If O(serial_numbers=hex-octets), strings such as V(01:02:AF) must be provided.
- You can use the filters P(community.crypto.parse_serial#filter) and P(community.crypto.to_serial#filter) to convert
these two representations.
type: raw
revocation_date:
description:
- The content of the CA's private key to use when signing the CRL.
- 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 O(privatekey_path).
- This is required if the private key is password protected.
type: str
issuer:
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 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:
- A list of dictionaries, where every dictionary must contain one key/value pair.
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 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
last_update:
description:
- The point in time from which this CRL can be trusted.
- 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 V(+32w1d2h)).
- Note that if using relative time this module is NOT idempotent, except when
O(ignore_timestamps) is set to V(true).
- The point in time the certificate was revoked.
- 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
V(+32w1d2h)).
- Note that if using relative time this module is NOT idempotent, except when O(ignore_timestamps) is set to V(true).
type: str
default: "+0s"
next_update:
issuer:
description:
- "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 V(+32w1d2h)).
- Note that if using relative time this module is NOT idempotent, except when
O(ignore_timestamps) is set to V(true).
- Required if O(state) is V(present).
type: str
digest:
- The certificate's issuer.
- 'Example: V(DNS:ca.example.org).'
type: list
elements: str
issuer_critical:
description:
- Digest algorithm to be used when signing the CRL.
type: str
default: sha256
serial_numbers:
- Whether the certificate issuer extension should be critical.
type: bool
default: false
reason:
description:
- This option determines which values will be accepted for O(revoked_certificates[].serial_number).
- If set to V(integer) (default), serial numbers are assumed to be integers, for example V(66223).
(This example value is equivalent to the hex octet string V(01:02:AF).)
- If set to V(hex-octets), serial numbers are assumed to be colon-separated hex octet strings,
for example V(01:02:AF).
(This example value is equivalent to the integer V(66223).)
- The value for the revocation reason extension.
type: str
choices:
- integer
- hex-octets
default: integer
version_added: 2.18.0
revoked_certificates:
- unspecified
- key_compromise
- ca_compromise
- affiliation_changed
- superseded
- cessation_of_operation
- certificate_hold
- privilege_withdrawn
- aa_compromise
- remove_from_crl
reason_critical:
description:
- List of certificates to be revoked.
- Required if O(state) is V(present).
type: list
elements: dict
suboptions:
path:
description:
- Path to a certificate in PEM format.
- The serial number and issuer will be extracted from the certificate.
- 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 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 O(revoked_certificates[].path) and
O(revoked_certificates[].content). One of these three options must
be specified.
- This option accepts integers or hex octet strings, depending on the value
of O(serial_numbers).
- If O(serial_numbers=integer), integers such as V(66223) must be provided.
- If O(serial_numbers=hex-octets), strings such as V(01:02:AF) must be provided.
- You can use the filters P(community.crypto.parse_serial#filter) and
P(community.crypto.to_serial#filter) to convert these two representations.
type: raw
revocation_date:
description:
- The point in time the certificate was revoked.
- 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 V(+32w1d2h)).
- Note that if using relative time this module is NOT idempotent, except when
O(ignore_timestamps) is set to V(true).
type: str
default: "+0s"
issuer:
description:
- The certificate's issuer.
- "Example: V(DNS:ca.example.org)"
type: list
elements: str
issuer_critical:
description:
- Whether the certificate issuer extension should be critical.
type: bool
default: false
reason:
description:
- The value for the revocation reason extension.
type: str
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 should be critical.
type: bool
default: false
invalidity_date:
description:
- The point in time it was known/suspected that the private key was compromised
or that the certificate otherwise became invalid.
- 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 V(+32w1d2h)).
- Note that if using relative time this module is NOT idempotent. This will NOT
change when O(ignore_timestamps) is set to V(true).
type: str
invalidity_date_critical:
description:
- Whether the invalidity date extension should be critical.
type: bool
default: false
ignore_timestamps:
- Whether the revocation reason extension should be critical.
type: bool
default: false
invalidity_date:
description:
- 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.
- The point in time it was known/suspected that the private key was compromised or that the certificate otherwise
became invalid.
- 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
V(+32w1d2h)).
- Note that if using relative time this module is NOT idempotent. This will NOT change when O(ignore_timestamps)
is set to V(true).
type: str
invalidity_date_critical:
description:
- Whether the invalidity date extension should be critical.
type: bool
default: false
return_content:
description:
- If set to V(true), will return the (current or generated) CRL's content as RV(crl).
type: bool
default: false
ignore_timestamps:
description:
- 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 V(true), will return the (current or generated) CRL's content as RV(crl).
type: bool
default: false
notes:
- All ASN.1 TIME values should be specified following the YYYYMMDDHHMMSSZ pattern.
- Date specified should be UTC. Minutes and seconds are mandatory.
- All ASN.1 TIME values should be specified following the YYYYMMDDHHMMSSZ pattern.
- Date specified should be UTC. Minutes and seconds are mandatory.
seealso:
- plugin: community.crypto.parse_serial
plugin_type: filter
- plugin: community.crypto.to_serial
plugin_type: filter
'''
- plugin: community.crypto.parse_serial
plugin_type: filter
- plugin: community.crypto.to_serial
plugin_type: filter
"""
EXAMPLES = r'''
EXAMPLES = r"""
- name: Generate a CRL
community.crypto.x509_crl:
path: /etc/ssl/my-ca.crl
@@ -320,128 +306,127 @@ EXAMPLES = r'''
invalidity_date: 20191001000000Z
- path: /etc/ssl/crt/revoked-cert.pem
revocation_date: 20191010010203Z
'''
"""
RETURN = r'''
RETURN = r"""
filename:
description: Path to the generated CRL.
returned: changed or success
type: str
sample: /path/to/my-ca.crl
description: Path to the generated CRL.
returned: changed or success
type: str
sample: /path/to/my-ca.crl
backup_file:
description: Name of backup file created.
returned: changed and if O(backup) is V(true)
type: str
sample: /path/to/my-ca.crl.2019-03-09@11:22~
description: Name of backup file created.
returned: changed and if O(backup) is V(true)
type: str
sample: /path/to/my-ca.crl.2019-03-09@11:22~
privatekey:
description: Path to the private CA key.
returned: changed or success
type: str
sample: /path/to/my-ca.pem
description: Path to the private CA key.
returned: changed or success
type: str
sample: /path/to/my-ca.pem
format:
description:
- Whether the CRL is in PEM format (V(pem)) or in DER format (V(der)).
returned: success
type: str
sample: pem
choices:
- pem
- der
description:
- 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 O(name_encoding) for how IDNs are handled.
returned: success
type: dict
sample: {"organizationName": "Ansible", "commonName": "ca.example.com"}
description:
- The CRL's issuer.
- Note that for repeated values, only the last one will be returned.
- See O(name_encoding) for how IDNs are handled.
returned: success
type: dict
sample: {"organizationName": "Ansible", "commonName": "ca.example.com"}
issuer_ordered:
description: The CRL's issuer as an ordered list of tuples.
returned: success
type: list
elements: list
sample: [["organizationName", "Ansible"], ["commonName": "ca.example.com"]]
description: The CRL's issuer as an ordered list of tuples.
returned: success
type: list
elements: list
sample: [["organizationName", "Ansible"], ["commonName": "ca.example.com"]]
last_update:
description: The point in time from which this CRL can be trusted as ASN.1 TIME.
returned: success
type: str
sample: 20190413202428Z
description: The point in time from which this CRL can be trusted as ASN.1 TIME.
returned: success
type: str
sample: 20190413202428Z
next_update:
description: The point in time from which a new CRL will be issued and the client has to check for it as ASN.1 TIME.
returned: success
type: str
sample: 20190413202428Z
description: The point in time from which a new CRL will be issued and the client has to check for it as ASN.1 TIME.
returned: success
type: str
sample: 20190413202428Z
digest:
description: The signature algorithm used to sign the CRL.
returned: success
type: str
sample: sha256WithRSAEncryption
description: The signature algorithm used to sign the CRL.
returned: success
type: str
sample: sha256WithRSAEncryption
revoked_certificates:
description: List of certificates to be revoked.
returned: success
type: list
elements: dict
contains:
serial_number:
description:
- Serial number of the certificate.
- This return value is an B(integer). If you need the serial numbers as a colon-separated hex string,
such as C(11:22:33), you need to convert it to that form with P(community.crypto.to_serial#filter).
type: int
sample: 1234
revocation_date:
description: The point in time the certificate was revoked as ASN.1 TIME.
type: str
sample: 20190413202428Z
issuer:
description:
- The certificate's issuer.
- See O(name_encoding) for how IDNs are handled.
type: list
elements: str
sample: ["DNS:ca.example.org"]
issuer_critical:
description: Whether the certificate issuer extension is critical.
type: bool
sample: false
reason:
description:
- The value for the revocation reason extension.
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
sample: false
invalidity_date:
description: |
The point in time it was known/suspected that the private key was compromised
or that the certificate otherwise became invalid as ASN.1 TIME.
type: str
sample: 20190413202428Z
invalidity_date_critical:
description: Whether the invalidity date extension is critical.
type: bool
sample: false
description: List of certificates to be revoked.
returned: success
type: list
elements: dict
contains:
serial_number:
description:
- Serial number of the certificate.
- This return value is an B(integer). If you need the serial numbers as a colon-separated hex string, such as C(11:22:33),
you need to convert it to that form with P(community.crypto.to_serial#filter).
type: int
sample: 1234
revocation_date:
description: The point in time the certificate was revoked as ASN.1 TIME.
type: str
sample: 20190413202428Z
issuer:
description:
- The certificate's issuer.
- See O(name_encoding) for how IDNs are handled.
type: list
elements: str
sample: ["DNS:ca.example.org"]
issuer_critical:
description: Whether the certificate issuer extension is critical.
type: bool
sample: false
reason:
description:
- The value for the revocation reason extension.
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
sample: false
invalidity_date:
description: |-
The point in time it was known/suspected that the private key was compromised
or that the certificate otherwise became invalid as ASN.1 TIME.
type: str
sample: 20190413202428Z
invalidity_date_critical:
description: Whether the invalidity date extension is critical.
type: bool
sample: false
crl:
description:
- The (current or generated) CRL's content.
- 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
'''
description:
- The (current or generated) CRL's content.
- 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
"""
import base64

256
plugins/modules/x509_crl_info.py
View File

@@ -9,55 +9,53 @@ from __future__ import absolute_import, division, print_function
__metaclass__ = type
DOCUMENTATION = r'''
---
DOCUMENTATION = r"""
module: x509_crl_info
version_added: '1.0.0'
short_description: Retrieve information on Certificate Revocation Lists (CRLs)
description:
- This module allows one to retrieve information on Certificate Revocation Lists (CRLs).
- This module allows one to retrieve information on Certificate Revocation Lists (CRLs).
requirements:
- cryptography >= 1.2
- cryptography >= 1.2
author:
- Felix Fontein (@felixfontein)
- Felix Fontein (@felixfontein)
extends_documentation_fragment:
- community.crypto.attributes
- community.crypto.attributes.info_module
- community.crypto.name_encoding
- community.crypto.attributes
- community.crypto.attributes.info_module
- community.crypto.name_encoding
options:
path:
description:
- Remote absolute path where the generated CRL file should be created or is already located.
- 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 O(path) or O(content) must be specified, but not both.
type: str
list_revoked_certificates:
description:
- 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.
type: bool
default: true
version_added: 1.7.0
path:
description:
- Remote absolute path where the generated CRL file should be created or is already located.
- 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 O(path) or O(content) must be specified, but not both.
type: str
list_revoked_certificates:
description:
- 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.
type: bool
default: true
version_added: 1.7.0
notes:
- All timestamp values are provided in ASN.1 TIME format, in other words, following the C(YYYYMMDDHHMMSSZ) pattern.
They are all in UTC.
- All timestamp values are provided in ASN.1 TIME format, in other words, following the C(YYYYMMDDHHMMSSZ) pattern. They
are all in UTC.
seealso:
- module: community.crypto.x509_crl
- plugin: community.crypto.x509_crl_info
plugin_type: filter
description: A filter variant of this module.
- plugin: community.crypto.to_serial
plugin_type: filter
'''
- module: community.crypto.x509_crl
- plugin: community.crypto.x509_crl_info
plugin_type: filter
description: A filter variant of this module.
- plugin: community.crypto.to_serial
plugin_type: filter
"""
EXAMPLES = r'''
EXAMPLES = r"""
- name: Get information on CRL
community.crypto.x509_crl_info:
path: /etc/ssl/my-ca.crl
@@ -72,106 +70,106 @@ EXAMPLES = r'''
path: /etc/ssl/very-large.crl
list_revoked_certificates: false
register: result
'''
"""
RETURN = r'''
RETURN = r"""
format:
description:
- Whether the CRL is in PEM format (V(pem)) or in DER format (V(der)).
returned: success
type: str
sample: pem
choices:
- pem
- der
description:
- 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 O(name_encoding) for how IDNs are handled.
returned: success
type: dict
sample: {"organizationName": "Ansible", "commonName": "ca.example.com"}
description:
- The CRL's issuer.
- Note that for repeated values, only the last one will be returned.
- See O(name_encoding) for how IDNs are handled.
returned: success
type: dict
sample: {"organizationName": "Ansible", "commonName": "ca.example.com"}
issuer_ordered:
description: The CRL's issuer as an ordered list of tuples.
returned: success
type: list
elements: list
sample: [["organizationName", "Ansible"], ["commonName": "ca.example.com"]]
description: The CRL's issuer as an ordered list of tuples.
returned: success
type: list
elements: list
sample: [["organizationName", "Ansible"], ["commonName": "ca.example.com"]]
last_update:
description: The point in time from which this CRL can be trusted as ASN.1 TIME.
returned: success
type: str
sample: '20190413202428Z'
description: The point in time from which this CRL can be trusted as ASN.1 TIME.
returned: success
type: str
sample: '20190413202428Z'
next_update:
description: The point in time from which a new CRL will be issued and the client has to check for it as ASN.1 TIME.
returned: success
type: str
sample: '20190413202428Z'
description: The point in time from which a new CRL will be issued and the client has to check for it as ASN.1 TIME.
returned: success
type: str
sample: '20190413202428Z'
digest:
description: The signature algorithm used to sign the CRL.
returned: success
type: str
sample: sha256WithRSAEncryption
description: The signature algorithm used to sign the CRL.
returned: success
type: str
sample: sha256WithRSAEncryption
revoked_certificates:
description: List of certificates to be revoked.
returned: success if O(list_revoked_certificates=true)
type: list
elements: dict
contains:
serial_number:
description:
- Serial number of the certificate.
- This return value is an B(integer). If you need the serial numbers as a colon-separated hex string,
such as C(11:22:33), you need to convert it to that form with P(community.crypto.to_serial#filter).
type: int
sample: 1234
revocation_date:
description: The point in time the certificate was revoked as ASN.1 TIME.
type: str
sample: '20190413202428Z'
issuer:
description:
- The certificate's issuer.
- See O(name_encoding) for how IDNs are handled.
type: list
elements: str
sample: ["DNS:ca.example.org"]
issuer_critical:
description: Whether the certificate issuer extension is critical.
type: bool
sample: false
reason:
description:
- The value for the revocation reason extension.
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
sample: false
invalidity_date:
description: |
The point in time it was known/suspected that the private key was compromised
or that the certificate otherwise became invalid as ASN.1 TIME.
type: str
sample: '20190413202428Z'
invalidity_date_critical:
description: Whether the invalidity date extension is critical.
type: bool
sample: false
'''
description: List of certificates to be revoked.
returned: success if O(list_revoked_certificates=true)
type: list
elements: dict
contains:
serial_number:
description:
- Serial number of the certificate.
- This return value is an B(integer). If you need the serial numbers as a colon-separated hex string, such as C(11:22:33),
you need to convert it to that form with P(community.crypto.to_serial#filter).
type: int
sample: 1234
revocation_date:
description: The point in time the certificate was revoked as ASN.1 TIME.
type: str
sample: '20190413202428Z'
issuer:
description:
- The certificate's issuer.
- See O(name_encoding) for how IDNs are handled.
type: list
elements: str
sample: ["DNS:ca.example.org"]
issuer_critical:
description: Whether the certificate issuer extension is critical.
type: bool
sample: false
reason:
description:
- The value for the revocation reason extension.
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
sample: false
invalidity_date:
description: |-
The point in time it was known/suspected that the private key was compromised
or that the certificate otherwise became invalid as ASN.1 TIME.
type: str
sample: '20190413202428Z'
invalidity_date_critical:
description: Whether the invalidity date extension is critical.
type: bool
sample: false
"""
import base64