OpenSSL

Table of Contents

1. Overview
2. Module Description - What does the module do?
3. Setup - The basics of getting started with openssl
   • What openssl affects
   • Setup requirements
4. Usage - Configuration options and additional functionality
5. Reference - An under-the-hood peek at what the module is doing and how
6. Limitations - OS compatibility, etc.
7. Development - Guide for contributing to the module

Overview

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

Module Description

The openssl module manages files containing X.509 certificates and keys.

In contrast to some other modules, this module does not generate the certificates and keys itself. Instead it uses a directory on the Puppet server where the certificates and keys can be fetched from. So you can run your own CA or take certificates received from a public CA and have them managed by Puppet.

Setup

What OpenSSL affects

The modules installs the OpenSSL package and provides defined types to manage certificates, keys and Diffie-Hellman parameter files on the nodes.

Setup Requirements

The module requires the Puppetlabs modules stdlib and concat. The openssl executable must be installed on the node. On RedHat based distributions the certutil executable is also needed.

Beginning with OpenSSL

The module must be initialized before you can manage certificates and keys:

class { 'openssl':
  cert_source_directory => '/etc/puppetlabs/code/private/certs',
}

The parameter cert_source_directory is mandatory and has no default value. This is a directory on the Puppet server where you keep your certificates and keys. This directory does not need to be inside a Puppet environment directory. It can be located anywhere on the Puppet server. But the content must by readable by the user running the Puppetserver application (normally puppet). So make sure the file permissions are set correctly.

The module expects to find certificate and key files in this directory on the Puppet server. As an example the directory used above might look like this listing:

# ls -l /etc/puppetlabs/code/private/certs/
total 236
-r-------- 1 puppet root 1509 May 25  2017 cloud.crt
-r-------- 1 puppet root 1675 May 25  2017 cloud.key
-r-------- 1 puppet root 1570 Mar  1 20:06 imap.crt
-r-------- 1 puppet root 1679 Mar  1 20:06 imap.key
-r-------- 1 puppet root 1647 May 27 05:17 letsencrypt-ca.crt
-r-------- 1 puppet root 1472 Mar 18  2016 vortex.crt
-r-------- 1 puppet root 1671 Mar 18  2016 vortex.key

Usage

Install Root CA certificates by default

If you want to provide certain Root or intermediate CA certificates by default, you can add a class parameter containing the list of certificate names:

class { 'openssl':
  cert_source_directory => '/etc/puppetlabs/code/private/certs',
  ca_certs              => [ 'letsencrypt-ca' ],
}

Internally the openssl::cacert defined type (see next section) is used.

Install a root CA certificate

The defined type openssl::cacert installs a trusted CA certificate:

openssl::cacert { 'letsencrypt-ca': }

This would install the Let's Encrypt certificate stored in the letsencrypt-ca.crt file. For the certificate the module automatically adds a trust attribute.

On Debian based distributions the certificate is stored in /usr/local/share/ca-certificates using a .crt extension. The module uses the update-ca-certificates script (included in the ca-certificates package) to include the certificate in /etc/ssl/certs/ca-certificates.crt and also create a symbolic link in /etc/ssl/certs pointing to the installed file:

lrwxrwxrwx 1 root root   18 Jul 14 13:27 /etc/ssl/certs/4f06f81d.0 -> /usr/local/share/ca-certificates/letsencrypt-ca.crt

On RedHat based distributions certificate is stored in /etc/pki/ca-trust/source/anchors using a .crt extension. The module uses the update-ca-trust script (included in the ca-certificates package) and also the certutil binary to add the certificate to the system-wide NSS database in /etc/pki/nssdb.

Install a certificate and key using defaults

The two defined types openssl::cert and openssl::key can be used to install a certificate and key using all defaults:

openssl::cert { 'imap': }
openssl::key { 'imap': }

This would take the files from the directory on the Puppet server (e.g. /etc/puppetlabs/code/private/certs if you set that using the cert_source_directory parameter). On the client the two files are created with restrictive permissions and ownership:

r-------- 1 root root 1679 Jan  3  2017 /etc/ssl/private/imap.key
r--r--r-- 1 root root 1570 Mar  1 20:07 /etc/ssl/certs/imap.crt

The default destination directories are distribution specific and can be configured using the class parameters default_key_dir and default_cert_dir.

Install a certificate and key for a specific application

The following code shows how to install a certificate and key in an application specific directory using application specific owner, group and mode:

openssl::key { 'postgresql':
  key     => $::hostname,
  owner   => 'root',
  group   => 'postgres',
  mode    => '0440',
  key_dir => '/etc/postgresql',
  source  => $::hostname,
}

