Skip to content

Latest commit

 

History

History
1730 lines (1099 loc) · 51.8 KB

REFERENCE.md

File metadata and controls

1730 lines (1099 loc) · 51.8 KB
Raw

Reference

Table of Contents

Classes

  • openssl: Manage X.509 certificates, keys and Diffie-Hellman parameter files

Defined types

Resource types

Data types

Classes

openssl

Manage X.509 certificates, keys and Diffie-Hellman parameter files

Examples

Declaring the class
class { 'openssl':
  cert_source_directory => '/etc/puppetlabs/code/private/certs',
}
Declaring the class and deploy a CA certificate
class { 'openssl':
  cert_source_directory => '/etc/puppetlabs/code/private/certs',
  root_ca_certs         => [ 'ACME-Root-CA' ],
}

Parameters

The following parameters are available in the openssl class:

cert_source_directory

Data type: Stdlib::Absolutepath

The directory on the Puppetmaster where all certificate and key files are kept. Every certificate or key file will be read from this directory and then deployed on the client. This directory is accessed using the file function and therefore does not need to be part of the Puppet directory structure. But obviously the directory and the files must be readable by the Puppet user. This parameter is mandatory and has no default.

default_key_dir

Data type: Stdlib::Absolutepath

The default directory where a key file is deployed. This is operating system specific. On Debian this is /etc/ssl/private and on RedHat this is /etc/pki/tls/private.

default_cert_dir

Data type: Stdlib::Absolutepath

The default directory where a certificate file is deployed. This is operating system specific. On Debian this is /etc/ssl/certs and on RedHat this is /etc/pki/tls/certs.

package_name

Data type: String

The name of the OpenSSL package to install.

package_ensure

Data type: String

The desired package state.

root_group

Data type: String

The group used for deployed files. This is operating system specific. On Linux this is normally root. On FreeBSD this is wheel.

ca_certs

Data type: Array[String]

An array of CA certificates that are installed by default. Internally this uses the openssl::cert defined type.

Defined types

openssl::cacert

Manage an X.509 CA certificate file in PEM format

Examples

Install the 'my-root-ca' trusted cert in the default location
openssl::cacert { 'my-root-ca': }

Parameters

The following parameters are available in the openssl::cacert defined type:

ensure

Data type: Enum['present','absent']

The state of the resource.

Default value: 'present'

cert

Data type: String

The basename of the file where the certificate will be stored on the client. The full filename will be created using the three components cert_dir, cert and extension.

Default value: $name

source

Data type: String

The basename of the file where the certificate is stored on the server. The full filename will be created using the three parameters cert_source_directory (see the base class openssl), source and source_extension.

Default value: $name

extension

Data type: String

The file extension used for files created on the client. This parameter is ignored on Debian and RedHat based distributions as the operating system specific tools require certificates to be installed using the .crt extension.

Default value: 'crt'

source_extension

Data type: String

The file extension used for files read on the server.

Default value: 'crt'

mode

Data type: Stdlib::Filemode

The file mode used for the resource. Note that certificate verification may fail if the file permissions are too restrictive.

Default value: '0444'

owner

Data type: String

The file owner used for the resource.

Default value: 'root'

group

Data type: Optional[String]

The file group used for the resource.

Default value: undef

cert_dir

Data type: Optional[Stdlib::Absolutepath]

The destination directory on the client where the certificate will be stored. This parameter is ignored on Debian and RedHat based distributions. Debian requires CA certificates to be stored in /usr/local/share/ca-certificates and RedHat requires CA certificates to be stored in /etc/pki/ca-trust/source/anchors.

Default value: undef

openssl::cert

Manage an X.509 certificate file in PEM format

Examples

Install the 'imap' cert in the default location
openssl::cert { 'imap': }
Install the 'postgresql' cert using application specific defaults
openssl::cert { 'postgresql':
  cert     => $facts['networking']['hostname'],
  owner    => 'root',
  group    => 'postgres',
  mode     => '0444',
  cert_dir => '/etc/postgresql',
  source   => $facts['networking']['hostname'],
}

