OpenSSL

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

Overview

Create and manage X.509 keys, requests, certificates and Diffie-Hellman parameter files.

Module Description

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

This module can not only generate keys, requests and certificates but also use 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 for some functions to work. On RedHat based distributions the certutil executable is also needed.

Beginning with OpenSSL

The module has two distinct use cases. First of all you can create OpenSSL keys, requests and certificates with this module (see below). Then you can use this module to deploy certificates and keys (not necessarily generated by this module) from the Puppetserver to your client nodes.

The module must be initialized before you can deploy 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

Generate RSA key with defaults

A generated RSA key will be 2048 bits by default.

openssl_key { '/etc/ssl/rsa-2048.key':
  algorithm => 'RSA',
}

Generate RSA key owned by another user

Owner, group and mode may be specified when a key is generated.

openssl_key { '/etc/apache/ssl/rsa-2048.key':
  algorithm => 'RSA',
  owner     => 'www-data',
  group     => 'www-data',
  mode      => '0640',
}

Generate encrypted EC key with defaults

A key may be protected by a password.

openssl_key { '/etc/ssl/ec-secp384r1.key':
  algorithm => 'EC',
  cipher    => 'aes128',
  password  => 'rosebud',
}

Generate a CA key and certificate

Generate an encrypted EC key is created using the openssl_key type provided by this module.

openssl_key { '/etc/ssl/ca.key':
  algorithm => 'EC',
  cipher    => 'aes128',
  password  => 'rosebud',
}

Then generate a certificate request using the key and its password. The X.509 Common Name is mandatory. Other X.509 attributes may also be used. The request will be also be regenerated if the subscribed key changes.

openssl_request { '/etc/ssl/ca.csr':
  key              => '/etc/ssl/ca.key',
  key_password     => 'rosebud',
  common_name      => 'ACME Demo CA',
  domain_component => ['example', 'com'],
  subscribe        => Openssl_key['/etc/ssl/ca.key'],
  notify           => Openssl_cert['/etc/ssl/ca.crt'],
}

Finally the certificate is signed using the same key used for the request (so it will be a self-signed certificate). Some extensions line KeyUsage and BasicConstraints are defined.


openssl_cert { '/etc/ssl/ca.crt':
  request                       => '/etc/ssl/ca.csr',
  issuer_key                    => '/etc/ssl/ca.key',
  issuer_key_password           => 'rosebud',
  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 a certificate for an application

Create an Elliptic Curve key using a specific curve.

openssl_key { '/etc/ssl/ec-prime256v1.key':
  algorithm => 'EC',
  curve     => 'prime256v1',
}

Generate a request for an application specific certificate. Some extensions are already set in the request and will be copied into the certificate.

openssl_request { "/etc/ssl/app.example.com.csr":
  key                         => '/etc/ssl/ec-prime256v1.key',
  common_name                 => 'app.example.com',
  key_usage                   => ['keyEncipherment', 'digitalSignature'],
  extended_key_usage          => ['serverAuth', 'clientAuth'],
  subject_alternate_names_dns => ['app.example.com'],
  subscribe                   => Openssl_key['/etc/ssl/ec-prime256v1.key'],
  notify                      => Openssl_cert["/etc/ssl/app.example.com.crt"],
}

Sign the request using a CA certificate and key. The X.509 subjectAltName and keyUsage extenstions will be copied from the request if they are set.

openssl_cert { "/etc/ssl/app.example.com.crt":
  request                  => "/etc/ssl/app.example.com.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'],
  days                     => 2000,
}

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.