W3cubDocs

/Ansible

openssl_csr - Generate OpenSSL Certificate Signing Request (CSR)

New in version 2.4.

Synopsis
Requirements (on host that executes module)
Options
Examples
Return Values
Notes
- Status

Synopsis

This module allows one to (re)generate OpenSSL certificate signing requests. It uses the pyOpenSSL python library to interact with openssl. This module supports the subjectAltName as well as the keyUsage and extendedKeyUsage extensions. Note: At least one of common_name or subject_alt_name must be specified. This module uses file common arguments to specify generated file permissions.

Requirements (on host that executes module)

python-pyOpenSSL

Options

parameter	required	default	choices	comments
common_name	no			commonName field of the certificate signing request subject aliases: CN, commonName
country_name	no			countryName field of the certificate signing request subject aliases: C, countryName
digest	no	sha256		Digest used when signing the certificate signing request with the private key
email_address	no			emailAddress field of the certificate signing request subject aliases: E, emailAddress
extended_key_usage	no			Additional restrictions (e.g. client authentication, server authentication) on the allowed purposes for which the public key may be used. This can either be a 'comma separated string' or a YAML list. aliases: extKeyUsage, extendedKeyUsage
extended_key_usage_critical	no			Should the extkeyUsage extension be considered as critical aliases: extKeyUsage_critical, extendedKeyUsage_critical
force	no		True False	Should the certificate signing request be forced regenerated by this ansible module
key_usage	no			This defines the purpose (e.g. encipherment, signature, certificate signing) of the key contained in the certificate. This can either be a 'comma separated string' or a YAML list. aliases: keyUsage
key_usage_critical	no			Should the keyUsage extension be considered as critical aliases: keyUsage_critical
locality_name	no			localityName field of the certificate signing request subject aliases: L, localityName
organization_name	no			organizationName field of the certificate signing request subject aliases: O, organizationName
organizational_unit_name	no			organizationalUnitName field of the certificate signing request subject aliases: OU, organizationalUnitName
path	yes			Name of the folder in which the generated OpenSSL certificate signing request will be written
privatekey_passphrase	no			The passphrase for the privatekey.
privatekey_path	yes			Path to the privatekey to use when signing the certificate signing request
state	no	present	present absent	Whether the certificate signing request should exist or not, taking action if the state is different from what is stated.
state_or_province_name	no			stateOrProvinceName field of the certificate signing request subject aliases: ST, stateOrProvinceName
subject_alt_name	no			SAN extension to attach to the certificate signing request This can either be a 'comma separated string' or a YAML list. aliases: subjectAltName
subject_alt_name_critical	no			Should the subjectAltName extension be considered as critical aliases: subjectAltName_critical
version	no	3		Version of the certificate signing request

Examples

# Generate an OpenSSL Certificate Signing Request
- openssl_csr:
    path: /etc/ssl/csr/www.ansible.com.csr
    privatekey_path: /etc/ssl/private/ansible.com.pem
    common_name: www.ansible.com

# Generate an OpenSSL Certificate Signing Request with a
# passphrase protected private key
- openssl_csr:
    path: /etc/ssl/csr/www.ansible.com.csr
    privatekey_path: /etc/ssl/private/ansible.com.pem
    privatekey_passphrase: ansible
    common_name: www.ansible.com

# Generate an OpenSSL Certificate Signing Request with Subject information
- openssl_csr:
    path: /etc/ssl/csr/www.ansible.com.csr
    privatekey_path: /etc/ssl/private/ansible.com.pem
    country_name: FR
    organization_name: Ansible
    email_address: [email protected]
    common_name: www.ansible.com

# Generate an OpenSSL Certificate Signing Request with subjectAltName extension
- openssl_csr:
    path: /etc/ssl/csr/www.ansible.com.csr
    privatekey_path: /etc/ssl/private/ansible.com.pem
    subject_alt_name: 'DNS:www.ansible.com,DNS:m.ansible.com'

# Force re-generate an OpenSSL Certificate Signing Request
- openssl_csr:
    path: /etc/ssl/csr/www.ansible.com.csr
    privatekey_path: /etc/ssl/private/ansible.com.pem
    force: True
    common_name: www.ansible.com

# Generate an OpenSSL Certificate Signing Request with special key usages
- openssl_csr:
    path: /etc/ssl/csr/www.ansible.com.csr
    privatekey_path: /etc/ssl/private/ansible.com.pem
    common_name: www.ansible.com
    key_usage:
      - digitlaSignature
      - keyAgreement
    extended_key_usage:
      - clientAuth

Return Values

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

name	description	returned	type	sample
keyUsage	Purpose for which the public key may be used	changed or success	list	['digitalSignature', 'keyAgreement']
extendedKeyUsage	Additional restriction on the public key purposes	changed or success	list	['clientAuth']
subjectAltName	The alternative names this CSR is valid for	changed or success	list	['DNS:www.ansible.com', 'DNS:m.ansible.com']
subject	A dictionnary of the subject attached to the CSR	changed or success	list	{'CN': 'www.ansible.com', 'O': 'Ansible'}
privatekey	Path to the TLS/SSL private key the CSR was generated for	changed or success	string	/etc/ssl/private/ansible.com.pem
filename	Path to the generated Certificate Signing Request	changed or success	string	/etc/ssl/csr/www.ansible.com.csr

Notes

Note

If the certificate signing request already exists it will be checked whether subjectAltName, keyUsage and extendedKeyUsage only contain the requested values and if the request was signed by the given private key

Status

This module is flagged as preview which means that it is not guaranteed to have a backwards compatible interface.

For help in developing on modules, should you be so inclined, please read Community Information & Contributing, Testing Ansible and Developing Modules.

© 2012–2017 Michael DeHaan
© 2017 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/openssl_csr_module.html