Parameters

The following parameters are available in the openssl::cert defined type:

ensure

Data type: Enum['present','absent']

The state of the resource.

Default value: 'present'

cert

Data type: String

The basename of the file where the certificate will be stored on the client. The full filename will be created using the three components cert_dir, cert and extension.

Default value: $name

source

Data type: String

The basename of the file where the certificate is stored on the server. The full filename will be created using the three parameters cert_source_directory (see the base class openssl), source and source_extension.

Default value: $name

cert_chain

Data type: Array[String]

An array of certificate names that are should be added to the certificate file. This allows the generation of certificate chains to provide a full verification path for the certificate if intermediate CAs are used. The chain is included in the generated certificate file. The certificates must be available in cert_source_directory on the server just like the ordinary certificate.

Default value: []

extension

Data type: String

The file extension used for files created on the client.

Default value: 'crt'

source_extension

Data type: String

The file extension used for files read on the server.

Default value: 'crt'

mode

Data type: Stdlib::Filemode

The file mode used for the resource.

Default value: '0444'

owner

Data type: String

The file owner used for the resource.

Default value: 'root'

group

Data type: Optional[String]

The file group used for the resource.

Default value: undef

cert_dir

Data type: Optional[Stdlib::Absolutepath]

The destination directory on the client where the certificate will be stored.

Default value: undef

openssl::key

Manage an X.509 key file in PEM format

Examples

Install the 'imap' key in the default location
openssl::key { 'imap': }
Install the 'postgresql' key using application specific defaults
openssl::key { 'postgresql':
  key     => $facts['networking']['hostname'],
  owner   => 'root',
  group   => 'postgres',
  mode    => '0440',
  key_dir => '/etc/postgresql',
  source  => $facts['networking']['hostname'],
}

Parameters

The following parameters are available in the openssl::key defined type:

ensure

Data type: Enum['present','absent']

The state of the resource.

Default value: 'present'

key

Data type: String

The basename of the file where the key will be stored on the client. The full filename will be created using the three components key_dir, key and extension.

Default value: $name

source

Data type: String

The basename of the file where the key is stored on the server. The full filename will be created using the three parameters cert_source_directory (see the base class openssl), source and source_extension.

Default value: $name

extension

Data type: String

The file extension used for files created on the client.

Default value: 'key'

source_extension

Data type: String

The file extension used for files read on the server.

Default value: 'key'

mode

Data type: Stdlib::Filemode

The file mode used for the resource.

Default value: '0400'

owner

Data type: String

The file owner used for the resource.

Default value: 'root'

group

Data type: Optional[String]

The file group used for the resource.

Default value: undef

key_dir

Data type: Optional[Stdlib::Absolutepath]

The destination directory on the client where the key will be stored.

Default value: undef

Resource types

openssl_cert

The type takes a Certificate Signing Request (create by openssl_request for example) and an issuer certificate and key as input to generate a signed certificate.

To create a self-signed certificate, set issuer_key to the same key that was used to create the request. Otherwise issuer_cert and issuer_key should point to your CA certificate and key.

The type uses a random 128 bit number as serial number.

The certificate validity starts the moment the certificate is signed and terminates as defined by the parameter days. The expiration time of the cerificate is additionally limited by the validity of your CA certificate unless you create a self-signed certificate.

The parameters copy_request_extensions and omit_request_extensions can be used to specifically allow or deny some extensions from the request. You can also use type parameters to set some extensions to a fixed value.

The type expects to find the "-----BEGIN CERTIFICATE-----" token in the file or it will overwrite the file content with a new certificate.

The type is refreshable and will generate a new certificate 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 issuer key, issuer certificate or request that is used to create the certificate, the openssl_cert resource will autorequire these resources

