Documentation

openssl_csr - Generate OpenSSL Certificate Signing Request (CSR)

New in version 2.4.

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.

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


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.