community / community.crypto / 2.18.0 / module / x509_crl Generate Certificate Revocation Lists (CRLs) | "added in version" 1.0.0 of community.crypto" Authors: Felix Fontein (@felixfontein)community.crypto.x509_crl (2.18.0) — module
Install with ansible-galaxy collection install community.crypto:==2.18.0
collections: - name: community.crypto version: 2.18.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.
- 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