Try SpotterGenerate Certificate Revocation Lists (CRLs)
| "added in version" 1.0.0 of community.crypto"
Authors: Felix Fontein (@felixfontein)
Install with ansible-galaxy collection install community.crypto:==2.18.0
collections:
- name: community.crypto
version: 2.18.0This 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.
- 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
mode:
choices:
- generate
- update
description:
- This parameter has been renamed to O(crl_mode). The old name O(mode) is now deprecated
and will be removed in community.crypto 3.0.0. Replace usage of this parameter with
O(crl_mode).
- Note that from community.crypto 3.0.0 on, O(mode) will be used for the CRL file's
mode.
type: str
path:
description:
- Remote absolute path where the generated CRL file should be created or is already
located.
required: true
type: path
force:
default: false
description:
- Should the CRL be forced to be regenerated.
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 CRL file 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 CRL back
if you overwrote it with a new one by accident.
type: bool
digest:
default: sha256
description:
- Digest algorithm to be used when signing the CRL.
type: str
format:
choices:
- pem
- der
default: pem
description:
- Whether the CRL file should be in PEM or DER format.
- If an existing CRL file does match everything but O(format), it will be converted
to the correct format instead of regenerated.
type: str
issuer:
description:
- Key/value pairs that will be present in the issuer name field of the CRL.
- If you need to specify more than one value with the same key, use a list as value.
- If the order of the components is important, use O(issuer_ordered).
- One of O(issuer) and O(issuer_ordered) is required if O(state) is V(present).
- Mutually exclusive with O(issuer_ordered).
type: dict
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
crl_mode:
choices:
- generate
- update
description:
- Defines how to process entries of existing CRLs.
- If set to V(generate), makes sure that the CRL has the exact set of revoked certificates
as specified in O(revoked_certificates).
- If set to V(update), makes sure that the CRL contains the revoked certificates from
O(revoked_certificates), but can also contain other revoked certificates. If the
CRL file already exists, all entries from the existing CRL will also be included
in the new CRL. When using V(update), you might be interested in setting O(ignore_timestamps)
to V(true).
- The default value is V(generate).
- This parameter was called O(mode) before community.crypto 2.13.0. It has been renamed
to avoid a collision with the common O(mode) parameter for setting the CRL file's
access mode.
type: str
version_added: 2.13.0
version_added_collection: community.crypto
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
last_update:
default: +0s
description:
- The point in time from which this CRL can be trusted.
- Time can be specified either as relative time or as absolute timestamp.
- Time will always be interpreted as UTC.
- Valid format is C([+-]timespec | ASN.1 TIME) where timespec can be an integer +
C([w | d | h | m | s]) (for example V(+32w1d2h)).
- Note that if using relative time this module is NOT idempotent, except when O(ignore_timestamps)
is set to V(true).
type: str
next_update:
description:
- The absolute latest point in time by which this O(issuer) is expected to have issued
another CRL. Many clients will treat a CRL as expired once O(next_update) occurs.
- Time can be specified either as relative time or as absolute timestamp.
- Time will always be interpreted as UTC.
- Valid format is C([+-]timespec | ASN.1 TIME) where timespec can be an integer +
C([w | d | h | m | s]) (for example V(+32w1d2h)).
- Note that if using relative time this module is NOT idempotent, except when O(ignore_timestamps)
is set to V(true).
- Required if O(state) is V(present).
type: str
name_encoding:
choices:
- ignore
- idna
- unicode
default: ignore
description:
- How to encode names (DNS names, URIs, email addresses) in return values.
- V(ignore) will use the encoding returned by the backend.
- V(idna) will convert all labels of domain names to IDNA encoding. IDNA2008 will
be preferred, and IDNA2003 will be used if IDNA2008 encoding fails.
- V(unicode) will convert all labels of domain names to Unicode. IDNA2008 will be
preferred, and IDNA2003 will be used if IDNA2008 decoding fails.
- B(Note) that V(idna) and V(unicode) require the L(idna Python library,https://pypi.org/project/idna/)
to be installed.
type: str
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
issuer_ordered:
description:
- A list of dictionaries, where every dictionary must contain one key/value pair.
This key/value pair will be present in the issuer name field of the CRL.
- If you want to specify more than one value with the same key in a row, you can use
a list as value.
- One of O(issuer) and O(issuer_ordered) is required if O(state) is V(present).
- Mutually exclusive with O(issuer).
elements: dict
type: list
version_added: 2.0.0
version_added_collection: community.crypto
return_content:
default: false
description:
- If set to V(true), will return the (current or generated) CRL's content as RV(crl).
type: bool
serial_numbers:
choices:
- integer
- hex-octets
default: integer
description:
- This option determines which values will be accepted for O(revoked_certificates[].serial_number).
- If set to V(integer) (default), serial numbers are assumed to be integers, for example
V(66223). (This example value is equivalent to the hex octet string V(01:02:AF).)
- If set to V(hex-octets), serial numbers are assumed to be colon-separated hex octet
strings, for example V(01:02:AF). (This example value is equivalent to the integer
V(66223).)
type: str
version_added: 2.18.0
version_added_collection: community.crypto
privatekey_path:
description:
- Path to the CA's private key to use when signing the CRL.
- Either O(privatekey_path) or O(privatekey_content) must be specified if O(state)
is V(present), but not both.
type: path
ignore_timestamps:
default: false
description:
- Whether the timestamps O(last_update), O(next_update) and O(revoked_certificates[].revocation_date)
should be ignored for idempotency checks. The timestamp O(revoked_certificates[].invalidity_date)
will never be ignored.
- Use this in combination with relative timestamps for these values to get idempotency.
type: bool
privatekey_content:
description:
- The content of the CA's private key to use when signing the CRL.
- Either O(privatekey_path) or O(privatekey_content) must be specified if O(state)
is V(present), but not both.
type: str
revoked_certificates:
description:
- List of certificates to be revoked.
- Required if O(state) is V(present).
elements: dict
suboptions:
content:
description:
- Content of a certificate in PEM format.
- The serial number and issuer will be extracted from the certificate.
- Mutually exclusive with O(revoked_certificates[].path) and O(revoked_certificates[].serial_number).
One of these three options must be specified.
type: str
invalidity_date:
description:
- The point in time it was known/suspected that the private key was compromised
or that the certificate otherwise became invalid.
- Time can be specified either as relative time or as absolute timestamp.
- Time will always be interpreted as UTC.
- Valid format is C([+-]timespec | ASN.1 TIME) where timespec can be an integer
+ C([w | d | h | m | s]) (for example V(+32w1d2h)).
- Note that if using relative time this module is NOT idempotent. This will NOT
change when O(ignore_timestamps) is set to V(true).
type: str
invalidity_date_critical:
default: false
description:
- Whether the invalidity date extension should be critical.
type: bool
issuer:
description:
- The certificate's issuer.
- 'Example: V(DNS:ca.example.org)'
elements: str
type: list
issuer_critical:
default: false
description:
- Whether the certificate issuer extension should be critical.
type: bool
path:
description:
- Path to a certificate in PEM format.
- The serial number and issuer will be extracted from the certificate.
- Mutually exclusive with O(revoked_certificates[].content) and O(revoked_certificates[].serial_number).
One of these three options must be specified.
type: path
reason:
choices:
- unspecified
- key_compromise
- ca_compromise
- affiliation_changed
- superseded
- cessation_of_operation
- certificate_hold
- privilege_withdrawn
- aa_compromise
- remove_from_crl
description:
- The value for the revocation reason extension.
type: str
reason_critical:
default: false
description:
- Whether the revocation reason extension should be critical.
type: bool
revocation_date:
default: +0s
description:
- The point in time the certificate was revoked.
- Time can be specified either as relative time or as absolute timestamp.
- Time will always be interpreted as UTC.
- Valid format is C([+-]timespec | ASN.1 TIME) where timespec can be an integer
+ C([w | d | h | m | s]) (for example V(+32w1d2h)).
- Note that if using relative time this module is NOT idempotent, except when
O(ignore_timestamps) is set to V(true).
type: str
serial_number:
description:
- Serial number of the certificate.
- Mutually exclusive with O(revoked_certificates[].path) and O(revoked_certificates[].content).
One of these three options must be specified.
- This option accepts integers or hex octet strings, depending on the value of
O(serial_numbers).
- If O(serial_numbers=integer), integers such as V(66223) must be provided.
- If O(serial_numbers=hex-octets), strings such as V(01:02:AF) must be provided.
- You can use the filters P(community.crypto.parse_serial#filter) and P(community.crypto.to_serial#filter)
to convert these two representations.
type: raw
type: list
privatekey_passphrase:
description:
- The passphrase for the O(privatekey_path).
- This is required if the private key is password protected.
type: str
backup_file:
description: Name of backup file created.
returned: changed and if O(backup) is V(true)
sample: /path/to/my-ca.crl.2019-03-09@11:22~
type: str
crl:
description:
- The (current or generated) CRL's content.
- Will be the CRL itself if O(format) is V(pem), and Base64 of the CRL if O(format)
is V(der).
returned: if O(state) is V(present) and O(return_content) is V(true)
type: str
digest:
description: The signature algorithm used to sign the CRL.
returned: success
sample: sha256WithRSAEncryption
type: str
filename:
description: Path to the generated CRL.
returned: changed or success
sample: /path/to/my-ca.crl
type: str
format:
choices:
- pem
- der
description:
- Whether the CRL is in PEM format (V(pem)) or in DER format (V(der)).
returned: success
sample: pem
type: str
issuer:
description:
- The CRL's issuer.
- Note that for repeated values, only the last one will be returned.
- See O(name_encoding) for how IDNs are handled.
returned: success
sample:
commonName: ca.example.com
organizationName: Ansible
type: dict
issuer_ordered:
description: The CRL's issuer as an ordered list of tuples.
elements: list
returned: success
sample:
- - organizationName
- Ansible
- - commonName: ca.example.com
type: list
last_update:
description: The point in time from which this CRL can be trusted as ASN.1 TIME.
returned: success
sample: 20190413202428Z
type: str
next_update:
description: The point in time from which a new CRL will be issued and the client
has to check for it as ASN.1 TIME.
returned: success
sample: 20190413202428Z
type: str
privatekey:
description: Path to the private CA key.
returned: changed or success
sample: /path/to/my-ca.pem
type: str
revoked_certificates:
contains:
invalidity_date:
description: 'The point in time it was known/suspected that the private key
was compromised
or that the certificate otherwise became invalid as ASN.1 TIME.
'
sample: 20190413202428Z
type: str
invalidity_date_critical:
description: Whether the invalidity date extension is critical.
sample: false
type: bool
issuer:
description:
- The certificate's issuer.
- See O(name_encoding) for how IDNs are handled.
elements: str
sample:
- DNS:ca.example.org
type: list
issuer_critical:
description: Whether the certificate issuer extension is critical.
sample: false
type: bool
reason:
choices:
- unspecified
- key_compromise
- ca_compromise
- affiliation_changed
- superseded
- cessation_of_operation
- certificate_hold
- privilege_withdrawn
- aa_compromise
- remove_from_crl
description:
- The value for the revocation reason extension.
sample: key_compromise
type: str
reason_critical:
description: Whether the revocation reason extension is critical.
sample: false
type: bool
revocation_date:
description: The point in time the certificate was revoked as ASN.1 TIME.
sample: 20190413202428Z
type: str
serial_number:
description:
- Serial number of the certificate.
- This return value is an B(integer). If you need the serial numbers as a colon-separated
hex string, such as C(11:22:33), you need to convert it to that form with
P(community.crypto.to_serial#filter).
sample: 1234
type: int
description: List of certificates to be revoked.
elements: dict
returned: success
type: list