openssl::cert { 'postgresql':
  cert     => $::hostname,
  owner    => 'root',
  group    => 'postgres',
  mode     => '0444',
  cert_dir => '/etc/postgresql',
  source   => $::hostname,
}

This example uses the hostname fact as the name of the key and therefore installs the cert and key on the host of the same name. If we assume that node vortex is your PostgreSQL server running Debian, then the following two files would be created by the manifest:

r--r----- 1 root postgres 1704 Jan  3  2017 /etc/postgresql/vortex.key
r--r--r-- 1 root postgres 1464 Jan  3  2017 /etc/postgresql/vortex.crt

Create a Diffie-Hellman parameter file

To use perfect forward secrecy cipher suites, you must set up Diffie-Hellman parameters on the server. Most applications allow including these parameters using a file. You can generate such a file using the openssl::dhparam defined type.

Using all the defaults (2048 bits):

openssl::dhparam { '/etc/nginx/ssl/dh2048.pem': }

Using 4096 bits and a different file group:

openssl::dhparam { '/etc/mail/tls/dh2048.pem':
  bits  => '4096',
  group => 'smmsp',
}

Reference

See REFERENCE.md

Development

Feel free to send pull requests for new features.

Reference

Table of Contents

Classes

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

Defined types

• openssl::cacert: Manage an X.509 CA certificate file in PEM format
• openssl::cert: Manage an X.509 certificate file in PEM format
• openssl::config: Create OpenSSL config for a CSR
• openssl::csr: Create OpenSSL certificate signing request (CSR)
• openssl::dhparam: Manage Diffie-Hellman parameter files
• openssl::key: Manage an X.509 key file in PEM format

Resource types

• openssl_certutil: Manage trusted certificates in the system-wide NSS database
• openssl_genparam: Generate Diffie-Hellman or Elliptic Curve parameter file
• openssl_genpkey: Generate OpenSSL private key files
• openssl_hash: Manage a symbolic link using the certificate hash
• openssl_selfsign: Create an OpenSSL self-signed certificate
• openssl_signcsr: Sign OpenSSL certificate signing request using a CA

Data types

• Openssl::Extendedkeyusage: Valid parameter values for the OpenSSL extendend key usage
• Openssl::Keyusage: Valid parameter values for the OpenSSL keyusage

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
• default_key_dir
• default_cert_dir
• package_name
• package_ensure
• root_group
• ca_certs

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
• cert
• source
• extension
• source_extension
• mode
• owner
• group
• cert_dir

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     => $::hostname,
  owner    => 'root',
  group    => 'postgres',
  mode     => '0444',
  cert_dir => '/etc/postgresql',
  source   => $::hostname,
}

Parameters

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

• ensure
• cert
• source
• cert_chain
• extension
• source_extension
• mode
• owner
• group
• cert_dir

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::config

Create OpenSSL config for a CSR

Examples

Creating a config file for a CSR

openssl::config { '/etc/ssl/www.example.com.cnf':
  common_name        => 'www.example.com',
  extended_key_usage => [ 'serverAuth', 'clientAuth' ],
}

Parameters

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

• common_name
• config
• subject_alternate_names_dns
• subject_alternate_names_ip
• key_usage
• extended_key_usage
• basic_constraints_ca
• owner
• group
• country_name
• state_or_province_name
• locality_name
• postal_code
• street_address
• organization_name
• organization_unit_name

common_name

Data type: String

The value of the X.509 CN attribute. This attribute is mandatory.

config

Data type: Stdlib::Absolutepath

The full path name of the OpenSSL configuration file that will be created. It contains a minimal set of configuration options that are needed to process a CSR.

Default value: $name

subject_alternate_names_dns

Data type: Array[Stdlib::Fqdn]

An array of DNS names that will be added as subject alternate names using the DNS prefix. The certificate can be used for all names given in this list. Normally the common name should be in this list or the certificate may be rejected by modern web browsers.

Default value: []

subject_alternate_names_ip

Data type: Array[Stdlib::IP::Address]

An array of IP addresses that will be added as subject alternate names using the IP prefix. The certificate can be used for all IP addresses given in this list.

Default value: []

key_usage

Data type: Array[Openssl::Keyusage]

The intended purposes of the certificate.

Default value: [ 'keyEncipherment', 'dataEncipherment' ]

extended_key_usage

Data type: Array[Openssl::Extendedkeyusage]

The extended key usage of the certificate.

