Resource Type: openssl_request

Defined in:
lib/puppet/type/openssl_request.rb

Summary

Create and maintain an OpenSSL Certificate Signing Request

Overview

**This type is still beta!**

The type creates a X.509 Certificate Signing Request (CSR) which can either be submitted to a Certificate Authority (CA) for signing or used to create a self-signed certificate. Both operations can also be performed using the ‘openssl_cert` type.

The X.509 subject of the request can be defined by using the ‘common_name`, `domain_component`, `organization_unit_name`, `organization_name`, `locality_name`, `state_or_province_name`, `country_name` and `email_address` parameters. Setting a Common Name is mandatory and the host fully-qualified domain name (FQDN) is commonly used for node or service certificates.

The request can also include the following extensions by setting the appropriate type parameters: ‘basicConstraints`, `keyUsage`, `extendedKeyUsage` and `subjectAltName`.

The type expects to find the “—–BEGIN CERTIFICATE REQUEST—–” token in the file or it will overwrite the file content with a new request.

The type is refreshable and will generate a new request if the resource is notified from another resource.

This type uses the Ruby OpenSSL library and does not need the ‘openssl` binary provided by the operating system.

Autorequires: If Puppet is managing the OpenSSL key that is used to create the CSR, the ‘openssl_request` resource will autorequire that key.

Examples:

Generate CSR to be used for a private Certificate Authority


openssl_request { '/etc/ssl/ca.csr':
  key              => '/etc/ssl/ca.key',
  common_name      => 'ACME Root CA',
  domain_component => [ 'ACME', 'US' ],
}

Generate CSR for a web application


openssl_request { "/etc/ssl/app.example.com.csr":
  key                         => '/etc/ssl/app.example.com.key',
  common_name                 => 'app.example.com',
  key_usage                   => ['keyEncipherment', 'digitalSignature'],
  extended_key_usage          => ['serverAuth', 'clientAuth'],
  subject_alternate_names_dns => ['app.example.com'],
  subject_alternate_names_ip  => ['192.0.2.42'],
}

Properties

  • ensure (defaults to: present)

    The basic property that the resource should be in.

    Supported values:
    • present
    • absent

Parameters

  • backup

    Specifies whether (and how) to back up the destination file before overwriting it. Your value gets passed on to Puppet’s native file resource for execution. Valid options: true, false, or a string representing either a target filebucket or a filename extension beginning with “.”.

  • basic_constraints_ca

    Whether the Basic Constraints CA extension should be set.

    Supported values:
    • true
    • false
    • yes
    • no
  • basic_constraints_ca_critical

    Whether the Basic Constraints CA extension should be critical.

    Supported values:
    • true
    • false
    • yes
    • no
  • common_name

    The value of the X.509 common name (CN) attribute.

  • country_name

    The value of the X.509 country © attribute.

  • domain_component

    The value of the X.509 domain component (DC) attributes. The value should be an array. The items are used in the same order, so for example the value ‘[’example’, ‘com’]‘ should be used to create the attribute `DC=example, DC=com` in the request.

  • email_address

    The value of the X.509 emailAddress attribute.

  • extended_key_usage

    The X.509v3 Extended Key Usage extension.

  • extended_key_usage_critical

    Whether the Extenden Key Usage extension should be critical.

    Supported values:
    • true
    • false
    • yes
    • no
  • group

    Specifies a permissions group for the destination file. Valid options: a string containing a group name or integer containing a gid.

  • key

    The path to the key file to use when creating the certificate request.

  • key_password (defaults to: '')

    The password to use when loading a protected key.

  • key_usage

    The X.509v3 Key Usage extension.

  • key_usage_critical

    Whether the Key Usage extension should be critical.

    Supported values:
    • true
    • false
    • yes
    • no
  • locality_name

    The value of the X.509 locality name (L) attribute.

  • mode

    Specifies the permissions mode of the destination file. Valid options: a string containing a permission mode value in octal notation.

  • organization_name

    The value of the X.509 organization name (O) attribute.

  • organization_unit_name

    The value of the X.509 organization unit name (OU) attribute.

  • owner

    Specifies the owner of the destination file. Valid options: a string containing a username or integer containing a uid.

  • path

    Specifies the destination file. Valid options: a string containing an absolute path. Default value: the title of your declared resource.

  • selinux_ignore_defaults

    See the file type’s selinux_ignore_defaults documentention: docs.puppetlabs.com/references/latest/type.html#file-attribute-selinux_ignore_defaults.

    Supported values:
    • true
    • false
    • yes
    • no
  • selrange

    See the file type’s selrange documentation: docs.puppetlabs.com/references/latest/type.html#file-attribute-selrange

  • selrole

    See the file type’s selrole documentation: docs.puppetlabs.com/references/latest/type.html#file-attribute-selrole

  • seltype

    See the file type’s seltype documentation: docs.puppetlabs.com/references/latest/type.html#file-attribute-seltype

  • seluser

    See the file type’s seluser documentation: docs.puppetlabs.com/references/latest/type.html#file-attribute-seluser

  • serial

    An otherwise unused serial number attribute that will be added to the request. This can be useful to ensure that requests using the same key and attributes (e.g. when regenerating the request after some time) will give a different binary representation of the request and actually trigger a refresh.

    Supported values:
    • %r{^[0-9]+$}
  • show_diff

    Specifies whether to set the show_diff parameter for the file resource.

    Supported values:
    • true
    • false
    • yes
    • no
  • signature_algorithm (defaults to: sha256)

    The signature algorithm to use. The algorithms ‘md2`, `md4`, `md5`, `sha` and `sha1` are only included for backwards compatibility and should be considered insecure for new certificates.

    Supported values:
    • md2
    • md4
    • md5
    • sha
    • sha1
    • sha224
    • sha256
    • sha384
    • sha512
  • state_or_province_name

    The value of the X.509 state or province name (ST) attribute.

  • subject_alternate_names_dns

    An array of DNS names that will be added as subject alternate names.

  • subject_alternate_names_ip

    An array of IP addresses that will be added as subject alternate names.