community / community.crypto / 2.18.0 / module / x509_certificate_pipe Generate and/or check OpenSSL certificates | "added in version" 1.3.0 of community.crypto" Authors: Yanis Guenane (@Spredzy), Markus Teufelberger (@MarkusTeufelberger), Felix Fontein (@felixfontein)community.crypto.x509_certificate_pipe (2.18.0) — module
Install with ansible-galaxy collection install community.crypto:==2.18.0
collections: - name: community.crypto version: 2.18.0
It implements a notion of provider (one of V(selfsigned), V(ownca), V(entrust)) for your certificate.
It uses the cryptography python library to interact with OpenSSL.
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_pipe: provider: selfsigned privatekey_path: /etc/ssl/private/ansible.com.pem csr_path: /etc/ssl/csr/ansible.com.csr register: result
- name: Print the certificate ansible.builtin.debug: var: result.certificate
# In the following example, both CSR and certificate file are stored on the # machine where ansible-playbook is executed, while the OwnCA data (certificate, # private key) are stored on the remote machine. - name: (1/2) Generate an OpenSSL Certificate with the CSR provided inline community.crypto.x509_certificate_pipe: provider: ownca content: "{{ lookup('ansible.builtin.file', '/etc/ssl/csr/www.ansible.com.crt') }}" csr_content: "{{ lookup('ansible.builtin.file', '/etc/ssl/csr/www.ansible.com.csr') }}" ownca_cert: /path/to/ca_cert.crt ownca_privatekey: /path/to/ca_cert.key ownca_privatekey_passphrase: hunter2 register: result
- name: (2/2) Store certificate ansible.builtin.copy: dest: /etc/ssl/csr/www.ansible.com.crt content: "{{ result.certificate }}" delegate_to: localhost when: result is changed
# In the following example, the certificate from another machine is signed by # our OwnCA whose private key and certificate are only available on this # machine (where ansible-playbook is executed), without having to write # the certificate file to disk on localhost. The CSR could have been # provided by community.crypto.openssl_csr_pipe earlier, or also have been # read from the remote machine. - name: (1/3) Read certificate's contents from remote machine ansible.builtin.slurp: src: /etc/ssl/csr/www.ansible.com.crt register: certificate_content
- name: (2/3) Generate an OpenSSL Certificate with the CSR provided inline community.crypto.x509_certificate_pipe: provider: ownca content: "{{ certificate_content.content | b64decode }}" csr_content: "{{ the_csr }}" ownca_cert: /path/to/ca_cert.crt ownca_privatekey: /path/to/ca_cert.key ownca_privatekey_passphrase: hunter2 delegate_to: localhost register: result
- name: (3/3) Store certificate ansible.builtin.copy: dest: /etc/ssl/csr/www.ansible.com.crt content: "{{ result.certificate }}" when: result is changed
force: default: false description: - Generate the certificate, even if it already exists. type: bool content: description: - The existing certificate. 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: - entrust - ownca - selfsigned description: - Name of the provider to use to generate/retrieve the OpenSSL certificate. - The V(entrust) provider requires credentials for the L(Entrust Certificate Services,https://www.entrustdatacard.com/products/categories/ssl-certificates) (ECS) API. required: true type: str 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 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 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 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 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 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 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
certificate: description: The (current or generated) certificate's content. returned: changed or success type: str