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

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 to fetch and deploy the certificates and keys 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 custom types and 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 some examples 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 use the deployment functionality:

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 OpenSSL key with defaults

By default the generated key will be an RSA key with 2048 bits.

openssl_key { '/etc/ssl/rsa-2048.key': }

Generate 4096 bits RSA key owned by another user

Owner, group and mode may be specified when a key is generated. The number of bits can be 1024, 2048 (default), 3072, 4096, 5120, 6144, 7168 or 8192 for an RSA key.

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

Generate encrypted EC key with defaults

You can also generate Elliptic-Curve keys (secp384r1 is the default curve) and a key may also be protected by a password.

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

Generate a CA key and certificate

First generate an encrypted EC key 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. Here 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 can be copied into the certificate by the CA.

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

openssl::cert { 'postgresql':
  cert     => $facts['networking']['hostname'],
  owner    => 'root',
  group    => 'postgres',
  mode     => '0444',
  cert_dir => '/etc/postgresql',
  source   => $facts['networking']['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 custom 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.