community.crypto.x509_crl – Generate Certificate Revocation Lists (CRLs)

Note

This plugin is part of the community.crypto collection (version 1.3.0).

To install it use: ansible-galaxy collection install community.crypto.

To use it in a playbook, specify: community.crypto.x509_crl.

New in version 1.0.0: of community.crypto

Synopsis

  • This module allows one to (re)generate or update Certificate Revocation Lists (CRLs).

  • Certificates on the revocation list can be either specified via serial number and (optionally) their issuer, or as a path to a certificate file in PEM format.

Requirements

The below requirements are needed on the host that executes this module.

  • cryptography >= 1.2

Parameters

Parameter Choices/Defaults Comments
attributes
string
added in 2.3 of ansible.builtin
The attributes the resulting file or directory should have.
To get supported flags look at the man page for chattr on the target system.
This string should contain the attributes in the same order as the one displayed by lsattr.
The = operator is assumed as default, otherwise + or - operators need to be included in the string.

aliases: attr
backup
boolean
    Choices:
  • no ←
  • yes
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.
digest
string
Default:
"sha256"
Digest algorithm to be used when signing the CRL.
force
boolean
    Choices:
  • no ←
  • yes
Should the CRL be forced to be regenerated.
format
string
    Choices:
  • pem ←
  • der
Whether the CRL file should be in PEM or DER format.
If an existing CRL file does match everything but format, it will be converted to the correct format instead of regenerated.
group
string
Name of the group that should own the file/directory, as would be fed to chown.
ignore_timestamps
boolean
    Choices:
  • no ←
  • yes