Examples

Create CA certificate from a CSR using the specified extensions
openssl_cert { '/etc/ssl/ca.crt':
  request                       => '/etc/ssl/ca.csr',
  issuer_key                    => '/etc/ssl/ca.key',
  key_usage                     => ['keyCertSign', 'cRLSign'],
  key_usage_critical            => true,
  basic_constraints_ca          => true,
  basic_constraints_ca_critical => true,
  subject_key_identifier        => 'hash',
  authority_key_identifier      => ['issuer', 'keyid:always'],
  days                          => 2922,
}
Create certificate for a node and copy two extensions from the CSR
openssl_cert { "/etc/ssl/${facts[networking][fqdn]}.crt":
  request                  => "/etc/ssl/${facts[networking][fqdn]}.csr",
  issuer_key               => '/etc/ssl/ca.key',
  issuer_cert              => '/etc/ssl/ca.crt',
  subject_key_identifier   => 'hash',
  authority_key_identifier => ['keyid', 'issuer'],
  copy_request_extensions  => ['subjectAltName', 'keyUsage'],
}

Properties

The following properties are available in the openssl_cert type.

ensure

Valid values: present, absent

The basic property that the resource should be in.

Default value: present

Parameters

The following parameters are available in the openssl_cert type.

authority_key_identifier

The Authority Key Identifier extension.

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

Valid values: true, false

Whether the Basic Constraints CA extension should be set.

Setting this parameter overrides the value of the basicConstraints extension from the request.

basic_constraints_ca_critical

Valid values: true, false

Whether the Basic Constraints CA extension should be critical.

copy_request_extensions

List of extensions to copy from the certificate request. If this parameter is set, then only these extensions are copied from the request into the final certificate. Otherwise all extensions are copied from the request unless the parameter omit_request_extensions disallows them.

Some extension names that might be useful to include here are basicConstraints, keyUsage, extendedKeyUsage, subjectAltName.

If an extension name is included in copy_request_extension and omit_request_extensions, then omit_request_extensions has precedence and the extension is not copied from the request to the final certificate.

Extensions defined by explicit type parameters always override extensions from the request.

Default value: []

days

Valid values: %r{^[0-9]+$}

The number of days that the certificate should be valid.

A certificate can't be valid after the issuing certificate has expired. So the validity is limited by the expiration time of the issuing certificate.

Default value: 365

extended_key_usage

The X.509v3 Extended Key Usage extension. Valid options: serverAuth, clientAuth, codeSigning, emailProtection, timeStamping, OCSPSigning, ipsecIKE, msCodeInd, msCodeCom, msCTLSign, msEFS.

Setting this parameter overrides the value of the extendedKeyUsage extension from the request.

extended_key_usage_critical

Valid values: true, false

Whether the Extenden Key Usage extension should be critical.

group

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

issuer_cert

The path to the certificate file that is used to issue the certificate.

issuer_key

The path to the key file that is used to issue the certificate. If this is the same key that was used to create the request, then a self-signed certificate will be created.

issuer_key_password

The password to use when loading a protected issuer key.

Default value: ''

key_usage

The X.509v3 Key Usage extension. Valid options: digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment, keyAgreement, keyCertSign, cRLSign, encipherOnly, decipherOnly.

Setting this parameter overrides the value of the keyUsage extension from the request.

key_usage_critical

Valid values: true, false

Whether the Key Usage extension should be critical.

mode

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

omit_request_extensions

List of extensions to omit from the certificate request. If this parameter is set, then the named extensions are never copied from the request into the final certificate. Otherwise all extensions are copied from the request unless the parameter copy_request_extensions restricts them.

Some extension names that might be useful to include here are basicConstraints, keyUsage, extendedKeyUsage, subjectAltName.

If an extension name is include in copy_request_extension and omit_request_extensions, then omit_request_extensions has precedence and the extension is not copied from the request to the final certificate.

