Try SpotterGenerate and/or check OpenSSL certificates
Authors: Yanis Guenane (@Spredzy), Markus Teufelberger (@MarkusTeufelberger)
Install with ansible-galaxy collection install community.crypto:==2.18.0
collections:
- name: community.crypto
version: 2.18.0It implements a notion of provider (one of V(selfsigned), V(ownca), V(acme), and V(entrust)) for your certificate.
It uses the cryptography python library to interact with OpenSSL.
Note that this module was called C(openssl_certificate) when included directly in Ansible up to version 2.9. When moved to the collection C(community.crypto), it was renamed to M(community.crypto.x509_certificate). From Ansible 2.10 on, it can still be used by the old short name (or by C(ansible.builtin.openssl_certificate)), which redirects to M(community.crypto.x509_certificate). When using FQCNs or when using the L(collections,https://docs.ansible.com/ansible/latest/user_guide/collections_using.html#using-collections-in-a-playbook) keyword, the new name M(community.crypto.x509_certificate) should be used to avoid a deprecation warning.
Please note that the module regenerates existing certificate if it does not match the module's options, or if it seems to be corrupt. If you are concerned that this could overwrite your existing certificate, consider using the O(backup) option.
The V(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.
- 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
mode:
description:
- The permissions the resulting filesystem object should have.
- For those used to I(/usr/bin/chmod) remember that modes are actually octal numbers.
You must give Ansible enough information to parse them correctly. For consistent
results, quote octal numbers (for example, V('644') or V('1777')) so Ansible receives
a string and can do its own conversion from string into number. Adding a leading
zero (for example, V(0755)) works sometimes, but can fail in loops and some other
circumstances.
- 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, V(u+rwx)
or V(u=rw,g=r,o=r)).
- If O(mode) is not specified and the destination filesystem object B(does not) exist,
the default C(umask) on the system will be used when setting the mode for the newly
created filesystem object.
- If O(mode) is not specified and the destination filesystem object B(does) exist,
the mode of the existing filesystem object will be used.
- Specifying O(mode) is the best way to ensure filesystem objects are created with
the correct permissions. See CVE-2020-1736 for further details.
type: raw
path:
description:
- Remote absolute path where the generated certificate file should be created or is
already located.
required: true
type: path
force:
default: false
description:
- Generate the certificate, even if it already exists.
type: bool
group:
description:
- Name of the group that should own the filesystem object, as would be fed to I(chown).
- 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.
type: str
owner:
description:
- Name of the user that should own the filesystem object, as would be fed to I(chown).
- 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.
type: str
state:
choices:
- absent
- present
default: present
description:
- Whether the certificate should exist or not, taking action if the state is different
from what is stated.
type: str
backup:
default: false
description:
- Create a backup file including a timestamp so you can get the original certificate
back if you overwrote it with a new one by accident.
type: bool
serole:
description:
- The role part of the SELinux filesystem object context.
- When set to V(_default), it will use the C(role) portion of the policy if available.
type: str
setype:
description:
- The type part of the SELinux filesystem object context.
- When set to V(_default), it will use the C(type) portion of the policy if available.
type: str
seuser:
description:
- The user part of the SELinux filesystem object context.
- By default it uses the V(system) policy, where applicable.
- When set to V(_default), it will use the C(user) portion of the policy if available.
type: str
selevel:
description:
- The level part of the SELinux filesystem object context.
- This is the MLS/MCS attribute, sometimes known as the C(range).
- When set to V(_default), it will use the C(level) portion of the policy if available.
type: str
csr_path:
description:
- Path to the Certificate Signing Request (CSR) used to generate this certificate.
- This is mutually exclusive with O(csr_content).
type: path
provider:
choices:
- acme
- entrust
- ownca
- selfsigned
description:
- Name of the provider to use to generate/retrieve the OpenSSL certificate. Please
see the examples on how to emulate it with M(community.crypto.x509_certificate_info),
M(community.crypto.openssl_csr_info), M(community.crypto.openssl_privatekey_info)
and M(ansible.builtin.assert).
- The V(entrust) provider was added for Ansible 2.9 and requires credentials for the
L(Entrust Certificate Services,https://www.entrustdatacard.com/products/categories/ssl-certificates)
(ECS) API.
- Required if O(state) is V(present).
type: str
acme_chain:
default: false
description:
- Include the intermediate certificate to the generated certificate
- This is only used by the V(acme) provider.
- Note that this is only available for older versions of C(acme-tiny). New versions
include the chain automatically, and setting O(acme_chain) to V(true) results in
an error.
type: bool
attributes:
aliases:
- attr
description:
- The attributes the resulting filesystem object should have.
- To get supported flags look at the man page for I(chattr) on the target system.
- This string should contain the attributes in the same order as the one displayed
by I(lsattr).
- The C(=) operator is assumed as default, otherwise C(+) or C(-) operators need to
be included in the string.
type: str
version_added: '2.3'
version_added_collection: ansible.builtin
ownca_path:
description:
- Remote absolute path of the CA (Certificate Authority) certificate.
- This is only used by the V(ownca) provider.
- This is mutually exclusive with O(ownca_content).
type: path
csr_content:
description:
- Content of the Certificate Signing Request (CSR) used to generate this certificate.
- This is mutually exclusive with O(csr_path).
type: str
version_added: 1.0.0
version_added_collection: community.crypto
ownca_digest:
default: sha256
description:
- The digest algorithm to be used for the V(ownca) certificate.
- This is only used by the V(ownca) provider.
type: str
ownca_content:
description:
- Content of the CA (Certificate Authority) certificate.
- This is only used by the V(ownca) provider.
- This is mutually exclusive with O(ownca_path).
type: str
version_added: 1.0.0
version_added_collection: community.crypto
ownca_version:
default: 3
description:
- The version of the V(ownca) certificate.
- Nowadays it should almost always be V(3).
- This is only used by the V(ownca) provider.
type: int
unsafe_writes:
default: false
description:
- 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.
type: bool
version_added: '2.2'
version_added_collection: ansible.builtin
acme_directory:
default: https://acme-v02.api.letsencrypt.org/directory
description:
- The ACME directory to use. You can use any directory that supports the ACME protocol,
such as Buypass or Let's Encrypt.
- Let's Encrypt recommends using their staging server while developing jobs. U(https://letsencrypt.org/docs/staging-environment/).
type: str
version_added: 1.0.0
version_added_collection: community.crypto
return_content:
default: false
description:
- If set to V(true), will return the (current or generated) certificate's content
as RV(certificate).
type: bool
version_added: 1.0.0
version_added_collection: community.crypto
entrust_api_key:
description:
- The key (password) for authentication to the Entrust Certificate Services (ECS)
API.
- This is only used by the V(entrust) provider.
- This is required if the provider is V(entrust).
type: str
ownca_not_after:
default: +3650d
description:
- 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 C([+-]timespec | ASN.1 TIME) where timespec can be an integer +
C([w | d | h | m | s]) (for example V(+32w1d2h)).
- If this value is not specified, the certificate will stop being valid 10 years from
now.
- Note that this value is B(not used to determine whether an existing certificate
should be regenerated). This can be changed by setting the O(ignore_timestamps)
option to V(false). Please note that you should avoid relative timestamps when setting
O(ignore_timestamps=false).
- This is only used by the V(ownca) provider.
- On macOS 10.15 and onwards, TLS server certificates must have a validity period
of 825 days or fewer. Please see U(https://support.apple.com/en-us/HT210176) for
more details.
type: str
privatekey_path:
description:
- Path to the private key to use when signing the certificate.
- This is mutually exclusive with O(privatekey_content).
type: path
entrust_api_user:
description:
- The username for authentication to the Entrust Certificate Services (ECS) API.
- This is only used by the V(entrust) provider.
- This is required if the provider is V(entrust).
type: str
ownca_not_before:
default: +0s
description:
- The point in time the certificate is valid from.
- Time can be specified either as relative time or as absolute timestamp.
- Time will always be interpreted as UTC.
- Valid format is C([+-]timespec | ASN.1 TIME) where timespec can be an integer +
C([w | d | h | m | s]) (for example V(+32w1d2h)).
- If this value is not specified, the certificate will start being valid from now.
- Note that this value is B(not used to determine whether an existing certificate
should be regenerated). This can be changed by setting the O(ignore_timestamps)
option to V(false). Please note that you should avoid relative timestamps when setting
O(ignore_timestamps=false).
- This is only used by the V(ownca) provider.
type: str
entrust_cert_type:
choices:
- STANDARD_SSL
- ADVANTAGE_SSL
- UC_SSL
- EV_SSL
- WILDCARD_SSL
- PRIVATE_SSL
- PD_SSL
- CDS_ENT_LITE
- CDS_ENT_PRO
- SMIME_ENT
default: STANDARD_SSL
description:
- Specify the type of certificate requested.
- This is only used by the V(entrust) provider.
type: str
entrust_not_after:
default: +365d
description:
- The point in time at which the certificate stops being valid.
- Time can be specified either as relative time or as an absolute timestamp.
- A valid absolute time format is C(ASN.1 TIME) such as V(2019-06-18).
- A valid relative time format is V([+-]timespec) where timespec can be an integer
+ C([w | d | h | m | s]), such as V(+365d) or V(+32w1d2h)).
- Time will always be interpreted as UTC.
- Note that only the date (day, month, year) is supported for specifying the expiry
date of the issued certificate.
- The full date-time is adjusted to EST (GMT -5:00) before issuance, which may result
in a certificate with an expiration date one day earlier than expected if a relative
time is used.
- The minimum certificate lifetime is 90 days, and maximum is three years.
- If this value is not specified, the certificate will stop being valid 365 days the
date of issue.
- This is only used by the V(entrust) provider.
- Please note that this value is B(not) covered by the O(ignore_timestamps) option.
type: str
ignore_timestamps:
default: true
description:
- Whether the "not before" and "not after" timestamps should be ignored for idempotency
checks.
- It is better to keep the default value V(true) when using relative timestamps (like
V(+0s) for now).
type: bool
version_added: 2.0.0
version_added_collection: community.crypto
selfsigned_digest:
default: sha256
description:
- Digest algorithm to be used when self-signing the certificate.
- This is only used by the V(selfsigned) provider.
type: str
privatekey_content:
description:
- Content of the private key to use when signing the certificate.
- This is mutually exclusive with O(privatekey_path).
type: str
version_added: 1.0.0
version_added_collection: community.crypto
selfsigned_version:
default: 3
description:
- Version of the V(selfsigned) certificate.
- Nowadays it should almost always be V(3).
- This is only used by the V(selfsigned) provider.
type: int
acme_challenge_path:
description:
- The path to the ACME challenge directory that is served on U(http://<HOST>:80/.well-known/acme-challenge/)
- This is only used by the V(acme) provider.
type: path
acme_accountkey_path:
description:
- The path to the accountkey for the V(acme) provider.
- This is only used by the V(acme) provider.
type: path
selfsigned_not_after:
aliases:
- selfsigned_notAfter
default: +3650d
description:
- 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 C([+-]timespec | ASN.1 TIME) where timespec can be an integer +
C([w | d | h | m | s]) (for example V(+32w1d2h)).
- If this value is not specified, the certificate will stop being valid 10 years from
now.
- Note that this value is B(not used to determine whether an existing certificate
should be regenerated). This can be changed by setting the O(ignore_timestamps)
option to V(false). Please note that you should avoid relative timestamps when setting
O(ignore_timestamps=false).
- This is only used by the V(selfsigned) provider.
- On macOS 10.15 and onwards, TLS server certificates must have a validity period
of 825 days or fewer. Please see U(https://support.apple.com/en-us/HT210176) for
more details.
type: str
ownca_privatekey_path:
description:
- Path to the CA (Certificate Authority) private key to use when signing the certificate.
- This is only used by the V(ownca) provider.
- This is mutually exclusive with O(ownca_privatekey_content).
type: path
privatekey_passphrase:
description:
- The passphrase for the O(privatekey_path) resp. O(privatekey_content).
- This is required if the private key is password protected.
type: str
select_crypto_backend:
choices:
- auto
- cryptography
default: auto
description:
- Determines which crypto backend to use.
- The default choice is V(auto), which tries to use C(cryptography) if available.
- If set to V(cryptography), will try to use the L(cryptography,https://cryptography.io/)
library.
type: str
selfsigned_not_before:
aliases:
- selfsigned_notBefore
default: +0s
description:
- The point in time the certificate is valid from.
- Time can be specified either as relative time or as absolute timestamp.
- Time will always be interpreted as UTC.
- Valid format is C([+-]timespec | ASN.1 TIME) where timespec can be an integer +
C([w | d | h | m | s]) (for example V(+32w1d2h)).
- If this value is not specified, the certificate will start being valid from now.
- Note that this value is B(not used to determine whether an existing certificate
should be regenerated). This can be changed by setting the O(ignore_timestamps)
option to V(false). Please note that you should avoid relative timestamps when setting
O(ignore_timestamps=false).
- This is only used by the V(selfsigned) provider.
type: str
entrust_requester_name:
description:
- The name of the requester of the certificate (for tracking purposes).
- This is only used by the V(entrust) provider.
- This is required if the provider is V(entrust).
type: str
entrust_requester_email:
description:
- The email of the requester of the certificate (for tracking purposes).
- This is only used by the V(entrust) provider.
- This is required if the provider is V(entrust).
type: str
entrust_requester_phone:
description:
- The phone number of the requester of the certificate (for tracking purposes).
- This is only used by the V(entrust) provider.
- This is required if the provider is V(entrust).
type: str
ownca_privatekey_content:
description:
- Content of the CA (Certificate Authority) private key to use when signing the certificate.
- This is only used by the V(ownca) provider.
- This is mutually exclusive with O(ownca_privatekey_path).
type: str
version_added: 1.0.0
version_added_collection: community.crypto
ownca_privatekey_passphrase:
description:
- The passphrase for the O(ownca_privatekey_path) resp. O(ownca_privatekey_content).
- This is only used by the V(ownca) provider.
type: str
entrust_api_client_cert_path:
description:
- The path to the client certificate used to authenticate to the Entrust Certificate
Services (ECS) API.
- This is only used by the V(entrust) provider.
- This is required if the provider is V(entrust).
type: path
entrust_api_specification_path:
default: https://cloud.entrust.net/EntrustCloud/documentation/cms-api-2.1.0.yaml
description:
- The path to the specification file defining the Entrust Certificate Services (ECS)
API configuration.
- You can use this to keep a local copy of the specification to avoid downloading
it every time the module is used.
- This is only used by the V(entrust) provider.
type: path
entrust_api_client_cert_key_path:
description:
- The path to the private key of the client certificate used to authenticate to the
Entrust Certificate Services (ECS) API.
- This is only used by the V(entrust) provider.
- This is required if the provider is V(entrust).
type: path
ownca_create_subject_key_identifier:
choices:
- create_if_not_provided
- always_create
- never_create
default: create_if_not_provided
description:
- Whether to create the Subject Key Identifier (SKI) from the public key.
- A value of V(create_if_not_provided) (default) only creates a SKI when the CSR does
not provide one.
- A value of V(always_create) always creates a SKI. If the CSR provides one, that
one is ignored.
- A value of V(never_create) never creates a SKI. If the CSR provides one, that one
is used.
- This is only used by the V(ownca) provider.
- Note that this is only supported if the C(cryptography) backend is used!
type: str
ownca_create_authority_key_identifier:
default: true
description:
- 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 V(ownca) provider.
- Note that this is only supported if the C(cryptography) backend is used!
type: bool
selfsigned_create_subject_key_identifier:
choices:
- create_if_not_provided
- always_create
- never_create
default: create_if_not_provided
description:
- Whether to create the Subject Key Identifier (SKI) from the public key.
- A value of V(create_if_not_provided) (default) only creates a SKI when the CSR does
not provide one.
- A value of V(always_create) always creates a SKI. If the CSR provides one, that
one is ignored.
- A value of V(never_create) never creates a SKI. If the CSR provides one, that one
is used.
- This is only used by the V(selfsigned) provider.
- Note that this is only supported if the C(cryptography) backend is used!
type: str
backup_file: description: Name of backup file created. returned: changed and if O(backup) is V(true) sample: /path/to/www.ansible.com.crt.2019-03-09@11:22~ type: str certificate: description: The (current or generated) certificate's content. returned: if O(state) is V(present) and O(return_content) is V(true) type: str version_added: 1.0.0 version_added_collection: community.crypto filename: description: Path to the generated certificate. returned: changed or success sample: /etc/ssl/crt/www.ansible.com.crt type: str