' + - '' + - _("Hide Search Matches") + - "
" - ) - ); - }, - - /** - * helper function to hide the search marks again - */ - hideSearchWords: () => { - document - .querySelectorAll("#searchbox .highlight-link") - .forEach((el) => el.remove()); - document - .querySelectorAll("span.highlighted") - .forEach((el) => el.classList.remove("highlighted")); - localStorage.removeItem("sphinx_highlight_terms") - }, - - initEscapeListener: () => { - // only install a listener if it is really needed - if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS) return; - - document.addEventListener("keydown", (event) => { - // bail for input elements - if (BLACKLISTED_KEY_CONTROL_ELEMENTS.has(document.activeElement.tagName)) return; - // bail with special keys - if (event.shiftKey || event.altKey || event.ctrlKey || event.metaKey) return; - if (DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS && (event.key === "Escape")) { - SphinxHighlight.hideSearchWords(); - event.preventDefault(); - } - }); - }, -}; - -_ready(() => { - /* Do not call highlightSearchWords() when we are on the search page. - * It will highlight words from the *previous* search query. - */ - if (typeof Search === "undefined") SphinxHighlight.highlightSearchWords(); - SphinxHighlight.initEscapeListener(); -}); diff --git a/pr/965/acme_account_facts_module.html b/pr/965/acme_account_facts_module.html deleted file mode 100644 index 3989b683..00000000 --- a/pr/965/acme_account_facts_module.html +++ /dev/null @@ -1,203 +0,0 @@ - - - - - - - - - -
- Note
-This plugin was part of the community.crypto collection (version 2.26.6).
-This module has been removed -in version 2.0.0 of community.crypto. -The ‘community.crypto.acme_account_facts’ module has been renamed to ‘community.crypto.acme_account_info’.
-
- Note
-This module is part of the community.crypto collection (version 2.26.6).
-It is not included in ansible-core.
-To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install community.crypto.
-You need further requirements to be able to use this module,
-see Requirements for details.
To use it in a playbook, specify: community.crypto.acme_account_info.
Allows to retrieve information on accounts a CA supporting the ACME protocol, such as Let’s Encrypt.
This module only works with the ACME v2 protocol.
The below requirements are needed on the host that executes this module.
-either openssl or cryptography >= 1.5
ipaddress
Parameter |
-Comments |
-
|---|---|
| - | Content of the ACME account RSA or Elliptic Curve key. -For Elliptic Curve keys only the following curves are supported: Mutually exclusive with Required if 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 |
-
| - | Phassphrase to use to decode the account key. -Note: this is not supported by the |
-
| - | Path to a file containing the ACME account RSA or Elliptic Curve key. -For Elliptic Curve keys only the following curves are supported: Private keys can be created with the community.crypto.openssl_privatekey or community.crypto.openssl_privatekey_pipe modules. If the requisite (cryptography) is not available, keys can also be created directly with the Mutually exclusive with Required if |
-
| - | 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. - |
-
| - | 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: https://letsencrypt.org/docs/staging-environment/. -For Let’s Encrypt, the production directory URL for ACME v2 is https://acme-v02.api.letsencrypt.org/directory. -For ZeroSSL, the production directory URL for ACME v2 is https://acme.zerossl.com/v2/DV90. -For Sectigo, the production directory URL for ACME v2 is https://acme-qa.secure.trust-provider.com/v2/DV. -For HARICA, the production directory URL for ACME v2 is https://acme.harica.gr/XXX/directory with XXX being specific to your account. -The notes for this module contain a list of ACME services this module has been tested against. - |
-
| - | The ACME version of the endpoint. -Must be The value Choices: -
|
-
| - | The time Ansible should wait for a response from the ACME API. -This timeout is applied to all HTTP(S) requests (HEAD, GET, POST). -Default: |
-
| - | Whether to retrieve the list of order URLs or order objects, if provided by the ACME server. -A value of If the value is not Currently, Let’s Encrypt does not return orders, so the Choices: -
|
-
| - | Determines which crypto backend to use. -The default choice is If set to If set to Choices: -
|
-
| - | Whether calls to the ACME directory will validate TLS certificates. -Warning: Should only ever be set to Choices: -
|
-
Attribute |
-Support |
-Description |
-
|---|---|---|
| - | Action groups: community.crypto.acme, acme - |
-Use |
-
| - | Support: full -This action does not modify state. - |
-Can run in |
-
| - | Support: N/A -This action does not modify state. - |
-Will return details on what has changed (or possibly needs changing in |
-
| - | Support: full -This action does not modify state. - |
-When run twice in a row outside check mode, with the same arguments, the second invocation indicates no change. -This assumes that the system controlled/queried by the module has not changed in a relevant way. - |
-
Note
-The community.crypto.acme_account module allows to modify, create and delete ACME accounts.
This module was called acme_account_facts before Ansible 2.8. The usage did not change.
Although the defaults are chosen so that the module can be used with the Let’s Encrypt CA, the module can in principle be used with any CA providing an ACME endpoint.
So far, the ACME modules have only been tested by the developers against Let’s Encrypt (staging and production), ZeroSSL (production), and Pebble testing server. We have got community feedback that they also work with Sectigo ACME Service for InCommon and with HARICA. If you experience problems with another ACME server, please create an issue to help us supporting it. Feedback that an ACME server not mentioned does work is also appreciated.
If a new enough version of the cryptography library is available (see Requirements for details), it will be used instead of the openssl binary. This can be explicitly disabled or enabled with the select_crypto_backend option. Note that using the openssl binary will be slower and less secure, as private key contents always have to be stored on disk (see account_key_content).
See also
-Allows to create, modify or delete an ACME account.
----
-- 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
- register: account_data
-- name: Verify that account exists
- ansible.builtin.assert:
- that:
- - account_data.exists
-- name: Print account URI
- ansible.builtin.debug:
- var: account_data.account_uri
-- name: Print account contacts
- ansible.builtin.debug:
- var: account_data.account.contact
-
-- name: Check whether the account exists and is accessible with the given account key
- acme_account_info:
- account_key_content: "{{ acme_account_key }}"
- account_uri: "{{ acme_account_uri }}"
- register: account_data
-- name: Verify that account exists
- ansible.builtin.assert:
- that:
- - account_data.exists
-- name: Print account contacts
- ansible.builtin.debug:
- var: account_data.account.contact
-Common return values are documented here, the following are the fields unique to this module:
-Key |
-Description |
-
|---|---|
| - | The account information, as retrieved from the ACME server. -Returned: if account exists - |
-
| - | The challenge resource that must be created for validation. -Returned: always -Sample: |
-
| - | A URL where a list of orders can be retrieved for this account. -Use the Returned: always -Sample: |
-
| - | The public account key as a JSON Web Key. -Returned: always -Sample: |
-
| - | The account’s status. -Returned: always -Can only return: -
Sample: |
-
| - | ACME account URI, or None if account does not exist. -Returned: always - |
-
| - | Whether the account exists. -Returned: always - |
-
| - | The list of orders. -If If Returned: if account exists, |
-
| - | The list of orders. -Returned: if account exists, |
-
| - | A list of URLs for authorizations for this order. -Returned: success - |
-
| - | The URL for retrieving the certificate. -Returned: when certificate was issued - |
-
| - | In case an error occurred during processing, this contains information about the error. -The field is structured as a problem document (RFC7807). -Returned: when an error occurred - |
-
| - | When the order expires. -Timestamp should be formatted as described in RFC3339. -Only required to be included in result when Returned: when server gives expiry date - |
-
| - | A URL used for finalizing an ACME order. -Returned: success - |
-
| - | List of identifiers this order is for. -Returned: success - |
-
| - | Type of identifier. -Returned: success -Can only return: -
|
-
| - | Name of identifier. Hostname or IP address. -Returned: success - |
-
| - | Whether Returned: required to be included if the identifier is wildcarded - |
-
| - | The requested value of the Date should be formatted as described in RFC3339. -Server is not required to return this. -Returned: when server returns this - |
-
| - | The requested value of the Date should be formatted as described in RFC3339. -Server is not required to return this. -Returned: when server returns this - |
-
| - | The order’s status. -Returned: success -Can only return: -
|
-
- Note
-This module is part of the community.crypto collection (version 2.26.6).
-It is not included in ansible-core.
-To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install community.crypto.
-You need further requirements to be able to use this module,
-see Requirements for details.
To use it in a playbook, specify: community.crypto.acme_account.
Allows to create, modify or delete accounts with a CA supporting the ACME protocol, such as Let’s Encrypt.
This module only works with the ACME v2 protocol.
The below requirements are needed on the host that executes this module.
-either openssl or cryptography >= 1.5
ipaddress
Parameter |
-Comments |
-
|---|---|
| - | Content of the ACME account RSA or Elliptic Curve key. -For Elliptic Curve keys only the following curves are supported: Mutually exclusive with Required if 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 |
-
| - | Phassphrase to use to decode the account key. -Note: this is not supported by the |
-
| - | Path to a file containing the ACME account RSA or Elliptic Curve key. -For Elliptic Curve keys only the following curves are supported: Private keys can be created with the community.crypto.openssl_privatekey or community.crypto.openssl_privatekey_pipe modules. If the requisite (cryptography) is not available, keys can also be created directly with the Mutually exclusive with Required if |
-
| - | 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. - |
-
| - | 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: https://letsencrypt.org/docs/staging-environment/. -For Let’s Encrypt, the production directory URL for ACME v2 is https://acme-v02.api.letsencrypt.org/directory. -For ZeroSSL, the production directory URL for ACME v2 is https://acme.zerossl.com/v2/DV90. -For Sectigo, the production directory URL for ACME v2 is https://acme-qa.secure.trust-provider.com/v2/DV. -For HARICA, the production directory URL for ACME v2 is https://acme.harica.gr/XXX/directory with XXX being specific to your account. -The notes for this module contain a list of ACME services this module has been tested against. - |
-
| - | The ACME version of the endpoint. -Must be The value Choices: -
|
-
| - | Whether account creation is allowed (when state is Choices: -
|
-
| - | A list of contact URLs. -Email addresses must be prefixed with See https://tools.ietf.org/html/rfc8555#section-7.3 for what is allowed. -Must be specified when state is Default: |
-
| - | Allows to provide external account binding data during account creation. -This is used by CAs like Sectigo, HARICA, or ZeroSSL 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. - |
-
| - | The MAC algorithm provided by the CA. -If not specified by the CA, this is probably Choices: -
|
-
| - | Base64 URL encoded value of the MAC key provided by the CA. -Padding ( |
-
| - | The key identifier provided by the CA. - |
-
| - | Content of the ACME account RSA or Elliptic Curve key to change to. -Same restrictions apply as to Mutually exclusive with Required if |
-
| - | Phassphrase to use to decode the new account key. -Note: this is not supported by the |
-
| - | Path to a file containing the ACME account RSA or Elliptic Curve key to change to. -Same restrictions apply as to Mutually exclusive with Required if |
-
| - | The time Ansible should wait for a response from the ACME API. -This timeout is applied to all HTTP(S) requests (HEAD, GET, POST). -Default: |
-
| - | Determines which crypto backend to use. -The default choice is If set to If set to Choices: -
|
-
| - | The state of the account, to be identified by its account key. -If the state is If the state is Choices: -
|
-
| - | Boolean indicating whether you agree to the terms of service document. -ACME servers can require this to be Choices: -
|
-
| - | Whether calls to the ACME directory will validate TLS certificates. -Warning: Should only ever be set to Choices: -
|
-
Attribute |
-Support |
-Description |
-
|---|---|---|
| - | Action groups: community.crypto.acme, acme - |
-Use |
-
| - | Support: full - |
-Can run in |
-
| - | Support: full - |
-Will return details on what has changed (or possibly needs changing in |
-
| - | Support: partial -If |
-When run twice in a row outside check mode, with the same arguments, the second invocation indicates no change. -This assumes that the system controlled/queried by the module has not changed in a relevant way. - |
-
Note
-The community.crypto.acme_certificate module also allows to do basic account management. When using both modules, it is recommended to disable account management for community.crypto.acme_certificate. For that, use the modify_account option of community.crypto.acme_certificate.
Although the defaults are chosen so that the module can be used with the Let’s Encrypt CA, the module can in principle be used with any CA providing an ACME endpoint.
So far, the ACME modules have only been tested by the developers against Let’s Encrypt (staging and production), ZeroSSL (production), and Pebble testing server. We have got community feedback that they also work with Sectigo ACME Service for InCommon and with HARICA. If you experience problems with another ACME server, please create an issue to help us supporting it. Feedback that an ACME server not mentioned does work is also appreciated.
If a new enough version of the cryptography library is available (see Requirements for details), it will be used instead of the openssl binary. This can be explicitly disabled or enabled with the select_crypto_backend option. Note that using the openssl binary will be slower and less secure, as private key contents always have to be stored on disk (see account_key_content).
See also
-The specification of the ACME protocol (RFC 8555).
-Retrieves facts about an ACME account.
-Can be used to create a private account key.
-Can be used to create a private account key without writing it to disk.
-Allows to debug problems.
----
-- 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
-
-- name: Make sure account has given email address. Do not create account if it does not exist
- community.crypto.acme_account:
- account_key_src: /etc/pki/cert/private/account.key
- state: present
- allow_creation: false
- contact:
- - mailto:me@example.com
-
-- name: Change account's key to the one stored in the variable new_account_key
- community.crypto.acme_account:
- account_key_src: /etc/pki/cert/private/account.key
- new_account_key_content: '{{ new_account_key }}'
- state: changed_key
-
-- name: Delete account (we have to use the new key)
- community.crypto.acme_account:
- account_key_content: '{{ new_account_key }}'
- state: absent
-Common return values are documented here, the following are the fields unique to this module:
-Key |
-Description |
-
|---|---|
| - | ACME account URI, or None if account does not exist. -Returned: always - |
-
- Note
-This module is part of the community.crypto collection (version 2.26.6).
-It is not included in ansible-core.
-To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install community.crypto.
-You need further requirements to be able to use this module,
-see Requirements for details.
To use it in a playbook, specify: community.crypto.acme_ari_info.
New in community.crypto 2.20.0
- -Allows to retrieve renewal information on a certificate obtained with the ACME protocol.
This module only works with the ACME v2 protocol, and requires the ACME server to support the ARI extension (RFC 9773).
The below requirements are needed on the host that executes this module.
-either openssl or cryptography >= 1.5
ipaddress
Parameter |
-Comments |
-
|---|---|
| - | 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: https://letsencrypt.org/docs/staging-environment/. -For Let’s Encrypt, the production directory URL for ACME v2 is https://acme-v02.api.letsencrypt.org/directory. -For ZeroSSL, the production directory URL for ACME v2 is https://acme.zerossl.com/v2/DV90. -For Sectigo, the production directory URL for ACME v2 is https://acme-qa.secure.trust-provider.com/v2/DV. -For HARICA, the production directory URL for ACME v2 is https://acme.harica.gr/XXX/directory with XXX being specific to your account. -The notes for this module contain a list of ACME services this module has been tested against. - |
-
| - | The ACME version of the endpoint. -Must be The value Choices: -
|
-
| - | The content of the X.509 certificate to request information for. -Exactly one of |
-
| - | A path to the X.509 certificate to request information for. -Exactly one of |
-
| - | The time Ansible should wait for a response from the ACME API. -This timeout is applied to all HTTP(S) requests (HEAD, GET, POST). -Default: |
-
| - | Determines which crypto backend to use. -The default choice is If set to If set to Choices: -
|
-
| - | Whether calls to the ACME directory will validate TLS certificates. -Warning: Should only ever be set to Choices: -
|
-
Attribute |
-Support |
-Description |
-
|---|---|---|
| - | Support: full -This action does not modify state. - |
-Can run in |
-
| - | Support: N/A -This action does not modify state. - |
-Will return details on what has changed (or possibly needs changing in |
-
| - | Support: full -This action does not modify state. - |
-When run twice in a row outside check mode, with the same arguments, the second invocation indicates no change. -This assumes that the system controlled/queried by the module has not changed in a relevant way. - |
-
Note
-Although the defaults are chosen so that the module can be used with the Let’s Encrypt CA, the module can in principle be used with any CA providing an ACME endpoint.
So far, the ACME modules have only been tested by the developers against Let’s Encrypt (staging and production), ZeroSSL (production), and Pebble testing server. We have got community feedback that they also work with Sectigo ACME Service for InCommon and with HARICA. If you experience problems with another ACME server, please create an issue to help us supporting it. Feedback that an ACME server not mentioned does work is also appreciated.
If a new enough version of the cryptography library is available (see Requirements for details), it will be used instead of the openssl binary. This can be explicitly disabled or enabled with the select_crypto_backend option. Note that using the openssl binary will be slower.
See also
-Allows to obtain a certificate using the ACME protocol.
-Allows to revoke a certificate using the ACME protocol.
----
-- name: Retrieve renewal information for a certificate
- community.crypto.acme_ari_info:
- certificate_path: /etc/httpd/ssl/sample.com.crt
- register: cert_data
-
-- name: Show the certificate renewal information
- ansible.builtin.debug:
- var: cert_data.renewal_info
-Common return values are documented here, the following are the fields unique to this module:
-Key |
-Description |
-
|---|---|
| - | The ARI renewal info object (https://www.rfc-editor.org/rfc/rfc9773.html#section-4.2). -Returned: success - |
-
| - | 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. -Returned: depends on the ACME server -Sample: |
-
| - | A timestamp before the next retry to ask for this information should not be made. -Returned: depends on the ACME server -Sample: |
-
| - | Describes the window during which the certificate should be renewed. -Returned: always - |
-
| - | The end of the window during which the certificate should be renewed. -The format is specified in RFC 3339. -Returned: always -Sample: |
-
| - | The start of the window during which the certificate should be renewed. -The format is specified in RFC 3339. -Returned: always -Sample: |
-
- Note
-This module is part of the community.crypto collection (version 2.26.6).
-It is not included in ansible-core.
-To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install community.crypto.
-You need further requirements to be able to use this module,
-see Requirements for details.
To use it in a playbook, specify: community.crypto.acme_certificate_deactivate_authz.
New in community.crypto 2.20.0
- -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 include_renewal_cert_id.
The below requirements are needed on the host that executes this module.
-either openssl or cryptography >= 1.5
ipaddress
Parameter |
-Comments |
-
|---|---|
| - | Content of the ACME account RSA or Elliptic Curve key. -For Elliptic Curve keys only the following curves are supported: Mutually exclusive with Required if 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 |
-
| - | Phassphrase to use to decode the account key. -Note: this is not supported by the |
-
| - | Path to a file containing the ACME account RSA or Elliptic Curve key. -For Elliptic Curve keys only the following curves are supported: Private keys can be created with the community.crypto.openssl_privatekey or community.crypto.openssl_privatekey_pipe modules. If the requisite (cryptography) is not available, keys can also be created directly with the Mutually exclusive with Required if |
-
| - | 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. - |
-
| - | 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: https://letsencrypt.org/docs/staging-environment/. -For Let’s Encrypt, the production directory URL for ACME v2 is https://acme-v02.api.letsencrypt.org/directory. -For ZeroSSL, the production directory URL for ACME v2 is https://acme.zerossl.com/v2/DV90. -For Sectigo, the production directory URL for ACME v2 is https://acme-qa.secure.trust-provider.com/v2/DV. -For HARICA, the production directory URL for ACME v2 is https://acme.harica.gr/XXX/directory with XXX being specific to your account. -The notes for this module contain a list of ACME services this module has been tested against. - |
-
| - | The ACME version of the endpoint. -Must be The value Choices: -
|
-
| - | The ACME v2 order to deactivate. -Can be obtained from |
-
| - | The time Ansible should wait for a response from the ACME API. -This timeout is applied to all HTTP(S) requests (HEAD, GET, POST). -Default: |
-
| - | Determines which crypto backend to use. -The default choice is If set to If set to Choices: -
|
-
| - | Whether calls to the ACME directory will validate TLS certificates. -Warning: Should only ever be set to Choices: -
|
-
Attribute |
-Support |
-Description |
-
|---|---|---|
| - | Action groups: community.crypto.acme, acme - |
-Use |
-
| - | Support: full - |
-Can run in |
-
| - | Support: none - |
-Will return details on what has changed (or possibly needs changing in |
-
| - | Support: full - |
-When run twice in a row outside check mode, with the same arguments, the second invocation indicates no change. -This assumes that the system controlled/queried by the module has not changed in a relevant way. - |
-
Note
-Although the defaults are chosen so that the module can be used with the Let’s Encrypt CA, the module can in principle be used with any CA providing an ACME endpoint.
So far, the ACME modules have only been tested by the developers against Let’s Encrypt (staging and production), ZeroSSL (production), and Pebble testing server. We have got community feedback that they also work with Sectigo ACME Service for InCommon and with HARICA. If you experience problems with another ACME server, please create an issue to help us supporting it. Feedback that an ACME server not mentioned does work is also appreciated.
If a new enough version of the cryptography library is available (see Requirements for details), it will be used instead of the openssl binary. This can be explicitly disabled or enabled with the select_crypto_backend option. Note that using the openssl binary will be slower and less secure, as private key contents always have to be stored on disk (see account_key_content).
See also
-Create SSL/TLS certificates with the ACME protocol.
----
-- 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 }}"
-
- Note
-This module is part of the community.crypto collection (version 2.26.6).
-It is not included in ansible-core.
-To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install community.crypto.
-You need further requirements to be able to use this module,
-see Requirements for details.
To use it in a playbook, specify: community.crypto.acme_certificate.
Create and renew SSL/TLS certificates with a CA supporting the ACME protocol, such as Let’s Encrypt. The current implementation supports the http-01, dns-01 and 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 data.
Between these two tasks you have to fulfill the required steps for the chosen challenge by whatever means necessary. For http-01 that means creating the necessary challenge file on the destination webserver. For dns-01 the necessary DNS record has to be created. For tls-alpn-01 the necessary certificate has to be created and served. It is not the responsibility of this module to perform these steps.
For details on how to fulfill these challenges, you might have to read through the main ACME specification and the TLS-ALPN-01 specification. Also, consider the examples provided for this module.
The module includes experimental support for IP identifiers according to the RFC 8738.
The below requirements are needed on the host that executes this module.
-either openssl or cryptography >= 1.5
ipaddress
Parameter |
-Comments |
-
|---|---|
| - | The email address associated with this account. -It will be used for certificate expiration warnings. -Note that when |
-
| - | Content of the ACME account RSA or Elliptic Curve key. -For Elliptic Curve keys only the following curves are supported: Mutually exclusive with Required if 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 |
-
| - | Phassphrase to use to decode the account key. -Note: this is not supported by the |
-
| - | Path to a file containing the ACME account RSA or Elliptic Curve key. -For Elliptic Curve keys only the following curves are supported: Private keys can be created with the community.crypto.openssl_privatekey or community.crypto.openssl_privatekey_pipe modules. If the requisite (cryptography) is not available, keys can also be created directly with the Mutually exclusive with Required if |
-
| - | 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. - |
-
| - | 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: https://letsencrypt.org/docs/staging-environment/. -For Let’s Encrypt, the production directory URL for ACME v2 is https://acme-v02.api.letsencrypt.org/directory. -For ZeroSSL, the production directory URL for ACME v2 is https://acme.zerossl.com/v2/DV90. -For Sectigo, the production directory URL for ACME v2 is https://acme-qa.secure.trust-provider.com/v2/DV. -For HARICA, the production directory URL for ACME v2 is https://acme.harica.gr/XXX/directory with XXX being specific to your account. -The notes for this module contain a list of ACME services this module has been tested against. - |
-
| - | The ACME version of the endpoint. -Must be The value Choices: -
|
-
| - | URI to a terms of service document you agree to when using the ACME v1 service at Default is latest gathered from This option will only be used when |
-
| - | If specified, the intermediate certificate will be written to this file. - |
-
| - | The challenge to be performed. -If set to Choices: -
|
-
| - | File containing the CSR for the new certificate. -Can be created with 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. -Note: the private key used to create the CSR 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 |
-
| - | Content of the CSR for the new certificate. -Can be created with 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. -Note: the private key used to create the CSR 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 |
-
| - | 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 Note: the |
-
| - | 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. -Choices: -
|
-
| - | The destination file for the certificate. -Required if |
-
| - | Enforces the execution of the challenge and validation, even if an existing certificate is still valid for more than This is especially helpful when having an updated CSR, for example with additional domains for which a new certificate is desired. -Choices: -
|
-
| - | The destination file for the full chain (that is, a certificate followed by chain of intermediate certificates). -Required if |
-
| - | Determines whether to request renewal of an existing certificate according to Section 5 of RFC 9773. -This is only used when the certificate specified in Generally you should use ACME servers might refuse to create new orders with If Choices: -
|
-
| - | Boolean indicating whether the module should create the account if necessary, and update its contact data. -Set to If set to Choices: -
|
-
| - | Selects the error handling strategy for ACME protocol errors if creating a new ACME order fails. -Choices: -
|
-
| - | Depending on the strategy selected in Default: |
-
| - | Chose a specific profile for certificate selection. The available profiles depend on the CA. -See a blog post by Let’s Encrypt and draft-aaron-acme-profiles-00 for more information. - |
-
| - | The number of days the certificate must have left being valid. If To make sure that the certificate is renewed in any case, you can use the Default: |
-
| - | The time Ansible should wait for a response from the ACME API. -This timeout is applied to all HTTP(S) requests (HEAD, GET, POST). -Default: |
-
| - | When set to Choices: -
|
-
| - | 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 Every criterium can consist of multiple different conditions, like This option can only be used with the |
-
| - | 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 |
-
| - | Allows to specify parts of the issuer of a certificate in the chain must have to be selected. -If An example value would be |
-
| - | Allows to specify parts of the subject of a certificate in the chain must have to be selected. -If An example value would be |
-
| - | 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 |
-
| - | Determines which certificates in the chain will be tested. -
Choices: -
|
-
| - | Determines which crypto backend to use. -The default choice is If set to If set to Choices: -
|
-
| - | 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 Choices: -
|
-
| - | Whether calls to the ACME directory will validate TLS certificates. -Warning: Should only ever be set to Choices: -
|
-
Attribute |
-Support |
-Description |
-
|---|---|---|
| - | Action groups: community.crypto.acme, acme - |
-Use |
-
| - | Support: full - |
-Can run in |
-
| - | Support: none - |
-Will return details on what has changed (or possibly needs changing in |
-
| - | Support: partial -If The second phase invocation of the module is always idempotent, assuming no error occurs. - |
-When run twice in a row outside check mode, with the same arguments, the second invocation indicates no change. -This assumes that the system controlled/queried by the module has not changed in a relevant way. - |
-
| - | Support: full - |
-Uses Ansible’s strict file operation functions to ensure proper permissions and avoid data corruption. - |
-
Note
-At least one of dest and 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 community.crypto.acme_account module and disable account management for this module using the modify_account option.
This module was called letsencrypt before Ansible 2.6. The usage did not change.
Although the defaults are chosen so that the module can be used with the Let’s Encrypt CA, the module can in principle be used with any CA providing an ACME endpoint.
So far, the ACME modules have only been tested by the developers against Let’s Encrypt (staging and production), ZeroSSL (production), and Pebble testing server. We have got community feedback that they also work with Sectigo ACME Service for InCommon and with HARICA. If you experience problems with another ACME server, please create an issue to help us supporting it. Feedback that an ACME server not mentioned does work is also appreciated.
If a new enough version of the cryptography library is available (see Requirements for details), it will be used instead of the openssl binary. This can be explicitly disabled or enabled with the select_crypto_backend option. Note that using the openssl binary will be slower and less secure, as private key contents always have to be stored on disk (see account_key_content).
See also
-Documentation for the Let’s Encrypt Certification Authority. Provides useful information for example on rate limits.
-The specification of the ACME protocol (RFC 8555).
-The specification of the tls-alpn-01 challenge (RFC 8737).
Helps preparing tls-alpn-01 challenges.
Can be used to create private keys (both for certificates and accounts).
-Can be used to create private keys without writing it to disk (both for certificates and accounts).
-Can be used to create a Certificate Signing Request (CSR).
-Can be used to create a Certificate Signing Request (CSR) without writing it to disk.
-Allows to find the root certificate for the returned fullchain.
-Allows to revoke certificates.
-Allows to create, modify or delete an ACME account.
-Allows to debug problems.
-Allows to deactivate (invalidate) ACME v2 orders.
----
-### Example with HTTP challenge ###
-
-- name: Create a challenge for sample.com using a account key from a variable.
- community.crypto.acme_certificate:
- account_key_content: "{{ account_private_key }}"
- csr: /etc/pki/cert/csr/sample.com.csr
- dest: /etc/httpd/ssl/sample.com.crt
- register: sample_com_challenge
-
-# Alternative first step:
-- name: Create a challenge for sample.com using a account key from Hashi Vault.
- community.crypto.acme_certificate:
- account_key_content: >-
- {{ lookup('community.hashi_vault.hashi_vault', 'secret=secret/account_private_key:value') }}
- csr: /etc/pki/cert/csr/sample.com.csr
- fullchain_dest: /etc/httpd/ssl/sample.com-fullchain.crt
- register: sample_com_challenge
-
-# Alternative first step:
-- name: Create a challenge for sample.com using a account key file.
- community.crypto.acme_certificate:
- account_key_src: /etc/pki/cert/private/account.key
- csr_content: "{{ lookup('file', '/etc/pki/cert/csr/sample.com.csr') }}"
- dest: /etc/httpd/ssl/sample.com.crt
- fullchain_dest: /etc/httpd/ssl/sample.com-fullchain.crt
- register: sample_com_challenge
-
-# perform the necessary steps to fulfill the challenge
-# for example:
-#
-# - name: Copy http-01 challenge for sample.com
-# ansible.builtin.copy:
-# dest: /var/www/html/{{ sample_com_challenge['challenge_data']['sample.com']['http-01']['resource'] }}
-# content: "{{ sample_com_challenge['challenge_data']['sample.com']['http-01']['resource_value'] }}"
-# when: sample_com_challenge is changed and 'sample.com' in sample_com_challenge['challenge_data']
-#
-# Alternative way:
-#
-# - name: Copy http-01 challenges
-# ansible.builtin.copy:
-# dest: /var/www/{{ item.key }}/{{ item.value['http-01']['resource'] }}
-# content: "{{ item.value['http-01']['resource_value'] }}"
-# loop: "{{ sample_com_challenge.challenge_data | dict2items }}"
-# when: sample_com_challenge is changed
-
-- name: Let the challenge be validated and retrieve the cert and intermediate certificate
- community.crypto.acme_certificate:
- account_key_src: /etc/pki/cert/private/account.key
- csr: /etc/pki/cert/csr/sample.com.csr
- dest: /etc/httpd/ssl/sample.com.crt
- fullchain_dest: /etc/httpd/ssl/sample.com-fullchain.crt
- chain_dest: /etc/httpd/ssl/sample.com-intermediate.crt
- data: "{{ sample_com_challenge }}"
-
----
-### Example with DNS challenge against production ACME server ###
-
-- name: Create a challenge for sample.com using a account key file.
- community.crypto.acme_certificate:
- account_key_src: /etc/pki/cert/private/account.key
- account_email: myself@sample.com
- src: /etc/pki/cert/csr/sample.com.csr
- cert: /etc/httpd/ssl/sample.com.crt
- challenge: dns-01
- acme_directory: https://acme-v01.api.letsencrypt.org/directory
- # Renew if the certificate is at least 30 days old
- remaining_days: 60
- register: sample_com_challenge
-
-# perform the necessary steps to fulfill the challenge
-# for example:
-#
-# - name: Create DNS record for sample.com dns-01 challenge
-# community.aws.route53:
-# zone: sample.com
-# record: "{{ sample_com_challenge.challenge_data['sample.com']['dns-01'].record }}"
-# type: TXT
-# ttl: 60
-# state: present
-# wait: true
-# # Note: route53 requires TXT entries to be enclosed in quotes
-# value: "{{ sample_com_challenge.challenge_data['sample.com']['dns-01'].resource_value | community.dns.quote_txt(always_quote=true) }}"
-# when: sample_com_challenge is changed and 'sample.com' in sample_com_challenge.challenge_data
-#
-# Alternative way:
-#
-# - name: Create DNS records for dns-01 challenges
-# community.aws.route53:
-# zone: sample.com
-# record: "{{ item.key }}"
-# type: TXT
-# ttl: 60
-# state: present
-# wait: true
-# # Note: item.value is a list of TXT entries, and route53
-# # requires every entry to be enclosed in quotes
-# value: "{{ item.value | map('community.dns.quote_txt', always_quote=true) | list }}"
-# loop: "{{ sample_com_challenge.challenge_data_dns | dict2items }}"
-# when: sample_com_challenge is changed
-
-- name: Let the challenge be validated and retrieve the cert and intermediate certificate
- community.crypto.acme_certificate:
- account_key_src: /etc/pki/cert/private/account.key
- account_email: myself@sample.com
- src: /etc/pki/cert/csr/sample.com.csr
- cert: /etc/httpd/ssl/sample.com.crt
- fullchain: /etc/httpd/ssl/sample.com-fullchain.crt
- chain: /etc/httpd/ssl/sample.com-intermediate.crt
- challenge: dns-01
- acme_directory: https://acme-v01.api.letsencrypt.org/directory
- remaining_days: 60
- data: "{{ sample_com_challenge }}"
- when: sample_com_challenge is changed
-
-# Alternative second step:
-- name: Let the challenge be validated and retrieve the cert and intermediate certificate
- community.crypto.acme_certificate:
- account_key_src: /etc/pki/cert/private/account.key
- account_email: myself@sample.com
- src: /etc/pki/cert/csr/sample.com.csr
- cert: /etc/httpd/ssl/sample.com.crt
- fullchain: /etc/httpd/ssl/sample.com-fullchain.crt
- chain: /etc/httpd/ssl/sample.com-intermediate.crt
- challenge: tls-alpn-01
- remaining_days: 60
- data: "{{ sample_com_challenge }}"
- # We use Let's Encrypt's ACME v2 endpoint
- acme_directory: https://acme-v02.api.letsencrypt.org/directory
- acme_version: 2
- # The following makes sure that if a chain with /CN=DST Root CA X3 in its issuer is provided
- # as an alternative, it will be selected. These are the roots cross-signed by IdenTrust.
- # As long as Let's Encrypt provides alternate chains with the cross-signed root(s) when
- # switching to their own ISRG Root X1 root, this will use the chain ending with a cross-signed
- # root. This chain is more compatible with older TLS clients.
- select_chain:
- - test_certificates: last
- issuer:
- CN: DST Root CA X3
- O: Digital Signature Trust Co.
- when: sample_com_challenge is changed
-Common return values are documented here, the following are the fields unique to this module:
-Key |
-Description |
-
|---|---|
| - | ACME account URI. -Returned: changed - |
-
| - | When See Section 7.4.2 of RFC8555 for details. -Returned: when certificate was retrieved and |
-
| - | The leaf certificate itself, in PEM format. -Returned: always - |
-
| - | The certificate chain, excluding the root, as concatenated PEM certificates. -Returned: always - |
-
| - | The certificate chain, excluding the root, but including the leaf certificate, as concatenated PEM certificates. -Returned: always - |
-
| - | ACME authorization data. -Maps an identifier to ACME authorization objects. See https://tools.ietf.org/html/rfc8555#section-7.1.4. -Returned: changed -Sample: |
-
| - | The number of days the certificate remains valid. -Returned: success - |
-
| - | Per identifier / challenge type challenge data. -Since Ansible 2.8.5, only challenges which are not yet valid are returned. -Returned: changed - |
-
| - | For every identifier, provides a dictionary of challenge types mapping to challenge data. -The keys in this dictionary are the identifiers. Note that the keys are not valid Jinja2 identifiers. -Returned: changed - |
-
| - | Data for every challenge type. -The keys in this dictionary are the challenge types. Note that the keys are not valid Jinja2 identifiers. -Returned: changed - |
-
| - | The full DNS record’s name for the challenge. -Returned: changed and challenge is Sample: |
-
| - | The challenge resource that must be created for validation. -Returned: changed -Sample: |
-
| - | The original challenge resource including type identifier for Returned: changed and Sample: |
-
| - | The value the resource has to produce for the validation. -For For Returned: changed -Sample: |
-
| - | List of TXT values per DNS record, in case challenge is Since Ansible 2.8.5, only challenges which are not yet valid are returned. -Returned: changed - |
-
| - | ACME finalization URI. -Returned: changed - |
-
| - | ACME order URI. -Returned: changed - |
-
- Note
-This module is part of the community.crypto collection (version 2.26.6).
-It is not included in ansible-core.
-To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install community.crypto.
-You need further requirements to be able to use this module,
-see Requirements for details.
To use it in a playbook, specify: community.crypto.acme_certificate_order_create.
New in community.crypto 2.24.0
- -Creates an ACME v2 order. This is the first step of obtaining a new certificate with the ACME protocol from a Certificate Authority such as Let’s Encrypt. This module does not support ACME v1, the original version of the ACME protocol before standardization.
The current implementation supports the http-01, dns-01 and tls-alpn-01 challenges.
This module needs to be used in conjunction with the community.crypto.acme_certificate_order_validate and. community.crypto.acme_certificate_order_finalize module. An order can be effectively deactivated with the community.crypto.acme_certificate_deactivate_authz module. Note that both modules require the output order_uri of this module.
To create or modify ACME accounts, use the community.crypto.acme_account module. This module will not create or update ACME accounts.
Between the call of this module and community.crypto.acme_certificate_order_finalize, you have to fulfill the required steps for the chosen challenge by whatever means necessary. For http-01 that means creating the necessary challenge file on the destination webserver. For dns-01 the necessary dns record has to be created. For tls-alpn-01 the necessary certificate has to be created and served. It is not the responsibility of this module to perform these steps.
For details on how to fulfill these challenges, you might have to read through the main ACME specification and the TLS-ALPN-01 specification. Also, consider the examples provided for this module.
The module includes support for IP identifiers according to the RFC 8738 ACME extension.
The below requirements are needed on the host that executes this module.
-either openssl or cryptography >= 1.5
ipaddress
Parameter |
-Comments |
-
|---|---|
| - | Content of the ACME account RSA or Elliptic Curve key. -For Elliptic Curve keys only the following curves are supported: Mutually exclusive with Required if 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 |
-
| - | Phassphrase to use to decode the account key. -Note: this is not supported by the |
-
| - | Path to a file containing the ACME account RSA or Elliptic Curve key. -For Elliptic Curve keys only the following curves are supported: Private keys can be created with the community.crypto.openssl_privatekey or community.crypto.openssl_privatekey_pipe modules. If the requisite (cryptography) is not available, keys can also be created directly with the Mutually exclusive with Required if |
-
| - | 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. - |
-
| - | 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: https://letsencrypt.org/docs/staging-environment/. -For Let’s Encrypt, the production directory URL for ACME v2 is https://acme-v02.api.letsencrypt.org/directory. -For ZeroSSL, the production directory URL for ACME v2 is https://acme.zerossl.com/v2/DV90. -For Sectigo, the production directory URL for ACME v2 is https://acme-qa.secure.trust-provider.com/v2/DV. -For HARICA, the production directory URL for ACME v2 is https://acme.harica.gr/XXX/directory with XXX being specific to your account. -The notes for this module contain a list of ACME services this module has been tested against. - |
-
| - | The ACME version of the endpoint. -Must be The value Choices: -
|
-
| - | File containing the CSR for the new certificate. -Can be created with 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. -Note: the private key used to create the CSR 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 |
-
| - | Content of the CSR for the new certificate. -Can be created with 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. -Note: the private key used to create the CSR 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 |
-
| - | Deactivate authentication objects (authz) 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. -Choices: -
|
-
| - | Selects the error handling strategy for ACME protocol errors if creating a new ACME order fails. -Choices: -
|
-
| - | Depending on the strategy selected in Default: |
-
| - | Chose a specific profile for certificate selection. The available profiles depend on the CA. -See a blog post by Let’s Encrypt and draft-aaron-acme-profiles-00 for more information. - |
-
| - | If provided, will request the order to replace the certificate identified by this certificate ID according to Section 5 of RFC 9773. -This certificate ID must be computed as specified in Section 4.1 of RFC 9773. It is returned as return value ACME servers might refuse to create new orders that indicate to replace a certificate for which an active replacement order already exists. 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. If If |
-
| - | The time Ansible should wait for a response from the ACME API. -This timeout is applied to all HTTP(S) requests (HEAD, GET, POST). -Default: |
-
| - | Determines which crypto backend to use. -The default choice is If set to If set to Choices: -
|
-
| - | Whether calls to the ACME directory will validate TLS certificates. -Warning: Should only ever be set to Choices: -
|
-
Attribute |
-Support |
-Description |
-
|---|---|---|
| - | Action groups: community.crypto.acme, acme - |
-Use |
-
| - | Support: none - |
-Can run in |
-
| - | Support: none - |
-Will return details on what has changed (or possibly needs changing in |
-
| - | Support: none - |
-When run twice in a row outside check mode, with the same arguments, the second invocation indicates no change. -This assumes that the system controlled/queried by the module has not changed in a relevant way. - |
-
Note
-Although the defaults are chosen so that the module can be used with the Let’s Encrypt CA, the module can in principle be used with any CA providing an ACME endpoint.
So far, the ACME modules have only been tested by the developers against Let’s Encrypt (staging and production), ZeroSSL (production), and Pebble testing server. We have got community feedback that they also work with Sectigo ACME Service for InCommon and with HARICA. If you experience problems with another ACME server, please create an issue to help us supporting it. Feedback that an ACME server not mentioned does work is also appreciated.
If a new enough version of the cryptography library is available (see Requirements for details), it will be used instead of the openssl binary. This can be explicitly disabled or enabled with the select_crypto_backend option. Note that using the openssl binary will be slower and less secure, as private key contents always have to be stored on disk (see account_key_content).
See also
-Validate pending authorizations of an ACME order.
-Finalize an ACME order after satisfying the challenges.
-Obtain information for an ACME order.
-Deactivate all authorizations (authz) of an ACME order, effectively deactivating the order itself.
-Determine whether a certificate should be renewed.
-Documentation for the Let’s Encrypt Certification Authority. Provides useful information for example on rate limits.
-The specification of the ACME protocol (RFC 8555).
-The specification of the tls-alpn-01 challenge (RFC 8737).
Helps preparing tls-alpn-01 challenges.
Can be used to create private keys (both for certificates and accounts).
-Can be used to create private keys without writing it to disk (both for certificates and accounts).
-Can be used to create a Certificate Signing Request (CSR).
-Can be used to create a Certificate Signing Request (CSR) without writing it to disk.
-Allows to create, modify or delete an ACME account.
-Allows to debug problems.
----
-### Example with HTTP-01 challenge ###
-
-- name: Create a challenge for sample.com using a account key from a variable
- community.crypto.acme_certificate_order_create:
- account_key_content: "{{ account_private_key }}"
- csr: /etc/pki/cert/csr/sample.com.csr
- register: sample_com_challenge
-
-# Alternative first step:
-- name: Create a challenge for sample.com using a account key from Hashi Vault
- community.crypto.acme_certificate_order_create:
- account_key_content: >-
- {{ lookup('community.hashi_vault.hashi_vault', 'secret=secret/account_private_key:value') }}
- csr: /etc/pki/cert/csr/sample.com.csr
- register: sample_com_challenge
-
-# Alternative first step:
-- name: Create a challenge for sample.com using a account key file
- community.crypto.acme_certificate_order_create:
- account_key_src: /etc/pki/cert/private/account.key
- csr_content: "{{ lookup('file', '/etc/pki/cert/csr/sample.com.csr') }}"
- register: sample_com_challenge
-
-# Perform the necessary steps to fulfill the challenge. For example:
-#
-# - name: Copy http-01 challenges
-# ansible.builtin.copy:
-# dest: /var/www/{{ item.identifier }}/{{ item.challenges['http-01'].resource }}
-# content: "{{ item.challenges['http-01'].resource_value }}"
-# loop: "{{ sample_com_challenge.challenge_data }}"
-# when: "'http-01' in item.challenges"
-
-- name: Let the challenge be validated
- community.crypto.acme_certificate_order_validate:
- account_key_src: /etc/pki/cert/private/account.key
- order_uri: "{{ sample_com_challenge.order_uri }}"
- challenge: http-01
-
-- name: Retrieve the cert and intermediate certificate
- community.crypto.acme_certificate_order_finalize:
- account_key_src: /etc/pki/cert/private/account.key
- csr: /etc/pki/cert/csr/sample.com.csr
- order_uri: "{{ sample_com_challenge.order_uri }}"
- cert_dest: /etc/httpd/ssl/sample.com.crt
- fullchain_dest: /etc/httpd/ssl/sample.com-fullchain.crt
- chain_dest: /etc/httpd/ssl/sample.com-intermediate.crt
-
----
-### Example with DNS challenge against production ACME server ###
-
-- name: Create a challenge for sample.com using a account key file.
- community.crypto.acme_certificate_order_create:
- acme_directory: https://acme-v01.api.letsencrypt.org/directory
- acme_version: 2
- account_key_src: /etc/pki/cert/private/account.key
- csr: /etc/pki/cert/csr/sample.com.csr
- register: sample_com_challenge
-
-# Perform the necessary steps to fulfill the challenge. For example:
-#
-# - name: Create DNS records for dns-01 challenges
-# community.aws.route53:
-# zone: sample.com
-# record: "{{ item.key }}"
-# type: TXT
-# ttl: 60
-# state: present
-# wait: true
-# # Note: item.value is a list of TXT entries, and route53
-# # requires every entry to be enclosed in quotes
-# value: "{{ item.value | map('community.dns.quote_txt', always_quote=true) | list }}"
-# loop: "{{ sample_com_challenge.challenge_data_dns | dict2items }}"
-
-- name: Let the challenge be validated
- community.crypto.acme_certificate_order_validate:
- acme_directory: https://acme-v01.api.letsencrypt.org/directory
- acme_version: 2
- account_key_src: /etc/pki/cert/private/account.key
- order_uri: "{{ sample_com_challenge.order_uri }}"
- challenge: dns-01
-
-- name: Retrieve the cert and intermediate certificate
- community.crypto.acme_certificate_order_finalize:
- acme_directory: https://acme-v01.api.letsencrypt.org/directory
- acme_version: 2
- account_key_src: /etc/pki/cert/private/account.key
- csr: /etc/pki/cert/csr/sample.com.csr
- order_uri: "{{ sample_com_challenge.order_uri }}"
- cert_dest: /etc/httpd/ssl/sample.com.crt
- fullchain_dest: /etc/httpd/ssl/sample.com-fullchain.crt
- chain_dest: /etc/httpd/ssl/sample.com-intermediate.crt
-Common return values are documented here, the following are the fields unique to this module:
-Key |
-Description |
-
|---|---|
| - | ACME account URI. -Returned: success - |
-
| - | For every identifier, provides the challenge information. -Only challenges which are not yet valid are returned. -Returned: changed - |
-
| - | Information for different challenge types supported for this identifier. -Note that the keys are not valid Jinja2 identifiers. -Returned: success - |
-
| - | Information for A DNS TXT record needs to be created with the record name Returned: if the identifier supports |
-
| - | The full DNS record’s name for the challenge. -Returned: success -Sample: |
-
| - | Always contains the string Returned: success -Sample: |
-
| - | The value the resource has to produce for the validation. -Returned: success -Sample: |
-
| - | Information for The server needs to make the path Returned: if the identifier supports |
-
| - | The path the value has to be provided under. -Returned: success -Sample: |
-
| - | The value the resource has to produce for the validation. -Returned: success -Sample: |
-
| - | Information for A certificate needs to be created for the DNS name See https://www.rfc-editor.org/rfc/rfc8737.html#section-3 for details. -Returned: if the identifier supports |
-
| - | The DNS name for DNS identifiers, and the reverse DNS mapping (RFC1034, RFC3596) for IP addresses. -Returned: success -Sample: |
-
| - | The original identifier including type identifier. -Returned: success -Sample: |
-
| - | The value the resource has to produce for the validation. -Note: this return value contains a Base64 encoded version of the correct binary blob which has to be put into the acmeValidation X.509 extension; see https://www.rfc-editor.org/rfc/rfc8737.html#section-3 for details. To do this, you might need the ansible.builtin.b64decode Jinja filter to extract the binary blob from this return value. -Returned: success -Sample: |
-
| - | The identifier for this challenge. -Returned: success -Sample: |
-
| - | The identifier’s type. -
Returned: success -Can only return: -
Sample: |
-
| - | List of TXT values per DNS record for Only challenges which are not yet valid are returned. -Returned: success - |
-
| - | ACME order URI. -Returned: success - |
-
- Note
-This module is part of the community.crypto collection (version 2.26.6).
-It is not included in ansible-core.
-To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install community.crypto.
-You need further requirements to be able to use this module,
-see Requirements for details.
To use it in a playbook, specify: community.crypto.acme_certificate_order_finalize.
New in community.crypto 2.24.0
- -Finalizes an ACME v2 order and obtains the certificate and certificate chains. This is the final step of obtaining a new certificate with the ACME protocol from a Certificate Authority such as Let’s Encrypt. This module does not support ACME v1, the original version of the ACME protocol before standardization.
This module needs to be used in conjunction with the community.crypto.acme_certificate_order_create and. community.crypto.acme_certificate_order_validate modules.
The below requirements are needed on the host that executes this module.
-either openssl or cryptography >= 1.5
ipaddress
Parameter |
-Comments |
-
|---|---|
| - | Content of the ACME account RSA or Elliptic Curve key. -For Elliptic Curve keys only the following curves are supported: Mutually exclusive with Required if 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 |
-
| - | Phassphrase to use to decode the account key. -Note: this is not supported by the |
-
| - | Path to a file containing the ACME account RSA or Elliptic Curve key. -For Elliptic Curve keys only the following curves are supported: Private keys can be created with the community.crypto.openssl_privatekey or community.crypto.openssl_privatekey_pipe modules. If the requisite (cryptography) is not available, keys can also be created directly with the Mutually exclusive with Required if |
-
| - | 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. - |
-
| - | 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: https://letsencrypt.org/docs/staging-environment/. -For Let’s Encrypt, the production directory URL for ACME v2 is https://acme-v02.api.letsencrypt.org/directory. -For ZeroSSL, the production directory URL for ACME v2 is https://acme.zerossl.com/v2/DV90. -For Sectigo, the production directory URL for ACME v2 is https://acme-qa.secure.trust-provider.com/v2/DV. -For HARICA, the production directory URL for ACME v2 is https://acme.harica.gr/XXX/directory with XXX being specific to your account. -The notes for this module contain a list of ACME services this module has been tested against. - |
-
| - | The ACME version of the endpoint. -Must be The value Choices: -
|
-
| - | The destination file for the certificate. - |
-
| - | If specified, the intermediate certificate will be written to this file. - |
-
| - | File containing the CSR for the new certificate. -Can be created with 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. -Note: the private key used to create the CSR 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 |
-
| - | Content of the CSR for the new certificate. -Can be created with 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. -Note: the private key used to create the CSR 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 |
-
| - | 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. -Choices: -
|
-
| - | The destination file for the full chain (that is, a certificate followed by chain of intermediate certificates). - |
-
| - | The order URI provided by |
-
| - | The time Ansible should wait for a response from the ACME API. -This timeout is applied to all HTTP(S) requests (HEAD, GET, POST). -Default: |
-
| - | When set to Choices: -
|
-
| - | 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 Every criterium can consist of multiple different conditions, like This option can only be used with the |
-
| - | 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 |
-
| - | Allows to specify parts of the issuer of a certificate in the chain must have to be selected. -If An example value would be |
-
| - | Allows to specify parts of the subject of a certificate in the chain must have to be selected. -If An example value would be |
-
| - | 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 |
-
| - | Determines which certificates in the chain will be tested. -
Choices: -
|
-
| - | Determines which crypto backend to use. -The default choice is If set to If set to Choices: -
|
-
| - | Whether calls to the ACME directory will validate TLS certificates. -Warning: Should only ever be set to Choices: -
|
-
Attribute |
-Support |
-Description |
-
|---|---|---|
| - | Action groups: community.crypto.acme, acme - |
-Use |
-
| - | Support: none - |
-Can run in |
-
| - | Support: none - |
-Will return details on what has changed (or possibly needs changing in |
-
| - | Support: full - |
-When run twice in a row outside check mode, with the same arguments, the second invocation indicates no change. -This assumes that the system controlled/queried by the module has not changed in a relevant way. - |
-
| - | Support: full - |
-Uses Ansible’s strict file operation functions to ensure proper permissions and avoid data corruption. - |
-
Note
-Although the defaults are chosen so that the module can be used with the Let’s Encrypt CA, the module can in principle be used with any CA providing an ACME endpoint.
So far, the ACME modules have only been tested by the developers against Let’s Encrypt (staging and production), ZeroSSL (production), and Pebble testing server. We have got community feedback that they also work with Sectigo ACME Service for InCommon and with HARICA. If you experience problems with another ACME server, please create an issue to help us supporting it. Feedback that an ACME server not mentioned does work is also appreciated.
If a new enough version of the cryptography library is available (see Requirements for details), it will be used instead of the openssl binary. This can be explicitly disabled or enabled with the select_crypto_backend option. Note that using the openssl binary will be slower and less secure, as private key contents always have to be stored on disk (see account_key_content).
See also
-Create an ACME order.
-Validate pending authorizations of an ACME order.
-Obtain information for an ACME order.
-Documentation for the Let’s Encrypt Certification Authority. Provides useful information for example on rate limits.
-The specification of the ACME protocol (RFC 8555).
-Allows to find the root certificate for the returned fullchain.
-Allows to revoke certificates.
-Allows to debug problems.
-Allows to deactivate (invalidate) ACME v2 orders.
----
-### Example with HTTP-01 challenge ###
-
-- name: Create a challenge for sample.com using a account key from a variable
- community.crypto.acme_certificate_order_create:
- account_key_content: "{{ account_private_key }}"
- csr: /etc/pki/cert/csr/sample.com.csr
- register: sample_com_challenge
-
-# Alternative first step:
-- name: Create a challenge for sample.com using a account key from Hashi Vault
- community.crypto.acme_certificate_order_create:
- account_key_content: >-
- {{ lookup('community.hashi_vault.hashi_vault', 'secret=secret/account_private_key:value') }}
- csr: /etc/pki/cert/csr/sample.com.csr
- register: sample_com_challenge
-
-# Alternative first step:
-- name: Create a challenge for sample.com using a account key file
- community.crypto.acme_certificate_order_create:
- account_key_src: /etc/pki/cert/private/account.key
- csr_content: "{{ lookup('file', '/etc/pki/cert/csr/sample.com.csr') }}"
- register: sample_com_challenge
-
-# Perform the necessary steps to fulfill the challenge. For example:
-#
-# - name: Copy http-01 challenges
-# ansible.builtin.copy:
-# dest: /var/www/{{ item.identifier }}/{{ item.challenges['http-01'].resource }}
-# content: "{{ item.challenges['http-01'].resource_value }}"
-# loop: "{{ sample_com_challenge.challenge_data }}"
-# when: "'http-01' in item.challenges"
-
-- name: Let the challenge be validated
- community.crypto.acme_certificate_order_validate:
- account_key_src: /etc/pki/cert/private/account.key
- order_uri: "{{ sample_com_challenge.order_uri }}"
- challenge: http-01
-
-- name: Retrieve the cert and intermediate certificate
- community.crypto.acme_certificate_order_finalize:
- account_key_src: /etc/pki/cert/private/account.key
- csr: /etc/pki/cert/csr/sample.com.csr
- order_uri: "{{ sample_com_challenge.order_uri }}"
- cert_dest: /etc/httpd/ssl/sample.com.crt
- fullchain_dest: /etc/httpd/ssl/sample.com-fullchain.crt
- chain_dest: /etc/httpd/ssl/sample.com-intermediate.crt
-
----
-### Example with DNS challenge against production ACME server ###
-
-- name: Create a challenge for sample.com using a account key file.
- community.crypto.acme_certificate_order_create:
- acme_directory: https://acme-v01.api.letsencrypt.org/directory
- acme_version: 2
- account_key_src: /etc/pki/cert/private/account.key
- csr: /etc/pki/cert/csr/sample.com.csr
- register: sample_com_challenge
-
-# Perform the necessary steps to fulfill the challenge. For example:
-#
-# - name: Create DNS records for dns-01 challenges
-# community.aws.route53:
-# zone: sample.com
-# record: "{{ item.key }}"
-# type: TXT
-# ttl: 60
-# state: present
-# wait: true
-# # Note: item.value is a list of TXT entries, and route53
-# # requires every entry to be enclosed in quotes
-# value: "{{ item.value | map('community.dns.quote_txt', always_quote=true) | list }}"
-# loop: "{{ sample_com_challenge.challenge_data_dns | dict2items }}"
-
-- name: Let the challenge be validated
- community.crypto.acme_certificate_order_validate:
- acme_directory: https://acme-v01.api.letsencrypt.org/directory
- acme_version: 2
- account_key_src: /etc/pki/cert/private/account.key
- order_uri: "{{ sample_com_challenge.order_uri }}"
- challenge: dns-01
-
-- name: Retrieve the cert and intermediate certificate
- community.crypto.acme_certificate_order_finalize:
- acme_directory: https://acme-v01.api.letsencrypt.org/directory
- acme_version: 2
- account_key_src: /etc/pki/cert/private/account.key
- csr: /etc/pki/cert/csr/sample.com.csr
- order_uri: "{{ sample_com_challenge.order_uri }}"
- cert_dest: /etc/httpd/ssl/sample.com.crt
- fullchain_dest: /etc/httpd/ssl/sample.com-fullchain.crt
- chain_dest: /etc/httpd/ssl/sample.com-intermediate.crt
-Common return values are documented here, the following are the fields unique to this module:
-Key |
-Description |
-
|---|---|
| - | ACME account URI. -Returned: success - |
-
| - | When See Section 7.4.2 of RFC8555 for details. -Returned: success and |
-
| - | The leaf certificate itself, in PEM format. -Returned: always - |
-
| - | The certificate chain, excluding the root, as concatenated PEM certificates. -Returned: always - |
-
| - | The certificate chain, excluding the root, but including the leaf certificate, as concatenated PEM certificates. -Returned: always - |
-
| - | The selected certificate chain. -If Returned: success - |
-
| - | The leaf certificate itself, in PEM format. -Returned: always - |
-
| - | The certificate chain, excluding the root, as concatenated PEM certificates. -Returned: always - |
-
| - | The certificate chain, excluding the root, but including the leaf certificate, as concatenated PEM certificates. -Returned: always - |
-
- Note
-This module is part of the community.crypto collection (version 2.26.6).
-It is not included in ansible-core.
-To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install community.crypto.
-You need further requirements to be able to use this module,
-see Requirements for details.
To use it in a playbook, specify: community.crypto.acme_certificate_order_info.
New in community.crypto 2.24.0
- -Obtain information for an ACME v2 order. This can be used during the process of obtaining a new certificate with the ACME protocol from a Certificate Authority such as Let’s Encrypt. This module does not support ACME v1, the original version of the ACME protocol before standardization.
This module needs to be used in conjunction with the community.crypto.acme_certificate_order_create, community.crypto.acme_certificate_order_validate, and community.crypto.acme_certificate_order_finalize modules.
The below requirements are needed on the host that executes this module.
-either openssl or cryptography >= 1.5
ipaddress
Parameter |
-Comments |
-
|---|---|
| - | Content of the ACME account RSA or Elliptic Curve key. -For Elliptic Curve keys only the following curves are supported: Mutually exclusive with Required if 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 |
-
| - | Phassphrase to use to decode the account key. -Note: this is not supported by the |
-
| - | Path to a file containing the ACME account RSA or Elliptic Curve key. -For Elliptic Curve keys only the following curves are supported: Private keys can be created with the community.crypto.openssl_privatekey or community.crypto.openssl_privatekey_pipe modules. If the requisite (cryptography) is not available, keys can also be created directly with the Mutually exclusive with Required if |
-
| - | 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. - |
-
| - | 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: https://letsencrypt.org/docs/staging-environment/. -For Let’s Encrypt, the production directory URL for ACME v2 is https://acme-v02.api.letsencrypt.org/directory. -For ZeroSSL, the production directory URL for ACME v2 is https://acme.zerossl.com/v2/DV90. -For Sectigo, the production directory URL for ACME v2 is https://acme-qa.secure.trust-provider.com/v2/DV. -For HARICA, the production directory URL for ACME v2 is https://acme.harica.gr/XXX/directory with XXX being specific to your account. -The notes for this module contain a list of ACME services this module has been tested against. - |
-
| - | The ACME version of the endpoint. -Must be The value Choices: -
|
-
| - | The order URI provided by |
-
| - | The time Ansible should wait for a response from the ACME API. -This timeout is applied to all HTTP(S) requests (HEAD, GET, POST). -Default: |
-
| - | Determines which crypto backend to use. -The default choice is If set to If set to Choices: -
|
-
| - | Whether calls to the ACME directory will validate TLS certificates. -Warning: Should only ever be set to Choices: -
|
-
Attribute |
-Support |
-Description |
-
|---|---|---|
| - | Action groups: community.crypto.acme, acme - |
-Use |
-
| - | Support: full -This action does not modify state. - |
-Can run in |
-
| - | Support: N/A -This action does not modify state. - |
-Will return details on what has changed (or possibly needs changing in |
-
| - | Support: full -This action does not modify state. - |
-When run twice in a row outside check mode, with the same arguments, the second invocation indicates no change. -This assumes that the system controlled/queried by the module has not changed in a relevant way. - |
-
Note
-Although the defaults are chosen so that the module can be used with the Let’s Encrypt CA, the module can in principle be used with any CA providing an ACME endpoint.
So far, the ACME modules have only been tested by the developers against Let’s Encrypt (staging and production), ZeroSSL (production), and Pebble testing server. We have got community feedback that they also work with Sectigo ACME Service for InCommon and with HARICA. If you experience problems with another ACME server, please create an issue to help us supporting it. Feedback that an ACME server not mentioned does work is also appreciated.
If a new enough version of the cryptography library is available (see Requirements for details), it will be used instead of the openssl binary. This can be explicitly disabled or enabled with the select_crypto_backend option. Note that using the openssl binary will be slower and less secure, as private key contents always have to be stored on disk (see account_key_content).
See also
-Create an ACME order.
-Validate pending authorizations of an ACME order.
-Finalize an ACME order after satisfying the challenges.
-The specification of the ACME protocol (RFC 8555).
-The specification of the tls-alpn-01 challenge (RFC 8737).
Allows to debug problems.
-Allows to deactivate (invalidate) ACME v2 orders.
----
-- name: Create a challenge for sample.com using a account key from a variable
- community.crypto.acme_certificate_order_create:
- account_key_content: "{{ account_private_key }}"
- csr: /etc/pki/cert/csr/sample.com.csr
- register: order
-
-- name: Obtain information on the order
- community.crypto.acme_certificate_order_info:
- account_key_src: /etc/pki/cert/private/account.key
- order_uri: "{{ order.order_uri }}"
- register: order_info
-
-- name: Show information
- ansible.builtin.debug:
- var: order_info
-Common return values are documented here, the following are the fields unique to this module:
-Key |
-Description |
-
|---|---|
| - | ACME account URI. -Returned: success - |
-
| - | A dictionary mapping identifiers to their authorization objects. -Returned: success - |
-
| - | The keys in this dictionary are the identifiers. See https://www.rfc-editor.org/rfc/rfc8555#section-7.1.4 for how authorization objects look like. -Returned: success - |
-
| - | For pending authorizations, the challenges that the client can fulfill in order to prove possession of the identifier. -For valid authorizations, the challenge that was validated. -For invalid authorizations, the challenge that was attempted and failed. -Each array entry is an object with parameters required to validate the challenge. A client should attempt to fulfill one of these challenges, and a server should consider any one of the challenges sufficient to make the authorization valid. -See https://www.rfc-editor.org/rfc/rfc8555#section-8 for the general structure. The structure of every entry depends on the challenge’s type. For Returned: always - |
-
| - | Error that occurred while the server was validating the challenge, if any. -This field is structured as a problem document according to RFC 7807. -Returned: always if |
-
| - | The status of this challenge. -See https://www.rfc-editor.org/rfc/rfc8555#section-7.1.6 for state changes. -Returned: always -Can only return: -
|
-
| - | The type of challenge encoded in the object. -Returned: always -Can only return: -
|
-
| - | The URL to which a response can be posted. -Returned: always - |
-
| - | The time at which the server validated this challenge. -Encoded in the format specified in RFC 3339. -Returned: always if |
-
| - | The timestamp after which the server will consider this authorization invalid. -Encoded in the format specified in RFC 3339. -Returned: if |
-
| - | The identifier that the account is authorized to represent. -Returned: always - |
-
| - | The type of identifier. -So far Returned: always -Can only return: -
Sample: |
-
| - | The identifier itself. -Returned: always -Sample: |
-
| - | The status of this authorization. -See https://www.rfc-editor.org/rfc/rfc8555#section-7.1.6 for state changes. -Returned: always -Can only return: -
|
-
| - | This field must be present and true for authorizations created as a result of a Wildcard domain names are described in https://www.rfc-editor.org/rfc/rfc8555#section-7.1.3 of the ACME specification. -Returned: sometimes - |
-
| - | For every status, a list of identifiers whose authorizations have this status. -Returned: success - |
-
| - | A list of all identifiers whose authorizations are in the See https://www.rfc-editor.org/rfc/rfc8555#section-7.1.6 for state changes of authorizations. -Returned: always - |
-
| - | A list of all identifiers whose authorizations are in the See https://www.rfc-editor.org/rfc/rfc8555#section-7.1.6 for state changes of authorizations. -Returned: always - |
-
| - | A list of all identifiers whose authorizations are in the See https://www.rfc-editor.org/rfc/rfc8555#section-7.1.6 for state changes of authorizations. -Returned: always - |
-
| - | A list of all identifiers whose authorizations are in the See https://www.rfc-editor.org/rfc/rfc8555#section-7.1.6 for state changes of authorizations. -Returned: always - |
-
| - | A list of all identifiers whose authorizations are in the See https://www.rfc-editor.org/rfc/rfc8555#section-7.1.6 for state changes of authorizations. -Returned: always - |
-
| - | A list of all identifiers whose authorizations are in the See https://www.rfc-editor.org/rfc/rfc8555#section-7.1.6 for state changes of authorizations. -Returned: always - |
-
| - | The order object. -See https://www.rfc-editor.org/rfc/rfc8555#section-7.1.3 for its specification. -Returned: success - |
-
| - | For pending orders, the authorizations that the client needs to complete before the requested certificate can be issued, including unexpired authorizations that the client has completed in the past for identifiers specified in the order. -The authorizations required are dictated by server policy; there may not be a 1:1 relationship between the order identifiers and the authorizations required. -For final orders (in the The authorizations themselves are returned as Returned: always - |
-
| - | A URL for the certificate that has been issued in response to this order. -Returned: when the certificate has been issued - |
-
| - | The error that occurred while processing the order, if any. -This field is structured as a problem document according to RFC 7807. -Returned: sometimes - |
-
| - | The timestamp after which the server will consider this order invalid. -Encoded in the format specified in RFC 3339. -Returned: if |
-
| - | A URL that a CSR must be POSTed to once all of the order’s authorizations are satisfied to finalize the order. The result of a successful finalization will be the population of the certificate URL for the order. -Returned: always - |
-
| - | An array of identifier objects that the order pertains to. -Returned: always - |
-
| - | The type of identifier. -So far Returned: always -Can only return: -
Sample: |
-
| - | The identifier itself. -Returned: always -Sample: |
-
| - | The requested value of the Encoded in the date format defined in RFC 3339. -Returned: depending on order - |
-
| - | The requested value of the Encoded in the date format defined in RFC 3339. -Returned: depending on order - |
-
| - | If the ACME CA supports profiles through the draft-aaron-acme-profiles mechanism and informs about the profile selected for this order, this field will contain the name of the profile used. -Returned: depending on the ACME CA - |
-
| - | If the order was created to replace an existing certificate using the Returned: when the certificate order is replacing a certificate through RFC 9773 - |
-
| - | The status of this order. -See https://www.rfc-editor.org/rfc/rfc8555#section-7.1.6 for state changes. -Returned: always -Can only return: -
|
-
| - | ACME order URI. -Returned: success - |
-
-
- Note
-This module is part of the community.crypto collection (version 2.26.6).
-It is not included in ansible-core.
-To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install community.crypto.
-You need further requirements to be able to use this module,
-see Requirements for details.
To use it in a playbook, specify: community.crypto.acme_certificate_renewal_info.
New in community.crypto 2.20.0
- -Uses various information to determine whether a certificate should be renewed or not.
If available, the ARI extension (ACME Renewal Information, RFC 9773) is used.
The below requirements are needed on the host that executes this module.
-either openssl or cryptography >= 1.5
ipaddress
Parameter |
-Comments |
-
|---|---|
| - | 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: https://letsencrypt.org/docs/staging-environment/. -For Let’s Encrypt, the production directory URL for ACME v2 is https://acme-v02.api.letsencrypt.org/directory. -For ZeroSSL, the production directory URL for ACME v2 is https://acme.zerossl.com/v2/DV90. -For Sectigo, the production directory URL for ACME v2 is https://acme-qa.secure.trust-provider.com/v2/DV. -For HARICA, the production directory URL for ACME v2 is https://acme.harica.gr/XXX/directory with XXX being specific to your account. -The notes for this module contain a list of ACME services this module has been tested against. - |
-
| - | The ACME version of the endpoint. -Must be The value Choices: -
|
-
| - | If ARI information is used, selects which algorithm is used to determine whether to renew now. -
Choices: -
|
-
| - | The content of the X.509 certificate to determine renewal of. -
|
-
| - | A path to the X.509 certificate to determine renewal of. -In case the certificate does not exist, the module will always return
|
-
| - | 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 |
-
| - | The number of days the certificate must have left being valid. -For example, if |
-
| - | The percentage of the certificate’s validity period that should be left. -For example, if Must be a value between 0 and 1. - |
-
| - | The time Ansible should wait for a response from the ACME API. -This timeout is applied to all HTTP(S) requests (HEAD, GET, POST). -Default: |
-
| - | Determines which crypto backend to use. -The default choice is If set to If set to Choices: -
|
-
| - | Determines the behavior when the certificate file exists or its contents are provided, but the certificate cannot be parsed. -If If If the file exists, but cannot be loaded due to I/O errors or permission errors, the module always fails. -Choices: -
|
-
| - | Whether to use ARI information, if available. -Set this to Choices: -
|
-
| - | Whether calls to the ACME directory will validate TLS certificates. -Warning: Should only ever be set to Choices: -
|
-
Attribute |
-Support |
-Description |
-
|---|---|---|
| - | Support: full -This action does not modify state. - |
-Can run in |
-
| - | Support: N/A -This action does not modify state. - |
-Will return details on what has changed (or possibly needs changing in |
-
| - | Support: partial -The module is not idempotent if If |
-When run twice in a row outside check mode, with the same arguments, the second invocation indicates no change. -This assumes that the system controlled/queried by the module has not changed in a relevant way. - |
-
Note
-Although the defaults are chosen so that the module can be used with the Let’s Encrypt CA, the module can in principle be used with any CA providing an ACME endpoint.
So far, the ACME modules have only been tested by the developers against Let’s Encrypt (staging and production), ZeroSSL (production), and Pebble testing server. We have got community feedback that they also work with Sectigo ACME Service for InCommon and with HARICA. If you experience problems with another ACME server, please create an issue to help us supporting it. Feedback that an ACME server not mentioned does work is also appreciated.
If a new enough version of the cryptography library is available (see Requirements for details), it will be used instead of the openssl binary. This can be explicitly disabled or enabled with the select_crypto_backend option. Note that using the openssl binary will be slower.
See also
-Allows to obtain a certificate using the ACME protocol.
-Obtain renewal information for a certificate.
----
-- name: Retrieve renewal information for a certificate
- community.crypto.acme_certificate_renewal_info:
- certificate_path: /etc/httpd/ssl/sample.com.crt
- register: cert_data
-
-- name: Should the certificate be renewed?
- ansible.builtin.debug:
- var: cert_data.should_renew
-Common return values are documented here, the following are the fields unique to this module:
-Key |
-Description |
-
|---|---|
| - | The certificate ID according to Section 4.1 in RFC 9773. -Returned: success, the certificate exists, and has an Authority Key Identifier X.509 extension -Sample: |
-
| - | Whether the certificate file exists, or Returned: success -Sample: |
-
| - | 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. -Returned: success -Sample: |
-
| - | Whether the certificate file exists, or Can only differ from Returned: success -Sample: |
-
| - | Whether the certificate should be renewed. -If no certificate is provided, or the certificate is expired, will always be Returned: success -Sample: |
-
| - | Whether ARI information was used to determine renewal. This can be used to determine whether to specify If Returned: success -Sample: |
-
- Note
-This module is part of the community.crypto collection (version 2.26.6).
-It is not included in ansible-core.
-To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install community.crypto.
-You need further requirements to be able to use this module,
-see Requirements for details.
To use it in a playbook, specify: community.crypto.acme_certificate_revoke.
Allows to revoke certificates issued by a CA supporting the ACME protocol, such as Let’s Encrypt.
The below requirements are needed on the host that executes this module.
-either openssl or cryptography >= 1.5
ipaddress
Parameter |
-Comments |
-
|---|---|
| - | Content of the ACME account RSA or Elliptic Curve key. -Note that exactly one of 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 |
-
| - | Phassphrase to use to decode the account key. -Note: this is not supported by the |
-
| - | Path to a file containing the ACME account RSA or Elliptic Curve key. -RSA keys can be created with Mutually exclusive with Required if |
-
| - | 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. - |
-
| - | 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: https://letsencrypt.org/docs/staging-environment/. -For Let’s Encrypt, the production directory URL for ACME v2 is https://acme-v02.api.letsencrypt.org/directory. -For ZeroSSL, the production directory URL for ACME v2 is https://acme.zerossl.com/v2/DV90. -For Sectigo, the production directory URL for ACME v2 is https://acme-qa.secure.trust-provider.com/v2/DV. -For HARICA, the production directory URL for ACME v2 is https://acme.harica.gr/XXX/directory with XXX being specific to your account. -The notes for this module contain a list of ACME services this module has been tested against. - |
-
| - | The ACME version of the endpoint. -Must be The value Choices: -
|
-
| - | Path to the certificate to revoke. - |
-
| - | Content of the certificate’s private key. -Note that exactly one of 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 |
-
| - | Phassphrase to use to decode the certificate’s private key. -Note: this is not supported by the |
-
| - | Path to the certificate’s private key. -Note that exactly one of |
-
| - | The time Ansible should wait for a response from the ACME API. -This timeout is applied to all HTTP(S) requests (HEAD, GET, POST). -Default: |
-
| - | One of the revocation reasonCodes defined in Section 5.3.1 of RFC5280. -Possible values are |
-
| - | Determines which crypto backend to use. -The default choice is If set to If set to Choices: -
|
-
| - | Whether calls to the ACME directory will validate TLS certificates. -Warning: Should only ever be set to Choices: -
|
-
Attribute |
-Support |
-Description |
-
|---|---|---|
| - | Action groups: community.crypto.acme, acme - |
-Use |
-
| - | Support: none - |
-Can run in |
-
| - | Support: none - |
-Will return details on what has changed (or possibly needs changing in |
-
| - | Support: full - |
-When run twice in a row outside check mode, with the same arguments, the second invocation indicates no change. -This assumes that the system controlled/queried by the module has not changed in a relevant way. - |
-
Note
-Exactly one of account_key_src, account_key_content, private_key_src, or 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.
Although the defaults are chosen so that the module can be used with the Let’s Encrypt CA, the module can in principle be used with any CA providing an ACME endpoint.
So far, the ACME modules have only been tested by the developers against Let’s Encrypt (staging and production), ZeroSSL (production), and Pebble testing server. We have got community feedback that they also work with Sectigo ACME Service for InCommon and with HARICA. If you experience problems with another ACME server, please create an issue to help us supporting it. Feedback that an ACME server not mentioned does work is also appreciated.
If a new enough version of the cryptography library is available (see Requirements for details), it will be used instead of the openssl binary. This can be explicitly disabled or enabled with the select_crypto_backend option. Note that using the openssl binary will be slower and less secure, as private key contents always have to be stored on disk (see account_key_content).
See also
-Documentation for the Let’s Encrypt Certification Authority. Provides useful information for example on rate limits.
-The specification of the ACME protocol (RFC 8555).
-Allows to debug problems.
----
-- name: Revoke certificate with account key
- community.crypto.acme_certificate_revoke:
- account_key_src: /etc/pki/cert/private/account.key
- certificate: /etc/httpd/ssl/sample.com.crt
-
-- name: Revoke certificate with certificate's private key
- community.crypto.acme_certificate_revoke:
- private_key_src: /etc/httpd/ssl/sample.com.key
- certificate: /etc/httpd/ssl/sample.com.crt
-
- tls-alpn-01Note
-This module is part of the community.crypto collection (version 2.26.6).
-It is not included in ansible-core.
-To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install community.crypto.
-You need further requirements to be able to use this module,
-see Requirements for details.
To use it in a playbook, specify: community.crypto.acme_challenge_cert_helper.
Prepares certificates for ACME challenges such as tls-alpn-01.
The raw data is provided by the 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.
The below requirements are needed on the host that executes this module.
-cryptography >= 1.3
Parameter |
-Comments |
-
|---|---|
| - | The challenge type. -Choices: -
|
-
| - | The |
-
| - | Content of the private key to use for this challenge certificate. -Mutually exclusive with |
-
| - | Phassphrase to use to decode the private key. - |
-
| - | Path to a file containing the private key file to use for this challenge certificate. -Mutually exclusive with |
-
Attribute |
-Support |
-Description |
-
|---|---|---|
| - | Support: none -This action does not modify state. - |
-Can run in |
-
| - | Support: N/A -This action does not modify state. - |
-Will return details on what has changed (or possibly needs changing in |
-
| - | Support: none -The certificates returned are never the same, since the Not Before and Not After timestamps depend on the invocation’s timestamp. - |
-When run twice in a row outside check mode, with the same arguments, the second invocation indicates no change. -This assumes that the system controlled/queried by the module has not changed in a relevant way. - |
-
See also
-The specification of the ACME protocol (RFC 8555).
-The specification of the tls-alpn-01 challenge (RFC 8737).
---
-- name: Create challenges for a given CRT for sample.com
- community.crypto.acme_certificate:
- account_key_src: /etc/pki/cert/private/account.key
- challenge: tls-alpn-01
- csr: /etc/pki/cert/csr/sample.com.csr
- dest: /etc/httpd/ssl/sample.com.crt
- register: sample_com_challenge
-
-- name: Create certificates for challenges
- community.crypto.acme_challenge_cert_helper:
- challenge: tls-alpn-01
- challenge_data: "{{ item.value['tls-alpn-01'] }}"
- private_key_src: /etc/pki/cert/key/sample.com.key
- loop: "{{ sample_com_challenge.challenge_data | dictsort }}"
- register: sample_com_challenge_certs
-
-- name: Install challenge certificates
- # We need to set up HTTPS such that for the domain,
- # regular_certificate is delivered for regular connections,
- # except if ALPN selects the "acme-tls/1"; then, the
- # challenge_certificate must be delivered.
- # This can for example be achieved with very new versions
- # of NGINX; search for ssl_preread and
- # ssl_preread_alpn_protocols for information on how to
- # route by ALPN protocol.
- ...:
- domain: "{{ item.domain }}"
- challenge_certificate: "{{ item.challenge_certificate }}"
- regular_certificate: "{{ item.regular_certificate }}"
- private_key: /etc/pki/cert/key/sample.com.key
- loop: "{{ sample_com_challenge_certs.results }}"
-
-- name: Create certificate for a given CSR for sample.com
- community.crypto.acme_certificate:
- account_key_src: /etc/pki/cert/private/account.key
- challenge: tls-alpn-01
- csr: /etc/pki/cert/csr/sample.com.csr
- dest: /etc/httpd/ssl/sample.com.crt
- data: "{{ sample_com_challenge }}"
-Common return values are documented here, the following are the fields unique to this module:
-Key |
-Description |
-
|---|---|
| - | The challenge certificate in PEM format. -Returned: always - |
-
| - | The domain the challenge is for. The certificate should be provided if this is specified in the request’s the Returned: always - |
-
| - | The identifier for the actual resource. Will be a domain name if Returned: always - |
-
| - | The identifier type for the actual resource identifier. -Returned: always -Can only return: -
|
-
| - | 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 - |
-
- Note
-This module is part of the community.crypto collection (version 2.26.6).
-It is not included in ansible-core.
-To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install community.crypto.
-You need further requirements to be able to use this module,
-see Requirements for details.
To use it in a playbook, specify: community.crypto.acme_inspect.
Allows to send direct requests to an ACME server with the ACME protocol, which is supported by CAs such as Let’s Encrypt.
This module can be used to debug failed certificate request attempts, for example when 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.
The below requirements are needed on the host that executes this module.
-either openssl or cryptography >= 1.5
ipaddress
Parameter |
-Comments |
-
|---|---|
| - | Content of the ACME account RSA or Elliptic Curve key. -For Elliptic Curve keys only the following curves are supported: Mutually exclusive with Required if 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 |
-
| - | Phassphrase to use to decode the account key. -Note: this is not supported by the |
-
| - | Path to a file containing the ACME account RSA or Elliptic Curve key. -For Elliptic Curve keys only the following curves are supported: Private keys can be created with the community.crypto.openssl_privatekey or community.crypto.openssl_privatekey_pipe modules. If the requisite (cryptography) is not available, keys can also be created directly with the Mutually exclusive with Required if |
-
| - | 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. - |
-
| - | 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: https://letsencrypt.org/docs/staging-environment/. -For Let’s Encrypt, the production directory URL for ACME v2 is https://acme-v02.api.letsencrypt.org/directory. -For ZeroSSL, the production directory URL for ACME v2 is https://acme.zerossl.com/v2/DV90. -For Sectigo, the production directory URL for ACME v2 is https://acme-qa.secure.trust-provider.com/v2/DV. -For HARICA, the production directory URL for ACME v2 is https://acme.harica.gr/XXX/directory with XXX being specific to your account. -The notes for this module contain a list of ACME services this module has been tested against. - |
-
| - | The ACME version of the endpoint. -Must be The value Choices: -
|
-
| - | - |
| - | If Choices: -
|
-
| - | The method to use to access the given URL on the ACME server. -The value The value The value Choices: -
|
-
| - | The time Ansible should wait for a response from the ACME API. -This timeout is applied to all HTTP(S) requests (HEAD, GET, POST). -Default: |
-
| - | Determines which crypto backend to use. -The default choice is If set to If set to Choices: -
|
-
| - | The URL to send the request to. -Must be specified if |
-
| - | Whether calls to the ACME directory will validate TLS certificates. -Warning: Should only ever be set to Choices: -
|
-
Attribute |
-Support |
-Description |
-
|---|---|---|
| - | Action groups: community.crypto.acme, acme - |
-Use |
-
| - | Support: none - |
-Can run in |
-
| - | Support: none - |
-Will return details on what has changed (or possibly needs changing in |
-
| - | Support: none - |
-When run twice in a row outside check mode, with the same arguments, the second invocation indicates no change. -This assumes that the system controlled/queried by the module has not changed in a relevant way. - |
-
Note
-The account_uri option must be specified for properly authenticated ACME v2 requests (except a new-account request).
Using the ansible tool, 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 /path/to/key is the correct private account key): 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".
Although the defaults are chosen so that the module can be used with the Let’s Encrypt CA, the module can in principle be used with any CA providing an ACME endpoint.
So far, the ACME modules have only been tested by the developers against Let’s Encrypt (staging and production), ZeroSSL (production), and Pebble testing server. We have got community feedback that they also work with Sectigo ACME Service for InCommon and with HARICA. If you experience problems with another ACME server, please create an issue to help us supporting it. Feedback that an ACME server not mentioned does work is also appreciated.
If a new enough version of the cryptography library is available (see Requirements for details), it will be used instead of the openssl binary. This can be explicitly disabled or enabled with the select_crypto_backend option. Note that using the openssl binary will be slower and less secure, as private key contents always have to be stored on disk (see account_key_content).
See also
-The specification of the ACME protocol (RFC 8555).
-The specification of the tls-alpn-01 challenge (RFC 8737).
---
-- name: Get directory
- community.crypto.acme_inspect:
- acme_directory: https://acme-staging-v02.api.letsencrypt.org/directory
- acme_version: 2
- method: directory-only
- register: directory
-
-- name: Create an account
- community.crypto.acme_inspect:
- acme_directory: https://acme-staging-v02.api.letsencrypt.org/directory
- acme_version: 2
- account_key_src: /etc/pki/cert/private/account.key
- url: "{{ directory.newAccount}}"
- method: post
- content: '{"termsOfServiceAgreed":true}'
- register: account_creation
- # account_creation.headers.location contains the account URI
- # if creation was successful
-
-- name: Get account information
- community.crypto.acme_inspect:
- acme_directory: https://acme-staging-v02.api.letsencrypt.org/directory
- acme_version: 2
- account_key_src: /etc/pki/cert/private/account.key
- account_uri: "{{ account_creation.headers.location }}"
- url: "{{ account_creation.headers.location }}"
- method: get
-
-- name: Update account contacts
- community.crypto.acme_inspect:
- acme_directory: https://acme-staging-v02.api.letsencrypt.org/directory
- acme_version: 2
- account_key_src: /etc/pki/cert/private/account.key
- account_uri: "{{ account_creation.headers.location }}"
- url: "{{ account_creation.headers.location }}"
- method: post
- content: '{{ account_info | to_json }}'
- vars:
- account_info:
- # For valid values, see
- # https://tools.ietf.org/html/rfc8555#section-7.3
- contact:
- - mailto:me@example.com
-
-- name: Create certificate order
- community.crypto.acme_certificate:
- acme_directory: https://acme-staging-v02.api.letsencrypt.org/directory
- acme_version: 2
- account_key_src: /etc/pki/cert/private/account.key
- account_uri: "{{ account_creation.headers.location }}"
- csr: /etc/pki/cert/csr/sample.com.csr
- fullchain_dest: /etc/httpd/ssl/sample.com-fullchain.crt
- challenge: http-01
- register: certificate_request
-
-# Assume something went wrong. certificate_request.order_uri contains
-# the order URI.
-
-- name: Get order information
- community.crypto.acme_inspect:
- acme_directory: https://acme-staging-v02.api.letsencrypt.org/directory
- acme_version: 2
- account_key_src: /etc/pki/cert/private/account.key
- account_uri: "{{ account_creation.headers.location }}"
- url: "{{ certificate_request.order_uri }}"
- method: get
- register: order
-
-- name: Get first authz for order
- community.crypto.acme_inspect:
- acme_directory: https://acme-staging-v02.api.letsencrypt.org/directory
- acme_version: 2
- account_key_src: /etc/pki/cert/private/account.key
- account_uri: "{{ account_creation.headers.location }}"
- url: "{{ order.output_json.authorizations[0] }}"
- method: get
- register: authz
-
-- name: Get HTTP-01 challenge for authz
- community.crypto.acme_inspect:
- acme_directory: https://acme-staging-v02.api.letsencrypt.org/directory
- acme_version: 2
- account_key_src: /etc/pki/cert/private/account.key
- account_uri: "{{ account_creation.headers.location }}"
- url: "{{ authz.output_json.challenges | selectattr('type', 'equalto', 'http-01') }}"
- method: get
- register: http01challenge
-
-- name: Activate HTTP-01 challenge manually
- community.crypto.acme_inspect:
- acme_directory: https://acme-staging-v02.api.letsencrypt.org/directory
- acme_version: 2
- account_key_src: /etc/pki/cert/private/account.key
- account_uri: "{{ account_creation.headers.location }}"
- url: "{{ http01challenge.url }}"
- method: post
- content: '{}'
-Common return values are documented here, the following are the fields unique to this module:
-Key |
-Description |
-
|---|---|
| - | The ACME directory’s content. -Returned: always -Sample: |
-
| - | The request’s HTTP headers (with lowercase keys). -Returned: always -Sample: |
-
| - | The output parsed as JSON. -Returned: if output can be parsed as JSON -Sample: |
-
| - | The raw text output. -Returned: always -Sample: |
-
- Note
-This module is part of the community.crypto collection (version 2.26.6).
-It is not included in ansible-core.
-To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install community.crypto.
-You need further requirements to be able to use this module,
-see Requirements for details.
To use it in a playbook, specify: community.crypto.certificate_complete_chain.
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 community.crypto.acme_certificate.
Note that this module does 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 openssl verify ....
The below requirements are needed on the host that executes this module.
-cryptography >= 1.5
Parameter |
-Comments |
-
|---|---|
| - | A concatenated set of certificates in PEM format forming a chain. -The module will try to complete this chain. - |
-
| - | 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. -Default: |
-
| - | 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. - |
-
Attribute |
-Support |
-Description |
-
|---|---|---|
| - | Support: full -This action does not modify state. - |
-Can run in |
-
| - | Support: N/A -This action does not modify state. - |
-Will return details on what has changed (or possibly needs changing in |
-
| - | Support: full -This action does not modify state. - |
-When run twice in a row outside check mode, with the same arguments, the second invocation indicates no change. -This assumes that the system controlled/queried by the module has not changed in a relevant way. - |
-
---
-# 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/
- register: www_ansible_com
-- name: Write root certificate to disk
- ansible.builtin.copy:
- dest: /etc/ssl/csr/www.ansible.com-root.pem
- content: "{{ www_ansible_com.root }}"
-
-# Given a leaf certificate for www.ansible.com, and a list of 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.pem') }}"
- intermediate_certificates:
- - /etc/ssl/csr/www.ansible.com-chain.pem
- root_certificates:
- - /etc/ca-certificates/
- register: www_ansible_com
-- name: Write complete chain to disk
- ansible.builtin.copy:
- dest: /etc/ssl/csr/www.ansible.com-completechain.pem
- content: "{{ ''.join(www_ansible_com.complete_chain) }}"
-- name: Write root chain (intermediates and root) to disk
- ansible.builtin.copy:
- dest: /etc/ssl/csr/www.ansible.com-rootchain.pem
- content: "{{ ''.join(www_ansible_com.chain) }}"
-Common return values are documented here, the following are the fields unique to this module:
-Key |
-Description |
-
|---|---|
| - | The chain added to the given input chain. Includes the root certificate. -Returned as a list of PEM certificates. -Returned: success - |
-
| - | The completed chain, including leaf, all intermediates, and root. -Returned as a list of PEM certificates. -Returned: success - |
-
| - | The root certificate in PEM format. -Returned: success - |
-
- Bugfix release.
-acme_* modules - also retry on HTTP responses 502 Bad Gateway and 504 Gateway Timeout. The latter is needed for ZeroSSL, which seems to have a lot of 504s (https://github.com/ansible-collections/community.crypto/issues/945, https://github.com/ansible-collections/community.crypto/pull/947).
acme_* modules - increase the maximum amount of retries from 10 to 20 to accomodate ZeroSSL’s buggy implementation (https://github.com/ansible-collections/community.crypto/pull/949).
Bugfix release.
-Improve error message when loading a private key fails due to correct private key files or wrong passwords. Also include the original cryptography error since it likely contains more helpful information (https://github.com/ansible-collections/community.crypto/issues/936, https://github.com/ansible-collections/community.crypto/pull/939).
Bugfix release.
-acme_account - make work with CAs that do not accept any account request without External Account Binding data (https://github.com/ansible-collections/community.crypto/issues/918, https://github.com/ansible-collections/community.crypto/pull/919).
Maintenance release announcing removal of the Entrust content from community.crypto 3.0.0.
-The Entrust service in currently being sunsetted after the sale of Entrust’s Public Certificates Business to Sectigo; see the announcement with key dates and the migration brief for customers for details (https://github.com/ansible-collections/community.crypto/issues/895, https://github.com/ansible-collections/community.crypto/pull/901).
ecs_certificate - the module will be removed from community.crypto 3.0.0 (https://github.com/ansible-collections/community.crypto/issues/895, https://github.com/ansible-collections/community.crypto/pull/901).
ecs_domain - the module will be removed from community.crypto 3.0.0 (https://github.com/ansible-collections/community.crypto/issues/895, https://github.com/ansible-collections/community.crypto/pull/901).
x509_certificate - the entrust provider will be removed from community.crypto 3.0.0 (https://github.com/ansible-collections/community.crypto/issues/895, https://github.com/ansible-collections/community.crypto/pull/901).
x509_certificate_pipe - the entrust provider will be removed from community.crypto 3.0.0 (https://github.com/ansible-collections/community.crypto/issues/895, https://github.com/ansible-collections/community.crypto/pull/901).
Bugfix and maintenance release with improved CI.
-luks_device - mark parameter passphrase_encoding as no_log=False to avoid confusing warning (https://github.com/ansible-collections/community.crypto/pull/867).
luks_device - removing a specific keyslot with remove_keyslot caused the module to hang while cryptsetup was waiting for a passphrase from stdin, while the module did not supply one. Since a keyslot is not necessary, do not provide one (https://github.com/ansible-collections/community.crypto/issues/864, https://github.com/ansible-collections/community.crypto/pull/868).
Feature release.
-openssl_pkcs12 - the module now supports certificate_content/other_certificates_content for cases where the data already exists in memory and not yet in a file (https://github.com/ansible-collections/community.crypto/issues/847, https://github.com/ansible-collections/community.crypto/pull/848).
Feature release.
-luks_device - allow passphrases to contain newlines (https://github.com/ansible-collections/community.crypto/pull/844).
New feature and bugfix release with multiple new modules. It also deprecates support for older ansible-core and Python versions.
-acme_certificate - add options order_creation_error_strategy and order_creation_max_retries which allow to configure the error handling behavior if creating a new ACME order fails. This is particularly important when using the include_renewal_cert_id option, and the default value auto for order_creation_error_strategy tries to gracefully handle related errors (https://github.com/ansible-collections/community.crypto/pull/842).
acme_certificate - allow to chose a profile for certificate generation, in case the CA supports this using Internet-Draft draft-aaron-acme-profiles (https://github.com/ansible-collections/community.crypto/pull/835).
acme_certificate_renewal_info - add exists and parsable return values and treat_parsing_error_as_non_existing option (https://github.com/ansible-collections/community.crypto/pull/838).
Support for ansible-core 2.11, 2.12, 2.13, 2.14, 2.15, and 2.16 is deprecated, and will be removed in the next major release (community.crypto 3.0.0). Some modules might still work with some of these versions afterwards, but we will no longer keep compatibility code that was needed to support them. Note that this means that support for all Python versions before 3.7 will be dropped, also on the target side (https://github.com/ansible-collections/community.crypto/issues/559, https://github.com/ansible-collections/community.crypto/pull/839).
Support for cryptography < 3.4 is deprecated, and will be removed in the next major release (community.crypto 3.0.0). Some modules might still work with older versions of cryptography, but we will no longer keep compatibility code that was needed to support them (https://github.com/ansible-collections/community.crypto/issues/559, https://github.com/ansible-collections/community.crypto/pull/839).
crypto_info - when running the module on Fedora 41 with cryptography installed from the package repository, the module crashed apparently due to some elliptic curves being removed from libssl against which cryptography is running, which cryptography did not expect (https://github.com/ansible-collections/community.crypto/pull/834).
community.crypto.acme_certificate_order_create - Create an ACME v2 order.
community.crypto.acme_certificate_order_finalize - Finalize an ACME v2 order.
community.crypto.acme_certificate_order_info - Obtain information for an ACME v2 order.
community.crypto.acme_certificate_order_validate - Validate authorizations of an ACME v2 order.
Feature release.
-acme_certificate - add compatibility for ACME CAs that are not fully RFC8555 compliant and do not provide challenges in authz objects (https://github.com/ansible-collections/community.crypto/issues/824, https://github.com/ansible-collections/community.crypto/pull/832).
luks_device - allow to provide passphrases base64-encoded (https://github.com/ansible-collections/community.crypto/issues/827, https://github.com/ansible-collections/community.crypto/pull/829).
x509_certificate_convert - add new option verify_cert_parsable which allows to check whether the certificate can actually be parsed (https://github.com/ansible-collections/community.crypto/issues/809, https://github.com/ansible-collections/community.crypto/pull/830).
openssl_pkcs12 - the PyOpenSSL based backend is deprecated and will be removed from community.crypto 3.0.0. From that point on you need cryptography 3.0 or newer to use this module (https://github.com/ansible-collections/community.crypto/issues/667, https://github.com/ansible-collections/community.crypto/pull/831).
Bugfix release.
-acme_* modules - when using the OpenSSL backend, explicitly use the UTC timezone in Python code (https://github.com/ansible-collections/community.crypto/pull/811).
time module utils - fix conversion of naive datetime objects to UNIX timestamps for Python 3 (https://github.com/ansible-collections/community.crypto/issues/808, https://github.com/ansible-collections/community.crypto/pull/810).
Bugfix release.
-acme_certificate - fix authorization failure when CSR contains SANs with mixed case (https://github.com/ansible-collections/community.crypto/pull/803).
Bugfix release.
-acme_* modules - when querying renewal information, make sure to insert a slash between the base URL and the certificate identifier (https://github.com/ansible-collections/community.crypto/issues/801, https://github.com/ansible-collections/community.crypto/pull/802).
various modules - pass absolute paths to module.atomic_move() (https://github.com/ansible/ansible/issues/83950, https://github.com/ansible-collections/community.crypto/pull/799).
Feature release.
-openssl_privatekey, openssl_privatekey_pipe - add default value auto for cipher option, which happens to be the only supported value for this option anyway. Therefore it is no longer necessary to specify cipher=auto when providing passphrase (https://github.com/ansible-collections/community.crypto/issues/793, https://github.com/ansible-collections/community.crypto/pull/794).
Maintenance release.
-When using cryptography >= 43.0.0, use offset-aware datetime.datetime objects (with timezone UTC) instead of offset-naive UTC timestamps for the InvalidityDate X.509 CRL extension (https://github.com/ansible-collections/community.crypto/issues/726, https://github.com/ansible-collections/community.crypto/pull/730).
Feature release.
-certificate_complete_chain - add ability to identify Ed25519 and Ed448 complete chains (https://github.com/ansible-collections/community.crypto/pull/777).
get_certificate - adds tls_ctx_options option for specifying SSL CTX options (https://github.com/ansible-collections/community.crypto/pull/779).
get_certificate - allow to obtain the certificate chain sent by the server, and the one used for validation, with the new get_certificate_chain option. Note that this option only works if the module is run with Python 3.10 or newer (https://github.com/ansible-collections/community.crypto/issues/568, https://github.com/ansible-collections/community.crypto/pull/784).
Feature and bugfix release.
-The deprecations in this release are only relevant for collections that use shared -code or docs fragments from this collection.
-acme_certificate - add include_renewal_cert_id option to allow requesting renewal of a specific certificate according to the current ACME Renewal Information specification draft (https://github.com/ansible-collections/community.crypto/pull/739).
acme documentation fragment - the default community.crypto.acme[.documentation] docs fragment is deprecated and will be removed from community.crypto 3.0.0. Replace it with both the new community.crypto.acme.basic and community.crypto.acme.account fragments (https://github.com/ansible-collections/community.crypto/pull/735).
acme.backends module utils - the get_cert_information() method for a ACME crypto backend must be implemented from community.crypto 3.0.0 on (https://github.com/ansible-collections/community.crypto/pull/736).
crypto.module_backends.common module utils - the crypto.module_backends.common module utils is deprecated and will be removed from community.crypto 3.0.0. Use the improved argspec module util instead (https://github.com/ansible-collections/community.crypto/pull/749).
x509_crl, x509_certificate, x509_certificate_info - when parsing absolute timestamps which omitted the second count, the first digit of the minutes was used as a one-digit minutes count, and the second digit of the minutes as a one-digit second count (https://github.com/ansible-collections/community.crypto/pull/745).
community.crypto.acme_ari_info - Retrieves ACME Renewal Information (ARI) for a certificate.
community.crypto.acme_certificate_deactivate_authz - Deactivate all authz for an ACME v2 order.
community.crypto.acme_certificate_renewal_info - Determine whether a certificate should be renewed or not.
Bugfix release.
-crypto.math module utils - change return values for quick_is_not_prime() and convert_int_to_bytes(0, 0) for special cases that do not appear when using the collection (https://github.com/ansible-collections/community.crypto/pull/733).
ecs_certificate - fixed csr option to be empty and allow renewal of a specific certificate according to the Renewal Information specification (https://github.com/ansible-collections/community.crypto/pull/740).
x509_certificate - since community.crypto 2.19.0 the module was no longer idempotent with respect to not_before and not_after times. This is now fixed (https://github.com/ansible-collections/community.crypto/issues/753, https://github.com/ansible-collections/community.crypto/pull/754).
Bugfix and feature release.
-When using cryptography >= 42.0.0, use offset-aware datetime.datetime objects (with timezone UTC) instead of offset-naive UTC timestamps (https://github.com/ansible-collections/community.crypto/issues/726, https://github.com/ansible-collections/community.crypto/pull/727).
openssh_cert - avoid UTC functions deprecated in Python 3.12 when using Python 3 (https://github.com/ansible-collections/community.crypto/pull/727).
acme.backends module utils - from community.crypto on, all implementations of CryptoBackend must override get_ordered_csr_identifiers(). The current default implementation, which simply sorts the result of get_csr_identifiers(), will then be removed (https://github.com/ansible-collections/community.crypto/pull/725).
acme_certificate - respect the order of the CNAME and SAN identifiers that are passed on when creating an ACME order (https://github.com/ansible-collections/community.crypto/issues/723, https://github.com/ansible-collections/community.crypto/pull/725).
community.crypto.x509_certificate_convert - Convert X.509 certificates
Bugfix and feature release.
-x509_crl - the new option serial_numbers allow to configure in which format serial numbers can be provided to revoked_certificates[].serial_number. The default is as integers (serial_numbers=integer) for backwards compatibility; setting serial_numbers=hex-octets allows to specify colon-separated hex octet strings like 00:11:22:FF (https://github.com/ansible-collections/community.crypto/issues/687, https://github.com/ansible-collections/community.crypto/pull/715).
openssl_csr_pipe, openssl_privatekey_pipe, x509_certificate_pipe - the current behavior of check mode is deprecated and will change in community.crypto 3.0.0. The current behavior is similar to the modules without _pipe: if the object needs to be (re-)generated, only the changed status is set, but the object is not updated. From community.crypto 3.0.0 on, the modules will ignore check mode and always act as if check mode is not active. This behavior can already achieved now by adding check_mode: false to the task. If you think this breaks your use-case of this module, please create an issue in the community.crypto repository (https://github.com/ansible-collections/community.crypto/issues/712, https://github.com/ansible-collections/community.crypto/pull/714).
luks_device - fixed module a bug that prevented using remove_keyslot with the value 0 (https://github.com/ansible-collections/community.crypto/pull/710).
luks_device - fixed module falsely outputting changed=false when trying to add a new slot with a key that is already present in another slot. The module now rejects adding keys that are already present in another slot (https://github.com/ansible-collections/community.crypto/pull/710).
luks_device - fixed testing of LUKS passphrases in when specifying a keyslot for cryptsetup version 2.0.3. The output of this cryptsetup version slightly differs from later versions (https://github.com/ansible-collections/community.crypto/pull/710).
community.crypto.parse_serial - Convert a serial number as a colon-separated list of hex numbers to an integer
community.crypto.to_serial - Convert an integer to a colon-separated list of hex numbers
Bugfix release for compatibility with cryptography 42.0.0.
-openssl_dhparam - was using an internal function instead of the public API to load DH param files when using the cryptography backend. The internal function was removed in cryptography 42.0.0. The module now uses the public API, which has been available since support for DH params was added to cryptography (https://github.com/ansible-collections/community.crypto/pull/698).
openssl_privatekey_info - check_consistency=true no longer works for RSA keys with cryptography 42.0.0+ (https://github.com/ansible-collections/community.crypto/pull/701).
openssl_privatekey_info - check_consistency=true now reports a warning if it cannot determine consistency (https://github.com/ansible-collections/community.crypto/pull/705).
Feature release.
-luks_device - add allow discards option (https://github.com/ansible-collections/community.crypto/pull/693).
Bugfix release.
-acme_* modules - directly react on bad return data for account creation/retrieval/updating requests (https://github.com/ansible-collections/community.crypto/pull/682).
acme_* modules - fix improved error reporting in case of socket errors, bad status lines, and unknown connection errors (https://github.com/ansible-collections/community.crypto/pull/684).
acme_* modules - increase number of retries from 5 to 10 to increase stability with unstable ACME endpoints (https://github.com/ansible-collections/community.crypto/pull/685).
acme_* modules - make account registration handling more flexible to accept 404 instead of 400 send by DigiCert’s ACME endpoint when an account does not exist (https://github.com/ansible-collections/community.crypto/pull/681).
Bugfix release.
-acme_* modules - also retry requests in case of socket errors, bad status lines, and unknown connection errors; improve error messages in these cases (https://github.com/ansible-collections/community.crypto/issues/680).
Bugfix release.
-luks_devices - add new options keyslot, new_keyslot, and remove_keyslot to allow adding/removing keys to/from specific keyslots (https://github.com/ansible-collections/community.crypto/pull/664).
openssl_pkcs12 - modify autodetect to not detect pyOpenSSL >= 23.3.0, which removed PKCS#12 support (https://github.com/ansible-collections/community.crypto/pull/666).
Bugfix release.
-acme_* modules - correctly handle error documents without type (https://github.com/ansible-collections/community.crypto/issues/651, https://github.com/ansible-collections/community.crypto/pull/652).
Bugfix and feature release.
-openssh_keypair - fail when comment cannot be updated (https://github.com/ansible-collections/community.crypto/pull/646).
get_certificate - the default false of the asn1_base64 option is deprecated and will change to true in community.crypto 3.0.0 (https://github.com/ansible-collections/community.crypto/pull/600).
openssh_cert, openssh_keypair - the modules ignored return codes of ssh and ssh-keygen in some cases (https://github.com/ansible-collections/community.crypto/issues/645, https://github.com/ansible-collections/community.crypto/pull/646).
openssh_keypair - fix comment updating for OpenSSH before 6.5 (https://github.com/ansible-collections/community.crypto/pull/646).
community.crypto.gpg_fingerprint - Retrieve a GPG fingerprint from a GPG public or private key
community.crypto.gpg_fingerprint - Retrieve a GPG fingerprint from a GPG public or private key file
Bugfix and maintenance release with updated documentation.
-From this version on, community.crypto is using the new Ansible semantic markup -in its documentation. If you look at documentation with the ansible-doc CLI tool -from ansible-core before 2.15, please note that it does not render the markup -correctly. You should be still able to read it in most cases, but you need -ansible-core 2.15 or later to see it as it is intended. Alternatively you can -look at the devel docsite -for the rendered HTML version of the documentation of the latest release.
-Fix PEM detection/identification to also accept random other lines before the line starting with -----BEGIN (https://github.com/ansible-collections/community.crypto/issues/627, https://github.com/ansible-collections/community.crypto/pull/628).
Ansible markup will show up in raw form on ansible-doc text output for ansible-core before 2.15. If you have trouble deciphering the documentation markup, please upgrade to ansible-core 2.15 (or newer), or read the HTML documentation on https://docs.ansible.com/ansible/devel/collections/community/crypto/.
Feature release.
-acme_certificate - allow to use no challenge by providing no challenge for the challenge option. This is needed for ACME servers where validation is done without challenges (https://github.com/ansible-collections/community.crypto/issues/613, https://github.com/ansible-collections/community.crypto/pull/615).
acme_certificate - validate and wait for challenges in parallel instead handling them one after another (https://github.com/ansible-collections/community.crypto/pull/617).
x509_certificate_info - added support for certificates in DER format when using path parameter (https://github.com/ansible-collections/community.crypto/issues/603).
Bugfix release.
-execution environment definition - fix installation of python3-pyOpenSSL package on CentOS and RHEL (https://github.com/ansible-collections/community.crypto/pull/606).
execution environment definition - fix source of python3-pyOpenSSL package for Rocky Linux 9+ (https://github.com/ansible-collections/community.crypto/pull/606).
Bugfix and maintenance release.
-x509_crl - the crl_mode option has been added to replace the existing mode option (https://github.com/ansible-collections/community.crypto/issues/596).
x509_crl - the mode option is deprecated; use crl_mode instead. The mode option will change its meaning in community.crypto 3.0.0, and will refer to the CRL file’s mode instead (https://github.com/ansible-collections/community.crypto/issues/596).
openssh_keypair - always generate a new key pair if the private key does not exist. Previously, the module would fail when regenerate=fail without an existing key, contradicting the documentation (https://github.com/ansible-collections/community.crypto/pull/598).
x509_crl - remove problem with ansible-core 2.16 due to AnsibleModule is now validating the mode parameter’s values (https://github.com/ansible-collections/community.crypto/issues/596).
Feature release.
-get_certificate - add asn1_base64 option to control whether the ASN.1 included in the extensions return value is binary data or Base64 encoded (https://github.com/ansible-collections/community.crypto/pull/592).
Maintenance release with improved documentation.
-Feature and bugfix release.
-get_certificate - adds ciphers option for custom cipher selection (https://github.com/ansible-collections/community.crypto/pull/571).
action plugin helper - fix handling of deprecations for ansible-core 2.14.2 (https://github.com/ansible-collections/community.crypto/pull/572).
execution environment binary dependencies (bindep.txt) - fix python3-pyOpenSSL dependency resolution on RHEL 9+ / CentOS Stream 9+ platforms (https://github.com/ansible-collections/community.crypto/pull/575).
various plugins - remove unnecessary imports (https://github.com/ansible-collections/community.crypto/pull/569).
Bugfix and feature release.
-openssl_csr, openssl_csr_pipe - prevent invalid values for crl_distribution_points that do not have one of full_name, relative_name, and crl_issuer (https://github.com/ansible-collections/community.crypto/pull/560).
openssl_publickey_info - do not crash with internal error when public key cannot be parsed (https://github.com/ansible-collections/community.crypto/pull/551).
community.crypto.openssl_csr_info - Retrieve information from OpenSSL Certificate Signing Requests (CSR)
community.crypto.openssl_privatekey_info - Retrieve information from OpenSSL private keys
community.crypto.openssl_publickey_info - Retrieve information from OpenSSL public keys in PEM format
community.crypto.split_pem - Split PEM file contents into multiple objects
community.crypto.x509_certificate_info - Retrieve information from X.509 certificates in PEM format
community.crypto.x509_crl_info - Retrieve information from X.509 CRLs in PEM format
Regular feature release.
-x509_certificate_info - adds issuer_uri field in return value based on Authority Information Access data (https://github.com/ansible-collections/community.crypto/pull/530).
Maintenance release with improved documentation.
-Feature release.
-acme_* modules - handle more gracefully if CA’s new nonce call does not return a nonce (https://github.com/ansible-collections/community.crypto/pull/525).
acme_* modules - include symbolic HTTP status codes in error and log messages when available (https://github.com/ansible-collections/community.crypto/pull/524).
openssl_pkcs12 - add option encryption_level which allows to chose compatibility2022 when cryptography >= 38.0.0 is used to enable a more backwards compatible encryption algorithm. If cryptography uses OpenSSL 3.0.0 or newer, the default algorithm is not compatible with older software (https://github.com/ansible-collections/community.crypto/pull/523).
Maintenance release.
-acme_* modules - improve feedback when importing cryptography does not work (https://github.com/ansible-collections/community.crypto/issues/518, https://github.com/ansible-collections/community.crypto/pull/519).
Feature release.
-acme* modules - also support the HTTP 503 Service Unavailable and 408 Request Timeout response status for automatic retries (https://github.com/ansible-collections/community.crypto/pull/513).
openssl_privatekey_pipe - ensure compatibility with newer versions of ansible-core (https://github.com/ansible-collections/community.crypto/pull/515).
Feature release.
-acme* modules - support the HTTP 429 Too Many Requests response status (https://github.com/ansible-collections/community.crypto/pull/508).
openssh_keypair - added pkcs1, pkcs8, and ssh to the available choices for the private_key_format option (https://github.com/ansible-collections/community.crypto/pull/511).
Maintenance release with improved licensing declaration and documentation fixes.
-All software licenses are now in the LICENSES/ directory of the collection root. Moreover, SPDX-License-Identifier: is used to declare the applicable license for every file that is not automatically generated (https://github.com/ansible-collections/community.crypto/pull/491).
Deprecation and bugfix release. No new features this time.
-Support for Ansible 2.9 and ansible-base 2.10 is deprecated, and will be removed in the next major release (community.crypto 3.0.0). Some modules might still work with these versions afterwards, but we will no longer keep compatibility code that was needed to support them (https://github.com/ansible-collections/community.crypto/pull/460).
openssl_pkcs12 - when using the pyOpenSSL backend, do not crash when trying to read non-existing other certificates (https://github.com/ansible-collections/community.crypto/issues/486, https://github.com/ansible-collections/community.crypto/pull/487).
Re-release of what was intended to be 2.3.3.
-A mistake during the release process caused the 2.3.3 tag to end up on the -commit for 1.9.17, which caused the release pipeline to re-publish 1.9.17 -as 2.3.3.
-This release is identical to what should have been 2.3.3, except that the -version number has been bumped to 2.3.4 and this changelog entry for 2.3.4 -has been added.
-Bugfix release.
-Include Apache-2.0.txt file for plugins/module_utils/crypto/_obj2txt.py and plugins/module_utils/crypto/_objects_data.py.
openssl_csr - the module no longer crashes with ‘permitted_subtrees/excluded_subtrees must be a non-empty list or None’ if only one of name_constraints_permitted and name_constraints_excluded is provided (https://github.com/ansible-collections/community.crypto/issues/481).
x509_crl - do not crash when signing CRL with Ed25519 or Ed448 keys (https://github.com/ansible-collections/community.crypto/issues/473, https://github.com/ansible-collections/community.crypto/pull/474).
Maintenance and bugfix release.
-Include simplified_bsd.txt license file for the ECS module utils.
certificate_complete_chain - do not stop execution if an unsupported signature algorithm is encountered; warn instead (https://github.com/ansible-collections/community.crypto/pull/457).
Maintenance release.
-Include PSF-license.txt file for plugins/module_utils/_version.py.
Feature and bugfix release.
-Prepare collection for inclusion in an Execution Environment by declaring its dependencies. Please note that system packages are used for cryptography and PyOpenSSL, which can be rather limited. If you need features from newer cryptography versions, you will have to manually force a newer version to be installed by pip by specifying something like cryptography >= 37.0.0 in your Execution Environment’s Python dependencies file (https://github.com/ansible-collections/community.crypto/pull/440).
Support automatic conversion for Internalionalized Domain Names (IDNs). When passing general names, for example Subject Alternative Names to community.crypto.openssl_csr, these will automatically be converted to IDNA. Conversion will be done per label to IDNA2008 if possible, and IDNA2003 if IDNA2008 conversion fails for that label. Note that IDNA conversion requires the Python idna library to be installed. Please note that depending on which versions of the cryptography library are used, it could try to process the converted IDNA another time with the Python idna library and reject IDNA2003 encoded values. Using a new enough cryptography version avoids this (https://github.com/ansible-collections/community.crypto/issues/426, https://github.com/ansible-collections/community.crypto/pull/436).
acme_* modules - add parameter request_timeout to manage HTTP(S) request timeout (https://github.com/ansible-collections/community.crypto/issues/447, https://github.com/ansible-collections/community.crypto/pull/448).
luks_devices - added perf_same_cpu_crypt, perf_submit_from_crypt_cpus, perf_no_read_workqueue, perf_no_write_workqueue for performance tuning when opening LUKS2 containers (https://github.com/ansible-collections/community.crypto/issues/427).
luks_devices - added persistent option when opening LUKS2 containers (https://github.com/ansible-collections/community.crypto/pull/434).
openssl_csr_info - add name_encoding option to control the encoding (IDNA, Unicode) used to return domain names in general names (https://github.com/ansible-collections/community.crypto/pull/436).
openssl_pkcs12 - allow to provide the private key as text instead of having to read it from a file. This allows to store the private key in an encrypted form, for example in Ansible Vault (https://github.com/ansible-collections/community.crypto/pull/452).
x509_certificate_info - add name_encoding option to control the encoding (IDNA, Unicode) used to return domain names in general names (https://github.com/ansible-collections/community.crypto/pull/436).
x509_crl - add name_encoding option to control the encoding (IDNA, Unicode) used to return domain names in general names (https://github.com/ansible-collections/community.crypto/pull/436).
x509_crl_info - add name_encoding option to control the encoding (IDNA, Unicode) used to return domain names in general names (https://github.com/ansible-collections/community.crypto/pull/436).
Make collection more robust when PyOpenSSL is used with an incompatible cryptography version (https://github.com/ansible-collections/community.crypto/pull/445).
x509_crl - fix crash when issuer for a revoked certificate is specified (https://github.com/ansible-collections/community.crypto/pull/441).
Regular maintenance release.
-openssh_* modules - fix exception handling to report traceback to users for enhanced traceability (https://github.com/ansible-collections/community.crypto/pull/417).
Regular bugfix release.
-luks_device - fix parsing of lsblk output when device name ends with crypt (https://github.com/ansible-collections/community.crypto/issues/409, https://github.com/ansible-collections/community.crypto/pull/410).
Regular bugfix release.
-In this release, we extended the test matrix to include Alpine 3, ArchLinux, Debian Bullseye, and CentOS Stream 8. CentOS 8 was removed from the test matrix.
-certificate_complete_chain - allow multiple potential intermediate certificates to have the same subject (https://github.com/ansible-collections/community.crypto/issues/399, https://github.com/ansible-collections/community.crypto/pull/403).
x509_certificate - for the ownca provider, check whether the CA private key actually belongs to the CA certificate (https://github.com/ansible-collections/community.crypto/pull/407).
x509_certificate - regenerate certificate when the CA’s public key changes for provider=ownca (https://github.com/ansible-collections/community.crypto/pull/407).
x509_certificate - regenerate certificate when the CA’s subject changes for provider=ownca (https://github.com/ansible-collections/community.crypto/issues/400, https://github.com/ansible-collections/community.crypto/pull/402).
x509_certificate - regenerate certificate when the private key changes for provider=selfsigned (https://github.com/ansible-collections/community.crypto/pull/407).
Bugfix release.
-openssh_cert - fixed false changed status for host certificates when using full_idempotence (https://github.com/ansible-collections/community.crypto/issues/395, https://github.com/ansible-collections/community.crypto/pull/396).
Regular bugfix and feature release.
-openssh_cert - added ignore_timestamps parameter so it can be used semi-idempotent with relative timestamps in valid_to/valid_from (https://github.com/ansible-collections/community.crypto/issues/379).
luks_devices - set LANG and similar environment variables to avoid translated output, which can break some of the module’s functionality like key management (https://github.com/ansible-collections/community.crypto/pull/388, https://github.com/ansible-collections/community.crypto/issues/385).
Feature and bugfix release.
-Adjust error messages that indicate cryptography is not installed from Can't to Cannot (https://github.com/ansible-collections/community.crypto/pull/374).
Various modules and plugins - use vendored version of distutils.version instead of the deprecated Python standard library distutils (https://github.com/ansible-collections/community.crypto/pull/353).
certificate_complete_chain - do not append root twice if the chain already ends with a root certificate (https://github.com/ansible-collections/community.crypto/pull/360).
certificate_complete_chain - do not hang when infinite loop is found (https://github.com/ansible-collections/community.crypto/issues/355, https://github.com/ansible-collections/community.crypto/pull/360).
community.crypto.crypto_info - Retrieve cryptographic capabilities
community.crypto.openssl_privatekey_convert - Convert OpenSSL private keys
Documentation fix release. No actual code changes.
-Bugfix release with extra forward compatibility for newer versions of cryptography.
-acme_* modules - fix usage of fetch_url with changes in latest ansible-core devel branch (https://github.com/ansible-collections/community.crypto/pull/339).
acme_certificate - avoid passing multiple certificates to cryptography’s X.509 certificate loader when fullchain_dest is used (https://github.com/ansible-collections/community.crypto/pull/324).
get_certificate, openssl_csr_info, x509_certificate_info - add fallback code for extension parsing that works with cryptography 36.0.0 and newer. This code re-serializes de-serialized extensions and thus can return slightly different values if the extension in the original CSR resp. certificate was not canonicalized correctly. This code is currently used as a fallback if the existing code stops working, but we will switch it to be the main code in a future release (https://github.com/ansible-collections/community.crypto/pull/331).
luks_device - now also runs a built-in LUKS signature cleaner on state=absent to make sure that also the secondary LUKS2 header is wiped when older versions of wipefs are used (https://github.com/ansible-collections/community.crypto/issues/326, https://github.com/ansible-collections/community.crypto/pull/327).
openssl_pkcs12 - use new PKCS#12 deserialization infrastructure from cryptography 36.0.0 if available (https://github.com/ansible-collections/community.crypto/pull/302).
A new major release of the community.crypto collection. The main changes are removal of the PyOpenSSL backends for almost all modules (openssl_pkcs12 being the only exception), and removal of the assertonly provider in the x509_certificate provider. There are also some other breaking changes which should improve the user interface/experience of this collection long-term.
acme_certificate - the subject and issuer fields in in the select_chain entries are now more strictly validated (https://github.com/ansible-collections/community.crypto/pull/316).
openssl_csr, openssl_csr_pipe - provide a new subject_ordered option if the order of the components in the subject is of importance (https://github.com/ansible-collections/community.crypto/issues/291, https://github.com/ansible-collections/community.crypto/pull/316).
openssl_csr, openssl_csr_pipe - there is now stricter validation of the values of the subject option (https://github.com/ansible-collections/community.crypto/pull/316).
openssl_privatekey_info - add check_consistency option to request private key consistency checks to be done (https://github.com/ansible-collections/community.crypto/pull/309).
x509_certificate, x509_certificate_pipe - add ignore_timestamps option which allows to enable idempotency for ‘not before’ and ‘not after’ options (https://github.com/ansible-collections/community.crypto/issues/295, https://github.com/ansible-collections/community.crypto/pull/317).
x509_crl - provide a new issuer_ordered option if the order of the components in the issuer is of importance (https://github.com/ansible-collections/community.crypto/issues/291, https://github.com/ansible-collections/community.crypto/pull/316).
x509_crl - there is now stricter validation of the values of the issuer option (https://github.com/ansible-collections/community.crypto/pull/316).
Adjust dirName text parsing and to text converting code to conform to Sections 2 and 3 of RFC 4514. This is similar to how cryptography handles this (https://github.com/ansible-collections/community.crypto/pull/274).
acme module utils - removing compatibility code (https://github.com/ansible-collections/community.crypto/pull/290).
acme_* modules - removed vendored copy of the Python library ipaddress. If you are using Python 2.x, please make sure to install the library (https://github.com/ansible-collections/community.crypto/pull/287).
compatibility module_utils - removed vendored copy of the Python library ipaddress (https://github.com/ansible-collections/community.crypto/pull/287).
crypto module utils - removing compatibility code (https://github.com/ansible-collections/community.crypto/pull/290).
get_certificate, openssl_csr_info, x509_certificate_info - depending on the cryptography version used, the modules might not return the ASN.1 value for an extension as contained in the certificate respectively CSR, but a re-encoded version of it. This should usually be identical to the value contained in the source file, unless the value was malformed. For extensions not handled by C(cryptography) the value contained in the source file is always returned unaltered (https://github.com/ansible-collections/community.crypto/pull/318).
module_utils - removed various PyOpenSSL support functions and default backend values that are not needed for the openssl_pkcs12 module (https://github.com/ansible-collections/community.crypto/pull/273).
openssl_csr, openssl_csr_pipe, x509_crl - the subject respectively issuer fields no longer ignore empty values, but instead fail when encountering them (https://github.com/ansible-collections/community.crypto/pull/316).
openssl_privatekey_info - by default consistency checks are not run; they need to be explicitly requested by passing check_consistency=true (https://github.com/ansible-collections/community.crypto/pull/309).
x509_crl - for idempotency checks, the issuer order is ignored. If order is important, use the new issuer_ordered option (https://github.com/ansible-collections/community.crypto/pull/316).
acme_* modules - ACME version 1 is now deprecated and support for it will be removed in community.crypto 2.0.0 (https://github.com/ansible-collections/community.crypto/pull/288).
acme_* modules - the acme_directory option is now required (https://github.com/ansible-collections/community.crypto/pull/290).
acme_* modules - the acme_version option is now required (https://github.com/ansible-collections/community.crypto/pull/290).
acme_account_facts - the deprecated redirect has been removed. Use community.crypto.acme_account_info instead (https://github.com/ansible-collections/community.crypto/pull/290).
acme_account_info - retrieve_orders=url_list no longer returns the return value orders. Use the order_uris return value instead (https://github.com/ansible-collections/community.crypto/pull/290).
crypto.info module utils - the deprecated redirect has been removed. Use crypto.pem instead (https://github.com/ansible-collections/community.crypto/pull/290).
get_certificate - removed the pyopenssl backend (https://github.com/ansible-collections/community.crypto/pull/273).
openssl_certificate - the deprecated redirect has been removed. Use community.crypto.x509_certificate instead (https://github.com/ansible-collections/community.crypto/pull/290).
openssl_certificate_info - the deprecated redirect has been removed. Use community.crypto.x509_certificate_info instead (https://github.com/ansible-collections/community.crypto/pull/290).
openssl_csr - removed the pyopenssl backend (https://github.com/ansible-collections/community.crypto/pull/273).
openssl_csr and openssl_csr_pipe - version now only accepts the (default) value 1 (https://github.com/ansible-collections/community.crypto/pull/290).
openssl_csr_info - removed the pyopenssl backend (https://github.com/ansible-collections/community.crypto/pull/273).
openssl_csr_pipe - removed the pyopenssl backend (https://github.com/ansible-collections/community.crypto/pull/273).
openssl_privatekey - removed the pyopenssl backend (https://github.com/ansible-collections/community.crypto/pull/273).
openssl_privatekey_info - removed the pyopenssl backend (https://github.com/ansible-collections/community.crypto/pull/273).
openssl_privatekey_pipe - removed the pyopenssl backend (https://github.com/ansible-collections/community.crypto/pull/273).
openssl_publickey - removed the pyopenssl backend (https://github.com/ansible-collections/community.crypto/pull/273).
openssl_publickey_info - removed the pyopenssl backend (https://github.com/ansible-collections/community.crypto/pull/273).
openssl_signature - removed the pyopenssl backend (https://github.com/ansible-collections/community.crypto/pull/273).
openssl_signature_info - removed the pyopenssl backend (https://github.com/ansible-collections/community.crypto/pull/273).
x509_certificate - remove assertonly provider (https://github.com/ansible-collections/community.crypto/pull/289).
x509_certificate - removed the pyopenssl backend (https://github.com/ansible-collections/community.crypto/pull/273).
x509_certificate_info - removed the pyopenssl backend (https://github.com/ansible-collections/community.crypto/pull/273).
x509_certificate_pipe - removed the pyopenssl backend (https://github.com/ansible-collections/community.crypto/pull/273).
cryptography backend - improve Unicode handling for Python 2 (https://github.com/ansible-collections/community.crypto/pull/313).
get_certificate - fix compatibility with the cryptography 35.0.0 release (https://github.com/ansible-collections/community.crypto/pull/294).
openssl_csr_info - fix compatibility with the cryptography 35.0.0 release (https://github.com/ansible-collections/community.crypto/pull/294).
openssl_pkcs12 - fix compatibility with the cryptography 35.0.0 release (https://github.com/ansible-collections/community.crypto/pull/296).
x509_certificate_info - fix compatibility with the cryptography 35.0.0 release (https://github.com/ansible-collections/community.crypto/pull/294).
Regular bugfix release.
-acme_* modules - fix commands composed for OpenSSL backend to retrieve information on CSRs and certificates from stdin to use /dev/stdin instead of -. This is needed for OpenSSL 1.0.1 and 1.0.2, apparently (https://github.com/ansible-collections/community.crypto/pull/279).
acme_challenge_cert_helper - only return exception when cryptography is not installed, not when a too old version of it is installed. This prevents Ansible’s callback to crash (https://github.com/ansible-collections/community.crypto/pull/281).
Regular bugfix release.
-openssl_csr and openssl_csr_pipe - make sure that Unicode strings are used to compare strings with the cryptography backend. This fixes idempotency problems with non-ASCII letters on Python 2 (https://github.com/ansible-collections/community.crypto/issues/270, https://github.com/ansible-collections/community.crypto/pull/271).
Bugfix release to fix the changelog. No other change compared to 1.9.0.
-Accidental 1.9.1 release. Identical to 1.9.0.
-Regular feature release.
-get_certificate - added starttls option to retrieve certificates from servers which require clients to request an encrypted connection (https://github.com/ansible-collections/community.crypto/pull/264).
openssh_keypair - added diff support (https://github.com/ansible-collections/community.crypto/pull/260).
keypair_backend module utils - simplify code to pass sanity tests (https://github.com/ansible-collections/community.crypto/pull/263).
openssh_keypair - fixed cryptography backend to preserve original file permissions when regenerating a keypair requires existing files to be overwritten (https://github.com/ansible-collections/community.crypto/pull/260).
openssh_keypair - fixed error handling to restore original keypair if regeneration fails (https://github.com/ansible-collections/community.crypto/pull/260).
x509_crl - restore inherited function signature to pass sanity tests (https://github.com/ansible-collections/community.crypto/pull/263).
Regular bugfix and feature release.
-Avoid internal ansible-core module_utils in favor of equivalent public API available since at least Ansible 2.9 (https://github.com/ansible-collections/community.crypto/pull/253).
openssh certificate module utils - new module_utils for parsing OpenSSH certificates (https://github.com/ansible-collections/community.crypto/pull/246).
openssh_cert - added regenerate option to validate additional certificate parameters which trigger regeneration of an existing certificate (https://github.com/ansible-collections/community.crypto/pull/256).
openssh_cert - adding diff support (https://github.com/ansible-collections/community.crypto/pull/255).
openssh_cert - fixed certificate generation to restore original certificate if an error is encountered (https://github.com/ansible-collections/community.crypto/pull/255).
openssh_keypair - fixed a bug that prevented custom file attributes being applied to public keys (https://github.com/ansible-collections/community.crypto/pull/257).
Bugfix release.
-openssl_pkcs12 - fix crash when loading passphrase-protected PKCS#12 files with cryptography backend (https://github.com/ansible-collections/community.crypto/issues/247, https://github.com/ansible-collections/community.crypto/pull/248).
Regular feature and bugfix release.
-cryptography_openssh module utils - new module_utils for managing asymmetric keypairs and OpenSSH formatted/encoded asymmetric keypairs (https://github.com/ansible-collections/community.crypto/pull/213).
openssh_keypair - added backend parameter for selecting between the cryptography library or the OpenSSH binary for the execution of actions performed by openssh_keypair (https://github.com/ansible-collections/community.crypto/pull/236).
openssh_keypair - added passphrase parameter for encrypting/decrypting OpenSSH private keys (https://github.com/ansible-collections/community.crypto/pull/225).
openssl_csr - add diff mode (https://github.com/ansible-collections/community.crypto/issues/38, https://github.com/ansible-collections/community.crypto/pull/150).
openssl_csr_info - now returns public_key_type and public_key_data (https://github.com/ansible-collections/community.crypto/pull/233).
openssl_csr_info - refactor module to allow code reuse for diff mode (https://github.com/ansible-collections/community.crypto/pull/204).
openssl_csr_pipe - add diff mode (https://github.com/ansible-collections/community.crypto/issues/38, https://github.com/ansible-collections/community.crypto/pull/150).
openssl_pkcs12 - added option select_crypto_backend and a cryptography backend. This requires cryptography 3.0 or newer, and does not support the iter_size and maciter_size options (https://github.com/ansible-collections/community.crypto/pull/234).
openssl_privatekey - add diff mode (https://github.com/ansible-collections/community.crypto/issues/38, https://github.com/ansible-collections/community.crypto/pull/150).
openssl_privatekey_info - refactor module to allow code reuse for diff mode (https://github.com/ansible-collections/community.crypto/pull/205).
openssl_privatekey_pipe - add diff mode (https://github.com/ansible-collections/community.crypto/issues/38, https://github.com/ansible-collections/community.crypto/pull/150).
openssl_publickey - add diff mode (https://github.com/ansible-collections/community.crypto/issues/38, https://github.com/ansible-collections/community.crypto/pull/150).
x509_certificate - add diff mode (https://github.com/ansible-collections/community.crypto/issues/38, https://github.com/ansible-collections/community.crypto/pull/150).
x509_certificate_info - now returns public_key_type and public_key_data (https://github.com/ansible-collections/community.crypto/pull/233).
x509_certificate_info - refactor module to allow code reuse for diff mode (https://github.com/ansible-collections/community.crypto/pull/206).
x509_certificate_pipe - add diff mode (https://github.com/ansible-collections/community.crypto/issues/38, https://github.com/ansible-collections/community.crypto/pull/150).
x509_crl - add diff mode (https://github.com/ansible-collections/community.crypto/issues/38, https://github.com/ansible-collections/community.crypto/pull/150).
x509_crl_info - add list_revoked_certificates option to avoid enumerating all revoked certificates (https://github.com/ansible-collections/community.crypto/pull/232).
x509_crl_info - refactor module to allow code reuse for diff mode (https://github.com/ansible-collections/community.crypto/pull/203).
openssh_keypair - fix check_mode to populate return values for existing keypairs (https://github.com/ansible-collections/community.crypto/issues/113, https://github.com/ansible-collections/community.crypto/pull/230).
various modules - prevent crashes when modules try to set attributes on not yet existing files in check mode. This will be fixed in ansible-core 2.12, but it is not backported to every Ansible version we support (https://github.com/ansible-collections/community.crypto/issue/242, https://github.com/ansible-collections/community.crypto/pull/243).
x509_certificate - fix crash when assertonly provider is used and some error conditions should be reported (https://github.com/ansible-collections/community.crypto/issues/240, https://github.com/ansible-collections/community.crypto/pull/241).
community.crypto.openssl_publickey_info - Provide information for OpenSSL public keys
Bugfix release. Fixes compatibility issue of ACME modules with step-ca.
-acme_* modules - avoid crashing for ACME servers where the meta directory key is not present (https://github.com/ansible-collections/community.crypto/issues/220, https://github.com/ansible-collections/community.crypto/pull/221).
Bugfix release.
-acme_* modules - fix wrong usages of ACMEProtocolException (https://github.com/ansible-collections/community.crypto/pull/216, https://github.com/ansible-collections/community.crypto/pull/217).
Fixes compatibility issues with the latest ansible-core 2.11 beta, and contains a lot of internal refactoring for the ACME modules and support for private key passphrases for them.
-acme module_utils - the acme module_utils has been split up into several Python modules (https://github.com/ansible-collections/community.crypto/pull/184).
acme_* modules - codebase refactor which should not be visible to end-users (https://github.com/ansible-collections/community.crypto/pull/184).
acme_* modules - support account key passphrases for cryptography backend (https://github.com/ansible-collections/community.crypto/issues/197, https://github.com/ansible-collections/community.crypto/pull/207).
acme_certificate_revoke - support revoking by private keys that are passphrase protected for cryptography backend (https://github.com/ansible-collections/community.crypto/pull/207).
acme_challenge_cert_helper - add private_key_passphrase parameter (https://github.com/ansible-collections/community.crypto/pull/207).
acme module_utils - the acme module_utils (ansible_collections.community.crypto.plugins.module_utils.acme) is deprecated and will be removed in community.crypto 2.0.0. Use the new Python modules in the acme package instead (ansible_collections.community.crypto.plugins.module_utils.acme.xxx) (https://github.com/ansible-collections/community.crypto/pull/184).
action_module plugin helper - make compatible with latest changes in ansible-core 2.11.0b3 (https://github.com/ansible-collections/community.crypto/pull/202).
openssl_privatekey_pipe - make compatible with latest changes in ansible-core 2.11.0b3 (https://github.com/ansible-collections/community.crypto/pull/202).
Regular feature and bugfix release. Deprecates a return value.
-acme_account_info - when retrieve_orders is not ignore and the ACME server allows to query orders, the new return value order_uris is always populated with a list of URIs (https://github.com/ansible-collections/community.crypto/pull/178).
luks_device - allow to specify sector size for LUKS2 containers with new sector_size parameter (https://github.com/ansible-collections/community.crypto/pull/193).
acme_account_info - when retrieve_orders=url_list, orders will no longer be returned in community.crypto 2.0.0. Use order_uris instead (https://github.com/ansible-collections/community.crypto/pull/178).
openssl_csr - no longer fails when comparing CSR without basic constraint when basic_constraints is specified (https://github.com/ansible-collections/community.crypto/issues/179, https://github.com/ansible-collections/community.crypto/pull/180).
Release with several new features and bugfixes.
-The ACME module_utils has been relicensed back from the Simplified BSD License (https://opensource.org/licenses/BSD-2-Clause) to the GPLv3+ (same license used by most other code in this collection). This undoes a licensing change when the original GPLv3+ licensed code was moved to module_utils in https://github.com/ansible/ansible/pull/40697 (https://github.com/ansible-collections/community.crypto/pull/165).
The crypto/identify.py module_utils has been renamed to crypto/pem.py (https://github.com/ansible-collections/community.crypto/pull/166).
luks_device - new_keyfile, new_passphrase, remove_keyfile and remove_passphrase are now idempotent (https://github.com/ansible-collections/community.crypto/issues/19, https://github.com/ansible-collections/community.crypto/pull/168).
luks_device - allow to configure PBKDF (https://github.com/ansible-collections/community.crypto/pull/163).
openssl_csr, openssl_csr_pipe - allow to specify CRL distribution endpoints with crl_distribution_points (https://github.com/ansible-collections/community.crypto/issues/147, https://github.com/ansible-collections/community.crypto/pull/167).
openssl_pkcs12 - allow to specify certificate bundles in other_certificates by using new option other_certificates_parse_all (https://github.com/ansible-collections/community.crypto/issues/149, https://github.com/ansible-collections/community.crypto/pull/166).
acme_certificate - error when requested challenge type is not found for non-valid challenges, instead of hanging on step 2 (https://github.com/ansible-collections/community.crypto/issues/171, https://github.com/ansible-collections/community.crypto/pull/173).
Contains new modules openssl_privatekey_pipe, openssl_csr_pipe and x509_certificate_pipe which allow to create or update private keys, CSRs and X.509 certificates without having to write them to disk.
openssh_cert - add module parameter use_agent to enable using signing keys stored in ssh-agent (https://github.com/ansible-collections/community.crypto/issues/116).
openssl_csr - refactor module to allow code reuse by openssl_csr_pipe (https://github.com/ansible-collections/community.crypto/pull/123).
openssl_privatekey - refactor module to allow code reuse by openssl_privatekey_pipe (https://github.com/ansible-collections/community.crypto/pull/119).
openssl_privatekey - the elliptic curve secp192r1 now triggers a security warning. Elliptic curves of at least 224 bits should be used for new keys; see here (https://github.com/ansible-collections/community.crypto/pull/132).
x509_certificate - for the selfsigned provider, a CSR is not required anymore. If no CSR is provided, the module behaves as if a minimal CSR which only contains the public key has been provided (https://github.com/ansible-collections/community.crypto/issues/32, https://github.com/ansible-collections/community.crypto/pull/129).
x509_certificate - refactor module to allow code reuse by x509_certificate_pipe (https://github.com/ansible-collections/community.crypto/pull/135).
openssl_pkcs12 - report the correct state when action is parse (https://github.com/ansible-collections/community.crypto/issues/143).
support code - improve handling of certificate and certificate signing request (CSR) loading with the cryptography backend when errors occur (https://github.com/ansible-collections/community.crypto/issues/138, https://github.com/ansible-collections/community.crypto/pull/139).
x509_certificate - fix entrust provider, which was broken since community.crypto 0.1.0 due to a feature added before the collection move (https://github.com/ansible-collections/community.crypto/pull/135).
community.crypto.openssl_csr_pipe - Generate OpenSSL Certificate Signing Request (CSR)
community.crypto.openssl_privatekey_pipe - Generate OpenSSL private keys without disk access
community.crypto.x509_certificate_pipe - Generate and/or check OpenSSL certificates
Please note that this release fixes a security issue (CVE-2020-25646).
-acme_certificate - allow to pass CSR file as content with new option csr_content (https://github.com/ansible-collections/community.crypto/pull/115).
x509_certificate_info - add fingerprints return value which returns certificate fingerprints (https://github.com/ansible-collections/community.crypto/pull/121).
openssl_csr - the option privatekey_content was not marked as no_log, resulting in it being dumped into the system log by default, and returned in the registered results in the invocation field (CVE-2020-25646, https://github.com/ansible-collections/community.crypto/pull/125).
openssl_privatekey_info - the option content was not marked as no_log, resulting in it being dumped into the system log by default, and returned in the registered results in the invocation field (CVE-2020-25646, https://github.com/ansible-collections/community.crypto/pull/125).
openssl_publickey - the option privatekey_content was not marked as no_log, resulting in it being dumped into the system log by default, and returned in the registered results in the invocation field (CVE-2020-25646, https://github.com/ansible-collections/community.crypto/pull/125).
openssl_signature - the option privatekey_content was not marked as no_log, resulting in it being dumped into the system log by default, and returned in the registered results in the invocation field (CVE-2020-25646, https://github.com/ansible-collections/community.crypto/pull/125).
x509_certificate - the options privatekey_content and ownca_privatekey_content were not marked as no_log, resulting in it being dumped into the system log by default, and returned in the registered results in the invocation field (CVE-2020-25646, https://github.com/ansible-collections/community.crypto/pull/125).
x509_crl - the option privatekey_content was not marked as no_log, resulting in it being dumped into the system log by default, and returned in the registered results in the invocation field (CVE-2020-25646, https://github.com/ansible-collections/community.crypto/pull/125).
openssl_pkcs12 - do not crash when reading PKCS#12 file which has no private key and/or no main certificate (https://github.com/ansible-collections/community.crypto/issues/103).
Bugfixes for Ansible 2.10.0.
-meta/runtime.yml - convert Ansible version numbers for old names of modules to collection version numbers (https://github.com/ansible-collections/community.crypto/pull/108).
openssl_csr - improve handling of IDNA errors (https://github.com/ansible-collections/community.crypto/issues/105).
Release for Ansible 2.10.0.
-acme_account - add external_account_binding option to allow creation of ACME accounts with External Account Binding (https://github.com/ansible-collections/community.crypto/issues/89).
acme_certificate - allow new selector test_certificates: first for select_chain parameter (https://github.com/ansible-collections/community.crypto/pull/102).
cryptography backends - support arbitrary dotted OIDs (https://github.com/ansible-collections/community.crypto/issues/39).
get_certificate - add support for SNI (https://github.com/ansible-collections/community.crypto/issues/69).
luks_device - add support for encryption options on container creation (https://github.com/ansible-collections/community.crypto/pull/97).
openssh_cert - add support for PKCS#11 tokens (https://github.com/ansible-collections/community.crypto/pull/95).
openssl_certificate - the PyOpenSSL backend now uses 160 bits of randomness for serial numbers, instead of a random number between 1000 and 99999. Please note that this is not a high quality random number (https://github.com/ansible-collections/community.crypto/issues/76).
openssl_csr - add support for name constraints extension (https://github.com/ansible-collections/community.crypto/issues/46).
openssl_csr_info - add support for name constraints extension (https://github.com/ansible-collections/community.crypto/issues/46).
acme_inspect - fix problem with Python 3.5 that JSON was not decoded (https://github.com/ansible-collections/community.crypto/issues/86).
get_certificate - fix ca_cert option handling when proxy_host is used (https://github.com/ansible-collections/community.crypto/pull/84).
openssl_*, x509_* modules - fix handling of general names which refer to IP networks and not IP addresses (https://github.com/ansible-collections/community.crypto/pull/92).
community.crypto.openssl_signature - Sign data with openssl
community.crypto.openssl_signature_info - Verify signatures with openssl
This is the first proper release of the community.crypto collection. This changelog contains all changes to the modules in this collection that were added after the release of Ansible 2.9.0.
luks_device - accept passphrase, new_passphrase and remove_passphrase.
luks_device - add keysize parameter to set key size at LUKS container creation
luks_device - added support to use UUIDs, and labels with LUKS2 containers
luks_device - added the type option that allows user explicit define the LUKS container format version
openssh_keypair - instead of regenerating some broken or password protected keys, fail the module. Keys can still be regenerated by calling the module with force=yes.
openssh_keypair - the regenerate option allows to configure the module’s behavior when it should or needs to regenerate private keys.
openssl_* modules - the cryptography backend now properly supports dirName, otherName and RID (Registered ID) names.
openssl_certificate - Add option for changing which ACME directory to use with acme-tiny. Set the default ACME directory to Let’s Encrypt instead of using acme-tiny’s default. (acme-tiny also uses Let’s Encrypt at the time being, so no action should be necessary.)
openssl_certificate - Change the required version of acme-tiny to >= 4.0.0
openssl_certificate - allow to provide content of some input files via the csr_content, privatekey_content, ownca_privatekey_content and ownca_content options.
openssl_certificate - allow to return the existing/generated certificate directly as certificate by setting return_content to yes.
openssl_certificate_info - allow to provide certificate content via content option (https://github.com/ansible/ansible/issues/64776).
openssl_csr - Add support for specifying the SAN otherName value in the OpenSSL ASN.1 UTF8 string format, otherName:<OID>;UTF8:string value.
openssl_csr - allow to provide private key content via private_key_content option.
openssl_csr - allow to return the existing/generated CSR directly as csr by setting return_content to yes.
openssl_csr_info - allow to provide CSR content via content option.
openssl_dhparam - allow to return the existing/generated DH params directly as dhparams by setting return_content to yes.
openssl_dhparam - now supports a cryptography-based backend. Auto-detection can be overwritten with the select_crypto_backend option.
openssl_pkcs12 - allow to return the existing/generated PKCS#12 directly as pkcs12 by setting return_content to yes.
openssl_privatekey - add format and format_mismatch options.
openssl_privatekey - allow to return the existing/generated private key directly as privatekey by setting return_content to yes.
openssl_privatekey - the regenerate option allows to configure the module’s behavior when it should or needs to regenerate private keys.
openssl_privatekey_info - allow to provide private key content via content option.
openssl_publickey - allow to provide private key content via private_key_content option.
openssl_publickey - allow to return the existing/generated public key directly as publickey by setting return_content to yes.
openssl_csr - all values for the version option except 1 are deprecated. The value 1 denotes the current only standardized CSR version.
The letsencrypt module has been removed. Use acme_certificate instead.
ACME modules: fix bug in ACME v1 account update code
ACME modules: make sure some connection errors are handled properly
ACME modules: support Buypass’ ACME v1 endpoint
acme_certificate - fix crash when module is used with Python 2.x.
acme_certificate - fix misbehavior when ACME v1 is used with modify_account set to false.
ecs_certificate - Always specify header connection: keep-alive for ECS API connections.
ecs_certificate - Fix formatting of contents of full_chain_path.
get_certificate - Fix cryptography backend when pyopenssl is unavailable (https://github.com/ansible/ansible/issues/67900)
openssh_keypair - add logic to avoid breaking password protected keys.
openssh_keypair - fixes idempotence issue with public key (https://github.com/ansible/ansible/issues/64969).
openssh_keypair - public key’s file attributes (permissions, owner, group, etc.) are now set to the same values as the private key.
openssl_* modules - prevent crash on fingerprint determination in FIPS mode (https://github.com/ansible/ansible/issues/67213).
openssl_certificate - When provider is entrust, use a connection: keep-alive header for ECS API connections.
openssl_certificate - provider option was documented as required, but it was not checked whether it was provided. It is now only required when state is present.
openssl_certificate - fix assertonly provider certificate verification, causing ‘private key mismatch’ and ‘subject mismatch’ errors.
openssl_certificate and openssl_csr - fix Ed25519 and Ed448 private key support for cryptography backend. This probably needs at least cryptography 2.8, since older versions have problems with signing certificates or CSRs with such keys. (https://github.com/ansible/ansible/issues/59039, PR https://github.com/ansible/ansible/pull/63984)
openssl_csr - a warning is issued if an unsupported value for version is used for the cryptography backend.
openssl_csr - the module will now enforce that privatekey_path is specified when state=present.
openssl_publickey - fix a module crash caused when pyOpenSSL is not installed (https://github.com/ansible/ansible/issues/67035).
community.crypto.ecs_domain - Request validation of a domain with the Entrust Certificate Services (ECS) API
community.crypto.x509_crl - Generate Certificate Revocation Lists (CRLs)
community.crypto.x509_crl_info - Retrieve information on Certificate Revocation Lists (CRLs)
- Note
-This module is part of the community.crypto collection (version 2.26.6).
-It is not included in ansible-core.
-To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install community.crypto.
To use it in a playbook, specify: community.crypto.crypto_info.
New in community.crypto 2.1.0
- -Retrieve information on cryptographic capabilities.
The current version retrieves information on the Python cryptography library available to Ansible modules, and on the OpenSSL binary openssl found in the path.
Attribute |
-Support |
-Description |
-
|---|---|---|
| - | Support: full -This action does not modify state. - |
-Can run in |
-
| - | Support: N/A -This action does not modify state. - |
-Will return details on what has changed (or possibly needs changing in |
-
| - | Support: full -This action does not modify state. - |
-When run twice in a row outside check mode, with the same arguments, the second invocation indicates no change. -This assumes that the system controlled/queried by the module has not changed in a relevant way. - |
-
---
-- name: Retrieve information
- community.crypto.crypto_info:
- account_key_src: /etc/pki/cert/private/account.key
- register: crypto_information
-
-- name: Show retrieved information
- ansible.builtin.debug:
- var: crypto_information
-Common return values are documented here, the following are the fields unique to this module:
-Key |
-Description |
-
|---|---|
| - | Information on the installed OpenSSL binary. -Returned: when |
-
| - | Path of the OpenSSL binary. -Returned: success -Sample: |
-
| - | The OpenSSL version. -Returned: success -Sample: |
-
| - | The complete output of Returned: success -Sample: |
-
| - | Whether the OpenSSL binary Returned: always -Sample: |
-
| - | Information on the installed Python cryptography library. -Returned: when |
-
| - | List of all supported elliptic curves. -Theoretically this should be non-empty for version 0.5 and higher, depending on the libssl version used. -Returned: success - |
-
| - | Whether DSA keys are supported. -Theoretically this should be the case for version 0.5 and higher. -Returned: success - |
-
| - | Whether signing with DSA keys is supported. -Theoretically this should be the case for version 1.5 and higher. -Returned: success - |
-
| - | Whether elliptic curves are supported. -Theoretically this should be the case for version 0.5 and higher, depending on the libssl version used. -Returned: success - |
-
| - | Whether signing with elliptic curves is supported. -Theoretically this should be the case for version 1.5 and higher, depending on the libssl version used. -Returned: success - |
-
| - | Whether Ed25519 keys are supported. -Theoretically this should be the case for version 2.6 and higher, depending on the libssl version used. -Returned: success - |
-
| - | Whether signing with Ed25519 keys is supported. -Theoretically this should be the case for version 2.6 and higher, depending on the libssl version used. -Returned: success - |
-
| - | Whether Ed448 keys are supported. -Theoretically this should be the case for version 2.6 and higher, depending on the libssl version used. -Returned: success - |
-
| - | Whether signing with Ed448 keys is supported. -Theoretically this should be the case for version 2.6 and higher, depending on the libssl version used. -Returned: success - |
-
| - | Whether RSA keys are supported. -Theoretically this should be the case for version 0.5 and higher. -Returned: success - |
-
| - | Whether signing with RSA keys is supported. -Theoretically this should be the case for version 1.4 and higher. -Returned: success - |
-
| - | Whether X25519 keys are supported. -Theoretically this should be the case for version 2.0 and higher, depending on the libssl version used. -Returned: success - |
-
| - | Whether serialization of X25519 keys is supported. -Theoretically this should be the case for version 2.5 and higher, depending on the libssl version used. -Returned: success - |
-
| - | Whether X448 keys are supported. -Theoretically this should be the case for version 2.5 and higher, depending on the libssl version used. -Returned: success - |
-
| - | The library version. -Returned: success - |
-
| - | Import error when trying to import the Python cryptography library. -Returned: when |
-
| - | - |
- The community.crypto collection offers multiple modules that create private keys, certificate signing requests, and certificates. This guide shows how to create your own small CA and how to use it to sign certificates.
-In all examples, we assume that the CA’s private key is password protected, where the password is provided in the secret_ca_passphrase variable.
Any certificate can be used as a CA certificate. You can create a self-signed certificate (see How to create self-signed certificates), use another CA certificate to sign a new certificate (using the instructions below for signing a certificate), ask (and pay) a commercial CA to sign your CA certificate, etc.
-The following instructions show how to set up a simple self-signed CA certificate.
-- name: Create private key with password protection
- community.crypto.openssl_privatekey:
- path: /path/to/ca-certificate.key
- passphrase: "{{ secret_ca_passphrase }}"
-
-- name: Create certificate signing request (CSR) for CA certificate
- community.crypto.openssl_csr_pipe:
- privatekey_path: /path/to/ca-certificate.key
- privatekey_passphrase: "{{ secret_ca_passphrase }}"
- common_name: Ansible CA
- use_common_name_for_san: false # since we do not specify SANs, don't use CN as a SAN
- basic_constraints:
- - 'CA:TRUE'
- basic_constraints_critical: true
- key_usage:
- - keyCertSign
- key_usage_critical: true
- register: ca_csr
-
-- name: Create self-signed CA certificate from CSR
- community.crypto.x509_certificate:
- path: /path/to/ca-certificate.pem
- csr_content: "{{ ca_csr.csr }}"
- privatekey_path: /path/to/ca-certificate.key
- privatekey_passphrase: "{{ secret_ca_passphrase }}"
- provider: selfsigned
-To sign a certificate, you must pass a CSR to the community.crypto.x509_certificate module or community.crypto.x509_certificate_pipe module.
-In the following example, we assume that the certificate to sign (including its private key) are on server_1, while our CA certificate is on server_2. We do not want any key material to leave each respective server.
- name: Create private key for new certificate on server_1
- community.crypto.openssl_privatekey:
- path: /path/to/certificate.key
- delegate_to: server_1
- run_once: true
-
-- name: Create certificate signing request (CSR) for new certificate
- community.crypto.openssl_csr_pipe:
- privatekey_path: /path/to/certificate.key
- subject_alt_name:
- - "DNS:ansible.com"
- - "DNS:www.ansible.com"
- - "DNS:docs.ansible.com"
- delegate_to: server_1
- run_once: true
- register: csr
-
-- name: Sign certificate with our CA
- community.crypto.x509_certificate_pipe:
- csr_content: "{{ csr.csr }}"
- provider: ownca
- ownca_path: /path/to/ca-certificate.pem
- ownca_privatekey_path: /path/to/ca-certificate.key
- ownca_privatekey_passphrase: "{{ secret_ca_passphrase }}"
- ownca_not_after: +365d # valid for one year
- ownca_not_before: "-1d" # valid since yesterday
- delegate_to: server_2
- run_once: true
- register: certificate
-
-- name: Write certificate file on server_1
- copy:
- dest: /path/to/certificate.pem
- content: "{{ certificate.certificate }}"
- delegate_to: server_1
- run_once: true
-Please note that the above procedure is not idempotent. The following extended example reads the existing certificate from server_1 (if exists) and provides it to the community.crypto.x509_certificate_pipe module, and only writes the result back if it was changed:
- name: Create private key for new certificate on server_1
- community.crypto.openssl_privatekey:
- path: /path/to/certificate.key
- delegate_to: server_1
- run_once: true
-
-- name: Create certificate signing request (CSR) for new certificate
- community.crypto.openssl_csr_pipe:
- privatekey_path: /path/to/certificate.key
- subject_alt_name:
- - "DNS:ansible.com"
- - "DNS:www.ansible.com"
- - "DNS:docs.ansible.com"
- delegate_to: server_1
- run_once: true
- register: csr
-
-- name: Check whether certificate exists
- stat:
- path: /path/to/certificate.pem
- delegate_to: server_1
- run_once: true
- register: certificate_exists
-
-- name: Read existing certificate if exists
- slurp:
- src: /path/to/certificate.pem
- when: certificate_exists.stat.exists
- delegate_to: server_1
- run_once: true
- register: certificate
-
-- name: Sign certificate with our CA
- community.crypto.x509_certificate_pipe:
- content: "{{ (certificate.content | b64decode) if certificate_exists.stat.exists else omit }}"
- csr_content: "{{ csr.csr }}"
- provider: ownca
- ownca_path: /path/to/ca-certificate.pem
- ownca_privatekey_path: /path/to/ca-certificate.key
- ownca_privatekey_passphrase: "{{ secret_ca_passphrase }}"
- ownca_not_after: +365d # valid for one year
- ownca_not_before: "-1d" # valid since yesterday
- delegate_to: server_2
- run_once: true
- register: certificate
-
-- name: Write certificate file on server_1
- copy:
- dest: /path/to/certificate.pem
- content: "{{ certificate.certificate }}"
- delegate_to: server_1
- run_once: true
- when: certificate is changed
-
- The community.crypto collection offers multiple modules that create private keys, certificate signing requests, and certificates. This guide shows how to create self-signed certificates.
-For creating any kind of certificate, you always have to start with a private key. You can use the community.crypto.openssl_privatekey module to create a private key. If you only specify path, the default parameters will be used. This will result in a 4096 bit RSA private key:
- name: Create private key (RSA, 4096 bits)
- community.crypto.openssl_privatekey:
- path: /path/to/certificate.key
-You can specify type to select another key type, size to select a different key size (only available for RSA and DSA keys), or passphrase if you want to store the key password-protected:
- name: Create private key (X25519) with password protection
- community.crypto.openssl_privatekey:
- path: /path/to/certificate.key
- type: X25519
- passphrase: changeme
-To create a very simple self-signed certificate with no specific information, you can proceed directly with the community.crypto.x509_certificate module:
-- name: Create simple self-signed certificate
- community.crypto.x509_certificate:
- path: /path/to/certificate.pem
- privatekey_path: /path/to/certificate.key
- provider: selfsigned
-(If you used passphrase for the private key, you have to provide privatekey_passphrase.)
You can use selfsigned_not_after to define when the certificate expires (default: in roughly 10 years), and selfsigned_not_before to define from when the certificate is valid (default: now).
To define further properties of the certificate, like the subject, Subject Alternative Names (SANs), key usages, name constraints, etc., you need to first create a Certificate Signing Request (CSR) and provide it to the community.crypto.x509_certificate module. If you do not need the CSR file, you can use the community.crypto.openssl_csr_pipe module as in the example below. (To store it to disk, use the community.crypto.openssl_csr module instead.)
-- name: Create certificate signing request (CSR) for self-signed certificate
- community.crypto.openssl_csr_pipe:
- privatekey_path: /path/to/certificate.key
- common_name: ansible.com
- organization_name: Ansible, Inc.
- subject_alt_name:
- - "DNS:ansible.com"
- - "DNS:www.ansible.com"
- - "DNS:docs.ansible.com"
- register: csr
-
-- name: Create self-signed certificate from CSR
- community.crypto.x509_certificate:
- path: /path/to/certificate.pem
- csr_content: "{{ csr.csr }}"
- privatekey_path: /path/to/certificate.key
- provider: selfsigned
-
- Note
-This module is part of the community.crypto collection (version 2.26.6).
-It is not included in ansible-core.
-To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install community.crypto.
-You need further requirements to be able to use this module,
-see Requirements for details.
To use it in a playbook, specify: community.crypto.ecs_certificate.
Create, reissue, and renew certificates with the Entrust Certificate Services (ECS) API.
Requires credentials for the Entrust Certificate Services (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 not the responsibility of this module to perform those steps.
The below requirements are needed on the host that executes this module.
-PyYAML >= 3.11
cryptography >= 1.6
Parameter |
-Comments |
-
|---|---|
| - | A list of additional email addresses to receive the delivery notice and expiry notification for the certificate. - |
-
| - | Whether a backup should be made for the certificate in Choices: -
|
-
| - | The date the certificate should be set to expire, in RFC3339 compliant date or date-time format. For example,
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 |
-
| - | The lifetime of the certificate. -Applies to all certificates for accounts with a non-pooling inventory model. -
Applies to certificates of
Only one of Choices: -
|
-
| - | Specify the type of certificate requested. -If a certificate is being reissued or renewed, this parameter is ignored, and the Choices: -
|
-
| - | 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 The issued certificate will have an organization value in the subject distinguished name represented by the client. -Default: |
-
| - | Base-64 encoded Certificate Signing Request (CSR). If no If If If The organization “O=” field from the CSR will not be used. It will be replaced in the issued certificate by |
-
| - | 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 If If Choices: -
|
-
| - | 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. - |
-
| - | Custom date field. - |
-
| - | Custom date field. - |
-
| - | Custom date field. - |
-
| - | Custom date field. - |
-
| - | Custom date field. - |
-
| - | Custom dropdown field. - |
-
| - | Custom dropdown field. - |
-
| - | Custom dropdown field. - |
-
| - | Custom dropdown field. - |
-
| - | Custom dropdown field. - |
-
| - | Custom email field. - |
-
| - | Custom email field. - |
-
| - | Custom email field. - |
-
| - | Custom email field. - |
-
| - | Custom email field. - |
-
| - | Custom number field. - |
-
| - | Custom number field. - |
-
| - | Custom number field. - |
-
| - | Custom number field. - |
-
| - | Custom number field. - |
-
| - | Custom text field (maximum 500 characters). - |
-
| - | Custom text field (maximum 500 characters). - |
-
| - | Custom text field (maximum 500 characters). - |
-
| - | Custom text field (maximum 500 characters). - |
-
| - | Custom text field (maximum 500 characters). - |
-
| - | Custom text field (maximum 500 characters). - |
-
| - | Custom text field (maximum 500 characters). - |
-
| - | Custom text field (maximum 500 characters). - |
-
| - | Custom text field (maximum 500 characters). - |
-
| - | Custom text field (maximum 500 characters). - |
-
| - | Custom text field (maximum 500 characters). - |
-
| - | Custom text field (maximum 500 characters). - |
-
| - | Custom text field (maximum 500 characters). - |
-
| - | Custom text field (maximum 500 characters). - |
-
| - | Custom text field (maximum 500 characters). - |
-
| - | If specified, overrides the key usage in the Choices: -
|
-
| - | 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 Applicable only to Choices: -
|
-
| - | The path to the key for the client certificate used to authenticate to the Entrust Certificate Services (ECS) API. - |
-
| - | The path to the client certificate used to authenticate to the Entrust Certificate Services (ECS) API. - |
-
| - | The key (password) for authentication to the Entrust Certificate Services (ECS) API. - |
-
| - | 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. -Default: |
-
| - | The username for authentication to the Entrust Certificate Services (ECS) API. - |
-
| - | If force is used, a certificate is requested regardless of whether If Choices: -
|
-
| - | The destination path for the full certificate chain of the certificate, intermediates, and roots. - |
-
| - | Organization “O=” to include in the certificate. -If Unless the |
-
| - | Organizational unit “OU=” to include in the certificate. -
If both If neither An invalid OU from A maximum of one OU may be specified for current products. Multiple OUs are reserved for future products. - |
-
| - | 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 If an existing certificate is being replaced (see |
-
| - | The number of days the certificate must have left being valid. If If For example, if you are requesting Certificates with a 90 day lifetime, do not set The Default: |
-
| - | The operation performed if Specifying Specifying Specifying Specifying If a certificate was issued within the past 30 days, the Note that check_mode is only supported if For example, setting Choices: -
|
-
| - | The requester email to associate with certificate tracking information and receive delivery and expiry notices for the certificate. - |
-
| - | The requester name to associate with certificate tracking information. - |
-
| - | The requester phone number to associate with certificate tracking information. - |
-
| - | The subject alternative name identifiers, as an array of values (applies to If you are requesting a new SSL certificate, and you pass a See In the case of certificates of type |
-
| - | The tracking ID of the certificate to reissue or renew. -
If there is a certificate present in If there is no certificate present in If there is no certificate present in 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 |
-
| - | Free form tracking information to attach to the record for the certificate. - |
-
Attribute |
-Support |
-Description |
-
|---|---|---|
| - | Support: partial -Check mode is only supported if |
-Can run in |
-
| - | Support: none - |
-Will return details on what has changed (or possibly needs changing in |
-
| - | Support: partial -The module is not idempotent if Under which conditions the module is idempotent still needs to be determined. If you are using this module and have more information, please contribute to the documentation! - |
-When run twice in a row outside check mode, with the same arguments, the second invocation indicates no change. -This assumes that the system controlled/queried by the module has not changed in a relevant way. - |
-
| - | Support: full - |
-Uses Ansible’s strict file operation functions to ensure proper permissions and avoid data corruption. - |
-
Note
-path must be specified as the output location of the certificate.
See also
-Can be used to create private keys (both for certificates and accounts).
-Can be used to create a Certificate Signing Request (CSR).
-Convert an integer to a colon-separated list of hex numbers.
----
-- 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
- full_chain_path: /etc/ssl/crt/ansible.com.chain.crt
- csr: /etc/ssl/csr/ansible.com.csr
- cert_type: EV_SSL
- requester_name: Jo Doe
- requester_email: jdoe@ansible.com
- requester_phone: 555-555-5555
- entrust_api_user: apiusername
- 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
-
-- 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
- cert_type: EV_SSL
- cert_expiry: '2020-08-20'
- request_type: renew
- remaining_days: 63
- requester_name: Jo Doe
- requester_email: jdoe@ansible.com
- requester_phone: 555-555-5555
- entrust_api_user: apiusername
- 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
-
-- 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
- tracking_id: 2378915
- request_type: renew
- remaining_days: 79
- entrust_api_user: apiusername
- 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
-
-- name: Force a reissue of the certificate specified by tracking_id.
- community.crypto.ecs_certificate:
- path: /etc/ssl/crt/ansible.com.crt
- force: true
- tracking_id: 2378915
- request_type: reissue
- entrust_api_user: apiusername
- 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
-
-- 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
- client_id: 2
- requester_name: Jo Doe
- requester_email: jdoe@ansible.com
- requester_phone: 555-555-5555
- entrust_api_user: apiusername
- 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
-
-- 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
- csr: /etc/ssl/csr/ansible.com.csr
- subject_alt_name:
- - ansible.testcertificates.com
- - www.testcertificates.com
- eku: SERVER_AND_CLIENT_AUTH
- ct_log: true
- org: Test Organization Inc.
- ou:
- - Administration
- tracking_info: "Submitted via Ansible"
- additional_emails:
- - itsupport@testcertificates.com
- - jsmith@ansible.com
- custom_fields:
- text1: Admin
- text2: Invoice 25
- number1: 342
- date1: '2018-01-01'
- email1: sales@ansible.testcertificates.com
- dropdown1: red
- cert_expiry: '2020-08-15'
- requester_name: Jo Doe
- requester_email: jdoe@ansible.com
- requester_phone: 555-555-5555
- entrust_api_user: apiusername
- 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
-Common return values are documented here, the following are the fields unique to this module:
-Key |
-Description |
-
|---|---|
| - | Name of backup file created for the certificate. -Returned: changed and if Sample: |
-
| - | Name of the backup file created for the certificate chain. -Returned: changed and if Sample: |
-
| - | The number of days the certificate remains valid. -Returned: success -Sample: |
-
| - | 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 - |
-
| - | The certificate status in ECS. -Current possible values (which may be expanded in the future) are: Returned: success -Sample: |
-
| - | The destination path for the generated certificate. -Returned: changed or success -Sample: |
-
| - | The serial number of the issued certificate. -This return value is an integer. If you need the serial numbers as a colon-separated hex string, such as Returned: success -Sample: |
-
| - | The tracking ID to reference and track the certificate in ECS. -Returned: success -Sample: |
-
- Note
-This module is part of the community.crypto collection (version 2.26.6).
-It is not included in ansible-core.
-To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install community.crypto.
-You need further requirements to be able to use this module,
-see Requirements for details.
To use it in a playbook, specify: community.crypto.ecs_domain.
New in community.crypto 1.0.0
- -Request validation or re-validation of a domain with the Entrust Certificate Services (ECS) API.
Requires credentials for the Entrust Certificate Services (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 verification_method specified is different than the current verification_method, the 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 changed will be false, unless domain_status=EXPIRED, in which case a re-validation will be performed.
If verification_method=dns, details about the required DNS entry will be specified in the return parameters dns_contents, dns_location, and dns_resource_type.
If verification_method=web_server, details about the required file details will be specified in the return parameters file_contents and file_location.
If verification_method=email, the email address(es) that the validation email(s) were sent to will be in the return parameter emails. This is purely informational. For domains requested using this module, this will always be a list of size 1.
The below requirements are needed on the host that executes this module.
-PyYAML >= 3.11
Parameter |
-Comments |
-
|---|---|
| - | 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. -Default: |
-
| - | The domain name to be verified or reverified. - |
-
| - | The path to the key for the client certificate used to authenticate to the Entrust Certificate Services (ECS) API. - |
-
| - | The path to the client certificate used to authenticate to the Entrust Certificate Services (ECS) API. - |
-
| - | The key (password) for authentication to the Entrust Certificate Services (ECS) API. - |
-
| - | 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. -Default: |
-
| - | The username for authentication to the Entrust Certificate Services (ECS) API. - |
-
| - | Email address to be used to verify domain ownership. -Email address must be either an email address present in the WHOIS data for Note that if If using the email values from the WHOIS data for the domain or its top level namespace, they must be exact matches. -If To verify domain ownership, domain owner must follow the instructions in the email they receive. -Only allowed if |
-
| - | The verification method to be used to prove control of the domain. -If If If If Choices: -
|
-
Attribute |
-Support |
-Description |
-
|---|---|---|
| - | Support: none - |
-Can run in |
-
| - | Support: none - |
-Will return details on what has changed (or possibly needs changing in |
-
| - | Support: partial -Under which conditions the module is idempotent still needs to be determined. If you are using this module and have more information, please contribute to the documentation! - |
-When run twice in a row outside check mode, with the same arguments, the second invocation indicates no change. -This assumes that the system controlled/queried by the module has not changed in a relevant way. - |
-
Note
-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 verification_method=dns or verification_method=web_server. Be aware of that if doing many domain validation requests.
See also
-Can be used to request certificates from ECS, with provider=entrust.
Can be used to request a Certificate from ECS using a verified domain.
----
-- name: Request domain validation using email validation for client ID of 2.
- community.crypto.ecs_domain:
- domain_name: ansible.com
- client_id: 2
- verification_method: email
- verification_email: admin@ansible.com
- entrust_api_user: apiusername
- 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
-
-- 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
- entrust_api_user: apiusername
- 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
-
-- 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
- entrust_api_user: apiusername
- 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
-
-- name: Request domain validation using manual validation.
- community.crypto.ecs_domain:
- domain_name: ansible.com
- verification_method: manual
- entrust_api_user: apiusername
- 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
-Common return values are documented here, the following are the fields unique to this module:
-Key |
-Description |
-
|---|---|
| - | - |
| - | The value that ECS will be expecting to find in the DNS record located at Returned: changed and if Sample: |
-
| - | The location that ECS will be expecting to be able to find the DNS entry for domain verification, containing the contents of Returned: changed and if Sample: |
-
| - | The type of resource record that ECS will be expecting for the DNS record located at Returned: changed and if Sample: |
-
| - | Status of the current domain. Will be one of Returned: changed or success -Sample: |
-
| - | 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: Sample: |
-
| - | The number of days the domain remains eligible for submission of “EV” certificates. Will never be greater than the value of Returned: success and Sample: |
-
| - | Whether the domain is eligible for submission of “EV” certificates. Will never be Returned: success and Sample: |
-
| - | The contents of the file that ECS will be expecting to find at Returned: Sample: |
-
| - | The location that ECS will be expecting to be able to find the file for domain verification, containing the contents of Returned: Sample: |
-
| - | The number of days the domain remains eligible for submission of “OV” certificates. Will never be less than the value of Returned: success and Sample: |
-
| - | Whether the domain is eligible for submission of “OV” certificates. Will never be Returned: success and Sample: |
-
| - | Verification method used to request the domain validation. If Returned: changed or success -Sample: |
-
- The following index documents all environment variables declared by plugins in collections. -Environment variables used by the ansible-core configuration are documented in Ansible Configuration Settings.
-No environment variables have been defined.
-
- Note
-This module is part of the community.crypto collection (version 2.26.6).
-It is not included in ansible-core.
-To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install community.crypto.
-You need further requirements to be able to use this module,
-see Requirements for details.
To use it in a playbook, specify: community.crypto.get_certificate.
Makes a secure connection and returns information about the presented certificate.
The module uses the cryptography Python library.
Support SNI (Server Name Indication) only with Python 2.7 and newer.
The below requirements are needed on the host that executes this module.
-Python >= 2.7 when using proxy_host, and Python >= 3.10 when get_certificate_chain=true
cryptography >= 1.6
Parameter |
-Comments |
-
|---|---|
| - | Whether to encode the ASN.1 values in the The documentation claimed for a long time that the values are Base64 encoded, but they never were. For compatibility this option is set to The default value Choices: -
|
-
| - | 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. - |
-
| - | SSL/TLS Ciphers to use for the request. -When a list is provided, all ciphers are joined in order with See the OpenSSL Cipher List Format for more details. -The available ciphers is dependent on the Python and OpenSSL/LibreSSL versions. - |
-
| - | If set to The chain as returned by the server can be found in Note that this needs 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. -Choices: -
|
-
| - | The host to get the cert for (IP is fine). - |
-
| - | The port to connect to. - |
-
| - | Proxy host used when get a certificate. - |
-
| - | Proxy port used when get a certificate. -Default: |
-
| - | Determines which crypto backend to use. -The default choice is If set to Choices: -
|
-
| - | Server name used for SNI (Server Name Indication) when hostname is an IP or is different from server name. - |
-
| - | Requests a secure connection for protocols which require clients to initiate encryption. -Only available for Choices: -
|
-
| - | The timeout in seconds. -Default: |
-
| - | TLS context options (TLS/SSL OP flags) to use for the request. -See the List of SSL OP Flags for more details. -The available TLS context options is dependent on the Python and OpenSSL/LibreSSL versions. - |
-
Attribute |
-Support |
-Description |
-
|---|---|---|
| - | Support: none -This action does not modify state. - |
-Can run in |
-
| - | Support: N/A -This action does not modify state. - |
-Will return details on what has changed (or possibly needs changing in |
-
| - | Support: full -This action does not modify state. - |
-When run twice in a row outside check mode, with the same arguments, the second invocation indicates no change. -This assumes that the system controlled/queried by the module has not changed in a relevant way. - |
-
Note
-When using ca_cert on OS X it has been reported that in some conditions the validate will always succeed.
See also
-Convert an integer to a colon-separated list of hex numbers.
----
-- name: Get the cert from an RDP port
- community.crypto.get_certificate:
- host: "1.2.3.4"
- port: 3389
- delegate_to: localhost
- run_once: true
- register: cert
-
-- name: Get a cert from an https port
- community.crypto.get_certificate:
- host: "www.google.com"
- port: 443
- delegate_to: localhost
- run_once: true
- register: cert
-
-- name: How many days until cert expires
- ansible.builtin.debug:
- msg: "cert expires in: {{ expire_days }} days."
- vars:
- expire_days: >-
- {{ (
- (cert.not_after | ansible.builtin.to_datetime('%Y%m%d%H%M%SZ')) -
- (ansible_date_time.iso8601 | ansible.builtin.to_datetime('%Y-%m-%dT%H:%M:%SZ'))
- ).days }}
-
-- name: Allow legacy insecure renegotiation to get a cert from a legacy device
- community.crypto.get_certificate:
- host: "legacy-device.domain.com"
- port: 443
- ciphers:
- - HIGH
- tls_ctx_options:
- - OP_ALL
- - OP_NO_SSLv3
- - OP_CIPHER_SERVER_PREFERENCE
- - OP_ENABLE_MIDDLEBOX_COMPAT
- - OP_NO_COMPRESSION
- - 4 # OP_LEGACY_SERVER_CONNECT
- delegate_to: localhost
- run_once: true
- register: legacy_cert
-Common return values are documented here, the following are the fields unique to this module:
-Key |
-Description |
-
|---|---|
| - | The certificate retrieved from the port. -Returned: success - |
-
| - | Boolean indicating if the cert is expired. -Returned: success - |
-
| - | Extensions applied to the cert. -Returned: success - |
-
| - | The ASN.1 content of the extension. -If 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 https://github.com/ansible/ansible/issues/80258 for more information. -Note that depending on the Returned: success - |
-
| - | Whether the extension is critical. -Returned: success - |
-
| - | The extension’s name. -Returned: success - |
-
| - | Information about the issuer of the cert. -Returned: success - |
-
| - | Expiration date of the cert. -Returned: success - |
-
| - | Issue date of the cert. -Returned: success - |
-
| - | The serial number of the cert. -This return value is an integer. If you need the serial numbers as a colon-separated hex string, such as Returned: success - |
-
| - | The algorithm used to sign the cert. -Returned: success - |
-
| - | Information about the subject of the cert ( Returned: success - |
-
| - | The certificate chain retrieved from the port. -The first entry is always Returned: success and |
-
| - | The verified certificate chain retrieved from the port. -The first entry is always The last certificate the root certificate the chain is traced to. If Note that Returned: success and |
-
| - | The version number of the certificate. -Returned: success - |
-
- Note
-This filter plugin is part of the community.crypto collection (version 2.26.6).
-It is not included in ansible-core.
-To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install community.crypto.
-You need further requirements to be able to use this filter plugin,
-see Requirements for details.
To use it in a playbook, specify: community.crypto.gpg_fingerprint.
New in community.crypto 2.15.0
- -Takes the content of a private or public GPG key as input and returns its fingerprint.
The below requirements are needed on the local controller node that executes this filter.
-GnuPG (gpg executable)
This describes the input of the filter, the value before | community.crypto.gpg_fingerprint.
Parameter |
-Comments |
-
|---|---|
| - | The content of a GPG public or private key. - |
-
See also
-Retrieve a GPG fingerprint from a GPG public or private key file.
----
-- name: Show fingerprint of GPG public key
- ansible.builtin.debug:
- msg: "{{ lookup('file', '/path/to/public_key.gpg') | community.crypto.gpg_fingerprint }}"
-Key |
-Description |
-
|---|---|
| - | The fingerprint of the provided public or private GPG key. -Returned: success - |
-
- Note
-This lookup plugin is part of the community.crypto collection (version 2.26.6).
-It is not included in ansible-core.
-To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install community.crypto.
-You need further requirements to be able to use this lookup plugin,
-see Requirements for details.
To use it in a playbook, specify: community.crypto.gpg_fingerprint.
New in community.crypto 2.15.0
- -Takes a list of filenames pointing to GPG public or private key files. Returns the fingerprints for each of these keys.
The below requirements are needed on the local controller node that executes this lookup.
-GnuPG (gpg executable)
Parameter |
-Comments |
-
|---|---|
| - | A path to a GPG public or private key. - |
-
See also
-Retrieve a GPG fingerprint from a GPG public or private key.
----
-- name: Show fingerprint of GPG public key
- ansible.builtin.debug:
- msg: "{{ lookup('community.crypto.gpg_fingerprint', '/path/to/public_key.gpg') }}"
-Key |
-Description |
-
|---|---|
| - | The fingerprints of the provided public or private GPG keys. -The list has one entry for every path provided. -Returned: success - |
-
- Collection version 2.26.6
- -Provides modules and plugins for many cryptographic operations.
-Author:
-Ansible (github.com/ansible)
Supported ansible-core versions:
-2.9.10 or newer
Matrix room #users:ansible.im: General usage and support questions.
IRC channel #ansible (Libera network):
-General usage and support questions.
These are the plugins in the community.crypto collection:
-acme_account module – Create, modify or delete ACME accounts
acme_account_info module – Retrieves information on ACME accounts
acme_ari_info module – Retrieves ACME Renewal Information (ARI) for a certificate
acme_certificate module – Create SSL/TLS certificates with the ACME protocol
acme_certificate_deactivate_authz module – Deactivate all authz for an ACME v2 order
acme_certificate_order_create module – Create an ACME v2 order
acme_certificate_order_finalize module – Finalize an ACME v2 order
acme_certificate_order_info module – Obtain information for an ACME v2 order
acme_certificate_order_validate module – Validate authorizations of an ACME v2 order
acme_certificate_renewal_info module – Determine whether a certificate should be renewed or not
acme_certificate_revoke module – Revoke certificates with the ACME protocol
acme_challenge_cert_helper module – Prepare certificates required for ACME challenges such as tls-alpn-01
acme_inspect module – Send direct requests to an ACME server
certificate_complete_chain module – Complete certificate chain given a set of untrusted and root certificates
crypto_info module – Retrieve cryptographic capabilities
ecs_certificate module – Request SSL/TLS certificates with the Entrust Certificate Services (ECS) API
ecs_domain module – Request validation of a domain with the Entrust Certificate Services (ECS) API
get_certificate module – Get a certificate from a host:port
luks_device module – Manage encrypted (LUKS) devices
openssh_cert module – Generate OpenSSH host or user certificates
openssh_keypair module – Generate OpenSSH private and public keys
openssl_csr module – Generate OpenSSL Certificate Signing Request (CSR)
openssl_csr_info module – Provide information of OpenSSL Certificate Signing Requests (CSR)
openssl_csr_pipe module – Generate OpenSSL Certificate Signing Request (CSR)
openssl_dhparam module – Generate OpenSSL Diffie-Hellman Parameters
openssl_pkcs12 module – Generate OpenSSL PKCS#12 archive
openssl_privatekey module – Generate OpenSSL private keys
openssl_privatekey_convert module – Convert OpenSSL private keys
openssl_privatekey_info module – Provide information for OpenSSL private keys
openssl_privatekey_pipe module – Generate OpenSSL private keys without disk access
openssl_publickey module – Generate an OpenSSL public key from its private key
openssl_publickey_info module – Provide information for OpenSSL public keys
openssl_signature module – Sign data with openssl
openssl_signature_info module – Verify signatures with openssl
x509_certificate module – Generate and/or check OpenSSL certificates
x509_certificate_convert module – Convert X.509 certificates
x509_certificate_info module – Provide information of OpenSSL X.509 certificates
x509_certificate_pipe module – Generate and/or check OpenSSL certificates
x509_crl module – Generate Certificate Revocation Lists (CRLs)
x509_crl_info module – Retrieve information on Certificate Revocation Lists (CRLs)
gpg_fingerprint filter – Retrieve a GPG fingerprint from a GPG public or private key
openssl_csr_info filter – Retrieve information from OpenSSL Certificate Signing Requests (CSR)
openssl_privatekey_info filter – Retrieve information from OpenSSL private keys
openssl_publickey_info filter – Retrieve information from OpenSSL public keys in PEM format
parse_serial filter – Convert a serial number as a colon-separated list of hex numbers to an integer
split_pem filter – Split PEM file contents into multiple objects
to_serial filter – Convert an integer to a colon-separated list of hex numbers
x509_certificate_info filter – Retrieve information from X.509 certificates in PEM format
x509_crl_info filter – Retrieve information from X.509 CRLs in PEM format
gpg_fingerprint lookup – Retrieve a GPG fingerprint from a GPG public or private key file
- Note
-This module is part of the community.crypto collection (version 2.26.6).
-It is not included in ansible-core.
-To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install community.crypto.
-You need further requirements to be able to use this module,
-see Requirements for details.
To use it in a playbook, specify: community.crypto.luks_device.
Module manages LUKS on given device. Supports creating, destroying, opening and closing of LUKS container and adding or removing new keys and passphrases.
The below requirements are needed on the host that executes this module.
- -Parameter |
-Comments |
-
|---|---|
| - | Allow discards (also known as TRIM) requests for device. -Will only be used when opening containers. -Choices: -
|
-
| - | 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 |
-
| - | Device to work with (for example |
-
| - | If set to BEWARE that when the last key has been removed from a container, the container can no longer be opened! -Choices: -
|
-
| - | 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. - |
-
| - | Used to unlock the container. Either a BEWARE that working with keyfiles in plaintext is dangerous. Make sure that they are protected. - |
-
| - | Sets the key size only if LUKS container does not exist. - |
-
| - | Adds the Note that a device of |
-
| - | - |
| - | Sets container name when |
-
| - | Adds additional key to given container on 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. - |
-
| - | Adds the additional Note that a device of |
-
| - | Adds additional passphrase to given container on 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. -Note that the passphrase must be UTF-8 encoded text. If you want to use arbitrary binary data, or text using another encoding, use the |
-
| - | Used to unlock the container. Either a Note that the passphrase must be UTF-8 encoded text. If you want to use arbitrary binary data, or text using another encoding, use the |
-
| - | Determine how passphrases are provided to parameters such as Choices: -
|
-
| - | 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. - |
-
| - | The algorithm to use. -Only available for the LUKS 2 format. -Choices: -
|
-
| - | Specify the iteration count used for the PBKDF. -Mutually exclusive with |
-
| - | Specify the iteration time used for the PBKDF. -Note that this is in seconds, not in milliseconds as on the command line. -Mutually exclusive with |
-
| - | The memory cost limit in kilobytes for the PBKDF. -This is not used for PBKDF2, but only for the Argon PBKDFs. - |
-
| - | 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. - |
-
| - | Allows the user to bypass dm-crypt internal workqueue and process read requests synchronously. -Will only be used when opening containers. -Choices: -
|
-
| - | Allows the user to bypass dm-crypt internal workqueue and process write requests synchronously. -Will only be used when opening containers. -Choices: -
|
-
| - | 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. -Choices: -
|
-
| - | 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. -Choices: -
|
-
| - | Allows the user to store options into container’s metadata persistently and automatically use them next time. Only Will only work with LUKS2 containers. -Will only be used when opening containers. -Choices: -
|
-
| - | Removes given key from the container on 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 BEWARE that working with keyfiles in plaintext is dangerous. Make sure that they are protected. - |
-
| - | Removes the key in the given slot on Note that a device of Note that the given |
-
| - | Removes given passphrase from the container on 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 Note that the passphrase must be UTF-8 encoded text. If you want to use arbitrary binary data, or text using another encoding, use the |
-
| - | This option allows the user to specify the sector size (in bytes) used for LUKS2 containers. -Will only be used on container creation. - |
-
| - | Desired state of the LUKS container. Based on its value creates, destroys, opens or closes the LUKS container on a given device. -
Choices: -
|
-
| - | This option allow the user explicit define the format of LUKS container that wants to work with. Options are Choices: -
|
-
| - | - |
Attribute |
-Support |
-Description |
-
|---|---|---|
| - | Support: full - |
-Can run in |
-
| - | Support: none - |
-Will return details on what has changed (or possibly needs changing in |
-
| - | Support: full - |
-When run twice in a row outside check mode, with the same arguments, the second invocation indicates no change. -This assumes that the system controlled/queried by the module has not changed in a relevant way. - |
-
---
-- name: Create LUKS container (remains unchanged if it already exists)
- community.crypto.luks_device:
- device: "/dev/loop0"
- state: "present"
- keyfile: "/vault/keyfile"
-
-- name: Create LUKS container with a passphrase
- community.crypto.luks_device:
- device: "/dev/loop0"
- state: "present"
- passphrase: "foo"
-
-- name: Create LUKS container with specific encryption
- community.crypto.luks_device:
- device: "/dev/loop0"
- state: "present"
- cipher: "aes"
- hash: "sha256"
-
-- name: (Create and) open the LUKS container; name it "mycrypt"
- community.crypto.luks_device:
- device: "/dev/loop0"
- state: "opened"
- name: "mycrypt"
- keyfile: "/vault/keyfile"
-
-- name: Close the existing LUKS container "mycrypt"
- community.crypto.luks_device:
- state: "closed"
- name: "mycrypt"
-
-- name: Make sure LUKS container exists and is closed
- community.crypto.luks_device:
- device: "/dev/loop0"
- state: "closed"
- keyfile: "/vault/keyfile"
-
-- name: Create container if it does not exist and add new key to it
- community.crypto.luks_device:
- device: "/dev/loop0"
- state: "present"
- keyfile: "/vault/keyfile"
- new_keyfile: "/vault/keyfile2"
-
-- name: Add new key to the LUKS container (container has to exist)
- community.crypto.luks_device:
- device: "/dev/loop0"
- keyfile: "/vault/keyfile"
- new_keyfile: "/vault/keyfile2"
-
-- name: Add new passphrase to the LUKS container
- community.crypto.luks_device:
- device: "/dev/loop0"
- keyfile: "/vault/keyfile"
- new_passphrase: "foo"
-
-- name: Remove existing keyfile from the LUKS container
- community.crypto.luks_device:
- device: "/dev/loop0"
- remove_keyfile: "/vault/keyfile2"
-
-- name: Remove existing passphrase from the LUKS container
- community.crypto.luks_device:
- device: "/dev/loop0"
- remove_passphrase: "foo"
-
-- name: Completely remove the LUKS container and its contents
- community.crypto.luks_device:
- device: "/dev/loop0"
- state: "absent"
-
-- name: Create a container with label
- community.crypto.luks_device:
- device: "/dev/loop0"
- state: "present"
- keyfile: "/vault/keyfile"
- label: personalLabelName
-
-- name: Open the LUKS container based on label without device; name it "mycrypt"
- community.crypto.luks_device:
- label: "personalLabelName"
- state: "opened"
- name: "mycrypt"
- keyfile: "/vault/keyfile"
-
-- name: Close container based on UUID
- community.crypto.luks_device:
- uuid: 03ecd578-fad4-4e6c-9348-842e3e8fa340
- state: "closed"
- name: "mycrypt"
-
-- name: Create a container using luks2 format
- community.crypto.luks_device:
- device: "/dev/loop0"
- state: "present"
- keyfile: "/vault/keyfile"
- type: luks2
-
-- name: Create a container with key in slot 4
- community.crypto.luks_device:
- device: "/dev/loop0"
- state: "present"
- keyfile: "/vault/keyfile"
- keyslot: 4
-
-- name: Add a new key in slot 5
- community.crypto.luks_device:
- device: "/dev/loop0"
- keyfile: "/vault/keyfile"
- new_keyfile: "/vault/keyfile"
- new_keyslot: 5
-
-- name: Remove the key from slot 4 (given keyfile must not be slot 4)
- community.crypto.luks_device:
- device: "/dev/loop0"
- keyfile: "/vault/keyfile"
- remove_keyslot: 4
-Common return values are documented here, the following are the fields unique to this module:
-Key |
-Description |
-
|---|---|
| - | When Returned: success -Sample: |
-
- Note
-This module is part of the community.crypto collection (version 2.26.6).
-It is not included in ansible-core.
-To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install community.crypto.
-You need further requirements to be able to use this module,
-see Requirements for details.
To use it in a playbook, specify: community.crypto.openssh_cert.
Generate and regenerate OpenSSH host or user certificates.
The below requirements are needed on the host that executes this module.
-ssh-keygen
Parameter |
-Comments |
-
|---|---|
| - | The attributes the resulting filesystem object should have. -To get supported flags look at the man page for This string should contain the attributes in the same order as the one displayed by The |
-
| - | Should the certificate be regenerated even if it already exists and is valid. -Equivalent to Choices: -
|
-
| - | Name of the group that should own the filesystem object, as would be fed to When left unspecified, it uses the current group of the current user unless you are root, in which case it can preserve the previous ownership. - |
-
| - | Specify the key identity when signing a public key. The identifier that is logged by the server when the certificate is used for authentication. - |
-
| - | Whether the However, the values will still be applied to a new certificate if it meets any other necessary conditions for generation/regeneration. -Choices: -
|
-
| - | The permissions the resulting filesystem object should have. -For those used to Giving Ansible a number without following either of these rules will end up with a decimal number which will have unexpected results. -As of Ansible 1.8, the mode may be specified as a symbolic mode (for example, If If Specifying |
-
| - | Specify certificate options when signing a key. The option that are valid for user certificates are: -
At present, no options are valid for host keys. - |
-
| - | Name of the user that should own the filesystem object, as would be fed to When left unspecified, it uses the current user unless you are root, in which case it can preserve the previous ownership. -Specifying a numeric username will be assumed to be a user ID and not a username. Avoid numeric usernames to avoid this confusion. - |
-
| - | Path of the file containing the certificate. - |
-
| - | 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 If this is set, |
-
| - | 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. - |
-
| - | The path to the public key that will be signed with the signing key in order to generate the certificate. -Required if |
-
| - | When When When When
Choices: -
|
-
| - | The level part of the SELinux filesystem object context. -This is the MLS/MCS attribute, sometimes known as the When set to |
-
| - | 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 integer. If you want to provide serial numbers as colon-separated hex strings, such as |
-
| - | The role part of the SELinux filesystem object context. -When set to |
-
| - | The type part of the SELinux filesystem object context. -When set to |
-
| - | The user part of the SELinux filesystem object context. -By default it uses the When set to |
-
| - | As of OpenSSH 8.2 the SHA-1 signature algorithm for RSA keys has been disabled and Using any value for this option with a non-RSA 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 https://www.openssh.com/txt/release-8.2 for more information. -Choices: -
|
-
| - | 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 ( Required if |
-
| - | Whether the host or user certificate should exist or not, taking action if the state is different from what is stated. -Choices: -
|
-
| - | Whether the module should generate a host or a user certificate. -Required if Choices: -
|
-
| - | Influence when to use atomic operation to prevent data corruption or inconsistent reads from the target filesystem object. -By default this module uses atomic operations to prevent data corruption or inconsistent reads from the target filesystem objects, but sometimes systems are configured or just broken in ways that prevent this. One example is docker mounted filesystem objects, which cannot be updated atomically from inside the container and can only be written in an unsafe manner. -This option allows Ansible to fall back to unsafe methods of updating filesystem objects when atomic operations fail (however, it doesn’t force Ansible to perform unsafe writes). -IMPORTANT! Unsafe writes are subject to race conditions and can lead to data corruption. -Choices: -
|
-
| - | Should the ssh-keygen use a CA key residing in a ssh-agent. -Choices: -
|
-
| - | 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 |
-
| - | 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: The value To ignore this value during comparison with an existing certificate set Required if |
-
| - | 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: To ignore this value during comparison with an existing certificate set Required if |
-
Attribute |
-Support |
-Description |
-
|---|---|---|
| - | Support: full - |
-Can run in |
-
| - | Support: full - |
-Will return details on what has changed (or possibly needs changing in |
-
| - | Support: partial -The module is not idempotent if If relative timestamps are used and |
-When run twice in a row outside check mode, with the same arguments, the second invocation indicates no change. -This assumes that the system controlled/queried by the module has not changed in a relevant way. - |
-
| - | Support: full - |
-Uses Ansible’s strict file operation functions to ensure proper permissions and avoid data corruption. - |
-
See also
-Convert a serial number as a colon-separated list of hex numbers to an integer.
----
-- name: Generate an OpenSSH user certificate that is valid forever and for all users
- community.crypto.openssh_cert:
- type: user
- signing_key: /path/to/private_key
- public_key: /path/to/public_key.pub
- path: /path/to/certificate
- valid_from: always
- valid_to: forever
-
-# Generate an OpenSSH host certificate that is valid for 32 weeks from now and will be regenerated
-# if it is valid for less than 2 weeks from the time the module is being run
-- name: Generate an OpenSSH host certificate with valid_from, valid_to and valid_at parameters
- community.crypto.openssh_cert:
- type: host
- signing_key: /path/to/private_key
- public_key: /path/to/public_key.pub
- path: /path/to/certificate
- valid_from: +0s
- valid_to: +32w
- valid_at: +2w
- ignore_timestamps: true
-
-- name: Generate an OpenSSH host certificate that is valid forever and only for example.com and examplehost
- community.crypto.openssh_cert:
- type: host
- signing_key: /path/to/private_key
- public_key: /path/to/public_key.pub
- path: /path/to/certificate
- valid_from: always
- valid_to: forever
- principals:
- - example.com
- - examplehost
-
-- name: Generate an OpenSSH host Certificate that is valid from 21.1.2001 to 21.1.2019
- community.crypto.openssh_cert:
- type: host
- signing_key: /path/to/private_key
- public_key: /path/to/public_key.pub
- path: /path/to/certificate
- valid_from: "2001-01-21"
- valid_to: "2019-01-21"
-
-- name: Generate an OpenSSH user Certificate with clear and force-command option
- community.crypto.openssh_cert:
- type: user
- signing_key: /path/to/private_key
- public_key: /path/to/public_key.pub
- path: /path/to/certificate
- valid_from: always
- valid_to: forever
- options:
- - "clear"
- - "force-command=/tmp/bla/foo"
-
-- name: Generate an OpenSSH user certificate using a PKCS#11 token
- community.crypto.openssh_cert:
- type: user
- signing_key: /path/to/ca_public_key.pub
- pkcs11_provider: libpkcs11.so
- public_key: /path/to/public_key.pub
- path: /path/to/certificate
- valid_from: always
- valid_to: forever
-Common return values are documented here, the following are the fields unique to this module:
-Key |
-Description |
-
|---|---|
| - | Path to the certificate. -Returned: changed or success -Sample: |
-
| - | Information about the certificate. Output of Returned: change or success - |
-
| - | Type of the certificate (host or user). -Returned: changed or success -Sample: |
-
- Note
-This module is part of the community.crypto collection (version 2.26.6).
-It is not included in ansible-core.
-To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install community.crypto.
-You need further requirements to be able to use this module,
-see Requirements for details.
To use it in a playbook, specify: community.crypto.openssh_keypair.
This module allows one to (re)generate OpenSSH private and public keys. It uses ssh-keygen to generate keys. One can generate rsa, dsa, rsa1, ed25519 or ecdsa private keys.
The below requirements are needed on the host that executes this module.
-ssh-keygen (if backend=openssh)
cryptography >= 2.6 (if backend=cryptography and OpenSSH < 7.8 is installed)
cryptography >= 3.0 (if backend=cryptography and OpenSSH >= 7.8 is installed)
Parameter |
-Comments |
-
|---|---|
| - | The attributes the resulting filesystem object should have. -To get supported flags look at the man page for This string should contain the attributes in the same order as the one displayed by The |
-
| - | Selects between the
Choices: -
|
-
| - | Provides a new comment to the public key. - |
-
| - | Should the key be regenerated even if it already exists. -Choices: -
|
-
| - | Name of the group that should own the filesystem object, as would be fed to When left unspecified, it uses the current group of the current user unless you are root, in which case it can preserve the previous ownership. - |
-
| - | The permissions the resulting filesystem object should have. -For those used to Giving Ansible a number without following either of these rules will end up with a decimal number which will have unexpected results. -As of Ansible 1.8, the mode may be specified as a symbolic mode (for example, If If Specifying |
-
| - | Name of the user that should own the filesystem object, as would be fed to When left unspecified, it uses the current user unless you are root, in which case it can preserve the previous ownership. -Specifying a numeric username will be assumed to be a user ID and not a username. Avoid numeric usernames to avoid this confusion. - |
-
| - | Passphrase used to decrypt an existing private key or encrypt a newly generated private key. -Passphrases are not supported for Can only be used when |
-
| - | Name of the files containing the public and private key. The file containing the public key will have the extension |
-
| - | Used when When set to 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 Choices: -
|
-
| - | 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 changed for Ansible 2.10. For Ansible 2.9, the behavior was as if If set to If set to If set to If set to If set to Note that adjusting the comment and the permissions can be changed without regeneration. Therefore, even for Choices: -
|
-
| - | The level part of the SELinux filesystem object context. -This is the MLS/MCS attribute, sometimes known as the When set to |
-
| - | The role part of the SELinux filesystem object context. -When set to |
-
| - | The type part of the SELinux filesystem object context. -When set to |
-
| - | The user part of the SELinux filesystem object context. -By default it uses the When set to |
-
| - | 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. - |
-
| - | Whether the private and public keys should exist or not, taking action if the state is different from what is stated. -Choices: -
|
-
| - | The algorithm used to generate the SSH private key. Choices: -
|
-
| - | Influence when to use atomic operation to prevent data corruption or inconsistent reads from the target filesystem object. -By default this module uses atomic operations to prevent data corruption or inconsistent reads from the target filesystem objects, but sometimes systems are configured or just broken in ways that prevent this. One example is docker mounted filesystem objects, which cannot be updated atomically from inside the container and can only be written in an unsafe manner. -This option allows Ansible to fall back to unsafe methods of updating filesystem objects when atomic operations fail (however, it doesn’t force Ansible to perform unsafe writes). -IMPORTANT! Unsafe writes are subject to race conditions and can lead to data corruption. -Choices: -
|
-
Attribute |
-Support |
-Description |
-
|---|---|---|
| - | Support: full - |
-Can run in |
-
| - | Support: full - |
-Will return details on what has changed (or possibly needs changing in |
-
| - | Support: partial -The module is not idempotent if |
-When run twice in a row outside check mode, with the same arguments, the second invocation indicates no change. -This assumes that the system controlled/queried by the module has not changed in a relevant way. - |
-
| - | Support: full - |
-Uses Ansible’s strict file operation functions to ensure proper permissions and avoid data corruption. - |
-
---
-- name: Generate an OpenSSH keypair with the default values (4096 bits, rsa)
- community.crypto.openssh_keypair:
- path: /tmp/id_ssh_rsa
-
-- name: Generate an OpenSSH keypair with the default values (4096 bits, rsa) and encrypted private key
- community.crypto.openssh_keypair:
- path: /tmp/id_ssh_rsa
- passphrase: super_secret_password
-
-- name: Generate an OpenSSH rsa keypair with a different size (2048 bits)
- community.crypto.openssh_keypair:
- path: /tmp/id_ssh_rsa
- size: 2048
-
-- name: Force regenerate an OpenSSH keypair if it already exists
- community.crypto.openssh_keypair:
- path: /tmp/id_ssh_rsa
- force: true
-
-- name: Regenerate SSH keypair only if format or options mismatch
- community.crypto.openssh_keypair:
- path: /home/devops/.ssh/id_ed25519
- type: ed25519
- regenerate: full_idempotence
- private_key_format: ssh
-
-- name: Generate an OpenSSH keypair with a different algorithm (dsa)
- community.crypto.openssh_keypair:
- path: /tmp/id_ssh_dsa
- type: dsa
-Common return values are documented here, the following are the fields unique to this module:
-Key |
-Description |
-
|---|---|
| - | The comment of the generated key. -Returned: changed or success -Sample: |
-
| - | Path to the generated SSH private key file. -Returned: changed or success -Sample: |
-
| - | The fingerprint of the key. -Returned: changed or success -Sample: |
-
| - | The public key of the generated SSH private key. -Returned: changed or success -Sample: |
-
| - | Size (in bits) of the SSH private key. -Returned: changed or success -Sample: |
-
| - | Algorithm used to generate the SSH private key. -Returned: changed or success -Sample: |
-
- Note
-This plugin was part of the community.crypto collection (version 2.26.6).
-This module has been removed -in version 2.0.0 of community.crypto. -The ‘community.crypto.openssl_certificate_info’ module has been renamed to ‘community.crypto.x509_certificate_info’
-
- Note
-This plugin was part of the community.crypto collection (version 2.26.6).
-This module has been removed -in version 2.0.0 of community.crypto. -The ‘community.crypto.openssl_certificate’ module has been renamed to ‘community.crypto.x509_certificate’
-
- Note
-This filter plugin is part of the community.crypto collection (version 2.26.6).
-It is not included in ansible-core.
-To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install community.crypto.
-You need further requirements to be able to use this filter plugin,
-see Requirements for details.
To use it in a playbook, specify: community.crypto.openssl_csr_info.
New in community.crypto 2.10.0
- -Provided an OpenSSL Certificate Signing Requests (CSR), retrieve information.
This is a filter version of the community.crypto.openssl_csr_info module.
The below requirements are needed on the local controller node that executes this filter.
-If name_encoding is set to another value than ignore, the idna Python library needs to be installed.
This describes the input of the filter, the value before | community.crypto.openssl_csr_info.
Parameter |
-Comments |
-
|---|---|
| - | The content of the OpenSSL CSR. - |
-
This describes keyword parameters of the filter. These are the values key1=value1, key2=value2 and so on in the following
-example: input | community.crypto.openssl_csr_info(key1=value1, key2=value2, ...)
Parameter |
-Comments |
-
|---|---|
| - | How to encode names (DNS names, URIs, email addresses) in return values. -
Note that Choices: -
|
-
See also
-Provide information of OpenSSL Certificate Signing Requests (CSR).
-Convert an integer to a colon-separated list of hex numbers.
----
-- name: Show the Subject Alt Names of the CSR
- ansible.builtin.debug:
- msg: >-
- {{
- (
- lookup('ansible.builtin.file', '/path/to/cert.csr')
- | community.crypto.openssl_csr_info
- ).subject_alt_name | join(', ')
- }}
-Key |
-Description |
-
|---|---|
| - | Information on the certificate. -Returned: success - |
-
| - | The CSR’s authority cert issuer as a list of general names. -Is See Returned: success -Sample: |
-
| - | The CSR’s authority cert serial number. -Is This return value is an integer. If you need the serial numbers as a colon-separated hex string, such as Returned: success -Sample: |
-
| - | The CSR’s authority key identifier. -The identifier is returned in hexadecimal, with Is Returned: success -Sample: |
-
| - | Entries in the Returned: success -Sample: |
-
| - | Whether the Returned: success - |
-
| - | Entries in the Returned: success -Sample: |
-
| - | Whether the Returned: success - |
-
| - | Returns a dictionary for every extension OID. -Returned: success -Sample: |
-
| - | Whether the extension is critical. -Returned: success - |
-
| - | The Base64 encoded value (in DER format) of the extension. -Note that depending on the Returned: success -Sample: |
-
| - | Entries in the Returned: success -Sample: |
-
| - | Whether the Returned: success - |
-
| - | Whether the Is Returned: success - |
-
| - | List of excluded subtrees the CA cannot sign certificates for. -Is See Returned: success -Sample: |
-
| - | List of permitted subtrees to sign certificates for. -Returned: success -Sample: |
-
| - |
Returned: success - |
-
| - | Whether the Returned: success - |
-
| - | CSR’s public key in PEM format. -Returned: success -Sample: |
-
| - | Public key data. Depends on the public key’s type. -Returned: success - |
-
| - | The curve’s name for ECC. -Returned: When |
-
| - | The RSA key’s public exponent. -Returned: When |
-
| - | The maximum number of bits of a private key. This is basically the bit size of the subgroup used. -Returned: When |
-
| - | The This is the element spanning the subgroup of the multiplicative group of the prime field used. -Returned: When |
-
| - | The RSA key’s modulus. -Returned: When |
-
| - | The This is the prime modulus upon which arithmetic takes place. -Returned: When |
-
| - | The This is a prime that divides Returned: When |
-
| - | Bit size of modulus (RSA) or prime number (DSA). -Returned: When |
-
| - | The Returned: When |
-
| - | For For Returned: When |
-
| - | Fingerprints of CSR’s public key. -For every hash algorithm available, the fingerprint is computed. -Returned: success -Sample: |
-
| - | The CSR’s public key’s type. -One of Will start with Returned: success -Sample: |
-
| - | Whether the CSR’s signature is valid. -In case the check returns Returned: success - |
-
| - | The CSR’s subject as a dictionary. -Note that for repeated values, only the last one will be returned. -Returned: success -Sample: |
-
| - | Entries in the See Returned: success -Sample: |
-
| - | Whether the Returned: success - |
-
| - | The CSR’s subject key identifier. -The identifier is returned in hexadecimal, with Is Returned: success -Sample: |
-
| - | The CSR’s subject as an ordered list of tuples. -Returned: success -Sample: |
-
- Note
-This module is part of the community.crypto collection (version 2.26.6).
-It is not included in ansible-core.
-To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install community.crypto.
-You need further requirements to be able to use this module,
-see Requirements for details.
To use it in a playbook, specify: community.crypto.openssl_csr_info.
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.
The below requirements are needed on the host that executes this module.
-If name_encoding is set to another value than ignore, the idna Python library needs to be installed.
cryptography >= 1.3
Parameter |
-Comments |
-
|---|---|
| - | - |
| - | How to encode names (DNS names, URIs, email addresses) in return values. -
Note that Choices: -
|
-
| - | - |
| - | Determines which crypto backend to use. -The default choice is If set to Choices: -
|
-
Attribute |
-Support |
-Description |
-
|---|---|---|
| - | Support: full -This action does not modify state. - |
-Can run in |
-
| - | Support: N/A -This action does not modify state. - |
-Will return details on what has changed (or possibly needs changing in |
-
| - | Support: full -This action does not modify state. - |
-When run twice in a row outside check mode, with the same arguments, the second invocation indicates no change. -This assumes that the system controlled/queried by the module has not changed in a relevant way. - |
-
See also
-Generate OpenSSL Certificate Signing Request (CSR).
-Generate OpenSSL Certificate Signing Request (CSR).
-A filter variant of this module.
-Convert an integer to a colon-separated list of hex numbers.
----
-- name: Generate an OpenSSL Certificate Signing Request
- community.crypto.openssl_csr:
- path: /etc/ssl/csr/www.ansible.com.csr
- privatekey_path: /etc/ssl/private/ansible.com.pem
- common_name: www.ansible.com
-
-- name: Get information on the CSR
- community.crypto.openssl_csr_info:
- path: /etc/ssl/csr/www.ansible.com.csr
- register: result
-
-- name: Dump information
- ansible.builtin.debug:
- var: result
-Common return values are documented here, the following are the fields unique to this module:
-Key |
-Description |
-
|---|---|
| - | The CSR’s authority cert issuer as a list of general names. -Is See Returned: success -Sample: |
-
| - | The CSR’s authority cert serial number. -Is This return value is an integer. If you need the serial numbers as a colon-separated hex string, such as Returned: success -Sample: |
-
| - | The CSR’s authority key identifier. -The identifier is returned in hexadecimal, with Is Returned: success -Sample: |
-
| - | Entries in the Returned: success -Sample: |
-
| - | Whether the Returned: success - |
-
| - | Entries in the Returned: success -Sample: |
-
| - | Whether the Returned: success - |
-
| - | Returns a dictionary for every extension OID. -Returned: success -Sample: |
-
| - | Whether the extension is critical. -Returned: success - |
-
| - | The Base64 encoded value (in DER format) of the extension. -Note that depending on the Returned: success -Sample: |
-
| - | Entries in the Returned: success -Sample: |
-
| - | Whether the Returned: success - |
-
| - | Whether the Is Returned: success - |
-
| - | List of excluded subtrees the CA cannot sign certificates for. -Is See Returned: success -Sample: |
-
| - | List of permitted subtrees to sign certificates for. -Returned: success -Sample: |
-
| - |
Returned: success - |
-
| - | Whether the Returned: success - |
-
| - | CSR’s public key in PEM format. -Returned: success -Sample: |
-
| - | Public key data. Depends on the public key’s type. -Returned: success - |
-
| - | The curve’s name for ECC. -Returned: When |
-
| - | The RSA key’s public exponent. -Returned: When |
-
| - | The maximum number of bits of a private key. This is basically the bit size of the subgroup used. -Returned: When |
-
| - | The This is the element spanning the subgroup of the multiplicative group of the prime field used. -Returned: When |
-
| - | The RSA key’s modulus. -Returned: When |
-
| - | The This is the prime modulus upon which arithmetic takes place. -Returned: When |
-
| - | The This is a prime that divides Returned: When |
-
| - | Bit size of modulus (RSA) or prime number (DSA). -Returned: When |
-
| - | The Returned: When |
-
| - | For For Returned: When |
-
| - | Fingerprints of CSR’s public key. -For every hash algorithm available, the fingerprint is computed. -Returned: success -Sample: |
-
| - | The CSR’s public key’s type. -One of Will start with Returned: success -Sample: |
-
| - | Whether the CSR’s signature is valid. -In case the check returns Returned: success - |
-
| - | The CSR’s subject as a dictionary. -Note that for repeated values, only the last one will be returned. -Returned: success -Sample: |
-
| - | Entries in the See Returned: success -Sample: |
-
| - | Whether the Returned: success - |
-
| - | The CSR’s subject key identifier. -The identifier is returned in hexadecimal, with Is Returned: success -Sample: |
-
| - | The CSR’s subject as an ordered list of tuples. -Returned: success -Sample: |
-
- Note
-This module is part of the community.crypto collection (version 2.26.6).
-It is not included in ansible-core.
-To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install community.crypto.
-You need further requirements to be able to use this module,
-see Requirements for details.
To use it in a playbook, specify: community.crypto.openssl_csr.
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 backup option.
This module allows one to (re)generate OpenSSL certificate signing requests.
This module supports the subjectAltName, keyUsage, extendedKeyUsage, basicConstraints and OCSP Must Staple extensions.
The below requirements are needed on the host that executes this module.
-cryptography >= 1.3
Parameter |
-Comments |
-
|---|---|
| - | The attributes the resulting filesystem object should have. -To get supported flags look at the man page for This string should contain the attributes in the same order as the one displayed by The |
-
| - | 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, Example: If 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 The |
-
| - | The authority cert serial number. -If specified, Note that this is only supported if the 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 This option accepts an integer. If you want to provide serial numbers as colon-separated hex strings, such as |
-
| - | The authority key identifier as a hex string, where two bytes are separated by colons. -Example: 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 The |
-
| - | 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. -Choices: -
|
-
| - | Indicates basic constraints, such as if the certificate is a CA. - |
-
| - | Should the basicConstraints extension be considered as critical. -Choices: -
|
-
| - | The commonName field of the certificate signing request subject. - |
-
| - | The countryName field of the certificate signing request subject. - |
-
| - | 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 Choices: -
|
-
| - | Allows to specify one or multiple CRL distribution points. -Only supported by the |
-
| - | Information about the issuer of the CRL. - |
-
| - | Describes how the CRL can be retrieved. -Mutually exclusive with Example: |
-
| - | List of reasons that this distribution point can be used for when performing revocation checks. -Choices: -
|
-
| - | Describes how the CRL can be retrieved relative to the CRL issuer. -Mutually exclusive with Example: Can only be used when cryptography >= 1.6 is installed. - |
-
| - | The digest used when signing the certificate signing request with the private key. -Default: |
-
| - | The emailAddress field of the certificate signing request subject. - |
-
| - | Additional restrictions (for example client authentication, server authentication) on the allowed purposes for which the public key may be used. - |
-
| - | Should the extkeyUsage extension be considered as critical. -Choices: -
|
-
| - | Should the certificate signing request be forced regenerated by this ansible module. -Choices: -
|
-
| - | Name of the group that should own the filesystem object, as would be fed to When left unspecified, it uses the current group of the current user unless you are root, in which case it can preserve the previous ownership. - |
-
| - | This defines the purpose (for example encipherment, signature, certificate signing) of the key contained in the certificate. - |
-
| - | Should the keyUsage extension be considered as critical. -Choices: -
|
-
| - | The localityName field of the certificate signing request subject. - |
-
| - | The permissions the resulting filesystem object should have. -For those used to Giving Ansible a number without following either of these rules will end up with a decimal number which will have unexpected results. -As of Ansible 1.8, the mode may be specified as a symbolic mode (for example, If If Specifying |
-
| - | Should the Name Constraints extension be considered as critical. -Choices: -
|
-
| - | For CA certificates, this specifies a list of identifiers which describe subtrees of names that this CA is not allowed to issue certificates for. -Values must be prefixed by their options. (That is, |
-
| - | 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, |
-
| - | Indicates that the certificate should contain the OCSP Must Staple extension (https://tools.ietf.org/html/rfc7633). -Choices: -
|
-
| - | 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 https://tools.ietf.org/html/rfc7633#section-4). -Choices: -
|
-
| - | The organizationName field of the certificate signing request subject. - |
-
| - | The organizationalUnitName field of the certificate signing request subject. - |
-
| - | Name of the user that should own the filesystem object, as would be fed to When left unspecified, it uses the current user unless you are root, in which case it can preserve the previous ownership. -Specifying a numeric username will be assumed to be a user ID and not a username. Avoid numeric usernames to avoid this confusion. - |
-
| - | The name of the file into which the generated OpenSSL certificate signing request will be written. - |
-
| - | The content of the private key to use when signing the certificate signing request. -Either |
-
| - | The passphrase for the private key. -This is required if the private key is password protected. - |
-
| - | The path to the private key to use when signing the certificate signing request. -Either |
-
| - | If set to Choices: -
|
-
| - | Determines which crypto backend to use. -The default choice is If set to Choices: -
|
-
| - | The level part of the SELinux filesystem object context. -This is the MLS/MCS attribute, sometimes known as the When set to |
-
| - | The role part of the SELinux filesystem object context. -When set to |
-
| - | The type part of the SELinux filesystem object context. -When set to |
-
| - | The user part of the SELinux filesystem object context. -By default it uses the When set to |
-
| - | Whether the certificate signing request should exist or not, taking action if the state is different from what is stated. -Choices: -
|
-
| - | The stateOrProvinceName field of the certificate signing request subject. - |
-
| - | 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 Mutually exclusive with |
-
| - | Subject Alternative Name (SAN) extension to attach to the certificate signing request. -Values must be prefixed by their options. (These are Note that if no SAN is specified, but a common name, the common name will be added as a SAN except if More at https://tools.ietf.org/html/rfc5280#section-4.2.1.6. - |
-
| - | Should the subjectAltName extension be considered as critical. -Choices: -
|
-
| - | The subject key identifier as a hex string, where two bytes are separated by colons. -Example: 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 Note that this is only supported if the |
-
| - | 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 |
-
| - | Influence when to use atomic operation to prevent data corruption or inconsistent reads from the target filesystem object. -By default this module uses atomic operations to prevent data corruption or inconsistent reads from the target filesystem objects, but sometimes systems are configured or just broken in ways that prevent this. One example is docker mounted filesystem objects, which cannot be updated atomically from inside the container and can only be written in an unsafe manner. -This option allows Ansible to fall back to unsafe methods of updating filesystem objects when atomic operations fail (however, it doesn’t force Ansible to perform unsafe writes). -IMPORTANT! Unsafe writes are subject to race conditions and can lead to data corruption. -Choices: -
|
-
| - | If set to Choices: -
|
-
| - | The version of the certificate signing request. -The only allowed value according to RFC 2986 is 1. -This option no longer accepts unsupported values since community.crypto 2.0.0. -Choices: -
|
-
Attribute |
-Support |
-Description |
-
|---|---|---|
| - | Support: full - |
-Can run in |
-
| - | Support: full - |
-Will return details on what has changed (or possibly needs changing in |
-
| - | Support: full - |
-When run twice in a row outside check mode, with the same arguments, the second invocation indicates no change. -This assumes that the system controlled/queried by the module has not changed in a relevant way. - |
-
| - | Support: full - |
-Uses Ansible’s strict file operation functions to ensure proper permissions and avoid data corruption. - |
-
Note
-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.
See also
-Generate OpenSSL Certificate Signing Request (CSR).
-Generate and/or check OpenSSL certificates.
-Generate and/or check OpenSSL certificates.
-Generate OpenSSL Diffie-Hellman Parameters.
-Generate OpenSSL PKCS#12 archive.
-Generate OpenSSL private keys.
-Generate OpenSSL private keys without disk access.
-Generate an OpenSSL public key from its private key.
-Provide information of OpenSSL Certificate Signing Requests (CSR).
-Convert a serial number as a colon-separated list of hex numbers to an integer.
----
-- name: Generate an OpenSSL Certificate Signing Request
- community.crypto.openssl_csr:
- path: /etc/ssl/csr/www.ansible.com.csr
- privatekey_path: /etc/ssl/private/ansible.com.pem
- common_name: www.ansible.com
-
-- name: Generate an OpenSSL Certificate Signing Request with an inline key
- community.crypto.openssl_csr:
- path: /etc/ssl/csr/www.ansible.com.csr
- privatekey_content: "{{ private_key_content }}"
- common_name: www.ansible.com
-
-- name: Generate an OpenSSL Certificate Signing Request with a passphrase protected private key
- community.crypto.openssl_csr:
- path: /etc/ssl/csr/www.ansible.com.csr
- privatekey_path: /etc/ssl/private/ansible.com.pem
- privatekey_passphrase: ansible
- common_name: www.ansible.com
-
-- name: Generate an OpenSSL Certificate Signing Request with Subject information
- community.crypto.openssl_csr:
- path: /etc/ssl/csr/www.ansible.com.csr
- privatekey_path: /etc/ssl/private/ansible.com.pem
- country_name: FR
- organization_name: Ansible
- email_address: jdoe@ansible.com
- common_name: www.ansible.com
-
-- name: Generate an OpenSSL Certificate Signing Request with subjectAltName extension
- community.crypto.openssl_csr:
- path: /etc/ssl/csr/www.ansible.com.csr
- privatekey_path: /etc/ssl/private/ansible.com.pem
- subject_alt_name: 'DNS:www.ansible.com,DNS:m.ansible.com'
-
-- name: Generate an OpenSSL CSR with subjectAltName extension with dynamic list
- community.crypto.openssl_csr:
- path: /etc/ssl/csr/www.ansible.com.csr
- privatekey_path: /etc/ssl/private/ansible.com.pem
- subject_alt_name: "{{ item.value | map('regex_replace', '^', 'DNS:') | list }}"
- with_dict:
- dns_server:
- - www.ansible.com
- - m.ansible.com
-
-- name: Force regenerate an OpenSSL Certificate Signing Request
- community.crypto.openssl_csr:
- path: /etc/ssl/csr/www.ansible.com.csr
- privatekey_path: /etc/ssl/private/ansible.com.pem
- force: true
- common_name: www.ansible.com
-
-- name: Generate an OpenSSL Certificate Signing Request with special key usages
- community.crypto.openssl_csr:
- path: /etc/ssl/csr/www.ansible.com.csr
- privatekey_path: /etc/ssl/private/ansible.com.pem
- common_name: www.ansible.com
- key_usage:
- - digitalSignature
- - keyAgreement
- extended_key_usage:
- - clientAuth
-
-- name: Generate an OpenSSL Certificate Signing Request with OCSP Must Staple
- community.crypto.openssl_csr:
- path: /etc/ssl/csr/www.ansible.com.csr
- privatekey_path: /etc/ssl/private/ansible.com.pem
- common_name: www.ansible.com
- ocsp_must_staple: true
-
-- name: Generate an OpenSSL Certificate Signing Request for WinRM Certificate authentication
- community.crypto.openssl_csr:
- path: /etc/ssl/csr/winrm.auth.csr
- privatekey_path: /etc/ssl/private/winrm.auth.pem
- common_name: username
- extended_key_usage:
- - 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
- community.crypto.openssl_csr:
- path: /etc/ssl/csr/www.ansible.com.csr
- privatekey_path: /etc/ssl/private/ansible.com.pem
- common_name: www.ansible.com
- crl_distribution_points:
- - full_name:
- - "URI:https://ca.example.com/revocations.crl"
- crl_issuer:
- - "URI:https://ca.example.com/"
- reasons:
- - key_compromise
- - ca_compromise
- - cessation_of_operation
-Common return values are documented here, the following are the fields unique to this module:
-Key |
-Description |
-
|---|---|
| - | Name of backup file created. -Returned: changed and if Sample: |
-
| - | Indicates if the certificate belongs to a CA. -Returned: changed or success -Sample: |
-
| - | The (current or generated) CSR’s content. -Returned: if |
-
| - | Additional restriction on the public key purposes. -Returned: changed or success -Sample: |
-
| - | Path to the generated Certificate Signing Request. -Returned: changed or success -Sample: |
-
| - | Purpose for which the public key may be used. -Returned: changed or success -Sample: |
-
| - | List of excluded subtrees the CA cannot sign certificates for. -Returned: changed or success -Sample: |
-
| - | List of permitted subtrees to sign certificates for. -Returned: changed or success -Sample: |
-
| - | Indicates whether the certificate has the OCSP Must Staple feature enabled. -Returned: changed or success -Sample: |
-
| - | Path to the TLS/SSL private key the CSR was generated for. -Will be Returned: changed or success -Sample: |
-
| - | A list of the subject tuples attached to the CSR. -Returned: changed or success -Sample: |
-
| - | The alternative names this CSR is valid for. -Returned: changed or success -Sample: |
-
- Note
-This module is part of the community.crypto collection (version 2.26.6).
-It is not included in ansible-core.
-To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install community.crypto.
-You need further requirements to be able to use this module,
-see Requirements for details.
To use it in a playbook, specify: community.crypto.openssl_csr_pipe.
New in community.crypto 1.3.0
- -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.
This module allows one to (re)generate OpenSSL certificate signing requests.
This module supports the subjectAltName, keyUsage, extendedKeyUsage, basicConstraints and OCSP Must Staple extensions.
The below requirements are needed on the host that executes this module.
-cryptography >= 1.3
Parameter |
-Comments |
-
|---|---|
| - | 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, Example: If 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 The |
-
| - | The authority cert serial number. -If specified, Note that this is only supported if the 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 This option accepts an integer. If you want to provide serial numbers as colon-separated hex strings, such as |
-
| - | The authority key identifier as a hex string, where two bytes are separated by colons. -Example: 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 The |
-
| - | Indicates basic constraints, such as if the certificate is a CA. - |
-
| - | Should the basicConstraints extension be considered as critical. -Choices: -
|
-
| - | The commonName field of the certificate signing request subject. - |
-
| - | The existing CSR. - |
-
| - | The countryName field of the certificate signing request subject. - |
-
| - | 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 Choices: -
|
-
| - | Allows to specify one or multiple CRL distribution points. -Only supported by the |
-
| - | Information about the issuer of the CRL. - |
-
| - | Describes how the CRL can be retrieved. -Mutually exclusive with Example: |
-
| - | List of reasons that this distribution point can be used for when performing revocation checks. -Choices: -
|
-
| - | Describes how the CRL can be retrieved relative to the CRL issuer. -Mutually exclusive with Example: Can only be used when cryptography >= 1.6 is installed. - |
-
| - | The digest used when signing the certificate signing request with the private key. -Default: |
-
| - | The emailAddress field of the certificate signing request subject. - |
-
| - | Additional restrictions (for example client authentication, server authentication) on the allowed purposes for which the public key may be used. - |
-
| - | Should the extkeyUsage extension be considered as critical. -Choices: -
|
-
| - | This defines the purpose (for example encipherment, signature, certificate signing) of the key contained in the certificate. - |
-
| - | Should the keyUsage extension be considered as critical. -Choices: -
|
-
| - | The localityName field of the certificate signing request subject. - |
-
| - | Should the Name Constraints extension be considered as critical. -Choices: -
|
-
| - | For CA certificates, this specifies a list of identifiers which describe subtrees of names that this CA is not allowed to issue certificates for. -Values must be prefixed by their options. (That is, |
-
| - | 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, |
-
| - | Indicates that the certificate should contain the OCSP Must Staple extension (https://tools.ietf.org/html/rfc7633). -Choices: -
|
-
| - | 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 https://tools.ietf.org/html/rfc7633#section-4). -Choices: -
|
-
| - | The organizationName field of the certificate signing request subject. - |
-
| - | The organizationalUnitName field of the certificate signing request subject. - |
-
| - | The content of the private key to use when signing the certificate signing request. -Either |
-
| - | The passphrase for the private key. -This is required if the private key is password protected. - |
-
| - | The path to the private key to use when signing the certificate signing request. -Either |
-
| - | Determines which crypto backend to use. -The default choice is If set to Choices: -
|
-
| - | The stateOrProvinceName field of the certificate signing request subject. - |
-
| - | 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 Mutually exclusive with |
-
| - | Subject Alternative Name (SAN) extension to attach to the certificate signing request. -Values must be prefixed by their options. (These are Note that if no SAN is specified, but a common name, the common name will be added as a SAN except if More at https://tools.ietf.org/html/rfc5280#section-4.2.1.6. - |
-
| - | Should the subjectAltName extension be considered as critical. -Choices: -
|
-
| - | The subject key identifier as a hex string, where two bytes are separated by colons. -Example: 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 Note that this is only supported if the |
-
| - | 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 |
-
| - | If set to Choices: -
|
-
| - | The version of the certificate signing request. -The only allowed value according to RFC 2986 is 1. -This option no longer accepts unsupported values since community.crypto 2.0.0. -Choices: -
|
-
Attribute |
-Support |
-Description |
-
|---|---|---|
| - | Support: full -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. - |
-Can run in |
-
| - | Support: full - |
-Will return details on what has changed (or possibly needs changing in |
-
| - | Support: full - |
-When run twice in a row outside check mode, with the same arguments, the second invocation indicates no change. -This assumes that the system controlled/queried by the module has not changed in a relevant way. - |
-
Note
-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.
See also
-Generate OpenSSL Certificate Signing Request (CSR).
-Generate and/or check OpenSSL certificates.
-Generate and/or check OpenSSL certificates.
-Generate OpenSSL Diffie-Hellman Parameters.
-Generate OpenSSL PKCS#12 archive.
-Generate OpenSSL private keys.
-Generate OpenSSL private keys without disk access.
-Generate an OpenSSL public key from its private key.
-Provide information of OpenSSL Certificate Signing Requests (CSR).
-Convert a serial number as a colon-separated list of hex numbers to an integer.
----
-- name: Generate an OpenSSL Certificate Signing Request
- community.crypto.openssl_csr_pipe:
- privatekey_path: /etc/ssl/private/ansible.com.pem
- common_name: www.ansible.com
- register: result
-- name: Print CSR
- ansible.builtin.debug:
- var: result.csr
-
-- name: Generate an OpenSSL Certificate Signing Request with an inline CSR
- community.crypto.openssl_csr:
- content: "{{ lookup('ansible.builtin.file', '/etc/ssl/csr/www.ansible.com.csr') }}"
- privatekey_content: "{{ private_key_content }}"
- common_name: www.ansible.com
- register: result
-- name: Store CSR
- ansible.builtin.copy:
- dest: /etc/ssl/csr/www.ansible.com.csr
- content: "{{ result.csr }}"
- when: result is changed
-Common return values are documented here, the following are the fields unique to this module:
-Key |
-Description |
-
|---|---|
| - | Indicates if the certificate belongs to a CA. -Returned: changed or success -Sample: |
-
| - | The (current or generated) CSR’s content. -Returned: changed or success - |
-
| - | Additional restriction on the public key purposes. -Returned: changed or success -Sample: |
-
| - | Purpose for which the public key may be used. -Returned: changed or success -Sample: |
-
| - | List of excluded subtrees the CA cannot sign certificates for. -Returned: changed or success -Sample: |
-
| - | List of permitted subtrees to sign certificates for. -Returned: changed or success -Sample: |
-
| - | Indicates whether the certificate has the OCSP Must Staple feature enabled. -Returned: changed or success -Sample: |
-
| - | Path to the TLS/SSL private key the CSR was generated for. -Will be Returned: changed or success -Sample: |
-
| - | A list of the subject tuples attached to the CSR. -Returned: changed or success -Sample: |
-
| - | The alternative names this CSR is valid for. -Returned: changed or success -Sample: |
-
- Note
-This module is part of the community.crypto collection (version 2.26.6).
-It is not included in ansible-core.
-To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install community.crypto.
-You need further requirements to be able to use this module,
-see Requirements for details.
To use it in a playbook, specify: community.crypto.openssl_dhparam.
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 backup option.
The module can use the cryptography Python library, or the openssl executable. By default, it tries to detect which one is available. This can be overridden with the select_crypto_backend option.
The below requirements are needed on the host that executes this module.
-Either cryptography >= 2.0
Or OpenSSL binary openssl
Parameter |
-Comments |
-
|---|---|
| - | The attributes the resulting filesystem object should have. -To get supported flags look at the man page for This string should contain the attributes in the same order as the one displayed by The |
-
| - | 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. -Choices: -
|
-
| - | Should the parameters be regenerated even it it already exists. -Choices: -
|
-
| - | Name of the group that should own the filesystem object, as would be fed to When left unspecified, it uses the current group of the current user unless you are root, in which case it can preserve the previous ownership. - |
-
| - | The permissions the resulting filesystem object should have. -For those used to Giving Ansible a number without following either of these rules will end up with a decimal number which will have unexpected results. -As of Ansible 1.8, the mode may be specified as a symbolic mode (for example, If If Specifying |
-
| - | Name of the user that should own the filesystem object, as would be fed to When left unspecified, it uses the current user unless you are root, in which case it can preserve the previous ownership. -Specifying a numeric username will be assumed to be a user ID and not a username. Avoid numeric usernames to avoid this confusion. - |
-
| - | Name of the file in which the generated parameters will be saved. - |
-
| - | If set to Choices: -
|
-
| - | Determines which crypto backend to use. -The default choice is If set to If set to Choices: -
|
-
| - | The level part of the SELinux filesystem object context. -This is the MLS/MCS attribute, sometimes known as the When set to |
-
| - | The role part of the SELinux filesystem object context. -When set to |
-
| - | The type part of the SELinux filesystem object context. -When set to |
-
| - | The user part of the SELinux filesystem object context. -By default it uses the When set to |
-
| - | Size (in bits) of the generated DH-params. -Default: |
-
| - | Whether the parameters should exist or not, taking action if the state is different from what is stated. -Choices: -
|
-
| - | Influence when to use atomic operation to prevent data corruption or inconsistent reads from the target filesystem object. -By default this module uses atomic operations to prevent data corruption or inconsistent reads from the target filesystem objects, but sometimes systems are configured or just broken in ways that prevent this. One example is docker mounted filesystem objects, which cannot be updated atomically from inside the container and can only be written in an unsafe manner. -This option allows Ansible to fall back to unsafe methods of updating filesystem objects when atomic operations fail (however, it doesn’t force Ansible to perform unsafe writes). -IMPORTANT! Unsafe writes are subject to race conditions and can lead to data corruption. -Choices: -
|
-
Attribute |
-Support |
-Description |
-
|---|---|---|
| - | Support: full - |
-Can run in |
-
| - | Support: none - |
-Will return details on what has changed (or possibly needs changing in |
-
| - | Support: partial -The module is not idempotent if |
-When run twice in a row outside check mode, with the same arguments, the second invocation indicates no change. -This assumes that the system controlled/queried by the module has not changed in a relevant way. - |
-
| - | Support: full - |
-Uses Ansible’s strict file operation functions to ensure proper permissions and avoid data corruption. - |
-
See also
-Generate and/or check OpenSSL certificates.
-Generate OpenSSL Certificate Signing Request (CSR).
-Generate OpenSSL PKCS#12 archive.
-Generate OpenSSL private keys.
-Generate an OpenSSL public key from its private key.
----
-- name: Generate Diffie-Hellman parameters with the default size (4096 bits)
- community.crypto.openssl_dhparam:
- path: /etc/ssl/dhparams.pem
-
-- name: Generate DH Parameters with a different size (2048 bits)
- community.crypto.openssl_dhparam:
- path: /etc/ssl/dhparams.pem
- size: 2048
-
-- name: Force regenerate an DH parameters if they already exist
- community.crypto.openssl_dhparam:
- path: /etc/ssl/dhparams.pem
- force: true
-Common return values are documented here, the following are the fields unique to this module:
-Key |
-Description |
-
|---|---|
| - | Name of backup file created. -Returned: changed and if Sample: |
-
| - | The (current or generated) DH params’ content. -Returned: if |
-
| - | Path to the generated Diffie-Hellman parameters. -Returned: changed or success -Sample: |
-
| - | Size (in bits) of the Diffie-Hellman parameters. -Returned: changed or success -Sample: |
-
- Note
-This module is part of the community.crypto collection (version 2.26.6).
-It is not included in ansible-core.
-To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install community.crypto.
-You need further requirements to be able to use this module,
-see Requirements for details.
To use it in a playbook, specify: community.crypto.openssl_pkcs12.
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 iter_size and maciter_size options are used. This can be overridden with the select_crypto_backend option.
The below requirements are needed on the host that executes this module.
-PyOpenSSL >= 0.15, < 23.3.0 or cryptography >= 3.0
Parameter |
-Comments |
-
|---|---|
| - |
Choices: -
|
-
| - | The attributes the resulting filesystem object should have. -To get supported flags look at the man page for This string should contain the attributes in the same order as the one displayed by The |
-
| - | 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. -Choices: -
|
-
| - | Content of the certificate file in PEM format. -Mutually exclusive with |
-
| - | The path to read certificates and private keys from. -Must be in PEM format. -Mutually exclusive with |
-
| - | Determines the encryption level used. -
Note that this option is not used for idempotency. -Choices: -
|
-
| - | Should the file be regenerated even if it already exists. -Choices: -
|
-
| - | Specifies the friendly name for the certificate and private key. - |
-
| - | Name of the group that should own the filesystem object, as would be fed to When left unspecified, it uses the current group of the current user unless you are root, in which case it can preserve the previous ownership. - |
-
| - | Number of times to repeat the encryption step. -This is not considered during idempotency checks. -This is only used by the When using it, the default is |
-
| - | Number of times to repeat the MAC step. -This is not considered during idempotency checks. -This is only used by the |
-
| - | The permissions the resulting filesystem object should have. -For those used to Giving Ansible a number without following either of these rules will end up with a decimal number which will have unexpected results. -As of Ansible 1.8, the mode may be specified as a symbolic mode (for example, If If Specifying |
-
| - | List of other certificates to include. Pre Ansible 2.8 this parameter was called Assumes there is one PEM-encoded certificate per file. If a file contains multiple PEM certificates, set Mutually exclusive with |
-
| - | List of other certificates to include. -Assumes there is one PEM-encoded certificate per item. If an item contains multiple PEM certificates, set Mutually exclusive with |
-
| - | If set to Choices: -
|
-
| - | Name of the user that should own the filesystem object, as would be fed to When left unspecified, it uses the current user unless you are root, in which case it can preserve the previous ownership. -Specifying a numeric username will be assumed to be a user ID and not a username. Avoid numeric usernames to avoid this confusion. - |
-
| - | The PKCS#12 password. -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. (Source). - |
-
| - | Filename to write the PKCS#12 file to. - |
-
| - | Content of the private key file. -Mutually exclusive with |
-
| - | Passphrase source to decrypt any input private keys with. - |
-
| - | File to read private key from. -Mutually exclusive with |
-
| - | If set to Choices: -
|
-
| - | Determines which crypto backend to use. -The default choice is If set to If set to Note that the Choices: -
|
-
| - | The level part of the SELinux filesystem object context. -This is the MLS/MCS attribute, sometimes known as the When set to |
-
| - | The role part of the SELinux filesystem object context. -When set to |
-
| - | The type part of the SELinux filesystem object context. -When set to |
-
| - | The user part of the SELinux filesystem object context. -By default it uses the When set to |
-
| - | PKCS#12 file path to parse. - |
-
| - | Whether the file should exist or not. All parameters except Choices: -
|
-
| - | Influence when to use atomic operation to prevent data corruption or inconsistent reads from the target filesystem object. -By default this module uses atomic operations to prevent data corruption or inconsistent reads from the target filesystem objects, but sometimes systems are configured or just broken in ways that prevent this. One example is docker mounted filesystem objects, which cannot be updated atomically from inside the container and can only be written in an unsafe manner. -This option allows Ansible to fall back to unsafe methods of updating filesystem objects when atomic operations fail (however, it doesn’t force Ansible to perform unsafe writes). -IMPORTANT! Unsafe writes are subject to race conditions and can lead to data corruption. -Choices: -
|
-
Attribute |
-Support |
-Description |
-
|---|---|---|
| - | Support: full - |
-Can run in |
-
| - | Support: none - |
-Will return details on what has changed (or possibly needs changing in |
-
| - | Support: partial -The module is not idempotent if |
-When run twice in a row outside check mode, with the same arguments, the second invocation indicates no change. -This assumes that the system controlled/queried by the module has not changed in a relevant way. - |
-
| - | Support: full - |
-Uses Ansible’s strict file operation functions to ensure proper permissions and avoid data corruption. - |
-
See also
-Generate and/or check OpenSSL certificates.
-Generate OpenSSL Certificate Signing Request (CSR).
-Generate OpenSSL Diffie-Hellman Parameters.
-Generate OpenSSL private keys.
-Generate an OpenSSL public key from its private key.
----
-- name: Generate PKCS#12 file
- community.crypto.openssl_pkcs12:
- action: export
- path: /opt/certs/ansible.p12
- friendly_name: raclette
- 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.
- state: present
-
-- name: Generate PKCS#12 file
- community.crypto.openssl_pkcs12:
- action: export
- path: /opt/certs/ansible.p12
- friendly_name: raclette
- privatekey_content: '{{ private_key_contents }}'
- certificate_path: /opt/certs/cert.pem
- 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.
- - /opt/certs/intermediate.pem
- # In case this file has multiple certificates in it,
- # all will be included as well.
- state: present
-
-- name: Change PKCS#12 file permission
- community.crypto.openssl_pkcs12:
- action: export
- path: /opt/certs/ansible.p12
- friendly_name: raclette
- privatekey_path: /opt/certs/keys/key.pem
- certificate_path: /opt/certs/cert.pem
- other_certificates: /opt/certs/ca.pem
- state: present
- mode: '0600'
-
-- name: Regen PKCS#12 file
- community.crypto.openssl_pkcs12:
- action: export
- src: /opt/certs/ansible.p12
- path: /opt/certs/ansible.p12
- friendly_name: raclette
- privatekey_path: /opt/certs/keys/key.pem
- certificate_path: /opt/certs/cert.pem
- other_certificates: /opt/certs/ca.pem
- state: present
- mode: '0600'
- force: true
-
-- name: Dump/Parse PKCS#12 file
- community.crypto.openssl_pkcs12:
- action: parse
- src: /opt/certs/ansible.p12
- path: /opt/certs/ansible.pem
- state: present
-
-- name: Remove PKCS#12 file
- community.crypto.openssl_pkcs12:
- path: /opt/certs/ansible.p12
- state: absent
-Common return values are documented here, the following are the fields unique to this module:
-Key |
-Description |
-
|---|---|
| - | Name of backup file created. -Returned: changed and if Sample: |
-
| - | Path to the generate PKCS#12 file. -Returned: changed or success -Sample: |
-
| - | The (current or generated) PKCS#12’s content Base64 encoded. -Returned: if |
-
| - | Path to the TLS/SSL private key the public key was generated from. -Returned: changed or success -Sample: |
-
- Note
-This module is part of the community.crypto collection (version 2.26.6).
-It is not included in ansible-core.
-To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install community.crypto.
-You need further requirements to be able to use this module,
-see Requirements for details.
To use it in a playbook, specify: community.crypto.openssl_privatekey_convert.
New in community.crypto 2.1.0
- -This module allows one to convert OpenSSL private keys.
The default mode for the private key file will be 0600 if mode is not explicitly set.
The below requirements are needed on the host that executes this module.
-cryptography >= 1.2.3 (older versions might work as well)
Parameter |
-Comments |
-
|---|---|
| - | The attributes the resulting filesystem object should have. -To get supported flags look at the man page for This string should contain the attributes in the same order as the one displayed by The |
-
| - | 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. -Choices: -
|
-
| - | The passphrase for the private key to store. - |
-
| - | Name of the file in which the generated TLS/SSL private key will be written. It will have |
-
| - | 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. -Choices: -
|
-
| - | Name of the group that should own the filesystem object, as would be fed to When left unspecified, it uses the current group of the current user unless you are root, in which case it can preserve the previous ownership. - |
-
| - | The permissions the resulting filesystem object should have. -For those used to Giving Ansible a number without following either of these rules will end up with a decimal number which will have unexpected results. -As of Ansible 1.8, the mode may be specified as a symbolic mode (for example, If If Specifying |
-
| - | Name of the user that should own the filesystem object, as would be fed to When left unspecified, it uses the current user unless you are root, in which case it can preserve the previous ownership. -Specifying a numeric username will be assumed to be a user ID and not a username. Avoid numeric usernames to avoid this confusion. - |
-
| - | The level part of the SELinux filesystem object context. -This is the MLS/MCS attribute, sometimes known as the When set to |
-
| - | The role part of the SELinux filesystem object context. -When set to |
-
| - | The type part of the SELinux filesystem object context. -When set to |
-
| - | The user part of the SELinux filesystem object context. -By default it uses the When set to |
-
| - | The content of the file containing the OpenSSL private key to convert. -Exactly one of |
-
| - | The passphrase for the private key to load. - |
-
| - | Name of the file containing the OpenSSL private key to convert. -Exactly one of |
-
| - | Influence when to use atomic operation to prevent data corruption or inconsistent reads from the target filesystem object. -By default this module uses atomic operations to prevent data corruption or inconsistent reads from the target filesystem objects, but sometimes systems are configured or just broken in ways that prevent this. One example is docker mounted filesystem objects, which cannot be updated atomically from inside the container and can only be written in an unsafe manner. -This option allows Ansible to fall back to unsafe methods of updating filesystem objects when atomic operations fail (however, it doesn’t force Ansible to perform unsafe writes). -IMPORTANT! Unsafe writes are subject to race conditions and can lead to data corruption. -Choices: -
|
-
Attribute |
-Support |
-Description |
-
|---|---|---|
| - | Support: full - |
-Can run in |
-
| - | Support: none - |
-Will return details on what has changed (or possibly needs changing in |
-
| - | Support: full - |
-When run twice in a row outside check mode, with the same arguments, the second invocation indicates no change. -This assumes that the system controlled/queried by the module has not changed in a relevant way. - |
-
| - | Support: full - |
-Uses Ansible’s strict file operation functions to ensure proper permissions and avoid data corruption. - |
-
See also
-Generate OpenSSL private keys.
-Generate OpenSSL private keys without disk access.
-Generate an OpenSSL public key from its private key.
----
-- 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
-Common return values are documented here, the following are the fields unique to this module:
-Key |
-Description |
-
|---|---|
| - | Name of backup file created. -Returned: changed and if Sample: |
-
- Note
-This filter plugin is part of the community.crypto collection (version 2.26.6).
-It is not included in ansible-core.
-To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install community.crypto.
-You need further requirements to be able to use this filter plugin,
-see Requirements for details.
To use it in a playbook, specify: community.crypto.openssl_privatekey_info.
New in community.crypto 2.10.0
- -Provided an OpenSSL private keys, retrieve information.
This is a filter version of the community.crypto.openssl_privatekey_info module.
The below requirements are needed on the local controller node that executes this filter.
-If name_encoding is set to another value than ignore, the idna Python library needs to be installed.
This describes the input of the filter, the value before | community.crypto.openssl_privatekey_info.
Parameter |
-Comments |
-
|---|---|
| - | The content of the OpenSSL private key. - |
-
This describes keyword parameters of the filter. These are the values key1=value1, key2=value2 and so on in the following
-example: input | community.crypto.openssl_privatekey_info(key1=value1, key2=value2, ...)
Parameter |
-Comments |
-
|---|---|
| - | How to encode names (DNS names, URIs, email addresses) in return values. -
Note that Choices: -
|
-
| - | The passphrase for the private key. - |
-
| - | Whether to return private key data. -Only set this to WARNING: you have to make sure that private key data is not accidentally logged! -Choices: -
|
-
See also
-Provide information for OpenSSL private keys.
----
-- name: Show the Subject Alt Names of the CSR
- ansible.builtin.debug:
- msg: >-
- {{
- (
- lookup('ansible.builtin.file', '/path/to/cert.csr')
- | community.crypto.openssl_privatekey_info
- ).subject_alt_name | join(', ')
- }}
-Key |
-Description |
-
|---|---|
| - | Information on the certificate. -Returned: success - |
-
| - | Private key data. Depends on key type. -Returned: success and when |
-
| - | Public key data. Depends on key type. -Returned: success - |
-
| - | The curve’s name for ECC. -Returned: When |
-
| - | The RSA key’s public exponent. -Returned: When |
-
| - | The maximum number of bits of a private key. This is basically the bit size of the subgroup used. -Returned: When |
-
| - | The This is the element spanning the subgroup of the multiplicative group of the prime field used. -Returned: When |
-
| - | The RSA key’s modulus. -Returned: When |
-
| - | The This is the prime modulus upon which arithmetic takes place. -Returned: When |
-
| - | The This is a prime that divides Returned: When |
-
| - | Bit size of modulus (RSA) or prime number (DSA). -Returned: When |
-
| - | The Returned: When |
-
| - | For For Returned: When |
-
| - | Private key’s public key in PEM format. -Returned: success -Sample: |
-
| - | Fingerprints of private key’s public key. -For every hash algorithm available, the fingerprint is computed. -Returned: success -Sample: |
-
| - | The key’s type. -One of Will start with Returned: success -Sample: |
-
- Note
-This module is part of the community.crypto collection (version 2.26.6).
-It is not included in ansible-core.
-To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install community.crypto.
-You need further requirements to be able to use this module,
-see Requirements for details.
To use it in a playbook, specify: community.crypto.openssl_privatekey_info.
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, none is returned for key_is_consistent.
It uses the cryptography python library to interact with OpenSSL.
The below requirements are needed on the host that executes this module.
-cryptography >= 1.2.3
Parameter |
-Comments |
-
|---|---|
| - | 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 side-channel attacks. -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. -Choices: -
|
-
| - | - |
| - | The passphrase for the private key. - |
-
| - | Remote absolute path where the private key file is loaded from. - |
-
| - | Whether to return private key data. -Only set this to WARNING: you have to make sure that private key data is not accidentally logged! -Choices: -
|
-
| - | Determines which crypto backend to use. -The default choice is If set to Choices: -
|
-
Attribute |
-Support |
-Description |
-
|---|---|---|
| - | Support: full -This action does not modify state. - |
-Can run in |
-
| - | Support: N/A -This action does not modify state. - |
-Will return details on what has changed (or possibly needs changing in |
-
| - | Support: full -This action does not modify state. - |
-When run twice in a row outside check mode, with the same arguments, the second invocation indicates no change. -This assumes that the system controlled/queried by the module has not changed in a relevant way. - |
-
See also
-Generate OpenSSL private keys.
-Generate OpenSSL private keys without disk access.
-A filter variant of this module.
----
-- name: Generate an OpenSSL private key with the default values (4096 bits, RSA)
- community.crypto.openssl_privatekey:
- path: /etc/ssl/private/ansible.com.pem
-
-- name: Get information on generated key
- community.crypto.openssl_privatekey_info:
- path: /etc/ssl/private/ansible.com.pem
- register: result
-
-- name: Dump information
- ansible.builtin.debug:
- var: result
-Common return values are documented here, the following are the fields unique to this module:
-Key |
-Description |
-
|---|---|
| - | Whether the module was able to load the private key from disk. -Returned: always - |
-
| - | Whether the module was able to parse the private key. -Returned: always - |
-
| - | Whether the key is consistent. Can also return In case the check returns Returned: when |
-
| - | Private key data. Depends on key type. -Returned: success and when |
-
| - | Public key data. Depends on key type. -Returned: success - |
-
| - | The curve’s name for ECC. -Returned: When |
-
| - | The RSA key’s public exponent. -Returned: When |
-
| - | The maximum number of bits of a private key. This is basically the bit size of the subgroup used. -Returned: When |
-
| - | The This is the element spanning the subgroup of the multiplicative group of the prime field used. -Returned: When |
-
| - | The RSA key’s modulus. -Returned: When |
-
| - | The This is the prime modulus upon which arithmetic takes place. -Returned: When |
-
| - | The This is a prime that divides Returned: When |
-
| - | - |
| - | The Returned: When |
-
| - | - |
| - | Private key’s public key in PEM format. -Returned: success -Sample: |
-
| - | Fingerprints of private key’s public key. -For every hash algorithm available, the fingerprint is computed. -Returned: success -Sample: |
-
| - | The key’s type. -One of Will start with Returned: success -Sample: |
-
- Note
-This module is part of the community.crypto collection (version 2.26.6).
-It is not included in ansible-core.
-To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install community.crypto.
-You need further requirements to be able to use this module,
-see Requirements for details.
To use it in a playbook, specify: community.crypto.openssl_privatekey.
Keys are generated in PEM format.
Please note that the module regenerates private keys if they do not match the module’s options. In particular, if you provide another passphrase (or specify none), change the keysize, and so on, the private key will be regenerated. If you are concerned that this could overwrite your private key, consider using the backup option.
The default mode for the private key file will be 0600 if mode is not explicitly set.
This module allows one to (re)generate OpenSSL private keys.
The below requirements are needed on the host that executes this module.
-cryptography >= 1.2.3 (older versions might work as well)
Parameter |
-Comments |
-
|---|---|
| - | The attributes the resulting filesystem object should have. -To get supported flags look at the man page for This string should contain the attributes in the same order as the one displayed by The |
-
| - | 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. -Choices: -
|
-
| - | The cipher to encrypt the private key. This is only used when Must be Default: |
-
| - | Note that not all curves are supported by all versions of For maximal interoperability, We use the curve names as defined in the IANA registry for TLS. -Please note that all curves except Choices: -
|
-
| - | Should the key be regenerated even if it already exists. -Choices: -
|
-
| - | 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 Note that if the format for an existing private key mismatches, the key is regenerated by default. To change this behavior, use the Choices: -
|
-
| - | 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 If set to Only supported by the Choices: -
|
-
| - | Name of the group that should own the filesystem object, as would be fed to When left unspecified, it uses the current group of the current user unless you are root, in which case it can preserve the previous ownership. - |
-
| - | The permissions the resulting filesystem object should have. -For those used to Giving Ansible a number without following either of these rules will end up with a decimal number which will have unexpected results. -As of Ansible 1.8, the mode may be specified as a symbolic mode (for example, If If Specifying |
-
| - | Name of the user that should own the filesystem object, as would be fed to When left unspecified, it uses the current user unless you are root, in which case it can preserve the previous ownership. -Specifying a numeric username will be assumed to be a user ID and not a username. Avoid numeric usernames to avoid this confusion. - |
-
| - | The passphrase for the private key. - |
-
| - | Name of the file in which the generated TLS/SSL private key will be written. It will have |
-
| - | 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 changed for Ansible 2.10. For Ansible 2.9, the behavior was as if If set to If set to If set to If set to If set to Note that if Choices: -
|
-
| - | If set to 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, and so on! Use with care! -Use Ansible’s Choices: -
|
-
| - | Determines which crypto backend to use. -The default choice is If set to Choices: -
|
-
| - | The level part of the SELinux filesystem object context. -This is the MLS/MCS attribute, sometimes known as the When set to |
-
| - | The role part of the SELinux filesystem object context. -When set to |
-
| - | The type part of the SELinux filesystem object context. -When set to |
-
| - | The user part of the SELinux filesystem object context. -By default it uses the When set to |
-
| - | Size (in bits) of the TLS/SSL key to generate. -Default: |
-
| - | Whether the private key should exist or not, taking action if the state is different from what is stated. -Choices: -
|
-
| - | The algorithm used to generate the TLS/SSL private key. -Note that Choices: -
|
-
| - | Influence when to use atomic operation to prevent data corruption or inconsistent reads from the target filesystem object. -By default this module uses atomic operations to prevent data corruption or inconsistent reads from the target filesystem objects, but sometimes systems are configured or just broken in ways that prevent this. One example is docker mounted filesystem objects, which cannot be updated atomically from inside the container and can only be written in an unsafe manner. -This option allows Ansible to fall back to unsafe methods of updating filesystem objects when atomic operations fail (however, it doesn’t force Ansible to perform unsafe writes). -IMPORTANT! Unsafe writes are subject to race conditions and can lead to data corruption. -Choices: -
|
-
Attribute |
-Support |
-Description |
-
|---|---|---|
| - | Support: full - |
-Can run in |
-
| - | Support: full - |
-Will return details on what has changed (or possibly needs changing in |
-
| - | Support: partial -The option |
-When run twice in a row outside check mode, with the same arguments, the second invocation indicates no change. -This assumes that the system controlled/queried by the module has not changed in a relevant way. - |
-
| - | Support: full - |
-Uses Ansible’s strict file operation functions to ensure proper permissions and avoid data corruption. - |
-
See also
-Generate OpenSSL private keys without disk access.
-Provide information for OpenSSL private keys.
-Generate and/or check OpenSSL certificates.
-Generate and/or check OpenSSL certificates.
-Generate OpenSSL Certificate Signing Request (CSR).
-Generate OpenSSL Certificate Signing Request (CSR).
-Generate OpenSSL Diffie-Hellman Parameters.
-Generate OpenSSL PKCS#12 archive.
-Generate an OpenSSL public key from its private key.
----
-- name: Generate an OpenSSL private key with the default values (4096 bits, RSA)
- community.crypto.openssl_privatekey:
- path: /etc/ssl/private/ansible.com.pem
-
-- name: Generate an OpenSSL private key with the default values (4096 bits, RSA) and a passphrase
- community.crypto.openssl_privatekey:
- path: /etc/ssl/private/ansible.com.pem
- passphrase: ansible
- cipher: auto
-
-- name: Generate an OpenSSL private key with a different size (2048 bits)
- community.crypto.openssl_privatekey:
- path: /etc/ssl/private/ansible.com.pem
- size: 2048
-
-- name: Force regenerate an OpenSSL private key if it already exists
- community.crypto.openssl_privatekey:
- path: /etc/ssl/private/ansible.com.pem
- force: true
-
-- name: Generate an OpenSSL private key with a different algorithm (DSA)
- community.crypto.openssl_privatekey:
- path: /etc/ssl/private/ansible.com.pem
- type: DSA
-
-- name: Generate an OpenSSL private key with elliptic curve cryptography (ECC)
- community.crypto.openssl_privatekey:
- path: /etc/ssl/private/ansible.com.pem
- type: ECC
- curve: secp256r1
-Common return values are documented here, the following are the fields unique to this module:
-Key |
-Description |
-
|---|---|
| - | Name of backup file created. -Returned: changed and if Sample: |
-
| - | Elliptic curve used to generate the TLS/SSL private key. -Returned: changed or success, and Sample: |
-
| - | Path to the generated TLS/SSL private key file. -Returned: changed or success -Sample: |
-
| - | The fingerprint of the public key. Fingerprint will be generated for each Returned: changed or success -Sample: |
-
| - | The (current or generated) private key’s content. -Will be Base64-encoded if the key is in raw format. -Returned: if |
-
| - | Size (in bits) of the TLS/SSL private key. -Returned: changed or success -Sample: |
-
| - | Algorithm used to generate the TLS/SSL private key. -Returned: changed or success -Sample: |
-
- Note
-This module is part of the community.crypto collection (version 2.26.6).
-It is not included in ansible-core.
-To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install community.crypto.
-You need further requirements to be able to use this module,
-see Requirements for details.
To use it in a playbook, specify: community.crypto.openssl_privatekey_pipe.
New in community.crypto 1.3.0
- -Keys are generated in PEM format.
Make sure to not write the result of this module into logs or to the console, as it contains private key data! Use the no_log task option to be sure.
Note that this module is implemented as an action plugin and will always be executed on the controller.
This allows to read and write keys to vaults without having to write intermediate versions to disk.
This module allows one to (re)generate OpenSSL private keys without disk access.
Note
-This module has a corresponding action plugin.
-The below requirements are needed on the host that executes this module.
-cryptography >= 1.2.3 (older versions might work as well)
Parameter |
-Comments |
-
|---|---|
| - | The cipher to encrypt the private key. This is only used when Must be Default: |
-
| - | 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. - |
-
| - | Set to Choices: -
|
-
| - | Note that not all curves are supported by all versions of For maximal interoperability, We use the curve names as defined in the IANA registry for TLS. -Please note that all curves except Choices: -
|
-
| - | 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 Note that if the format for an existing private key mismatches, the key is regenerated by default. To change this behavior, use the Choices: -
|
-
| - | 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 If set to Only supported by the Choices: -
|
-
| - | The passphrase for the private key. - |
-
| - | 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 changed for Ansible 2.10. For Ansible 2.9, the behavior was as if If set to If set to If set to If set to If set to Note that if Choices: -
|
-
| - | Set to Note that in case of check mode, when this option is not set to Choices: -
|
-
| - | Determines which crypto backend to use. -The default choice is If set to Choices: -
|
-
| - | Size (in bits) of the TLS/SSL key to generate. -Default: |
-
| - | The algorithm used to generate the TLS/SSL private key. -Note that Choices: -
|
-
Attribute |
-Support |
-Description |
-
|---|---|---|
| - | Support: full - |
-Indicates this has a corresponding action plugin so some parts of the options can be executed on the controller. - |
-
| - | Support: none -This action runs completely on the controller. - |
-Supports being used with the |
-
| - | Support: full -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. - |
-Can run in |
-
| - | Support: full - |
-Will return details on what has changed (or possibly needs changing in |
-
| - | Support: partial -The option |
-When run twice in a row outside check mode, with the same arguments, the second invocation indicates no change. -This assumes that the system controlled/queried by the module has not changed in a relevant way. - |
-
See also
-Generate OpenSSL private keys.
-Provide information for OpenSSL private keys.
-Generate and/or check OpenSSL certificates.
-Generate and/or check OpenSSL certificates.
-Generate OpenSSL Certificate Signing Request (CSR).
-Generate OpenSSL Certificate Signing Request (CSR).
-Generate OpenSSL Diffie-Hellman Parameters.
-Generate OpenSSL PKCS#12 archive.
-Generate an OpenSSL public key from its private key.
----
-- 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!
-- name: Show generated key
- ansible.builtin.debug:
- msg: "{{ output.privatekey }}"
- # DO NOT OUTPUT KEY MATERIAL TO CONSOLE OR LOGS IN PRODUCTION!
-
-
-# The following example needs CNCF SOPS (https://github.com/getsops/sops) set up and
-# the community.sops collection installed. See also
-# https://docs.ansible.com/ansible/latest/collections/community/sops/docsite/guide.html
-
-- name: Generate or update a CNCF SOPS encrypted key
- block:
- - name: Update SOPS-encrypted key with the community.sops collection
- community.crypto.openssl_privatekey_pipe:
- 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!
-
- - name: Update encrypted key when openssl_privatekey_pipe reported a change
- community.sops.sops_encrypt:
- path: private_key.pem.sops
- content_text: "{{ output.privatekey }}"
- when: output is changed
- always:
- - name: Make sure that output (which contains the private key) is overwritten
- ansible.builtin.set_fact:
- output: ''
-Common return values are documented here, the following are the fields unique to this module:
-Key |
-Description |
-
|---|---|
| - | Elliptic curve used to generate the TLS/SSL private key. -Returned: changed or success, and Sample: |
-
| - | The fingerprint of the public key. Fingerprint will be generated for each Returned: changed or success -Sample: |
-
| - | 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 Will be Base64-encoded if the key is in raw format. -Returned: changed, or |
-
| - | Size (in bits) of the TLS/SSL private key. -Returned: changed or success -Sample: |
-
| - | Algorithm used to generate the TLS/SSL private key. -Returned: changed or success -Sample: |
-
- Note
-This filter plugin is part of the community.crypto collection (version 2.26.6).
-It is not included in ansible-core.
-To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install community.crypto.
To use it in a playbook, specify: community.crypto.openssl_publickey_info.
New in community.crypto 2.10.0
- -Provided a public key in OpenSSL PEM format, retrieve information.
This is a filter version of the community.crypto.openssl_publickey_info module.
This describes the input of the filter, the value before | community.crypto.openssl_publickey_info.
Parameter |
-Comments |
-
|---|---|
| - | The content of the OpenSSL PEM public key. - |
-
See also
-Provide information for OpenSSL public keys.
----
-- name: Show the type of a public key
- ansible.builtin.debug:
- msg: >-
- {{
- (
- lookup('ansible.builtin.file', '/path/to/public-key.pem')
- | community.crypto.openssl_publickey_info
- ).type
- }}
-Key |
-Description |
-
|---|---|
| - | Information on the public key. -Returned: success - |
-
| - | Fingerprints of public key. -For every hash algorithm available, the fingerprint is computed. -Returned: success -Sample: |
-
| - | Public key data. Depends on key type. -Returned: success - |
-
| - | The curve’s name for ECC. -Returned: When |
-
| - | The RSA key’s public exponent. -Returned: When |
-
| - | The maximum number of bits of a private key. This is basically the bit size of the subgroup used. -Returned: When |
-
| - | The This is the element spanning the subgroup of the multiplicative group of the prime field used. -Returned: When |
-
| - | The RSA key’s modulus. -Returned: When |
-
| - | The This is the prime modulus upon which arithmetic takes place. -Returned: When |
-
| - | The This is a prime that divides Returned: When |
-
| - | Bit size of modulus (RSA) or prime number (DSA). -Returned: When |
-
| - | The Returned: When |
-
| - | For For Returned: When |
-
| - | The key’s type. -One of Will start with Returned: success -Sample: |
-
- Note
-This module is part of the community.crypto collection (version 2.26.6).
-It is not included in ansible-core.
-To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install community.crypto.
-You need further requirements to be able to use this module,
-see Requirements for details.
To use it in a playbook, specify: community.crypto.openssl_publickey_info.
New in community.crypto 1.7.0
- -This module allows one to query information on OpenSSL public keys.
It uses the cryptography python library to interact with OpenSSL.
The below requirements are needed on the host that executes this module.
-cryptography >= 1.2.3
Parameter |
-Comments |
-
|---|---|
| - | - |
| - | Remote absolute path where the public key file is loaded from. - |
-
| - | Determines which crypto backend to use. -The default choice is If set to Choices: -
|
-
Attribute |
-Support |
-Description |
-
|---|---|---|
| - | Support: full -This action does not modify state. - |
-Can run in |
-
| - | Support: N/A -This action does not modify state. - |
-Will return details on what has changed (or possibly needs changing in |
-
| - | Support: full -This action does not modify state. - |
-When run twice in a row outside check mode, with the same arguments, the second invocation indicates no change. -This assumes that the system controlled/queried by the module has not changed in a relevant way. - |
-
See also
-Generate an OpenSSL public key from its private key.
-Provide information for OpenSSL private keys.
-A filter variant of this module.
----
-- name: Generate an OpenSSL private key with the default values (4096 bits, RSA)
- community.crypto.openssl_privatekey:
- path: /etc/ssl/private/ansible.com.pem
-
-- name: Create public key from private key
- community.crypto.openssl_publickey:
- privatekey_path: /etc/ssl/private/ansible.com.pem
- path: /etc/ssl/ansible.com.pub
-
-- name: Get information on public key
- community.crypto.openssl_publickey_info:
- path: /etc/ssl/ansible.com.pub
- register: result
-
-- name: Dump information
- ansible.builtin.debug:
- var: result
-Common return values are documented here, the following are the fields unique to this module:
-Key |
-Description |
-
|---|---|
| - | Fingerprints of public key. -For every hash algorithm available, the fingerprint is computed. -Returned: success -Sample: |
-
| - | Public key data. Depends on key type. -Returned: success - |
-
| - | The curve’s name for ECC. -Returned: When |
-
| - | The RSA key’s public exponent. -Returned: When |
-
| - | The maximum number of bits of a private key. This is basically the bit size of the subgroup used. -Returned: When |
-
| - | The This is the element spanning the subgroup of the multiplicative group of the prime field used. -Returned: When |
-
| - | The RSA key’s modulus. -Returned: When |
-
| - | The This is the prime modulus upon which arithmetic takes place. -Returned: When |
-
| - | The This is a prime that divides Returned: When |
-
| - | - |
| - | The Returned: When |
-
| - | - |
| - | The key’s type. -One of Will start with Returned: success -Sample: |
-
- Note
-This module is part of the community.crypto collection (version 2.26.6).
-It is not included in ansible-core.
-To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install community.crypto.
-You need further requirements to be able to use this module,
-see Requirements for details.
To use it in a playbook, specify: community.crypto.openssl_publickey.
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. OpenSSH private keys are not supported, use the community.crypto.openssh_keypair module to manage these.
The module uses the cryptography Python library.
The below requirements are needed on the host that executes this module.
-cryptography >= 1.2.3 (older versions might work as well)
Needs cryptography >= 1.4 if format is OpenSSH
Parameter |
-Comments |
-
|---|---|
| - | The attributes the resulting filesystem object should have. -To get supported flags look at the man page for This string should contain the attributes in the same order as the one displayed by The |
-
| - | 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. -Choices: -
|
-
| - | Should the key be regenerated even it it already exists. -Choices: -
|
-
| - | The format of the public key. -Choices: -
|
-
| - | Name of the group that should own the filesystem object, as would be fed to When left unspecified, it uses the current group of the current user unless you are root, in which case it can preserve the previous ownership. - |
-
| - | The permissions the resulting filesystem object should have. -For those used to Giving Ansible a number without following either of these rules will end up with a decimal number which will have unexpected results. -As of Ansible 1.8, the mode may be specified as a symbolic mode (for example, If If Specifying |
-
| - | Name of the user that should own the filesystem object, as would be fed to When left unspecified, it uses the current user unless you are root, in which case it can preserve the previous ownership. -Specifying a numeric username will be assumed to be a user ID and not a username. Avoid numeric usernames to avoid this confusion. - |
-
| - | Name of the file in which the generated TLS/SSL public key will be written. - |
-
| - | The content of the TLS/SSL private key from which to generate the public key. -Either |
-
| - | The passphrase for the private key. - |
-
| - | Path to the TLS/SSL private key from which to generate the public key. -Either |
-
| - | If set to Choices: -
|
-
| - | Determines which crypto backend to use. -The default choice is If set to Choices: -
|
-
| - | The level part of the SELinux filesystem object context. -This is the MLS/MCS attribute, sometimes known as the When set to |
-
| - | The role part of the SELinux filesystem object context. -When set to |
-
| - | The type part of the SELinux filesystem object context. -When set to |
-
| - | The user part of the SELinux filesystem object context. -By default it uses the When set to |
-
| - | Whether the public key should exist or not, taking action if the state is different from what is stated. -Choices: -
|
-
| - | Influence when to use atomic operation to prevent data corruption or inconsistent reads from the target filesystem object. -By default this module uses atomic operations to prevent data corruption or inconsistent reads from the target filesystem objects, but sometimes systems are configured or just broken in ways that prevent this. One example is docker mounted filesystem objects, which cannot be updated atomically from inside the container and can only be written in an unsafe manner. -This option allows Ansible to fall back to unsafe methods of updating filesystem objects when atomic operations fail (however, it doesn’t force Ansible to perform unsafe writes). -IMPORTANT! Unsafe writes are subject to race conditions and can lead to data corruption. -Choices: -
|
-
Attribute |
-Support |
-Description |
-
|---|---|---|
| - | Support: full - |
-Can run in |
-
| - | Support: full - |
-Will return details on what has changed (or possibly needs changing in |
-
| - | Support: partial -The module is not idempotent if |
-When run twice in a row outside check mode, with the same arguments, the second invocation indicates no change. -This assumes that the system controlled/queried by the module has not changed in a relevant way. - |
-
| - | Support: full - |
-Uses Ansible’s strict file operation functions to ensure proper permissions and avoid data corruption. - |
-
See also
-Generate and/or check OpenSSL certificates.
-Generate and/or check OpenSSL certificates.
-Generate OpenSSL Certificate Signing Request (CSR).
-Generate OpenSSL Certificate Signing Request (CSR).
-Generate OpenSSL Diffie-Hellman Parameters.
-Generate OpenSSL PKCS#12 archive.
-Generate OpenSSL private keys.
-Generate OpenSSL private keys without disk access.
----
-- name: Generate an OpenSSL public key in PEM format
- community.crypto.openssl_publickey:
- path: /etc/ssl/public/ansible.com.pem
- privatekey_path: /etc/ssl/private/ansible.com.pem
-
-- name: Generate an OpenSSL public key in PEM format from an inline key
- community.crypto.openssl_publickey:
- path: /etc/ssl/public/ansible.com.pem
- privatekey_content: "{{ private_key_content }}"
-
-- name: Generate an OpenSSL public key in OpenSSH v2 format
- community.crypto.openssl_publickey:
- path: /etc/ssl/public/ansible.com.pem
- privatekey_path: /etc/ssl/private/ansible.com.pem
- format: OpenSSH
-
-- name: Generate an OpenSSL public key with a passphrase protected private key
- community.crypto.openssl_publickey:
- path: /etc/ssl/public/ansible.com.pem
- privatekey_path: /etc/ssl/private/ansible.com.pem
- privatekey_passphrase: ansible
-
-- name: Force regenerate an OpenSSL public key if it already exists
- community.crypto.openssl_publickey:
- path: /etc/ssl/public/ansible.com.pem
- privatekey_path: /etc/ssl/private/ansible.com.pem
- force: true
-
-- name: Remove an OpenSSL public key
- community.crypto.openssl_publickey:
- path: /etc/ssl/public/ansible.com.pem
- state: absent
-Common return values are documented here, the following are the fields unique to this module:
-Key |
-Description |
-
|---|---|
| - | Name of backup file created. -Returned: changed and if Sample: |
-
| - | Path to the generated TLS/SSL public key file. -Returned: changed or success -Sample: |
-
| - | The fingerprint of the public key. Fingerprint will be generated for each hashlib.algorithms available. -Returned: changed or success -Sample: |
-
| - | The format of the public key (PEM, OpenSSH, …). -Returned: changed or success -Sample: |
-
| - | Path to the TLS/SSL private key the public key was generated from. -Will be Returned: changed or success -Sample: |
-
| - | The (current or generated) public key’s content. -Returned: if |
-
- Note
-This module is part of the community.crypto collection (version 2.26.6).
-It is not included in ansible-core.
-To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install community.crypto.
-You need further requirements to be able to use this module,
-see Requirements for details.
To use it in a playbook, specify: community.crypto.openssl_signature_info.
New in community.crypto 1.1.0
- -This module allows one to verify a signature for a file by a certificate.
The module uses the cryptography Python library.
The below requirements are needed on the host that executes this module.
-cryptography >= 1.4 (some key types require newer versions)
Parameter |
-Comments |
-
|---|---|
| - | The content of the certificate used to verify the signature. -Either |
-
| - | The path to the certificate used to verify the signature. -Either |
-
| - | The signed file to verify. -This file will only be read and not modified. - |
-
| - | Determines which crypto backend to use. -The default choice is If set to Choices: -
|
-
| - | Base64 encoded signature. - |
-
Attribute |
-Support |
-Description |
-
|---|---|---|
| - | Support: full -This action does not modify state. - |
-Can run in |
-
| - | Support: N/A -This action does not modify state. - |
-Will return details on what has changed (or possibly needs changing in |
-
| - | Support: full -This action does not modify state. - |
-When run twice in a row outside check mode, with the same arguments, the second invocation indicates no change. -This assumes that the system controlled/queried by the module has not changed in a relevant way. - |
-
Note
-When using the cryptography backend, the following key types require at least the following cryptography version:
-RSA keys: cryptography >= 1.4
-DSA and ECDSA keys: cryptography >= 1.5
-ed448 and ed25519 keys: cryptography >= 2.6.
See also
-Sign data with openssl.
-Generate and/or check OpenSSL certificates.
----
-- name: Sign example file
- community.crypto.openssl_signature:
- privatekey_path: private.key
- path: /tmp/example_file
- register: sig
-
-- name: Verify signature of example file
- community.crypto.openssl_signature_info:
- certificate_path: cert.pem
- path: /tmp/example_file
- signature: "{{ sig.signature }}"
- register: verify
-
-- name: Make sure the signature is valid
- ansible.builtin.assert:
- that:
- - verify.valid
-Common return values are documented here, the following are the fields unique to this module:
-Key |
-Description |
-
|---|---|
| - |
Returned: success - |
-
- Note
-This module is part of the community.crypto collection (version 2.26.6).
-It is not included in ansible-core.
-To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install community.crypto.
-You need further requirements to be able to use this module,
-see Requirements for details.
To use it in a playbook, specify: community.crypto.openssl_signature.
New in community.crypto 1.1.0
- -This module allows one to sign data using a private key.
The module uses the cryptography Python library.
The below requirements are needed on the host that executes this module.
-cryptography >= 1.4 (some key types require newer versions)
Parameter |
-Comments |
-
|---|---|
| - | The file to sign. -This file will only be read and not modified. - |
-
| - | The content of the private key to use when signing the certificate signing request. -Either |
-
| - | The passphrase for the private key. -This is required if the private key is password protected. - |
-
| - | The path to the private key to use when signing. -Either |
-
| - | Determines which crypto backend to use. -The default choice is If set to Choices: -
|
-
Attribute |
-Support |
-Description |
-
|---|---|---|
| - | Support: full -This action does not modify state. - |
-Can run in |
-
| - | Support: none - |
-Will return details on what has changed (or possibly needs changing in |
-
| - | Support: partial -Signature algorithms are generally not deterministic. Thus the generated signature can change from one invocation to the next. - |
-When run twice in a row outside check mode, with the same arguments, the second invocation indicates no change. -This assumes that the system controlled/queried by the module has not changed in a relevant way. - |
-
Note
-When using the cryptography backend, the following key types require at least the following cryptography version:
-RSA keys: cryptography >= 1.4
-DSA and ECDSA keys: cryptography >= 1.5
-ed448 and ed25519 keys: cryptography >= 2.6.
See also
-Verify signatures with openssl.
-Generate OpenSSL private keys.
----
-- name: Sign example file
- community.crypto.openssl_signature:
- privatekey_path: private.key
- path: /tmp/example_file
- register: sig
-
-- name: Verify signature of example file
- community.crypto.openssl_signature_info:
- certificate_path: cert.pem
- path: /tmp/example_file
- signature: "{{ sig.signature }}"
- register: verify
-
-- name: Make sure the signature is valid
- ansible.builtin.assert:
- that:
- - verify.valid
-Common return values are documented here, the following are the fields unique to this module:
-Key |
-Description |
-
|---|---|
| - | Base64 encoded signature. -Returned: success - |
-
- Note
-This filter plugin is part of the community.crypto collection (version 2.26.6).
-It is not included in ansible-core.
-To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install community.crypto.
To use it in a playbook, specify: community.crypto.parse_serial.
New in community.crypto 2.18.0
- -Parses a colon-separated list of hex numbers of the form 00:11:22:33 and returns the corresponding integer.
This describes the input of the filter, the value before | community.crypto.parse_serial.
Parameter |
-Comments |
-
|---|---|
| - | 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, |
-
See also
-Convert an integer to a colon-separated list of hex numbers.
----
-- name: Parse serial number
- ansible.builtin.debug:
- msg: "{{ '11:22:33' | community.crypto.parse_serial }}"
-Key |
-Description |
-
|---|---|
| - | The serial number as an integer. -Returned: success - |
-
- tls-alpn-01","community.crypto.acme_inspect module \u2013 Send direct requests to an ACME server","community.crypto.certificate_complete_chain module \u2013 Complete certificate chain given a set of untrusted and root certificates","Community.Crypto Release Notes","community.crypto.crypto_info module \u2013 Retrieve cryptographic capabilities","How to create a small CA","How to create self-signed certificates","community.crypto.ecs_certificate module \u2013 Request SSL/TLS certificates with the Entrust Certificate Services (ECS) API","community.crypto.ecs_domain module \u2013 Request validation of a domain with the Entrust Certificate Services (ECS) API","Index of all Collection Environment Variables","community.crypto.get_certificate module \u2013 Get a certificate from a host:port","community.crypto.gpg_fingerprint filter \u2013 Retrieve a GPG fingerprint from a GPG public or private key","community.crypto.gpg_fingerprint lookup \u2013 Retrieve a GPG fingerprint from a GPG public or private key file","Community.Crypto","community.crypto.luks_device module \u2013 Manage encrypted (LUKS) devices","community.crypto.openssh_cert module \u2013 Generate OpenSSH host or user certificates","community.crypto.openssh_keypair module \u2013 Generate OpenSSH private and public keys","community.crypto.openssl_certificate_info","community.crypto.openssl_certificate","community.crypto.openssl_csr_info filter \u2013 Retrieve information from OpenSSL Certificate Signing Requests (CSR)","community.crypto.openssl_csr_info module \u2013 Provide information of OpenSSL Certificate Signing Requests (CSR)","community.crypto.openssl_csr module \u2013 Generate OpenSSL Certificate Signing Request (CSR)","community.crypto.openssl_csr_pipe module \u2013 Generate OpenSSL Certificate Signing Request (CSR)","community.crypto.openssl_dhparam module \u2013 Generate OpenSSL Diffie-Hellman Parameters","community.crypto.openssl_pkcs12 module \u2013 Generate OpenSSL PKCS#12 archive","community.crypto.openssl_privatekey_convert module \u2013 Convert OpenSSL private keys","community.crypto.openssl_privatekey_info filter \u2013 Retrieve information from OpenSSL private keys","community.crypto.openssl_privatekey_info module \u2013 Provide information for OpenSSL private keys","community.crypto.openssl_privatekey module \u2013 Generate OpenSSL private keys","community.crypto.openssl_privatekey_pipe module \u2013 Generate OpenSSL private keys without disk access","community.crypto.openssl_publickey_info filter \u2013 Retrieve information from OpenSSL public keys in PEM format","community.crypto.openssl_publickey_info module \u2013 Provide information for OpenSSL public keys","community.crypto.openssl_publickey module \u2013 Generate an OpenSSL public key from its private key","community.crypto.openssl_signature_info module \u2013 Verify signatures with openssl","community.crypto.openssl_signature module \u2013 Sign data with openssl","community.crypto.parse_serial filter \u2013 Convert a serial number as a colon-separated list of hex numbers to an integer","community.crypto.split_pem filter \u2013 Split PEM file contents into multiple objects","community.crypto.to_serial filter \u2013 Convert an integer to a colon-separated list of hex numbers","community.crypto.x509_certificate_convert module \u2013 Convert X.509 certificates","community.crypto.x509_certificate_info filter \u2013 Retrieve information from X.509 certificates in PEM format","community.crypto.x509_certificate_info module \u2013 Provide information of OpenSSL X.509 certificates","community.crypto.x509_certificate module \u2013 Generate and/or check OpenSSL certificates","community.crypto.x509_certificate_pipe module \u2013 Generate and/or check OpenSSL certificates","community.crypto.x509_crl_info filter \u2013 Retrieve information from X.509 CRLs in PEM format","community.crypto.x509_crl_info module \u2013 Retrieve information on Certificate Revocation Lists (CRLs)","community.crypto.x509_crl module \u2013 Generate Certificate Revocation Lists (CRLs)"],"titleterms":{"0":15,"01":12,"1":15,"10":15,"11":15,"12":[15,36],"13":15,"14":15,"15":15,"16":15,"17":15,"18":15,"19":15,"2":15,"20":15,"21":15,"22":15,"23":15,"24":15,"25":15,"26":15,"3":15,"4":15,"5":15,"509":[50,51,52,55],"6":15,"7":15,"8":15,"9":15,"access":41,"account":[1,2],"acm":[1,2,3,4,5,6,7,8,9,11,12,13],"acme_account":2,"acme_account_fact":0,"acme_account_info":1,"acme_ari_info":3,"acme_certif":5,"acme_certificate_deactivate_authz":4,"acme_certificate_order_cr":6,"acme_certificate_order_fin":7,"acme_certificate_order_info":8,"acme_certificate_order_valid":9,"acme_certificate_renewal_info":10,"acme_certificate_revok":11,"acme_challenge_cert_help":12,"acme_inspect":13,"all":[4,21],"alpn":12,"also":[1,2,3,4,5,6,7,8,9,10,11,12,13,19,20,22,23,24,27,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,49,50,51,52,53,54,55,56,57],"an":[4,6,7,8,9,13,44,47,49],"api":[19,20],"archiv":36,"ari":3,"attribut":[1,2,3,4,5,6,7,8,9,10,11,12,13,14,16,19,20,22,26,27,28,32,33,34,35,36,37,39,40,41,43,44,45,46,50,52,53,54,56,57],"author":[1,2,3,4,5,6,7,8,9,10,11,12,13,14,16,19,20,22,23,24,26,27,28,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57],"authz":4,"break":15,"bugfix":15,"ca":17,"capabl":16,"certif":[3,5,10,11,12,14,17,18,19,20,22,27,31,32,33,34,50,51,52,53,54,56,57],"certificate_complete_chain":14,"chain":14,"challeng":12,"chang":15,"changelog":25,"check":[53,54],"collect":[1,2,3,4,5,6,7,8,9,10,11,12,13,14,16,19,20,21,22,23,24,26,27,28,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57],"colon":[47,49],"commun":[0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,19,20,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57],"complet":14,"content":48,"convert":[37,47,49,50],"creat":[2,5,6,17,18],"crl":[55,56,57],"crypto":[0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,19,20,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57],"crypto_info":16,"cryptograph":16,"csr":[31,32,33,34],"data":46,"deactiv":4,"delet":2,"deprec":15,"descript":25,"determin":10,"devic":26,"diffi":35,"direct":13,"disk":41,"domain":20,"ec":[19,20],"ecs_certif":19,"ecs_domain":20,"encrypt":26,"entrust":[19,20],"environ":21,"exampl":[1,2,3,4,5,6,7,8,9,10,11,12,13,14,16,19,20,22,23,24,26,27,28,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57],"featur":15,"file":[24,48],"filter":[15,23,25,31,38,42,47,48,49,51,55],"final":7,"fingerprint":[23,24],"fix":15,"format":[42,51,55],"from":[22,23,24,31,38,42,44,51,55],"gener":[27,28,33,34,35,36,40,41,44,53,54,57],"get":22,"get_certif":22,"given":14,"gpg":[23,24],"gpg_fingerprint":[23,24],"guid":[15,25],"hellman":35,"hex":[47,49],"host":[22,27],"how":[17,18],"index":[21,25],"inform":[1,3,8,31,32,38,39,42,43,51,52,55,56],"input":[23,31,38,42,47,48,49,51,55],"integ":[47,49],"issu":15,"its":44,"kei":[23,24,28,37,38,39,40,41,42,43,44],"keyword":[31,38,51,55],"known":15,"link":[1,2,3,4,5,6,7,8,9,10,11,12,13,14,16,19,20,22,23,24,26,27,28,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57],"list":[47,49,56,57],"lookup":[15,24,25],"luk":26,"luks_devic":26,"manag":26,"minor":15,"modifi":2,"modul":[1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,19,20,22,25,26,27,28,32,33,34,35,36,37,39,40,41,43,44,45,46,50,52,53,54,56,57],"multipl":48,"new":15,"note":[1,2,3,4,5,6,7,8,9,10,11,13,15,19,20,22,28,33,34,45,46,52,53,54,56,57],"number":[47,49],"object":48,"obtain":8,"openssh":[27,28],"openssh_cert":27,"openssh_keypair":28,"openssl":[31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,52,53,54],"openssl_certif":30,"openssl_certificate_info":29,"openssl_csr":33,"openssl_csr_info":[31,32],"openssl_csr_pip":34,"openssl_dhparam":35,"openssl_pkcs12":36,"openssl_privatekei":40,"openssl_privatekey_convert":37,"openssl_privatekey_info":[38,39],"openssl_privatekey_pip":41,"openssl_publickei":44,"openssl_publickey_info":[42,43],"openssl_signatur":46,"openssl_signature_info":45,"order":[4,6,7,8,9],"paramet":[1,2,3,4,5,6,7,8,9,10,11,12,13,14,19,20,22,26,27,28,31,32,33,34,35,36,37,38,39,40,41,43,44,45,46,50,51,52,53,54,55,56,57],"parse_seri":47,"pem":[42,48,51,55],"pkc":36,"plugin":[15,25],"port":[15,22],"prepar":12,"previous":15,"privat":[23,24,28,37,38,39,40,41,44],"protocol":[5,11],"provid":[32,39,43,52],"public":[23,24,28,42,43,44],"releas":15,"remov":15,"renew":[3,10],"request":[13,19,20,31,32,33,34],"requir":[1,2,3,4,5,6,7,8,9,10,11,12,13,14,19,20,22,23,24,26,27,28,31,32,33,34,35,36,37,38,39,40,41,43,44,45,46,50,51,52,53,54,55,56,57],"retriev":[1,3,16,23,24,31,38,42,51,55,56],"return":[1,2,3,5,6,7,8,9,10,12,13,14,16,19,20,22,23,24,26,27,28,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57],"revoc":[56,57],"revok":11,"root":14,"scenario":25,"secur":15,"see":[1,2,3,4,5,6,7,8,9,10,11,12,13,19,20,22,23,24,27,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,49,50,51,52,53,54,55,56,57],"self":18,"send":13,"separ":[47,49],"serial":47,"server":13,"servic":[19,20],"set":[14,17],"should":10,"sign":[17,18,31,32,33,34,46],"signatur":45,"small":17,"split":48,"split_pem":48,"ssl":[5,19],"summari":15,"synopsi":[1,2,3,4,5,6,7,8,9,10,11,12,13,14,16,19,20,22,23,24,26,27,28,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57],"term":24,"tl":[5,12,19],"to_seri":49,"topic":15,"untrust":14,"up":17,"us":17,"user":27,"v1":15,"v2":[4,6,7,8,9,15],"valid":[9,20],"valu":[1,2,3,5,6,7,8,9,10,12,13,14,16,19,20,22,23,24,26,27,28,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57],"variabl":21,"verifi":45,"whether":10,"without":41,"x":[50,51,52,55],"x509_certif":53,"x509_certificate_convert":50,"x509_certificate_info":[51,52],"x509_certificate_pip":54,"x509_crl":57,"x509_crl_info":[55,56]}})
\ No newline at end of file
diff --git a/pr/965/split_pem_filter.html b/pr/965/split_pem_filter.html
deleted file mode 100644
index 7a6a3420..00000000
--- a/pr/965/split_pem_filter.html
+++ /dev/null
@@ -1,305 +0,0 @@
-
-
-
-
-
-
-
-
-
-
- Note
-This filter plugin is part of the community.crypto collection (version 2.26.6).
-It is not included in ansible-core.
-To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install community.crypto.
To use it in a playbook, specify: community.crypto.split_pem.
New in community.crypto 2.10.0
- -Split PEM file contents into multiple PEM objects. Comments or invalid parts are ignored.
This describes the input of the filter, the value before | community.crypto.split_pem.
Parameter |
-Comments |
-
|---|---|
| - | The PEM contents to split. - |
-
---
-- name: Print all CA certificates
- ansible.builtin.debug:
- msg: '{{ item }}'
- loop: >-
- {{ lookup('ansible.builtin.file', '/path/to/ca-bundle.pem') | community.crypto.split_pem }}
-Key |
-Description |
-
|---|---|
| - | A list of PEM file contents. -Returned: success - |
-
- Note
-This filter plugin is part of the community.crypto collection (version 2.26.6).
-It is not included in ansible-core.
-To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install community.crypto.
To use it in a playbook, specify: community.crypto.to_serial.
New in community.crypto 2.18.0
- -Converts an integer to a colon-separated list of hex numbers of the form 00:11:22:33.
This describes the input of the filter, the value before | community.crypto.to_serial.
Parameter |
-Comments |
-
|---|---|
| - | The non-negative integer to convert. - |
-
See also
-Convert an integer to a colon-separated list of hex numbers.
----
-- name: Convert integer to serial number
- ansible.builtin.debug:
- msg: "{{ 1234567 | community.crypto.to_serial }}"
-Key |
-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 Returned: success - |
-
- Note
-This module is part of the community.crypto collection (version 2.26.6).
-It is not included in ansible-core.
-To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install community.crypto.
-You need further requirements to be able to use this module,
-see Requirements for details.
To use it in a playbook, specify: community.crypto.x509_certificate_convert.
New in community.crypto 2.19.0
- -This module allows to convert X.509 certificates between different formats.
The below requirements are needed on the host that executes this module.
-cryptography >= 1.6 if verify_cert_parsable=true
Parameter |
-Comments |
-
|---|---|
| - | The attributes the resulting filesystem object should have. -To get supported flags look at the man page for This string should contain the attributes in the same order as the one displayed by The |
-
| - | 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. -Choices: -
|
-
| - | Name of the file in which the generated TLS/SSL X.509 certificate will be written. - |
-
| - | 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. -Choices: -
|
-
| - | Name of the group that should own the filesystem object, as would be fed to When left unspecified, it uses the current group of the current user unless you are root, in which case it can preserve the previous ownership. - |
-
| - | The permissions the resulting filesystem object should have. -For those used to Giving Ansible a number without following either of these rules will end up with a decimal number which will have unexpected results. -As of Ansible 1.8, the mode may be specified as a symbolic mode (for example, If If Specifying |
-
| - | Name of the user that should own the filesystem object, as would be fed to When left unspecified, it uses the current user unless you are root, in which case it can preserve the previous ownership. -Specifying a numeric username will be assumed to be a user ID and not a username. Avoid numeric usernames to avoid this confusion. - |
-
| - | The level part of the SELinux filesystem object context. -This is the MLS/MCS attribute, sometimes known as the When set to |
-
| - | The role part of the SELinux filesystem object context. -When set to |
-
| - | The type part of the SELinux filesystem object context. -When set to |
-
| - | The user part of the SELinux filesystem object context. -By default it uses the When set to |
-
| - | 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 Exactly one of |
-
| - | If set to Choices: -
|
-
| - | Name of the file containing the X.509 certificate to convert. -Exactly one of |
-
| - | 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 See also the Choices: -
|
-
| - | Influence when to use atomic operation to prevent data corruption or inconsistent reads from the target filesystem object. -By default this module uses atomic operations to prevent data corruption or inconsistent reads from the target filesystem objects, but sometimes systems are configured or just broken in ways that prevent this. One example is docker mounted filesystem objects, which cannot be updated atomically from inside the container and can only be written in an unsafe manner. -This option allows Ansible to fall back to unsafe methods of updating filesystem objects when atomic operations fail (however, it doesn’t force Ansible to perform unsafe writes). -IMPORTANT! Unsafe writes are subject to race conditions and can lead to data corruption. -Choices: -
|
-
| - | If set to To ensure that a PEM file does not contain multiple certificates, use the Choices: -
|
-
Attribute |
-Support |
-Description |
-
|---|---|---|
| - | Support: full - |
-Can run in |
-
| - | Support: none - |
-Will return details on what has changed (or possibly needs changing in |
-
| - | Support: full - |
-When run twice in a row outside check mode, with the same arguments, the second invocation indicates no change. -This assumes that the system controlled/queried by the module has not changed in a relevant way. - |
-
| - | Support: full - |
-Uses Ansible’s strict file operation functions to ensure proper permissions and avoid data corruption. - |
-
See also
-The official documentation on the ansible.builtin.b64encode filter plugin.
-Generate and/or check OpenSSL certificates.
-Generate and/or check OpenSSL certificates.
-Provide information of OpenSSL X.509 certificates.
----
-- 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
-Common return values are documented here, the following are the fields unique to this module:
-Key |
-Description |
-
|---|---|
| - | Name of backup file created. -Returned: changed and if Sample: |
-
- Note
-This filter plugin is part of the community.crypto collection (version 2.26.6).
-It is not included in ansible-core.
-To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install community.crypto.
-You need further requirements to be able to use this filter plugin,
-see Requirements for details.
To use it in a playbook, specify: community.crypto.x509_certificate_info.
New in community.crypto 2.10.0
- -Provided a X.509 certificate in PEM format, retrieve information.
This is a filter version of the community.crypto.x509_certificate_info module.
The below requirements are needed on the local controller node that executes this filter.
-If name_encoding is set to another value than ignore, the idna Python library needs to be installed.
This describes the input of the filter, the value before | community.crypto.x509_certificate_info.
Parameter |
-Comments |
-
|---|---|
| - | The content of the X.509 certificate in PEM format. - |
-
This describes keyword parameters of the filter. These are the values key1=value1, key2=value2 and so on in the following
-example: input | community.crypto.x509_certificate_info(key1=value1, key2=value2, ...)
Parameter |
-Comments |
-
|---|---|
| - | How to encode names (DNS names, URIs, email addresses) in return values. -
Note that Choices: -
|
-
See also
-Provide information of OpenSSL X.509 certificates.
-Convert an integer to a colon-separated list of hex numbers.
----
-- name: Show the Subject Alt Names of the certificate
- ansible.builtin.debug:
- msg: >-
- {{
- (
- lookup('ansible.builtin.file', '/path/to/cert.pem')
- | community.crypto.x509_certificate_info
- ).subject_alt_name | join(', ')
- }}
-Key |
-Description |
-
|---|---|
| - | Information on the certificate. -Returned: success - |
-
| - | The certificate’s authority cert issuer as a list of general names. -Is See Returned: success -Sample: |
-
| - | The certificate’s authority cert serial number. -Is This return value is an integer. If you need the serial numbers as a colon-separated hex string, such as Returned: success -Sample: |
-
| - | The certificate’s authority key identifier. -The identifier is returned in hexadecimal, with Is Returned: success -Sample: |
-
| - | Entries in the Returned: success -Sample: |
-
| - | Whether the Returned: success - |
-
| - | Whether the certificate is expired (in other words, Returned: success - |
-
| - | Entries in the Returned: success -Sample: |
-
| - | Whether the Returned: success - |
-
| - | Returns a dictionary for every extension OID. -Returned: success -Sample: |
-
| - | Whether the extension is critical. -Returned: success - |
-
| - | The Base64 encoded value (in DER format) of the extension. -Note that depending on the Returned: success -Sample: |
-
| - | Fingerprints of the DER-encoded form of the whole certificate. -For every hash algorithm available, the fingerprint is computed. -Returned: success -Sample: |
-
| - | The certificate’s issuer. -Note that for repeated values, only the last one will be returned. -Returned: success -Sample: |
-
| - | The certificate’s issuer as an ordered list of tuples. -Returned: success -Sample: |
-
| - | The Issuer URI, if included in the certificate. Will be Returned: success - |
-
| - | Entries in the Returned: success -Sample: |
-
| - | Whether the Returned: success - |
-
| - |
Returned: success -Sample: |
-
| - |
Returned: success -Sample: |
-
| - |
Returned: success - |
-
| - | Whether the Returned: success - |
-
| - | The OCSP responder URI, if included in the certificate. Will be Returned: success - |
-
| - | Certificate’s public key in PEM format. -Returned: success -Sample: |
-
| - | Public key data. Depends on the public key’s type. -Returned: success - |
-
| - | The curve’s name for ECC. -Returned: When |
-
| - | The RSA key’s public exponent. -Returned: When |
-
| - | The maximum number of bits of a private key. This is basically the bit size of the subgroup used. -Returned: When |
-
| - | The This is the element spanning the subgroup of the multiplicative group of the prime field used. -Returned: When |
-
| - | The RSA key’s modulus. -Returned: When |
-
| - | The This is the prime modulus upon which arithmetic takes place. -Returned: When |
-
| - | The This is a prime that divides Returned: When |
-
| - | Bit size of modulus (RSA) or prime number (DSA). -Returned: When |
-
| - | The Returned: When |
-
| - | For For Returned: When |
-
| - | Fingerprints of certificate’s public key. -For every hash algorithm available, the fingerprint is computed. -Returned: success -Sample: |
-
| - | The certificate’s public key’s type. -One of Will start with Returned: success -Sample: |
-
| - | The certificate’s serial number. -This return value is an integer. If you need the serial numbers as a colon-separated hex string, such as Returned: success -Sample: |
-
| - | The signature algorithm used to sign the certificate. -Returned: success -Sample: |
-
| - | The certificate’s subject as a dictionary. -Note that for repeated values, only the last one will be returned. -Returned: success -Sample: |
-
| - | Entries in the See Returned: success -Sample: |
-
| - | Whether the Returned: success - |
-
| - | The certificate’s subject key identifier. -The identifier is returned in hexadecimal, with Is Returned: success -Sample: |
-
| - | The certificate’s subject as an ordered list of tuples. -Returned: success -Sample: |
-
| - | The certificate version. -Returned: success -Sample: |
-
- Note
-This module is part of the community.crypto collection (version 2.26.6).
-It is not included in ansible-core.
-To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install community.crypto.
-You need further requirements to be able to use this module,
-see Requirements for details.
To use it in a playbook, specify: community.crypto.x509_certificate_info.
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 openssl_certificate_info when included directly in Ansible up to version 2.9. When moved to the collection community.crypto, it was renamed to community.crypto.x509_certificate_info. From Ansible 2.10 on, it can still be used by the old short name (or by ansible.builtin.openssl_certificate_info), which redirects to community.crypto.x509_certificate_info. When using FQCNs or when using the collections keyword, the new name community.crypto.x509_certificate_info should be used to avoid a deprecation warning.
The below requirements are needed on the host that executes this module.
-If name_encoding is set to another value than ignore, the idna Python library needs to be installed.
cryptography >= 1.6
Parameter |
-Comments |
-
|---|---|
| - | - |
| - | How to encode names (DNS names, URIs, email addresses) in return values. -
Note that Choices: -
|
-
| - | - |
| - | Determines which crypto backend to use. -The default choice is If set to Choices: -
|
-
| - | 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 Time can be specified either as relative time or as absolute timestamp. -Time will always be interpreted as UTC. -Valid format is |
-
Attribute |
-Support |
-Description |
-
|---|---|---|
| - | Support: full -This action does not modify state. - |
-Can run in |
-
| - | Support: N/A -This action does not modify state. - |
-Will return details on what has changed (or possibly needs changing in |
-
| - | Support: full -This action does not modify state. - |
-When run twice in a row outside check mode, with the same arguments, the second invocation indicates no change. -This assumes that the system controlled/queried by the module has not changed in a relevant way. - |
-
Note
-All timestamp values are provided in ASN.1 TIME format, in other words, following the YYYYMMDDHHMMSSZ pattern. They are all in UTC.
See also
-Generate and/or check OpenSSL certificates.
-Generate and/or check OpenSSL certificates.
-A filter variant of this module.
-Convert an integer to a colon-separated list of hex numbers.
----
-- name: Generate a Self Signed OpenSSL certificate
- community.crypto.x509_certificate:
- path: /etc/ssl/crt/ansible.com.crt
- privatekey_path: /etc/ssl/private/ansible.com.pem
- csr_path: /etc/ssl/csr/ansible.com.csr
- provider: selfsigned
-
-
-# Get information on the certificate
-
-- name: Get information on generated certificate
- community.crypto.x509_certificate_info:
- path: /etc/ssl/crt/ansible.com.crt
- register: result
-
-- name: Dump information
- ansible.builtin.debug:
- var: result
-
-
-# Check whether the certificate is valid or not valid at certain times, fail
-# if this is not the case. The first task (x509_certificate_info) collects
-# the information, and the second task (assert) validates the result and
-# makes the playbook fail in case something is not as expected.
-
-- name: Test whether that certificate is valid tomorrow and/or in three weeks
- community.crypto.x509_certificate_info:
- path: /etc/ssl/crt/ansible.com.crt
- valid_at:
- point_1: "+1d"
- point_2: "+3w"
- register: result
-
-- 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
-Common return values are documented here, the following are the fields unique to this module:
-Key |
-Description |
-
|---|---|
| - | The certificate’s authority cert issuer as a list of general names. -Is See Returned: success -Sample: |
-
| - | The certificate’s authority cert serial number. -Is This return value is an integer. If you need the serial numbers as a colon-separated hex string, such as Returned: success -Sample: |
-
| - | The certificate’s authority key identifier. -The identifier is returned in hexadecimal, with Is Returned: success -Sample: |
-
| - | Entries in the Returned: success -Sample: |
-
| - | Whether the Returned: success - |
-
| - | Whether the certificate is expired (in other words, Returned: success - |
-
| - | Entries in the Returned: success -Sample: |
-
| - | Whether the Returned: success - |
-
| - | Returns a dictionary for every extension OID. -Returned: success -Sample: |
-
| - | Whether the extension is critical. -Returned: success - |
-
| - | The Base64 encoded value (in DER format) of the extension. -Note that depending on the Returned: success -Sample: |
-
| - | Fingerprints of the DER-encoded form of the whole certificate. -For every hash algorithm available, the fingerprint is computed. -Returned: success -Sample: |
-
| - | The certificate’s issuer. -Note that for repeated values, only the last one will be returned. -Returned: success -Sample: |
-
| - | The certificate’s issuer as an ordered list of tuples. -Returned: success -Sample: |
-
| - | The Issuer URI, if included in the certificate. Will be Returned: success - |
-
| - | Entries in the Returned: success -Sample: |
-
| - | Whether the Returned: success - |
-
| - |
Returned: success -Sample: |
-
| - |
Returned: success -Sample: |
-
| - |
Returned: success - |
-
| - | Whether the Returned: success - |
-
| - | The OCSP responder URI, if included in the certificate. Will be Returned: success - |
-
| - | Certificate’s public key in PEM format. -Returned: success -Sample: |
-
| - | Public key data. Depends on the public key’s type. -Returned: success - |
-
| - | The curve’s name for ECC. -Returned: When |
-
| - | The RSA key’s public exponent. -Returned: When |
-
| - | The maximum number of bits of a private key. This is basically the bit size of the subgroup used. -Returned: When |
-
| - | The This is the element spanning the subgroup of the multiplicative group of the prime field used. -Returned: When |
-
| - | The RSA key’s modulus. -Returned: When |
-
| - | The This is the prime modulus upon which arithmetic takes place. -Returned: When |
-
| - | The This is a prime that divides Returned: When |
-
| - | Bit size of modulus (RSA) or prime number (DSA). -Returned: When |
-
| - | The Returned: When |
-
| - | For For Returned: When |
-
| - | Fingerprints of certificate’s public key. -For every hash algorithm available, the fingerprint is computed. -Returned: success -Sample: |
-
| - | The certificate’s public key’s type. -One of Will start with Returned: success -Sample: |
-
| - | The certificate’s serial number. -This return value is an integer. If you need the serial numbers as a colon-separated hex string, such as Returned: success -Sample: |
-
| - | The signature algorithm used to sign the certificate. -Returned: success -Sample: |
-
| - | The certificate’s subject as a dictionary. -Note that for repeated values, only the last one will be returned. -Returned: success -Sample: |
-
| - | Entries in the See Returned: success -Sample: |
-
| - | Whether the Returned: success - |
-
| - | The certificate’s subject key identifier. -The identifier is returned in hexadecimal, with Is Returned: success -Sample: |
-
| - | The certificate’s subject as an ordered list of tuples. -Returned: success -Sample: |
-
| - | For every time stamp provided in the Returned: success - |
-
| - | The certificate version. -Returned: success -Sample: |
-
- Note
-This module is part of the community.crypto collection (version 2.26.6).
-It is not included in ansible-core.
-To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install community.crypto.
-You need further requirements to be able to use this module,
-see Requirements for details.
To use it in a playbook, specify: community.crypto.x509_certificate.
It implements a notion of provider (one of selfsigned, ownca, acme, and entrust) for your certificate.
It uses the cryptography python library to interact with OpenSSL.
Note that this module was called openssl_certificate when included directly in Ansible up to version 2.9. When moved to the collection community.crypto, it was renamed to community.crypto.x509_certificate. From Ansible 2.10 on, it can still be used by the old short name (or by ansible.builtin.openssl_certificate), which redirects to community.crypto.x509_certificate. When using FQCNs or when using the collections keyword, the new name community.crypto.x509_certificate should be used to avoid a deprecation warning.
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 backup option.
The ownca provider is intended for generating an OpenSSL certificate signed with your own CA (Certificate Authority) certificate (self-signed certificate).
This module allows one to (re)generate OpenSSL certificates.
The below requirements are needed on the host that executes this module.
-acme-tiny >= 4.0.0 (if using the acme provider)
cryptography >= 1.6 (if using selfsigned or ownca provider)
Parameter |
-Comments |
-
|---|---|
| - | The path to the accountkey for the This is only used by the |
-
| - | Include the intermediate certificate to the generated certificate -This is only used by the Note that this is only available for older versions of Choices: -
|
-
| - | The path to the ACME challenge directory that is served on http://<HOST>:80/.well-known/acme-challenge/ -This is only used by the |
-
| - | The ACME directory to use. You can use any directory that supports the ACME protocol, such as Let’s Encrypt. -Let’s Encrypt recommends using their staging server while developing jobs. https://letsencrypt.org/docs/staging-environment/. -Default: |
-
| - | The attributes the resulting filesystem object should have. -To get supported flags look at the man page for This string should contain the attributes in the same order as the one displayed by The |
-
| - | 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. -Choices: -
|
-
| - | Content of the Certificate Signing Request (CSR) used to generate this certificate. -This is mutually exclusive with |
-
| - | Path to the Certificate Signing Request (CSR) used to generate this certificate. -This is mutually exclusive with |
-
| - | The path to the private key of the client certificate used to authenticate to the Entrust Certificate Services (ECS) API. -This is only used by the This is required if the provider is |
-
| - | The path to the client certificate used to authenticate to the Entrust Certificate Services (ECS) API. -This is only used by the This is required if the provider is |
-
| - | The key (password) for authentication to the Entrust Certificate Services (ECS) API. -This is only used by the This is required if the provider is |
-
| - | The path to the specification file defining the Entrust Certificate Services (ECS) API configuration. -You can use this to keep a local copy of the specification to avoid downloading it every time the module is used. -This is only used by the Default: |
-
| - | The username for authentication to the Entrust Certificate Services (ECS) API. -This is only used by the This is required if the provider is |
-
| - | Specify the type of certificate requested. -This is only used by the Choices: -
|
-
| - | The point in time at which the certificate stops being valid. -Time can be specified either as relative time or as an absolute timestamp. -A valid absolute time format is A valid relative time format is Time will always be interpreted as UTC. -Note that only the date (day, month, year) is supported for specifying the expiry date of the issued certificate. -The full date-time is adjusted to EST (GMT -5:00) before issuance, which may result in a certificate with an expiration date one day earlier than expected if a relative time is used. -The minimum certificate lifetime is 90 days, and maximum is three years. -If this value is not specified, the certificate will stop being valid 365 days the date of issue. -This is only used by the Please note that this value is not covered by the Default: |
-
| - | The email of the requester of the certificate (for tracking purposes). -This is only used by the This is required if the provider is |
-
| - | The name of the requester of the certificate (for tracking purposes). -This is only used by the This is required if the provider is |
-
| - | The phone number of the requester of the certificate (for tracking purposes). -This is only used by the This is required if the provider is |
-
| - | Generate the certificate, even if it already exists. -Choices: -
|
-
| - | Name of the group that should own the filesystem object, as would be fed to When left unspecified, it uses the current group of the current user unless you are root, in which case it can preserve the previous ownership. - |
-
| - | Whether the “not before” and “not after” timestamps should be ignored for idempotency checks. -It is better to keep the default value Choices: -
|
-
| - | The permissions the resulting filesystem object should have. -For those used to Giving Ansible a number without following either of these rules will end up with a decimal number which will have unexpected results. -As of Ansible 1.8, the mode may be specified as a symbolic mode (for example, If If Specifying |
-
| - | Content of the CA (Certificate Authority) certificate. -This is only used by the This is mutually exclusive with |
-
| - | Create a Authority Key Identifier from the CA’s certificate. If the CSR provided a authority key identifier, it is ignored. -The Authority Key Identifier is generated from the CA certificate’s Subject Key Identifier, if available. If it is not available, the CA certificate’s public key will be used. -This is only used by the Note that this is only supported if the Choices: -
|
-
| - | Whether to create the Subject Key Identifier (SKI) from the public key. -A value of A value of A value of This is only used by the Note that this is only supported if the Choices: -
|
-
| - | The digest algorithm to be used for the This is only used by the Default: |
-
| - | The point in time at which the certificate stops being valid. -Time can be specified either as relative time or as absolute timestamp. -Time will always be interpreted as UTC. -Valid format is If this value is not specified, the certificate will stop being valid 10 years from now. -Note that this value is not used to determine whether an existing certificate should be regenerated. This can be changed by setting the This is only used by the On macOS 10.15 and onwards, TLS server certificates must have a validity period of 825 days or fewer. Please see https://support.apple.com/en-us/HT210176 for more details. -Default: |
-
| - | 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 format is If this value is not specified, the certificate will start being valid from now. -Note that this value is not used to determine whether an existing certificate should be regenerated. This can be changed by setting the This is only used by the Default: |
-
| - | Remote absolute path of the CA (Certificate Authority) certificate. -This is only used by the This is mutually exclusive with |
-
| - | Content of the CA (Certificate Authority) private key to use when signing the certificate. -This is only used by the This is mutually exclusive with |
-
| - | The passphrase for the This is only used by the |
-
| - | Path to the CA (Certificate Authority) private key to use when signing the certificate. -This is only used by the This is mutually exclusive with |
-
| - | The version of the Nowadays it should almost always be This is only used by the Default: |
-
| - | Name of the user that should own the filesystem object, as would be fed to When left unspecified, it uses the current user unless you are root, in which case it can preserve the previous ownership. -Specifying a numeric username will be assumed to be a user ID and not a username. Avoid numeric usernames to avoid this confusion. - |
-
| - | Remote absolute path where the generated certificate file should be created or is already located. - |
-
| - | Content of the private key to use when signing the certificate. -This is mutually exclusive with |
-
| - | The passphrase for the This is required if the private key is password protected. - |
-
| - | Path to the private key to use when signing the certificate. -This is mutually exclusive with |
-
| - | Name of the provider to use to generate/retrieve the OpenSSL certificate. Please see the examples on how to emulate it with community.crypto.x509_certificate_info, community.crypto.openssl_csr_info, community.crypto.openssl_privatekey_info and ansible.builtin.assert. -The Required if Choices: -
|
-
| - | If set to Choices: -
|
-
| - | Determines which crypto backend to use. -The default choice is If set to Choices: -
|
-
| - | The level part of the SELinux filesystem object context. -This is the MLS/MCS attribute, sometimes known as the When set to |
-
| - | Whether to create the Subject Key Identifier (SKI) from the public key. -A value of A value of A value of This is only used by the Note that this is only supported if the Choices: -
|
-
| - | Digest algorithm to be used when self-signing the certificate. -This is only used by the Default: |
-
| - | The point in time at which the certificate stops being valid. -Time can be specified either as relative time or as absolute timestamp. -Time will always be interpreted as UTC. -Valid format is If this value is not specified, the certificate will stop being valid 10 years from now. -Note that this value is not used to determine whether an existing certificate should be regenerated. This can be changed by setting the This is only used by the On macOS 10.15 and onwards, TLS server certificates must have a validity period of 825 days or fewer. Please see https://support.apple.com/en-us/HT210176 for more details. -Default: |
-
| - | 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 format is If this value is not specified, the certificate will start being valid from now. -Note that this value is not used to determine whether an existing certificate should be regenerated. This can be changed by setting the This is only used by the Default: |
-
| - | Version of the Nowadays it should almost always be This is only used by the Default: |
-
| - | The role part of the SELinux filesystem object context. -When set to |
-
| - | The type part of the SELinux filesystem object context. -When set to |
-
| - | The user part of the SELinux filesystem object context. -By default it uses the When set to |
-
| - | Whether the certificate should exist or not, taking action if the state is different from what is stated. -Choices: -
|
-
| - | Influence when to use atomic operation to prevent data corruption or inconsistent reads from the target filesystem object. -By default this module uses atomic operations to prevent data corruption or inconsistent reads from the target filesystem objects, but sometimes systems are configured or just broken in ways that prevent this. One example is docker mounted filesystem objects, which cannot be updated atomically from inside the container and can only be written in an unsafe manner. -This option allows Ansible to fall back to unsafe methods of updating filesystem objects when atomic operations fail (however, it doesn’t force Ansible to perform unsafe writes). -IMPORTANT! Unsafe writes are subject to race conditions and can lead to data corruption. -Choices: -
|
-
Attribute |
-Support |
-Description |
-
|---|---|---|
| - | Support: full - |
-Can run in |
-
| - | Support: full - |
-Will return details on what has changed (or possibly needs changing in |
-
| - | Support: partial -If relative timestamps are used and The option |
-When run twice in a row outside check mode, with the same arguments, the second invocation indicates no change. -This assumes that the system controlled/queried by the module has not changed in a relevant way. - |
-
| - | Support: full - |
-Uses Ansible’s strict file operation functions to ensure proper permissions and avoid data corruption. - |
-
Note
-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 ownca provider, you should NOT run 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.
For the selfsigned provider, csr_path and csr_content are optional. If not provided, a certificate without any information (Subject, Subject Alternative Names, Key Usage, etc.) is created.
See also
-Generate and/or check OpenSSL certificates.
-Generate OpenSSL Certificate Signing Request (CSR).
-Generate OpenSSL Certificate Signing Request (CSR).
-Generate OpenSSL Diffie-Hellman Parameters.
-Generate OpenSSL PKCS#12 archive.
-Generate OpenSSL private keys.
-Generate OpenSSL private keys without disk access.
-Generate an OpenSSL public key from its private key.
----
-- name: Generate a Self Signed OpenSSL certificate
- community.crypto.x509_certificate:
- path: /etc/ssl/crt/ansible.com.crt
- privatekey_path: /etc/ssl/private/ansible.com.pem
- csr_path: /etc/ssl/csr/ansible.com.csr
- provider: selfsigned
-
-- name: Generate an OpenSSL certificate signed with your own CA certificate
- community.crypto.x509_certificate:
- path: /etc/ssl/crt/ansible.com.crt
- csr_path: /etc/ssl/csr/ansible.com.csr
- ownca_path: /etc/ssl/crt/ansible_CA.crt
- ownca_privatekey_path: /etc/ssl/private/ansible_CA.pem
- provider: ownca
-
-- name: Generate a Let's Encrypt Certificate
- community.crypto.x509_certificate:
- path: /etc/ssl/crt/ansible.com.crt
- csr_path: /etc/ssl/csr/ansible.com.csr
- provider: acme
- acme_accountkey_path: /etc/ssl/private/ansible.com.pem
- acme_challenge_path: /etc/ssl/challenges/ansible.com/
-
-- name: Force (re-)generate a new Let's Encrypt Certificate
- community.crypto.x509_certificate:
- path: /etc/ssl/crt/ansible.com.crt
- csr_path: /etc/ssl/csr/ansible.com.csr
- provider: acme
- acme_accountkey_path: /etc/ssl/private/ansible.com.pem
- acme_challenge_path: /etc/ssl/challenges/ansible.com/
- force: true
-
-- name: Generate an Entrust certificate via the Entrust Certificate Services (ECS) API
- community.crypto.x509_certificate:
- path: /etc/ssl/crt/ansible.com.crt
- csr_path: /etc/ssl/csr/ansible.com.csr
- provider: entrust
- entrust_requester_name: Jo Doe
- entrust_requester_email: jdoe@ansible.com
- entrust_requester_phone: 555-555-5555
- entrust_cert_type: STANDARD_SSL
- entrust_api_user: apiusername
- 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-key.crt
- entrust_api_specification_path: /etc/ssl/entrust/api-docs/cms-api-2.1.0.yaml
-
-# The following example shows how to emulate the behavior of the removed
-# "assertonly" provider with the x509_certificate_info, openssl_csr_info,
-# openssl_privatekey_info and assert modules:
-
-- name: Get certificate information
- community.crypto.x509_certificate_info:
- path: /etc/ssl/crt/ansible.com.crt
- # for valid_at, invalid_at and valid_in
- valid_at:
- one_day_ten_hours: "+1d10h"
- fixed_timestamp: 20200331202428Z
- ten_seconds: "+10"
- register: result
-
-- name: Get CSR information
- community.crypto.openssl_csr_info:
- # Verifies that the CSR signature is valid; module will fail if not
- path: /etc/ssl/csr/ansible.com.csr
- register: result_csr
-
-- name: Get private key information
- community.crypto.openssl_privatekey_info:
- path: /etc/ssl/csr/ansible.com.key
- register: result_privatekey
-
-- name: Check conditions on certificate, CSR, and private key
- ansible.builtin.assert:
- that:
- # When private key was specified for assertonly, this was checked:
- - result.public_key == result_privatekey.public_key
- # When CSR was specified for assertonly, this was checked:
- - result.public_key == result_csr.public_key
- - result.subject_ordered == result_csr.subject_ordered
- - result.extensions_by_oid == result_csr.extensions_by_oid
- # signature_algorithms check
- - "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
- # issuer and issuer_strict
- - "result.issuer.commonName == 'ansible.com'"
- - "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
- # 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
- # 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
- # 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
-Common return values are documented here, the following are the fields unique to this module:
-Key |
-Description |
-
|---|---|
| - | Name of backup file created. -Returned: changed and if Sample: |
-
| - | The (current or generated) certificate’s content. -Returned: if |
-
| - | Path to the generated certificate. -Returned: changed or success -Sample: |
-
- Note
-This module is part of the community.crypto collection (version 2.26.6).
-It is not included in ansible-core.
-To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install community.crypto.
-You need further requirements to be able to use this module,
-see Requirements for details.
To use it in a playbook, specify: community.crypto.x509_certificate_pipe.
New in community.crypto 1.3.0
- -It implements a notion of provider (one of selfsigned, ownca, entrust) for your certificate.
It uses the cryptography python library to interact with OpenSSL.
The ownca provider is intended for generating an OpenSSL certificate signed with your own CA (Certificate Authority) certificate (self-signed certificate).
This module allows one to (re)generate OpenSSL certificates.
The below requirements are needed on the host that executes this module.
-cryptography >= 1.6 (if using selfsigned or ownca provider)
Parameter |
-Comments |
-
|---|---|
| - | The existing certificate. - |
-
| - | Content of the Certificate Signing Request (CSR) used to generate this certificate. -This is mutually exclusive with |
-
| - | Path to the Certificate Signing Request (CSR) used to generate this certificate. -This is mutually exclusive with |
-
| - | The path to the private key of the client certificate used to authenticate to the Entrust Certificate Services (ECS) API. -This is only used by the This is required if the provider is |
-
| - | The path to the client certificate used to authenticate to the Entrust Certificate Services (ECS) API. -This is only used by the This is required if the provider is |
-
| - | The key (password) for authentication to the Entrust Certificate Services (ECS) API. -This is only used by the This is required if the provider is |
-
| - | The path to the specification file defining the Entrust Certificate Services (ECS) API configuration. -You can use this to keep a local copy of the specification to avoid downloading it every time the module is used. -This is only used by the Default: |
-
| - | The username for authentication to the Entrust Certificate Services (ECS) API. -This is only used by the This is required if the provider is |
-
| - | Specify the type of certificate requested. -This is only used by the Choices: -
|
-
| - | The point in time at which the certificate stops being valid. -Time can be specified either as relative time or as an absolute timestamp. -A valid absolute time format is A valid relative time format is Time will always be interpreted as UTC. -Note that only the date (day, month, year) is supported for specifying the expiry date of the issued certificate. -The full date-time is adjusted to EST (GMT -5:00) before issuance, which may result in a certificate with an expiration date one day earlier than expected if a relative time is used. -The minimum certificate lifetime is 90 days, and maximum is three years. -If this value is not specified, the certificate will stop being valid 365 days the date of issue. -This is only used by the Please note that this value is not covered by the Default: |
-
| - | The email of the requester of the certificate (for tracking purposes). -This is only used by the This is required if the provider is |
-
| - | The name of the requester of the certificate (for tracking purposes). -This is only used by the This is required if the provider is |
-
| - | The phone number of the requester of the certificate (for tracking purposes). -This is only used by the This is required if the provider is |
-
| - | Generate the certificate, even if it already exists. -Choices: -
|
-
| - | Whether the “not before” and “not after” timestamps should be ignored for idempotency checks. -It is better to keep the default value Choices: -
|
-
| - | Content of the CA (Certificate Authority) certificate. -This is only used by the This is mutually exclusive with |
-
| - | Create a Authority Key Identifier from the CA’s certificate. If the CSR provided a authority key identifier, it is ignored. -The Authority Key Identifier is generated from the CA certificate’s Subject Key Identifier, if available. If it is not available, the CA certificate’s public key will be used. -This is only used by the Note that this is only supported if the Choices: -
|
-
| - | Whether to create the Subject Key Identifier (SKI) from the public key. -A value of A value of A value of This is only used by the Note that this is only supported if the Choices: -
|
-
| - | The digest algorithm to be used for the This is only used by the Default: |
-
| - | The point in time at which the certificate stops being valid. -Time can be specified either as relative time or as absolute timestamp. -Time will always be interpreted as UTC. -Valid format is If this value is not specified, the certificate will stop being valid 10 years from now. -Note that this value is not used to determine whether an existing certificate should be regenerated. This can be changed by setting the This is only used by the On macOS 10.15 and onwards, TLS server certificates must have a validity period of 825 days or fewer. Please see https://support.apple.com/en-us/HT210176 for more details. -Default: |
-
| - | 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 format is If this value is not specified, the certificate will start being valid from now. -Note that this value is not used to determine whether an existing certificate should be regenerated. This can be changed by setting the This is only used by the Default: |
-
| - | Remote absolute path of the CA (Certificate Authority) certificate. -This is only used by the This is mutually exclusive with |
-
| - | Content of the CA (Certificate Authority) private key to use when signing the certificate. -This is only used by the This is mutually exclusive with |
-
| - | The passphrase for the This is only used by the |
-
| - | Path to the CA (Certificate Authority) private key to use when signing the certificate. -This is only used by the This is mutually exclusive with |
-
| - | The version of the Nowadays it should almost always be This is only used by the Default: |
-
| - | Content of the private key to use when signing the certificate. -This is mutually exclusive with |
-
| - | The passphrase for the This is required if the private key is password protected. - |
-
| - | Path to the private key to use when signing the certificate. -This is mutually exclusive with |
-
| - | Name of the provider to use to generate/retrieve the OpenSSL certificate. -The Choices: -
|
-
| - | Determines which crypto backend to use. -The default choice is If set to Choices: -
|
-
| - | Whether to create the Subject Key Identifier (SKI) from the public key. -A value of A value of A value of This is only used by the Note that this is only supported if the Choices: -
|
-
| - | Digest algorithm to be used when self-signing the certificate. -This is only used by the Default: |
-
| - | The point in time at which the certificate stops being valid. -Time can be specified either as relative time or as absolute timestamp. -Time will always be interpreted as UTC. -Valid format is If this value is not specified, the certificate will stop being valid 10 years from now. -Note that this value is not used to determine whether an existing certificate should be regenerated. This can be changed by setting the This is only used by the On macOS 10.15 and onwards, TLS server certificates must have a validity period of 825 days or fewer. Please see https://support.apple.com/en-us/HT210176 for more details. -Default: |
-
| - | 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 format is If this value is not specified, the certificate will start being valid from now. -Note that this value is not used to determine whether an existing certificate should be regenerated. This can be changed by setting the This is only used by the Default: |
-
| - | Version of the Nowadays it should almost always be This is only used by the Default: |
-
Attribute |
-Support |
-Description |
-
|---|---|---|
| - | Support: full -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. - |
-Can run in |
-
| - | Support: full - |
-Will return details on what has changed (or possibly needs changing in |
-
| - | Support: partial -If relative timestamps are used and The option |
-When run twice in a row outside check mode, with the same arguments, the second invocation indicates no change. -This assumes that the system controlled/queried by the module has not changed in a relevant way. - |
-
Note
-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 ownca provider, you should NOT run 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.
For the selfsigned provider, csr_path and csr_content are optional. If not provided, a certificate without any information (Subject, Subject Alternative Names, Key Usage, etc.) is created.
See also
-Generate and/or check OpenSSL certificates.
-Generate OpenSSL Certificate Signing Request (CSR).
-Generate OpenSSL Certificate Signing Request (CSR).
-Generate OpenSSL Diffie-Hellman Parameters.
-Generate OpenSSL PKCS#12 archive.
-Generate OpenSSL private keys.
-Generate OpenSSL private keys without disk access.
-Generate an OpenSSL public key from its private key.
----
-- name: Generate a Self Signed OpenSSL certificate
- community.crypto.x509_certificate_pipe:
- provider: selfsigned
- privatekey_path: /etc/ssl/private/ansible.com.pem
- csr_path: /etc/ssl/csr/ansible.com.csr
- register: result
-- name: Print the certificate
- ansible.builtin.debug:
- var: result.certificate
-
-# In the following example, both CSR and certificate file are stored on the
-# machine where ansible-playbook is executed, while the OwnCA data (certificate,
-# private key) are stored on the remote machine.
-
-- name: (1/2) Generate an OpenSSL Certificate with the CSR provided inline
- community.crypto.x509_certificate_pipe:
- provider: ownca
- content: "{{ lookup('ansible.builtin.file', '/etc/ssl/csr/www.ansible.com.crt') }}"
- csr_content: "{{ lookup('ansible.builtin.file', '/etc/ssl/csr/www.ansible.com.csr') }}"
- ownca_cert: /path/to/ca_cert.crt
- ownca_privatekey: /path/to/ca_cert.key
- ownca_privatekey_passphrase: hunter2
- register: result
-
-- name: (2/2) Store certificate
- ansible.builtin.copy:
- dest: /etc/ssl/csr/www.ansible.com.crt
- content: "{{ result.certificate }}"
- delegate_to: localhost
- when: result is changed
-
-# In the following example, the certificate from another machine is signed by
-# our OwnCA whose private key and certificate are only available on this
-# machine (where ansible-playbook is executed), without having to write
-# the certificate file to disk on localhost. The CSR could have been
-# provided by community.crypto.openssl_csr_pipe earlier, or also have been
-# read from the remote machine.
-
-- name: (1/3) Read certificate's contents from remote machine
- ansible.builtin.slurp:
- src: /etc/ssl/csr/www.ansible.com.crt
- register: certificate_content
-
-- name: (2/3) Generate an OpenSSL Certificate with the CSR provided inline
- community.crypto.x509_certificate_pipe:
- provider: ownca
- content: "{{ certificate_content.content | b64decode }}"
- csr_content: "{{ the_csr }}"
- ownca_cert: /path/to/ca_cert.crt
- ownca_privatekey: /path/to/ca_cert.key
- ownca_privatekey_passphrase: hunter2
- delegate_to: localhost
- register: result
-
-- name: (3/3) Store certificate
- ansible.builtin.copy:
- dest: /etc/ssl/csr/www.ansible.com.crt
- content: "{{ result.certificate }}"
- when: result is changed
-Common return values are documented here, the following are the fields unique to this module:
-Key |
-Description |
-
|---|---|
| - | The (current or generated) certificate’s content. -Returned: changed or success - |
-
- Note
-This filter plugin is part of the community.crypto collection (version 2.26.6).
-It is not included in ansible-core.
-To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install community.crypto.
-You need further requirements to be able to use this filter plugin,
-see Requirements for details.
To use it in a playbook, specify: community.crypto.x509_crl_info.
New in community.crypto 2.10.0
- -Provided a X.509 crl in PEM format, retrieve information.
This is a filter version of the community.crypto.x509_crl_info module.
The below requirements are needed on the local controller node that executes this filter.
-If name_encoding is set to another value than ignore, the idna Python library needs to be installed.
This describes the input of the filter, the value before | community.crypto.x509_crl_info.
Parameter |
-Comments |
-
|---|---|
| - | The content of the X.509 CRL in PEM format. - |
-
This describes keyword parameters of the filter. These are the values key1=value1, key2=value2 and so on in the following
-example: input | community.crypto.x509_crl_info(key1=value1, key2=value2, ...)
Parameter |
-Comments |
-
|---|---|
| - | If set to 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. -Choices: -
|
-
| - | How to encode names (DNS names, URIs, email addresses) in return values. -
Note that Choices: -
|
-
See also
-Retrieve information on Certificate Revocation Lists (CRLs).
-Convert an integer to a colon-separated list of hex numbers.
----
-- name: Show the Organization Name of the CRL's subject
- ansible.builtin.debug:
- msg: >-
- {{
- (
- lookup('ansible.builtin.file', '/path/to/cert.pem')
- | community.crypto.x509_crl_info
- ).issuer.organizationName
- }}
-Key |
-Description |
-
|---|---|
| - | Information on the CRL. -Returned: success - |
-
| - | The signature algorithm used to sign the CRL. -Returned: success -Sample: |
-
| - | Whether the CRL is in PEM format ( Returned: success -Can only return: -
Sample: |
-
| - | The CRL’s issuer. -Note that for repeated values, only the last one will be returned. -See Returned: success -Sample: |
-
| - | The CRL’s issuer as an ordered list of tuples. -Returned: success -Sample: |
-
| - | The point in time from which this CRL can be trusted as ASN.1 TIME. -Returned: success -Sample: |
-
| - | 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 -Sample: |
-
| - | List of certificates to be revoked. -Returned: success if |
-
| - | 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. -Returned: success -Sample: |
-
| - | Whether the invalidity date extension is critical. -Returned: success -Sample: |
-
| - | The certificate’s issuer. -See Returned: success -Sample: |
-
| - | Whether the certificate issuer extension is critical. -Returned: success -Sample: |
-
| - | The value for the revocation reason extension. -Returned: success -Can only return: -
Sample: |
-
| - | Whether the revocation reason extension is critical. -Returned: success -Sample: |
-
| - | The point in time the certificate was revoked as ASN.1 TIME. -Returned: success -Sample: |
-
| - | Serial number of the certificate. -This return value is an integer. If you need the serial numbers as a colon-separated hex string, such as Returned: success -Sample: |
-
- Note
-This module is part of the community.crypto collection (version 2.26.6).
-It is not included in ansible-core.
-To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install community.crypto.
-You need further requirements to be able to use this module,
-see Requirements for details.
To use it in a playbook, specify: community.crypto.x509_crl_info.
New in community.crypto 1.0.0
- -This module allows one to retrieve information on Certificate Revocation Lists (CRLs).
The below requirements are needed on the host that executes this module.
-If name_encoding is set to another value than ignore, the idna Python library needs to be installed.
cryptography >= 1.2
Parameter |
-Comments |
-
|---|---|
| - | - |
| - | If set to 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. -Choices: -
|
-
| - | How to encode names (DNS names, URIs, email addresses) in return values. -
Note that Choices: -
|
-
| - | - |
Attribute |
-Support |
-Description |
-
|---|---|---|
| - | Support: full -This action does not modify state. - |
-Can run in |
-
| - | Support: N/A -This action does not modify state. - |
-Will return details on what has changed (or possibly needs changing in |
-
| - | Support: full -This action does not modify state. - |
-When run twice in a row outside check mode, with the same arguments, the second invocation indicates no change. -This assumes that the system controlled/queried by the module has not changed in a relevant way. - |
-
Note
-All timestamp values are provided in ASN.1 TIME format, in other words, following the YYYYMMDDHHMMSSZ pattern. They are all in UTC.
See also
-Generate Certificate Revocation Lists (CRLs).
-A filter variant of this module.
-Convert an integer to a colon-separated list of hex numbers.
----
-- name: Get information on CRL
- community.crypto.x509_crl_info:
- path: /etc/ssl/my-ca.crl
- register: result
-
-- name: Print the information
- ansible.builtin.debug:
- msg: "{{ result }}"
-
-- name: Get information on CRL without list of revoked certificates
- community.crypto.x509_crl_info:
- path: /etc/ssl/very-large.crl
- list_revoked_certificates: false
- register: result
-Common return values are documented here, the following are the fields unique to this module:
-Key |
-Description |
-
|---|---|
| - | The signature algorithm used to sign the CRL. -Returned: success -Sample: |
-
| - | Whether the CRL is in PEM format ( Returned: success -Can only return: -
Sample: |
-
| - | The CRL’s issuer. -Note that for repeated values, only the last one will be returned. -See Returned: success -Sample: |
-
| - | The CRL’s issuer as an ordered list of tuples. -Returned: success -Sample: |
-
| - | The point in time from which this CRL can be trusted as ASN.1 TIME. -Returned: success -Sample: |
-
| - | 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 -Sample: |
-
| - | List of certificates to be revoked. -Returned: success if |
-
| - | 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. -Returned: success -Sample: |
-
| - | Whether the invalidity date extension is critical. -Returned: success -Sample: |
-
| - | The certificate’s issuer. -See Returned: success -Sample: |
-
| - | Whether the certificate issuer extension is critical. -Returned: success -Sample: |
-
| - | The value for the revocation reason extension. -Returned: success -Can only return: -
Sample: |
-
| - | Whether the revocation reason extension is critical. -Returned: success -Sample: |
-
| - | The point in time the certificate was revoked as ASN.1 TIME. -Returned: success -Sample: |
-
| - | Serial number of the certificate. -This return value is an integer. If you need the serial numbers as a colon-separated hex string, such as Returned: success -Sample: |
-
- Note
-This module is part of the community.crypto collection (version 2.26.6).
-It is not included in ansible-core.
-To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install community.crypto.
-You need further requirements to be able to use this module,
-see Requirements for details.
To use it in a playbook, specify: community.crypto.x509_crl.
New in community.crypto 1.0.0
- -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.
The below requirements are needed on the host that executes this module.
-If name_encoding is set to another value than ignore, the idna Python library needs to be installed.
cryptography >= 1.2
Parameter |
-Comments |
-
|---|---|
| - | The attributes the resulting filesystem object should have. -To get supported flags look at the man page for This string should contain the attributes in the same order as the one displayed by The |
-
| - | 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. -Choices: -
|
-
| - | Defines how to process entries of existing CRLs. -If set to If set to The default value is This parameter was called Choices: -
|
-
| - | Digest algorithm to be used when signing the CRL. -Default: |
-
| - | Should the CRL be forced to be regenerated. -Choices: -
|
-
| - | Whether the CRL file should be in PEM or DER format. -If an existing CRL file does match everything but Choices: -
|
-
| - | Name of the group that should own the filesystem object, as would be fed to When left unspecified, it uses the current group of the current user unless you are root, in which case it can preserve the previous ownership. - |
-
| - | Whether the timestamps Use this in combination with relative timestamps for these values to get idempotency. -Choices: -
|
-
| - | 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 One of Mutually exclusive with |
-
| - | 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 Mutually exclusive with |
-
| - | 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 Note that if using relative time this module is NOT idempotent, except when Default: |
-
| - | - |
| - | How to encode names (DNS names, URIs, email addresses) in return values. -
Note that Choices: -
|
-
| - | The absolute latest point in time by which this Time can be specified either as relative time or as absolute timestamp. -Time will always be interpreted as UTC. -Valid format is Note that if using relative time this module is NOT idempotent, except when Required if |
-
| - | Name of the user that should own the filesystem object, as would be fed to When left unspecified, it uses the current user unless you are root, in which case it can preserve the previous ownership. -Specifying a numeric username will be assumed to be a user ID and not a username. Avoid numeric usernames to avoid this confusion. - |
-
| - | Remote absolute path where the generated CRL file should be created or is already located. - |
-
| - | The content of the CA’s private key to use when signing the CRL. -Either |
-
| - | The passphrase for the This is required if the private key is password protected. - |
-
| - | Path to the CA’s private key to use when signing the CRL. -Either |
-
| - | If set to Choices: -
|
-
| - | List of certificates to be revoked. -Required if |
-
| - | Content of a certificate in PEM format. -The serial number and issuer will be extracted from the certificate. -Mutually exclusive with |
-
| - | 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 Note that if using relative time this module is NOT idempotent. This will NOT change when |
-
| - | Whether the invalidity date extension should be critical. -Choices: -
|
-
| - | The certificate’s issuer. -Example: |
-
| - | Whether the certificate issuer extension should be critical. -Choices: -
|
-
| - | Path to a certificate in PEM format. -The serial number and issuer will be extracted from the certificate. -Mutually exclusive with |
-
| - | The value for the revocation reason extension. -Choices: -
|
-
| - | Whether the revocation reason extension should be critical. -Choices: -
|
-
| - | 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 Note that if using relative time this module is NOT idempotent, except when Default: |
-
| - | Serial number of the certificate. -Mutually exclusive with This option accepts integers or hex octet strings, depending on the value of If If You can use the filters community.crypto.parse_serial and community.crypto.to_serial to convert these two representations. - |
-
| - | The level part of the SELinux filesystem object context. -This is the MLS/MCS attribute, sometimes known as the When set to |
-
| - | This option determines which values will be accepted for If set to If set to Choices: -
|
-
| - | The role part of the SELinux filesystem object context. -When set to |
-
| - | The type part of the SELinux filesystem object context. -When set to |
-
| - | The user part of the SELinux filesystem object context. -By default it uses the When set to |
-
| - | Whether the CRL file should exist or not, taking action if the state is different from what is stated. -Choices: -
|
-
| - | Influence when to use atomic operation to prevent data corruption or inconsistent reads from the target filesystem object. -By default this module uses atomic operations to prevent data corruption or inconsistent reads from the target filesystem objects, but sometimes systems are configured or just broken in ways that prevent this. One example is docker mounted filesystem objects, which cannot be updated atomically from inside the container and can only be written in an unsafe manner. -This option allows Ansible to fall back to unsafe methods of updating filesystem objects when atomic operations fail (however, it doesn’t force Ansible to perform unsafe writes). -IMPORTANT! Unsafe writes are subject to race conditions and can lead to data corruption. -Choices: -
|
-
Attribute |
-Support |
-Description |
-
|---|---|---|
| - | Support: full - |
-Can run in |
-
| - | Support: full - |
-Will return details on what has changed (or possibly needs changing in |
-
| - | Support: partial -The module is not idempotent if If relative timestamps and |
-When run twice in a row outside check mode, with the same arguments, the second invocation indicates no change. -This assumes that the system controlled/queried by the module has not changed in a relevant way. - |
-
| - | Support: full - |
-Uses Ansible’s strict file operation functions to ensure proper permissions and avoid data corruption. - |
-
Note
-All ASN.1 TIME values should be specified following the YYYYMMDDHHMMSSZ pattern.
Date specified should be UTC. Minutes and seconds are mandatory.
See also
-Convert a serial number as a colon-separated list of hex numbers to an integer.
-Convert an integer to a colon-separated list of hex numbers.
----
-- name: Generate a CRL
- community.crypto.x509_crl:
- path: /etc/ssl/my-ca.crl
- privatekey_path: /etc/ssl/private/my-ca.pem
- issuer:
- CN: My CA
- last_update: "+0s"
- next_update: "+7d"
- revoked_certificates:
- - serial_number: 1234
- revocation_date: 20190331202428Z
- issuer:
- CN: My CA
- - serial_number: 2345
- revocation_date: 20191013152910Z
- reason: affiliation_changed
- invalidity_date: 20191001000000Z
- - path: /etc/ssl/crt/revoked-cert.pem
- revocation_date: 20191010010203Z
-Common return values are documented here, the following are the fields unique to this module:
-Key |
-Description |
-
|---|---|
| - | Name of backup file created. -Returned: changed and if Sample: |
-
| - | The (current or generated) CRL’s content. -Will be the CRL itself if Returned: if |
-
| - | The signature algorithm used to sign the CRL. -Returned: success -Sample: |
-
| - | Path to the generated CRL. -Returned: changed or success -Sample: |
-
| - | Whether the CRL is in PEM format ( Returned: success -Can only return: -
Sample: |
-
| - | The CRL’s issuer. -Note that for repeated values, only the last one will be returned. -See Returned: success -Sample: |
-
| - | The CRL’s issuer as an ordered list of tuples. -Returned: success -Sample: |
-
| - | The point in time from which this CRL can be trusted as ASN.1 TIME. -Returned: success -Sample: |
-
| - | 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 -Sample: |
-
| - | Path to the private CA key. -Returned: changed or success -Sample: |
-
| - | List of certificates to be revoked. -Returned: success - |
-
| - | 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. -Returned: success -Sample: |
-
| - | Whether the invalidity date extension is critical. -Returned: success -Sample: |
-
| - | The certificate’s issuer. -See Returned: success -Sample: |
-
| - | Whether the certificate issuer extension is critical. -Returned: success -Sample: |
-
| - | The value for the revocation reason extension. -Returned: success -Can only return: -
Sample: |
-
| - | Whether the revocation reason extension is critical. -Returned: success -Sample: |
-
| - | The point in time the certificate was revoked as ASN.1 TIME. -Returned: success -Sample: |
-
| - | Serial number of the certificate. -This return value is an integer. If you need the serial numbers as a colon-separated hex string, such as Returned: success -Sample: |
-