Whether the timestamps last_update, next_update and revocation_date (in revoked_certificates) should be ignored for idempotency checks. The timestamp invalidity_date in revoked_certificates will never be ignored.
Use this in combination with relative timestamps for these values to get idempotency.
issuer
dictionary
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.
Required if state is present.
last_update
string
Default:
"+0s"
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 [+-]timespec | ASN.1 TIME where timespec can be an integer + [w | d | h | m | s] (e.g. +32w1d2h.
Note that if using relative time this module is NOT idempotent, except when ignore_timestamps is set to yes.
mode
string
    Choices:
  • generate ←
  • update
Defines how to process entries of existing CRLs.
If set to generate, makes sure that the CRL has the exact set of revoked certificates as specified in revoked_certificates.
If set to update, makes sure that the CRL contains the revoked certificates from 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 update, you might be interested in setting ignore_timestamps to yes.
next_update
string
The absolute latest point in time by which this issuer is expected to have issued another CRL. Many clients will treat a CRL as expired once 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 [+-]timespec | ASN.1 TIME where timespec can be an integer + [w | d | h | m | s] (e.g. +32w1d2h.
Note that if using relative time this module is NOT idempotent, except when ignore_timestamps is set to yes.
Required if state is present.
owner
string
Name of the user that should own the file/directory, as would be fed to chown.
path
path / required
Remote absolute path where the generated CRL file should be created or is already located.
privatekey_content
string
The content of the CA's private key to use when signing the CRL.
Either privatekey_path or privatekey_content must be specified if state is present, but not both.
privatekey_passphrase
string
The passphrase for the privatekey_path.
This is required if the private key is password protected.
privatekey_path
path
Path to the CA's private key to use when signing the CRL.
Either privatekey_path or privatekey_content must be specified if state is present, but not both.
return_content
boolean
    Choices:
  • no ←
  • yes
If set to yes, will return the (current or generated) CRL's content as crl.
revoked_certificates
list / elements=dictionary
List of certificates to be revoked.
Required if state is present.
content
string
Content of a certificate in PEM format.
The serial number and issuer will be extracted from the certificate.
Mutually exclusive with path and serial_number. One of these three options must be specified.
invalidity_date
string
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 [+-]timespec | ASN.1 TIME where timespec can be an integer + [w | d | h | m | s] (e.g. +32w1d2h.
Note that if using relative time this module is NOT idempotent. This will NOT change when ignore_timestamps is set to yes.
invalidity_date_critical
boolean
    Choices:
  • no ←
  • yes
Whether the invalidity date extension should be critical.
issuer
list / elements=string
The certificate's issuer.
Example: DNS:ca.example.org
issuer_critical
boolean
    Choices:
  • no ←
  • yes
Whether the certificate issuer extension should be critical.
path
path
Path to a certificate in PEM format.
The serial number and issuer will be extracted from the certificate.
Mutually exclusive with content and serial_number. One of these three options must be specified.
reason
string
    Choices:
  • unspecified
  • key_compromise
  • ca_compromise
  • affiliation_changed
  • superseded
  • cessation_of_operation
  • certificate_hold
  • privilege_withdrawn
  • aa_compromise
  • remove_from_crl
The value for the revocation reason extension.
reason_critical
boolean
    Choices:
  • no ←
  • yes
Whether the revocation reason extension should be critical.
revocation_date
string
Default:
"+0s"
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 [+-]timespec | ASN.1 TIME where timespec can be an integer + [w | d | h | m | s] (e.g. +32w1d2h.
Note that if using relative time this module is NOT idempotent, except when ignore_timestamps is set to yes.
serial_number
integer
Serial number of the certificate.
Mutually exclusive with path and content. One of these three options must be specified.
selevel
string
The level part of the SELinux file context.
This is the MLS/MCS attribute, sometimes known as the range.
When set to _default, it will use the level portion of the policy if available.
serole
string
The role part of the SELinux file context.
When set to _default, it will use the role portion of the policy if available.
setype
string
The type part of the SELinux file context.
When set to _default, it will use the type portion of the policy if available.
seuser
string
The user part of the SELinux file context.
By default it uses the system policy, where applicable.
When set to _default, it will use the user portion of the policy if available.
state
string
    Choices:
  • absent
  • present ←
Whether the CRL file should exist or not, taking action if the state is different from what is stated.
unsafe_writes
boolean
added in 2.2 of ansible.builtin
    Choices:
  • no ←
  • yes
Influence when to use atomic operation to prevent data corruption or inconsistent reads from the target file.
By default this module uses atomic operations to prevent data corruption or inconsistent reads from the target files, but sometimes systems are configured or just broken in ways that prevent this. One example is docker mounted files, 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 files 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.

Notes

Note

  • All ASN.1 TIME values should be specified following the YYYYMMDDHHMMSSZ pattern.

  • Date specified should be UTC. Minutes and seconds are mandatory.

Examples

- 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

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key Returned Description
backup_file
string
changed and if backup is yes
Name of backup file created.

Sample:
/path/to/[email protected]:22~
crl
string
if state is present and return_content is yes
The (current or generated) CRL's content.
Will be the CRL itself if format is pem, and Base64 of the CRL if format is der.

digest
string
success
The signature algorithm used to sign the CRL.

Sample:
sha256WithRSAEncryption
filename
string
changed or success
Path to the generated CRL

Sample:
/path/to/my-ca.crl
format
string
success
Whether the CRL is in PEM format (pem) or in DER format (der).

Sample:
pem
issuer
dictionary
success
The CRL's issuer.
Note that for repeated values, only the last one will be returned.

Sample:
{"organizationName": "Ansible", "commonName": "ca.example.com"}
issuer_ordered
list / elements=list
success
The CRL's issuer as an ordered list of tuples.

Sample:
[["organizationName", "Ansible"], ["commonName": "ca.example.com"]]
last_update
string
success
The point in time from which this CRL can be trusted as ASN.1 TIME.

Sample:
20190413202428Z
next_update
string
success
The point in time from which a new CRL will be issued and the client has to check for it as ASN.1 TIME.

Sample:
20190413202428Z
privatekey
string
changed or success
Path to the private CA key

Sample:
/path/to/my-ca.pem
revoked_certificates
list / elements=dictionary
success
List of certificates to be revoked.

 
invalidity_date
string
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.

Sample:
20190413202428Z
 
invalidity_date_critical
boolean
success
Whether the invalidity date extension is critical.

 
issuer
list / elements=string
success
The certificate's issuer.

Sample:
["DNS:ca.example.org"]
 
issuer_critical
boolean
success
Whether the certificate issuer extension is critical.

 
reason
string
success
The value for the revocation reason extension.
One of unspecified, key_compromise, ca_compromise, affiliation_changed, superseded, cessation_of_operation, certificate_hold, privilege_withdrawn, aa_compromise, and remove_from_crl.

Sample:
key_compromise
 
reason_critical
boolean
success
Whether the revocation reason extension is critical.

 
revocation_date
string
success
The point in time the certificate was revoked as ASN.1 TIME.

Sample:
20190413202428Z
 
serial_number
integer
success
Serial number of the certificate.

Sample:
1234


Authors

  • Felix Fontein (@felixfontein)