Extensions defined by explicit type parameters always override extensions from the request.

Default value: []

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.

request

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

selinux_ignore_defaults

Valid values: true, false, yes, no

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

selrange

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

selrole

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

seltype

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

seluser

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

show_diff

Valid values: true, false, yes, no

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

signature_algorithm

Valid values: md2, md4, md5, sha, sha1, sha224, sha256, sha384, sha512

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.

Default value: sha256

subject_key_identifier

The Subject Key Identifier extension. Normally the value hash is used when creating certificates.

subject_key_identifier_critical

Valid values: true, false

Whether the Subject Key Identifier extension should be critical.

openssl_certutil

This type installs the certificate specified with filename as a trusted certificate if ensure => present. The trust is removed if ensure => absent.

The certutil executable is required for this type. In general it is only available on RedHat-based distributions.

The certificate file itself is not managed by this type.

The file must already exist on the node before it can be added to the NSS database. Make sure you add the correct dependency if you manage the certificate file with Puppet.

There is an unsolved issue if a certificate is added a second time to the NSS database using a different name. In this case certutil does not add the certificate but also does not report an error. Therefore Puppet will try to add the certificate every time it runs. As a workaround the already installed certificate should be removed.

Examples

Add a certificate to the NSS database and set trust level for SSL
openssl_certutil { '/etc/ssl/certs/My-Root-CA.crt':
  ensure    => present,
  ssl_trust => 'C',
}
Remove a certificate from the NSS database
openssl_certutil { '/etc/ssl/certs/My-Root-CA.crt':
  ensure => absent,
}

Properties

The following properties are available in the openssl_certutil type.

email_trust

Valid values: %r{[pPcCT]*}

Email trust attributes for the certificate.

ensure

Valid values: present, absent

The basic property that the resource should be in.

Default value: present

object_signing_trust

Valid values: %r{[pPcCT]*}

Object signing trust attributes for the certificate.

ssl_trust

Valid values: %r{[pPcCT]*}

SSL trust attributes for the certificate.

Parameters

The following parameters are available in the openssl_certutil type.

filename

The filename of the certificate.

name

namevar

The nickname of the certificate in the certificate database.

provider

The specific backend to use for this openssl_certutil resource. You will seldom need to specify this --- Puppet will usually discover the appropriate provider for your platform.

openssl_dhparam

Generate Diffie-Hellman parameters for an TLS enabled application by specifying the number of bits and the generator number to use.

The type expects to find the "-----BEGIN DH PARAMETERS-----" token in the file or it will overwrite the file content with new parameters.

The type is refreshable and will generate new parameters 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.

Note: The creation of Diffie-Hellman parameters with a larger number of bits takes a significant amount of CPU time (sometimes multiple minutes). This might look as if the Puppet Agent is hanging.

Examples

Generate Diffie-Hellman parameter file
openssl_dhparam { '/etc/postfix/dh2048.pem':
  owner   => 'root',
  group   => 'root',
  mode    => '0644'
  require => Package['postfix'],
  notify  => Service['postfix'],
}
Trigger refresh using another resource
openssl_dhparam { '/etc/postfix/dh2048.pem':
  subscribe => Package['postfix'],
}

Properties

The following properties are available in the openssl_dhparam type.

ensure

Valid values: present, absent

The basic property that the resource should be in.

Default value: present

Parameters

The following parameters are available in the openssl_dhparam type.

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 ".".

bits

Valid values: 1024, 2048, 3072, 4096, 5120, 6144, 7168, 8192

The number of bits for the Diffie-Hellman parameters.

Default value: 2048

generator

Valid values: 2, 5

The generator number for the Diffie-Hellman parameters.

Default value: 2

group

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

mode

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

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

Valid values: true, false, yes, no

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

selrange

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

selrole

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

seltype

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

seluser

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

show_diff

Valid values: true, false, yes, no

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

openssl_genparam