Default value: [ 'serverAuth' ]

basic_constraints_ca

Data type: Boolean

Whether the subject of the certificate is a CA.

Default value: false

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

country_name

Data type: Optional[String]

The value of the X.509 C attribute.

Default value: undef

state_or_province_name

Data type: Optional[String]

The value of the X.509 ST attribute.

Default value: undef

locality_name

Data type: Optional[String]

The value of the X.509 L attribute.

Default value: undef

postal_code

Data type: Optional[String]

The value of the X.509 PC attribute.

Default value: undef

street_address

Data type: Optional[String]

The value of the X.509 STREET attribute.

Default value: undef

organization_name

Data type: Optional[String]

The value of the X.509 O attribute.

Default value: undef

organization_unit_name

Data type: Optional[String]

The value of the X.509 OU attribute.

Default value: undef

openssl::csr

Create OpenSSL certificate signing request (CSR)

Examples

Creating a CSR with subject alternate names

openssl::csr { '/etc/ssl/www.example.com.csr':
  common_name                 => 'www.example.com',
  subject_alternate_names_dns => [ 'www.example.com', 'example.com', ],
  config                      => '/etc/ssl/www.example.com.cnf',
  key_file                    => '/etc/ssl/www.example.com.key',
}

Parameters

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

• common_name
• csr_file
• config
• key_file
• subject_alternate_names_dns
• subject_alternate_names_ip
• key_usage
• extended_key_usage
• basic_constraints_ca
• mode
• owner
• group
• country_name
• state_or_province_name
• locality_name
• postal_code
• street_address
• organization_name
• organization_unit_name

common_name

Data type: String

The value of the X.509 CN attribute. This attribute is mandatory.

csr_file

Data type: Stdlib::Absolutepath

The full path name of the signing request file that will be created. It contains the attributes that will be included in the certificate and also the public part of the key. Default is the name of the resource.

Default value: $name

config

Data type: Stdlib::Absolutepath

The full path name of the OpenSSL configuration file that will be created. It contains a minimal set of configuration options that are needed to process the CSR. It can also be used when the CSR is used to create a self-signed certificate. Updates to the config file will not trigger the generation of a new certificate.

key_file

Data type: Stdlib::Absolutepath

The full path of the private key file. This file including the key must already be present to generate the CSR.

subject_alternate_names_dns

Data type: Array[Stdlib::Fqdn]

An array of DNS names that will be added as subject alternate names using the DNS prefix. The certificate can be used for all names given in this list. Normally the common name should be in this list or the certificate may be rejected by modern web browsers.

Default value: []

subject_alternate_names_ip

Data type: Array[Stdlib::IP::Address]

An array of IP addresses that will be added as subject alternate names using the IP prefix. The certificate can be used for all IP addresses given in this list.

Default value: []

key_usage

Data type: Array[Openssl::Keyusage]

The intended purposes of the certificate.

Default value: [ 'keyEncipherment', 'dataEncipherment' ]

extended_key_usage

Data type: Array[Openssl::Extendedkeyusage]

The extended key usage of the certificate.

Default value: [ 'serverAuth' ]

basic_constraints_ca

Data type: Boolean

Whether the subject of the certificate is a CA.

Default value: false

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

country_name

Data type: Optional[String]

The value of the X.509 C attribute.

Default value: undef

state_or_province_name

Data type: Optional[String]

The value of the X.509 ST attribute.

Default value: undef

locality_name

Data type: Optional[String]

The value of the X.509 L attribute.

Default value: undef

postal_code

Data type: Optional[String]

The value of the X.509 PC attribute.

Default value: undef

street_address

Data type: Optional[String]

The value of the X.509 STREET attribute.

Default value: undef

organization_name

Data type: Optional[String]

The value of the X.509 O attribute.

Default value: undef

organization_unit_name

Data type: Optional[String]

The value of the X.509 OU attribute.

Default value: undef

openssl::dhparam

Manage Diffie-Hellman parameter files

Examples

Create a parameter file using default parameters

openssl::dhparam { '/etc/ssl/dhparam.pem': }

Create a parameter file using 4096 bits

openssl::dhparam { '/etc/ssl/dhparam.pem':
  bits => '4096',
}

Create a parameter file using non-default permissions

openssl::dhparam { '/etc/ssl/dhparam.pem':
  owner => 'www-data',
  group => 'www-data',
  mode  => '0640',
}

Parameters

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

• ensure
• file
• bits
• generator
• mode
• owner
• group

ensure

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

The state of the resource.

Default value: 'present'

file

Data type: Stdlib::Absolutepath

