diff --git a/plugins/doc_fragments/acme.py b/plugins/doc_fragments/acme.py index e5ee3ec4e..0838ce9d5 100644 --- a/plugins/doc_fragments/acme.py +++ b/plugins/doc_fragments/acme.py @@ -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 @@ class ModuleDocFragment(object): 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 @@ class ModuleDocFragment(object): 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 @@ class ModuleDocFragment(object): 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 -''' +""" diff --git a/plugins/doc_fragments/attributes.py b/plugins/doc_fragments/attributes.py index 11f6b5754..815357121 100644 --- a/plugins/doc_fragments/attributes.py +++ b/plugins/doc_fragments/attributes.py @@ -11,14 +11,14 @@ 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 @@ class ModuleDocFragment(object): - 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 @@ class ModuleDocFragment(object): 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. +""" diff --git a/plugins/doc_fragments/ecs_credential.py b/plugins/doc_fragments/ecs_credential.py index 0b6d40371..90a28e4da 100644 --- a/plugins/doc_fragments/ecs_credential.py +++ b/plugins/doc_fragments/ecs_credential.py @@ -11,34 +11,34 @@ 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" +""" diff --git a/plugins/doc_fragments/module_certificate.py b/plugins/doc_fragments/module_certificate.py index 5691e7bbf..6dcb136b3 100644 --- a/plugins/doc_fragments/module_certificate.py +++ b/plugins/doc_fragments/module_certificate.py @@ -12,80 +12,79 @@ 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 - - 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_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 - - 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 ] + 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 + + 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 + + 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] 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: diff --git a/plugins/doc_fragments/module_csr.py b/plugins/doc_fragments/module_csr.py index e2a0bdd94..e9b7e3cdb 100644 --- a/plugins/doc_fragments/module_csr.py +++ b/plugins/doc_fragments/module_csr.py @@ -11,319 +11,306 @@ 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: - 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. + 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: + - 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 - aliases: [ keyUsage ] - key_usage_critical: - description: - - Should the keyUsage extension be considered as critical. - type: bool - default: false - aliases: [ keyUsage_critical ] - extended_key_usage: + relative_name: description: - - Additional restrictions (for example client authentication, server authentication) - on the allowed purposes for which the public key may be used. + - 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 - 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: + crl_issuer: description: - - Indicates basic constraints, such as if the certificate is a CA. + - Information about the issuer of the CRL. 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: + reasons: 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). + - List of reasons that this distribution point can be used for when performing revocation checks. 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 + choices: + - 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 +""" diff --git a/plugins/doc_fragments/module_privatekey.py b/plugins/doc_fragments/module_privatekey.py index 36a7bc977..fe89787d3 100644 --- a/plugins/doc_fragments/module_privatekey.py +++ b/plugins/doc_fragments/module_privatekey.py @@ -11,138 +11,130 @@ 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 +""" diff --git a/plugins/doc_fragments/module_privatekey_convert.py b/plugins/doc_fragments/module_privatekey_convert.py index 973d1fe00..63e7ce116 100644 --- a/plugins/doc_fragments/module_privatekey_convert.py +++ b/plugins/doc_fragments/module_privatekey_convert.py @@ -11,38 +11,37 @@ 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 +""" diff --git a/plugins/doc_fragments/name_encoding.py b/plugins/doc_fragments/name_encoding.py index b51408530..14c88bd57 100644 --- a/plugins/doc_fragments/name_encoding.py +++ b/plugins/doc_fragments/name_encoding.py @@ -9,23 +9,24 @@ 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. +""" diff --git a/plugins/filter/gpg_fingerprint.py b/plugins/filter/gpg_fingerprint.py index bd9d21ecb..7ce53473d 100644 --- a/plugins/filter/gpg_fingerprint.py +++ b/plugins/filter/gpg_fingerprint.py @@ -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 @@ 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 diff --git a/plugins/filter/openssl_csr_info.py b/plugins/filter/openssl_csr_info.py index c66f44b32..0485f90a2 100644 --- a/plugins/filter/openssl_csr_info.py +++ b/plugins/filter/openssl_csr_info.py @@ -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 @@ | 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 diff --git a/plugins/filter/openssl_privatekey_info.py b/plugins/filter/openssl_privatekey_info.py index 5ad928e2b..d9bbcabcb 100644 --- a/plugins/filter/openssl_privatekey_info.py +++ b/plugins/filter/openssl_privatekey_info.py @@ -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 @@ | 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 diff --git a/plugins/filter/openssl_publickey_info.py b/plugins/filter/openssl_publickey_info.py index c9994e867..e294e19b9 100644 --- a/plugins/filter/openssl_publickey_info.py +++ b/plugins/filter/openssl_publickey_info.py @@ -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 @@ | 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 diff --git a/plugins/filter/parse_serial.py b/plugins/filter/parse_serial.py index f78dc45d9..ed48c9f5e 100644 --- a/plugins/filter/parse_serial.py +++ b/plugins/filter/parse_serial.py @@ -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 @@ 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 diff --git a/plugins/filter/split_pem.py b/plugins/filter/split_pem.py index a58ce5060..eae46759f 100644 --- a/plugins/filter/split_pem.py +++ b/plugins/filter/split_pem.py @@ -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 diff --git a/plugins/filter/to_serial.py b/plugins/filter/to_serial.py index 78f337fdd..e49467957 100644 --- a/plugins/filter/to_serial.py +++ b/plugins/filter/to_serial.py @@ -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 @@ 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 diff --git a/plugins/filter/x509_certificate_info.py b/plugins/filter/x509_certificate_info.py index 7a18c2c0b..774e44a23 100644 --- a/plugins/filter/x509_certificate_info.py +++ b/plugins/filter/x509_certificate_info.py @@ -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 @@ | 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 diff --git a/plugins/filter/x509_crl_info.py b/plugins/filter/x509_crl_info.py index db1dc5369..d897b91ff 100644 --- a/plugins/filter/x509_crl_info.py +++ b/plugins/filter/x509_crl_info.py @@ -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 @@ | 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 diff --git a/plugins/lookup/gpg_fingerprint.py b/plugins/lookup/gpg_fingerprint.py index c562faed8..642e133a8 100644 --- a/plugins/lookup/gpg_fingerprint.py +++ b/plugins/lookup/gpg_fingerprint.py @@ -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 @@ 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 diff --git a/plugins/modules/acme_account.py b/plugins/modules/acme_account.py index 960bad313..1c7e2f359 100644 --- a/plugins/modules/acme_account.py +++ b/plugins/modules/acme_account.py @@ -9,21 +9,18 @@ __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 @@ 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 @@ - 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 @@ 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 @@ 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 @@ 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 diff --git a/plugins/modules/acme_account_info.py b/plugins/modules/acme_account_info.py index 33313fe75..00c82a9a5 100644 --- a/plugins/modules/acme_account_info.py +++ b/plugins/modules/acme_account_info.py @@ -9,21 +9,17 @@ __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 @@ 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 @@ 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 @@ - 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 @@ 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 @@ 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 @@ 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 @@ 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, diff --git a/plugins/modules/acme_ari_info.py b/plugins/modules/acme_ari_info.py index 7783236f0..52283f0d3 100644 --- a/plugins/modules/acme_ari_info.py +++ b/plugins/modules/acme_ari_info.py @@ -9,18 +9,16 @@ __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 @@ 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 @@ - 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 @@ 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 @@ 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, diff --git a/plugins/modules/acme_certificate.py b/plugins/modules/acme_certificate.py index 228090ae3..97c85a052 100644 --- a/plugins/modules/acme_certificate.py +++ b/plugins/modules/acme_certificate.py @@ -9,49 +9,37 @@ __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 @@ 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 @@ 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 @@ 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 @@ - 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 diff --git a/plugins/modules/acme_certificate_deactivate_authz.py b/plugins/modules/acme_certificate_deactivate_authz.py index 133f777d6..1503c6f55 100644 --- a/plugins/modules/acme_certificate_deactivate_authz.py +++ b/plugins/modules/acme_certificate_deactivate_authz.py @@ -9,21 +9,18 @@ __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 @@ - 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, diff --git a/plugins/modules/acme_certificate_renewal_info.py b/plugins/modules/acme_certificate_renewal_info.py index 1e2b16918..60ebe9506 100644 --- a/plugins/modules/acme_certificate_renewal_info.py +++ b/plugins/modules/acme_certificate_renewal_info.py @@ -9,16 +9,15 @@ __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 @@ 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 @@ - 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 @@ - 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 @@ 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 @@ returned: success, the certificate exists, and has an Authority Key Identifier X.509 extension type: str sample: aYhba4dGQEHhs3uEe6CuLN4ByNQ.AIdlQyE -''' +""" import os import random diff --git a/plugins/modules/acme_certificate_revoke.py b/plugins/modules/acme_certificate_revoke.py index 2661a1525..d6264cd79 100644 --- a/plugins/modules/acme_certificate_revoke.py +++ b/plugins/modules/acme_certificate_revoke.py @@ -9,27 +9,22 @@ __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 @@ 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 @@ 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, diff --git a/plugins/modules/acme_challenge_cert_helper.py b/plugins/modules/acme_challenge_cert_helper.py index edd2c3331..fa6bea1d9 100644 --- a/plugins/modules/acme_challenge_cert_helper.py +++ b/plugins/modules/acme_challenge_cert_helper.py @@ -9,16 +9,14 @@ __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 @@ 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 @@ 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 @@ - 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 diff --git a/plugins/modules/acme_inspect.py b/plugins/modules/acme_inspect.py index c7ee49765..c7bf0b19c 100644 --- a/plugins/modules/acme_inspect.py +++ b/plugins/modules/acme_inspect.py @@ -9,31 +9,24 @@ __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 @@ 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 @@ # 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 @@ 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": ';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": ';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 diff --git a/plugins/modules/certificate_complete_chain.py b/plugins/modules/certificate_complete_chain.py index 6e33009ea..83c616a42 100644 --- a/plugins/modules/certificate_complete_chain.py +++ b/plugins/modules/certificate_complete_chain.py @@ -9,78 +9,70 @@ __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: [] -''' - - -EXAMPLES = ''' + 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 = 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 @@ 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 @@ 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 diff --git a/plugins/modules/crypto_info.py b/plugins/modules/crypto_info.py index d776ac52c..a00652791 100644 --- a/plugins/modules/crypto_info.py +++ b/plugins/modules/crypto_info.py @@ -9,8 +9,7 @@ __metaclass__ = type -DOCUMENTATION = r''' ---- +DOCUMENTATION = r""" module: crypto_info author: "Felix Fontein (@felixfontein)" short_description: Retrieve cryptographic capabilities @@ -23,9 +22,9 @@ - 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 @@ - 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 @@ description: The complete output of C(openssl version). type: str sample: 'OpenSSL 1.1.1m 14 Dec 2021\n' -''' +""" import traceback diff --git a/plugins/modules/ecs_certificate.py b/plugins/modules/ecs_certificate.py index b325d614c..3214da322 100644 --- a/plugins/modules/ecs_certificate.py +++ b/plugins/modules/ecs_certificate.py @@ -9,355 +9,369 @@ __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 . only + the www.. value is accepted. If the CN of the certificate is www.. only the . + 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 . only the www.. value - is accepted. If the CN of the certificate is www.. only the . 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 + text11: + 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. + text12: + description: Custom text field (maximum 500 characters). type: str - choices: [ P1Y, P2Y, P3Y ] + 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 -''' - -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. + - 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. community.crypto.ecs_certificate: backup: true path: /etc/ssl/crt/ansible.com.crt @@ -372,10 +386,8 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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, diff --git a/plugins/modules/ecs_domain.py b/plugins/modules/ecs_domain.py index 0ee9380f1..93e76c3c1 100644 --- a/plugins/modules/ecs_domain.py +++ b/plugins/modules/ecs_domain.py @@ -9,87 +9,91 @@ __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 @@ 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 @@ 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 @@ 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 diff --git a/plugins/modules/get_certificate.py b/plugins/modules/get_certificate.py index ceb6f5b46..92ff82ac2 100644 --- a/plugins/modules/get_certificate.py +++ b/plugins/modules/get_certificate.py @@ -9,15 +9,15 @@ __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 @@ 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 @@ 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 @@ - 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ 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 @@ delegate_to: localhost run_once: true register: legacy_cert -''' +""" import atexit import base64 diff --git a/plugins/modules/luks_device.py b/plugins/modules/luks_device.py index 5c41eddd3..cf0be06ca 100644 --- a/plugins/modules/luks_device.py +++ b/plugins/modules/luks_device.py @@ -7,318 +7,269 @@ __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: - 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: + 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: - - "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: + - 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: - - "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)." + - Specify the iteration count used for the PBKDF. + - Mutually exclusive with O(pbkdf.iteration_time). 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: + algorithm: 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)." + - The algorithm to use. + - Only available for the LUKS 2 format. + choices: + - argon2i + - argon2id + - pbkdf2 type: str - version_added: '1.0.0' - remove_keyslot: + memory: 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." + - 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: '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: + parallel: 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." + - 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: '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 @@ 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 diff --git a/plugins/modules/openssh_cert.py b/plugins/modules/openssh_cert.py index 8e864cd7d..bda3673bc 100644 --- a/plugins/modules/openssh_cert.py +++ b/plugins/modules/openssh_cert.py @@ -9,197 +9,193 @@ __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 @@ 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 @@ 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 @@ 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 diff --git a/plugins/modules/openssh_keypair.py b/plugins/modules/openssh_keypair.py index 7bb35b27f..1263c684e 100644 --- a/plugins/modules/openssh_keypair.py +++ b/plugins/modules/openssh_keypair.py @@ -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 @@ 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 diff --git a/plugins/modules/openssl_csr.py b/plugins/modules/openssl_csr.py index 01a748e79..87853df31 100644 --- a/plugins/modules/openssl_csr.py +++ b/plugins/modules/openssl_csr.py @@ -10,71 +10,70 @@ __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 @@ 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 @@ 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 @@ - 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 diff --git a/plugins/modules/openssl_csr_info.py b/plugins/modules/openssl_csr_info.py index fc7eaf18e..5b3bc9848 100644 --- a/plugins/modules/openssl_csr_info.py +++ b/plugins/modules/openssl_csr_info.py @@ -10,56 +10,54 @@ __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 @@ - 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 diff --git a/plugins/modules/openssl_csr_pipe.py b/plugins/modules/openssl_csr_pipe.py index 0c42d5e78..682951652 100644 --- a/plugins/modules/openssl_csr_pipe.py +++ b/plugins/modules/openssl_csr_pipe.py @@ -10,49 +10,47 @@ __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 @@ 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 diff --git a/plugins/modules/openssl_dhparam.py b/plugins/modules/openssl_dhparam.py index d0d5e148d..159b65d29 100644 --- a/plugins/modules/openssl_dhparam.py +++ b/plugins/modules/openssl_dhparam.py @@ -9,89 +9,85 @@ __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 -''' - -EXAMPLES = r''' + - 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""" - name: Generate Diffie-Hellman parameters with the default size (4096 bits) community.crypto.openssl_dhparam: path: /etc/ssl/dhparams.pem @@ -105,30 +101,30 @@ 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 diff --git a/plugins/modules/openssl_pkcs12.py b/plugins/modules/openssl_pkcs12.py index 28efa0480..994543984 100644 --- a/plugins/modules/openssl_pkcs12.py +++ b/plugins/modules/openssl_pkcs12.py @@ -9,173 +9,163 @@ __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 -''' - -EXAMPLES = r''' + - 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""" - name: Generate PKCS#12 file community.crypto.openssl_pkcs12: action: export @@ -184,9 +174,9 @@ 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 @@ 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 @@ 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 diff --git a/plugins/modules/openssl_privatekey.py b/plugins/modules/openssl_privatekey.py index a55395d3f..32f6d820b 100644 --- a/plugins/modules/openssl_privatekey.py +++ b/plugins/modules/openssl_privatekey.py @@ -9,79 +9,76 @@ __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 @@ 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 diff --git a/plugins/modules/openssl_privatekey_convert.py b/plugins/modules/openssl_privatekey_convert.py index a09e3e10d..5f383a02a 100644 --- a/plugins/modules/openssl_privatekey_convert.py +++ b/plugins/modules/openssl_privatekey_convert.py @@ -9,60 +9,59 @@ __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 diff --git a/plugins/modules/openssl_privatekey_info.py b/plugins/modules/openssl_privatekey_info.py index 220bf988e..5b4dbc937 100644 --- a/plugins/modules/openssl_privatekey_info.py +++ b/plugins/modules/openssl_privatekey_info.py @@ -10,81 +10,76 @@ __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 @@ - 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 diff --git a/plugins/modules/openssl_privatekey_pipe.py b/plugins/modules/openssl_privatekey_pipe.py index 5ec2c4c60..925515bc3 100644 --- a/plugins/modules/openssl_privatekey_pipe.py +++ b/plugins/modules/openssl_privatekey_pipe.py @@ -9,93 +9,89 @@ __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 @@ 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 @@ - 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 +""" diff --git a/plugins/modules/openssl_publickey.py b/plugins/modules/openssl_publickey.py index 98eca22ac..041577253 100644 --- a/plugins/modules/openssl_publickey.py +++ b/plugins/modules/openssl_publickey.py @@ -9,104 +9,103 @@ __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 -''' - -EXAMPLES = r''' + - 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""" - name: Generate an OpenSSL public key in PEM format community.crypto.openssl_publickey: path: /etc/ssl/public/ansible.com.pem @@ -139,49 +138,49 @@ 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 diff --git a/plugins/modules/openssl_publickey_info.py b/plugins/modules/openssl_publickey_info.py index d6e28fdd0..8be4599a6 100644 --- a/plugins/modules/openssl_publickey_info.py +++ b/plugins/modules/openssl_publickey_info.py @@ -9,50 +9,49 @@ __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 - - 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 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] 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. -''' - -EXAMPLES = r''' + - 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""" - 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 @@ - 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 diff --git a/plugins/modules/openssl_signature.py b/plugins/modules/openssl_signature.py index 8236839c2..1881c8394 100644 --- a/plugins/modules/openssl_signature.py +++ b/plugins/modules/openssl_signature.py @@ -9,70 +9,67 @@ __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 @@ 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 diff --git a/plugins/modules/openssl_signature_info.py b/plugins/modules/openssl_signature_info.py index 2a5d3b3d9..8a9d631ba 100644 --- a/plugins/modules/openssl_signature_info.py +++ b/plugins/modules/openssl_signature_info.py @@ -9,63 +9,60 @@ __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 @@ 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 diff --git a/plugins/modules/x509_certificate.py b/plugins/modules/x509_certificate.py index f1c7d6b00..fc2a11c8f 100644 --- a/plugins/modules/x509_certificate.py +++ b/plugins/modules/x509_certificate.py @@ -10,99 +10,93 @@ __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 ] - - 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 ] - - 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 - - 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' + 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 + + 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' + + 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' 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 @@ - "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 diff --git a/plugins/modules/x509_certificate_convert.py b/plugins/modules/x509_certificate_convert.py index d3e39dc11..c9f1c6ab5 100644 --- a/plugins/modules/x509_certificate_convert.py +++ b/plugins/modules/x509_certificate_convert.py @@ -9,96 +9,92 @@ __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 -''' - -EXAMPLES = r''' + - 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""" - 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 diff --git a/plugins/modules/x509_certificate_info.py b/plugins/modules/x509_certificate_info.py index 9e8c20e29..2c9bf0b00 100644 --- a/plugins/modules/x509_certificate_info.py +++ b/plugins/modules/x509_certificate_info.py @@ -10,78 +10,74 @@ __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 -''' - -EXAMPLES = r''' + - 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""" - name: Generate a Self Signed OpenSSL certificate community.crypto.x509_certificate: path: /etc/ssl/crt/ansible.com.crt @@ -118,284 +114,280 @@ - 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 diff --git a/plugins/modules/x509_certificate_pipe.py b/plugins/modules/x509_certificate_pipe.py index a968ef4c3..a4caa0b12 100644 --- a/plugins/modules/x509_certificate_pipe.py +++ b/plugins/modules/x509_certificate_pipe.py @@ -11,55 +11,52 @@ __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 - - content: - description: - - The existing certificate. - type: str + 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 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 @@ 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 diff --git a/plugins/modules/x509_crl.py b/plugins/modules/x509_crl.py index 2fc71c246..30917adee 100644 --- a/plugins/modules/x509_crl.py +++ b/plugins/modules/x509_crl.py @@ -9,298 +9,284 @@ __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: - description: - - Remote absolute path where the generated CRL file should be created or is already located. - type: path - required: true + 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 + 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_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_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 + privatekey_passphrase: + description: + - The passphrase for the O(privatekey_path). + - This is required if the private key is password protected. + type: str - issuer: + 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: - - 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: + - 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: - - 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: + - 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 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: - 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: + - 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 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. + - Whether the revocation reason extension should be critical. type: bool default: false - - return_content: + invalidity_date: description: - - If set to V(true), will return the (current or generated) CRL's content as RV(crl). + - 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 -notes: - - All ASN.1 TIME values should be specified following the YYYYMMDDHHMMSSZ pattern. - - Date specified should be UTC. Minutes and seconds are mandatory. + 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. 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 @@ 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 diff --git a/plugins/modules/x509_crl_info.py b/plugins/modules/x509_crl_info.py index 2cf25f530..363bba377 100644 --- a/plugins/modules/x509_crl_info.py +++ b/plugins/modules/x509_crl_info.py @@ -9,55 +9,53 @@ __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 -''' - -EXAMPLES = r''' + - 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""" - name: Get information on CRL community.crypto.x509_crl_info: path: /etc/ssl/my-ca.crl @@ -72,106 +70,106 @@ 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