The type is refreshable. The openssl_genparam type will regenerate the parameters if the resource is notified from another resource.

Examples

Create a Diffie-Hellman parameter file using 2048 bits
openssl_genparam { '/tmp/dhparam.pem':
  algorithm => 'DH',
  bits      => '2048,
  generator => '2',
}
Create an Elliptic Curve parameter file using the secp521e1 curve
openssl_genparam { '/tmp/ecparam.pem':
  algorithm => 'EC',
  curve     => 'secp521r1',
}
Automatically refresh a parameter file every 3 months
openssl_genparam { '/tmp/dhparam.pem':
  algorithm        => 'DH',
  bits             => '2048,
  generator        => '2',
  refresh_interval => '3mo',
}
Refresh a parameter file if another file changes
openssl_genparam { '/tmp/dhparam.pem':
  algorithm => 'DH',
  bits      => '2048,
  subscribe => File['/etc/ssl/parameters.trigger'],
}

Properties

The following properties are available in the openssl_genparam type.

ensure

Valid values: present, absent

The basic property that the resource should be in.

Default value: present

Parameters

The following parameters are available in the openssl_genparam type.

algorithm

Valid values: DH, EC

The algorithm to generate the parameters for.

bits

Valid values: 2048, 4096, 8192

The number of bits to use for Diffie-Hellman parameters.

curve

Valid values: %r{^[a-zA-Z][a-zA-Z0-9-]+[0-9]$}

The name of the curve to use for Elliptic Curve parameters.

file

The name of the parameter file to manage.

generator

Valid values: 2, 5

The generator to use for Diffie-Hellman parameters.

provider

The specific backend to use for this openssl_genparam resource. You will seldom need to specify this --- Puppet will usually discover the appropriate provider for your platform.

refresh_interval

Valid values: %r{^[0-9]+(y|mo|w|d|h|mi|s)?$}

The Refresh interval for the parameter file. A new parameter file will be generated after this time.

The value must be a number optionally followed by a time unit. The following units are understood: y for year (365 days), mo for months (30 days), w for week (7 days), d for days (24 hours), h for hours (60 minutes), mi for minute (60 seconds). When the unit s or no unit is used then the value is interpreted as the number of seconds.

openssl_hash

If ensure => present a symbolic link using the certificate hash will be created in the same directory as the certificate. The link is removed if ensure => absent.

This link is used to find a trusted cert when a certificate chain is validated.

The certificate file itself is not managed by this type.

The file must exist before the link can be created as it is accessed by OpenSSL to calculate the hash. For the same reason the file can only be deleted after the link has been removed.

Examples

Mark an existing certificate as trusted
openssl_trustcert { '/etc/ssl/certs/My-Root-CA.crt':
  ensure => present,
}
Mark an existing certificate as not trusted
openssl_trustcert { '/etc/ssl/certs/My-Root-CA.crt':
  ensure => absent,
}

Properties

The following properties are available in the openssl_hash type.

ensure

Valid values: present, absent

The basic property that the resource should be in.

Default value: present

Parameters

The following parameters are available in the openssl_hash type.

name

namevar

The name of the certificate file to manage.

provider

The specific backend to use for this openssl_hash resource. You will seldom need to specify this --- Puppet will usually discover the appropriate provider for your platform.

openssl_key

This type creates RSA or Elliptic Curve keys depending on the parameter algorithm.

The key can optionally be encrypted using a supplied password.

The type expects to find the "-----BEGIN PRIVATE KEY-----" token in the file or it will overwrite the file content with a new key.

The type is refreshable and will generate a new key 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.

Examples

