https://github.com/smoeding/puppet-openssl
Use Puppet to manage X.509 certificates, keys and parameter files
https://github.com/smoeding/puppet-openssl
openssl openssl-certs puppet
Last synced: about 1 month ago
JSON representation
Use Puppet to manage X.509 certificates, keys and parameter files
- Host: GitHub
- URL: https://github.com/smoeding/puppet-openssl
- Owner: smoeding
- License: bsd-2-clause
- Created: 2018-02-16T18:27:10.000Z (about 7 years ago)
- Default Branch: master
- Last Pushed: 2025-01-24T13:58:08.000Z (4 months ago)
- Last Synced: 2025-04-07T21:07:20.073Z (about 1 month ago)
- Topics: openssl, openssl-certs, puppet
- Language: Ruby
- Homepage:
- Size: 524 KB
- Stars: 1
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# OpenSSL
[](https://github.com/smoeding/puppet-openssl/actions/workflows/CI.yaml)
[](https://forge.puppetlabs.com/stm/openssl)
[](https://raw.githubusercontent.com/smoeding/puppet-openssl/master/LICENSE)
#### Table of Contents
1. [Overview](#overview)
2. [Module Description - What does the module do?](#module-description)
3. [Setup - The basics of getting started with openssl](#setup)
* [What openssl affects](#what-openssl-affects)
* [Setup requirements](#setup-requirements)
4. [Usage - Configuration options and additional functionality](#usage)
5. [Reference - An under-the-hood peek at what the module is doing and how](#reference)
5. [Limitations - OS compatibility, etc.](#limitations)
6. [Development - Guide for contributing to the module](#development)
## 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:
``` puppet
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:
``` text
# 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.
``` puppet
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.
``` puppet
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.
``` puppet
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.
``` puppet
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.
``` puppet
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.
``` puppet
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.
``` puppet
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.
``` puppet
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.
``` puppet
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:
``` puppet
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:
``` puppet
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:
``` text
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:
``` puppet
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:
``` text
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:
``` text
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:
``` text
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):
``` text
openssl_dhparam { '/etc/nginx/ssl/dh2048.pem': }
```
Using 4096 bits and a different file group:
``` text
openssl_dhparam { '/etc/mail/tls/dh2048.pem':
bits => 4096,
group => 'smmsp',
}
```
## Reference
See [REFERENCE.md](https://github.com/smoeding/puppet-openssl/blob/master/REFERENCE.md)
## Development
Feel free to send pull requests for new features.