community.crypto.x509_crl module – Generate Certificate Revocation Lists (CRLs)
Note
This module is part of the community.crypto collection (version 2.3.4).
You might already have this collection installed if you are using the ansible package.
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.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 by 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.
If name_encoding is set to another value than
ignore, the idna Python library needs to be installed.cryptography >= 1.2
Parameters
Parameter |
Comments |
|---|---|
The attributes the resulting filesystem object 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 |
|
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:
|
|
Digest algorithm to be used when signing the CRL. Default: “sha256” |
|
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 format, it will be converted to the correct format instead of regenerated. Choices:
|
|
Name of the group that should own the filesystem object, as would be fed to chown. |
|
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. 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 issuer_ordered. One of issuer and issuer_ordered is required if state is Mutually exclusive with issuer_ordered. |
|
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 issuer and issuer_ordered is required if state is Mutually exclusive with issuer. |
|
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 ignore_timestamps is set to Default: “+0s” |
|
Defines how to process entries of existing CRLs. If set to If set to Choices:
|
|
How to encode names (DNS names, URIs, email addresses) in return values.
Note that Choices:
|
|
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 Note that if using relative time this module is NOT idempotent, except when ignore_timestamps is set to Required if state is |
|
Name of the user that should own the filesystem object, as would be fed to chown. |
|
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 privatekey_path or privatekey_content must be specified if state is |
|
The passphrase for the privatekey_path. This is required if the private key is password protected. |
|
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 |
|
If set to Choices:
|
|
List of certificates to be revoked. Required if state is |
|
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. |
|
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 ignore_timestamps is set to |
|
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 content and serial_number. One of these three options must be specified. |
|
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 ignore_timestamps is set to Default: “+0s” |
|
Serial number of the certificate. Mutually exclusive with path and content. One of these three options must be specified. |
|
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 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 objecs, 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:
|
Notes
Note
All ASN.1 TIME values should be specified following the YYYYMMDDHHMMSSZ pattern.
Date specified should be UTC. Minutes and seconds are mandatory.
Supports
check_mode.
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 |
Description |
|---|---|
Name of backup file created. Returned: changed and if backup is Sample: “/path/to/my-ca.crl.2019-03-09@11:22~” |
|
The (current or generated) CRL’s content. Will be the CRL itself if format is Returned: if state is |
|
The signature algorithm used to sign the CRL. Returned: success Sample: “sha256WithRSAEncryption” |
|
Path to the generated CRL. Returned: changed or success Sample: “/path/to/my-ca.crl” |
|
Whether the CRL is in PEM format ( Returned: success Sample: “pem” |
|
The CRL’s issuer. Note that for repeated values, only the last one will be returned. See name_encoding for how IDNs are handled. Returned: success Sample: “{\”organizationName\”: \”Ansible\”, \”commonName\”: \”ca.example.com\”}” |
|
The CRL’s issuer as an ordered list of tuples. Returned: success Sample: “[[\”organizationName\”, \”Ansible\”], [\”commonName\”: \”ca.example.com\”]]” |
|
The point in time from which this CRL can be trusted as ASN.1 TIME. Returned: success Sample: “20190413202428Z” |
|
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” |
|
Path to the private CA key. Returned: changed or success Sample: “/path/to/my-ca.pem” |
|
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: “20190413202428Z” |
|
Whether the invalidity date extension is critical. Returned: success Sample: false |
|
The certificate’s issuer. See name_encoding for how IDNs are handled. Returned: success Sample: “[\”DNS:ca.example.org\”]” |
|
Whether the certificate issuer extension is critical. Returned: success Sample: false |
|
The value for the revocation reason extension. One of Returned: success Sample: “key_compromise” |
|
Whether the revocation reason extension is critical. Returned: success Sample: false |
|
The point in time the certificate was revoked as ASN.1 TIME. Returned: success Sample: “20190413202428Z” |
|
Serial number of the certificate. Returned: success Sample: 1234 |
Authors
Felix Fontein (@felixfontein)
Collection links
Issue Tracker Repository (Sources) Submit a bug report Request a feature Communication