The file name where the DH parameters are stored on the node. Must be an absolute path.

Default value: $name

bits

Data type: Enum['2048','3072','4096','5120','6144','7168','8192']

The number of bits to generate.

Default value: '2048'

generator

Data type: Enum['2','5']

The generator to use. Check the OpenSSL documentation for details about this parameter.

Default value: '2'

mode

Data type: Stdlib::Filemode

The file mode used for the resource.

Default value: '0644'

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

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     => $::hostname,
  owner   => 'root',
  group   => 'postgres',
  mode    => '0440',
  key_dir => '/etc/postgresql',
  source  => $::hostname,
}

Parameters

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

• ensure
• key
• source
• extension
• source_extension
• mode
• owner
• group
• key_dir

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_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

Specifies whether the resource should exist.

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
• name
• provider

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_genparam

The type is refreshable. The openssl_genaram 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

Specifies whether the resource should exist.

Default value: present

Parameters

The following parameters are available in the openssl_genparam type.

• algorithm
• bits
• curve
• file
• generator
• provider
• refresh_interval

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_genpkey

This type is still beta!

Generate an OpenSSL private key file. The type creates RSA or Elliptic Curve keys depending on the parameter algorithm.

The key can optionally be encrypted using a supplied password. Encryption uses the -passin option when calling openssl so the password is not visible in the process listing.

The type is refreshable. The openssl_genpkey type will regenerate the key if the resource is notified from another resource.

Examples

Generate a 2048 bit RSA key file

openssl_genpkey { '/tmp/rsa-2048.key':
  algorithm => 'RSA',
  bits      => '2048',
}

Generate AES encrypted Elliptic Curve private key

openssl_genpkey { '/tmp/ec-secp256k1.key':
  algorithm => 'EC',
  curve     => 'secp256k1',
  cipher    => 'aes128',
  password  => 'rosebud',
}

Regenerate the key if another file changes

openssl_genpkey { '/tmp/rsa-2048.key':
  algorithm => 'RSA',
  bits      => '2048',
  subscribe => File['/etc/ssl/key.trigger'],
}

Properties

The following properties are available in the openssl_genpkey type.

ensure

Valid values: present, absent

Specifies whether the resource should exist.

Default value: present

Parameters

The following parameters are available in the openssl_genpkey type.

• algorithm
• bits
• cipher
• curve
• file
• password
• provider

algorithm

Valid values: RSA, EC

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

bits

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

The number of bits for the RSA key. This parameter is mandatory for RSA keys.

cipher

Encrypt the key with the supplied cipher. A password must be given in this case.

curve

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

The curve to use for elliptic curve key. This parameter is mandatory for EC keys.

file

The name of the private key file to manage.

password

Use the supplied password when encrypting the key.

provider

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

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

Specifies whether the resource should exist.

Default value: present

Parameters

The following parameters are available in the openssl_hash type.

• name
• provider

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_selfsign

This type is still beta!

The type takes a certificate signing request (CSR) and a key file to generate a self-signed certificate.

Certificate extensions can be added by using the extensions and extfile parameters.

Optionally a key password can be provided if the used key is encrypted.

The certificate will be valid for the given number of days.

The type is refreshable. The openssl_selfsign type will regenerate the certificate if the resource is notified from another resource.

Examples

Create a self-signed certificate with extensions valid for one year

openssl_signcsr { '/tmp/cert.crt':
  csr        => '/tmp/cert.csr',
  signkey    => '/tmp/cert.key',
  extfile    => '/tmp/cert.cnf',
  extensions => 'v3_ext',
  days       => '365',
}

Properties

The following properties are available in the openssl_selfsign type.

ensure

Valid values: present, absent

Specifies whether the resource should exist.

Default value: present

Parameters

The following parameters are available in the openssl_selfsign type.

• csr
• days
• extensions
• extfile
• file
• password
• provider
• signkey

csr

Required. The file containing the certificate signing request.

days

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

The number of days the certificate should be valid.

Default value: 370

extensions

The section name of the extensions. The OpenSSL defaults will be used if the parameter is undef.

extfile

The file with the certificate extensions.

file

The signed certificate file to manage.

password

The password to decrypt the key. Leave the parameter undefined if the key is not encrypted.

provider

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

signkey

Required. The file with the OpenSSL key to use for the self-signed certificate.

openssl_signcsr

This type is still beta!

The name and configuration file of a CA is required.

Certificate extensions can be added by using the extensions and extfile parameters.

Optionally a key password can be provided if the used key is encrypted.