Generate a 2048 bit RSA key
openssl_key { '/etc/ssl/rsa-2048.key':
  algorithm => 'RSA',
  bits      => 2048,
}
Generate an Elliptic Curve key that is encrypted using AES128
openssl_key { '/etc/ssl/ec-secp256k1.key':
  algorithm => 'EC',
  curve     => 'secp256k1',
  cipher    => 'aes128',
  password  => 'rosebud',
}
Create a key and regenerate it if another resource changes
openssl_key { '/etc/ssl/rsa-2048.key':
  algorithm => 'RSA',
  bits      => 2048,
  subscribe => File['/etc/ssl/key.trigger'],
}

Properties

The following properties are available in the openssl_key type.

ensure

Valid values: present, absent

The basic property that the resource should be in.

Default value: present

Parameters

The following parameters are available in the openssl_key type.

algorithm

Valid values: RSA, EC

The algorithm to use when generating a private key. The number of bits must be supplied if an RSA key is generated. For an EC key the curve name must be given.

Default value: RSA

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 ".".

bits

Valid values: 1024, 2048, 3072, 4096, 5120, 6144, 7168, 8192

The number of bits for the RSA key. This parameter is mandatory for RSA keys. Keys with 1024 bits should only be used for specific applications like DKIM.

Default value: 2048

cipher

Encrypt the key with the supplied cipher. A password must be given if this parameter is set.

curve

The curve to use for elliptic curve key. This parameter is mandatory for EC keys. Consult your OpenSSL documentation to find out what curves are supported on your system. The following curves should be available for TLS 1.3 and earlier: secp256r1, secp384r1, secp521r1.

Default value: secp384r1

group

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

mode

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

owner

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

password

Use the supplied password to encrypt the key. Setting only a password without a cipher creates an unprotected key.

path

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

selinux_ignore_defaults

Valid values: true, false, yes, no

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

selrange

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

selrole

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

seltype

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

seluser

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

show_diff

Valid values: true, false, yes, no

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

openssl_request

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

The following properties are available in the openssl_request type.

ensure

Valid values: present, absent

The basic property that the resource should be in.

Default value: present

Parameters

The following parameters are available in the openssl_request type.

authenticator_control

An authenticator control contains information used to establish a non-cryptographic check of identity by the CA. Consult the documentation of your CA if this is necessary and what value you need to set. Also see RFC RFC 4211 for more details.

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

Valid values: true, false, yes, no

Whether the Basic Constraints CA extension should be set.

basic_constraints_ca_critical

Valid values: true, false, yes, no

Whether the Basic Constraints CA extension should be critical.

common_name

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

country_name

The value of the X.509 country (C) 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

Valid values: true, false, yes, no

Whether the Extenden Key Usage extension should be critical.

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

The password to use when loading a protected key.

Default value: ''

key_usage

The X.509v3 Key Usage extension.

key_usage_critical

Valid values: true, false, yes, no

Whether the Key Usage extension should be critical.

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.

registration_token_control

The registration token control contains one-time information that can be used by the CA to verify the identity of the subject. Consult the documentation of your CA if this is necessary and what value you need to set. Also see RFC RFC 4211 for more details.

selinux_ignore_defaults

Valid values: true, false, yes, no

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

selrange

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

selrole

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

seltype

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

seluser

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

serial

Valid values: %r{^[0-9]+$}

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.

show_diff

Valid values: true, false, yes, no

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

signature_algorithm

Valid values: md2, md4, md5, sha, sha1, sha224, sha256, sha384, sha512

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.

Default value: sha256

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.

Data types

Openssl::Extendedkeyusage

Valid parameter values for the OpenSSL extendend key usage

Alias of Enum['serverAuth', 'clientAuth', 'codeSigning', 'emailProtection', 'timeStamping', 'OCSPSigning', 'ipsecIKE', 'msCodeInd', 'msCodeCom', 'msCTLSign', 'msEFS']

Openssl::Keyusage

Valid parameter values for the OpenSSL keyusage

Alias of Enum['digitalSignature', 'nonRepudiation', 'keyEncipherment', 'dataEncipherment', 'keyAgreement', 'keyCertSign', 'cRLSign', 'encipherOnly', 'decipherOnly']