The certificate will be valid for the given number of days.

The type is refreshable. The openssl_signcsr type will regenerate the certificate if the resource is notified from another resource.

Examples

Use a CA to sign a CSR

openssl_signcsr { '/tmp/cert.crt':
  csr       => '/tmp/cert.csr',
  ca_name   => 'My-Root-CA',
  ca_config => '/etc/ssl/CA.cnf',
  days      => '365',
}

Regenerate a certificate if the CSR changes

openssl_signcsr { '/tmp/cert.crt':
  csr       => '/tmp/cert.csr',
  ca_name   => 'My-Root-CA',
  ca_config => '/etc/ssl/CA.cnf',
  subscribe => File['/tmp/cert.csr'],
}

Properties

The following properties are available in the openssl_signcsr type.

ensure

Valid values: present, absent

Specifies whether the resource should exist.

Default value: present

Parameters

The following parameters are available in the openssl_signcsr type.

• ca_config
• ca_name
• csr
• days
• extensions
• extfile
• file
• password
• provider

ca_config

Required. The configuration file of the CA that is used to sign the CSR.

ca_name

Required. The name of the CA that is used to sign the CSR.

csr

Required. The file containing the certificate signing request.

days

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

The number of days the certificate should be valid.

Default value: 370

extensions

The section name of the extensions. The OpenSSL defaults will be used if the parameter is undef.

extfile

The file with the certificate extensions.

file

The signed certificate file to manage.

password

The password to decrypt the CA key. Leave the parameter undefined if the key is not encrypted.

provider

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

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']

2022-02-25 - Release 3.4.0

Features

• The OpenSSL config file to generate a CSR can now be generated on it's own using the new defined type openssl::config.
• Add new data type Openssl::Extendedkeyusage.

2022-02-16 - Release 3.3.0

Features

• Support additional choices for the number of bits in RSA keys

2021-09-01 - Release 3.2.0

Features

• Add support for Stdlib 8.x.
• Add support for FreeBSD 13
• Add support for Debian 11

Bug Fixes

• Fix error propagation in custom types. A custom type now fails as it should if an error condition occurs while creating the resource.

2021-03-09 - Release 3.1.0

Features

• Add support for Puppet 7.
• Add support for Stdlib 7.x.

2020-12-09 - Release 3.0.0

Breaking changes

• Removed Support for Debian-8, Ubuntu-14.04, CentOS-6, RedHat-6 and FreeBSD-10
• The parameter manage_trust for the defined type openssl::cert has been removed. CA certificates should be managed using the openssl::cacert defined type.
• The class parameter openssl::ca_certs internally uses the openssl::cacert defined type.

Features

• Add Support for FreeBSD-12
• On RedHat based distributions the defined type openssl::cacert will keep all CA certificates in /etc/pki/ca-trust/source/anchors and also call the update-ca-trust script.

2020-10-14 - Release 2.2.0

Features

• Add support for Ubuntu 20.04
• Add new defined type openssl::cacert to install a trusted CA certificate. The parameter manage_trust for the defined type openssl::cert is now deprecated and will be removed in the next major version.

2019-11-03 - Release 2.1.0

Features

• Add support for Debian-10, CentOS-8, RedHat-8.

Bugfixes

• Fix openssl_version fact to handle versions without a trailing letter.

2019-10-09 - Release 2.0.0

Breaking changes

• Remove support for Puppet 4.
• For the openssl::cert defined type the attribute makehash has been replaced by the more general attribute manage_trust. On RedHat based distributions the certificate will now be added to the system-wide NSS database when this parameter is true.

Enhancements

• Add support for Stdlib 6.x.
• Add support for Concat 6.x.
• Add new custom type openssl_hash to manage symbolic links using a certificate hash as name.
• Add new custom type openssl_certutil to manage certificates in the system-wide NSS database.

2019-02-23 - Release 1.4.0

Summary

• Add documentation in the REFERENCE.md file.

2018-10-14 - Release 1.3.0

Features

• Support Puppet 6

2018-10-14 - Release 1.2.0

Features

• Implement an additional parameter source_extension for the openssl::cert and openssl::key defined types. This parameter sets the file extension for certificates (default: crt) and keys (default: key) on the server.

• The version requirements for the stdlib and concat modules have been updated.

2018-08-05 - Release 1.1.0

Bugfixes

• The initial release was missing the default hiera configuration for Ubuntu. This release uses the operating system family to load the hiera configuration. Ubuntu is therefore handled as a member of the Debian family.

2018-07-27 - Release 1.0.0

Summary

Initial release.