ssl

The primary purpose of this module is to install certificates and keys in a few common formats.

• Storing certificates and keys
• Deploying certificates and keys
  • ssl::cert
  • ssl::cert::haproxy
• Additional usage info
• Changelog
• Development

Storing certificates and keys

This requires that certificates and keys are stored separately. Keys should be stored in Hiera, while files must be stored in the files/ directory of one of your profiles.

The primary certificate must be named "name.crt", and the intermediate certificate must be name "name_inter.crt". For example, if you store your files in profile::ssl:

site/profile/files/ssl/puppet.com.crt
site/profile/files/ssl/puppet.com_inter.crt
site/profile/files/ssl/forge.puppet.com.crt
site/profile/files/ssl/forge.puppet.com_inter.crt

Set the profile to use in Hiera, or by setting the cert_source parameter directly on the ssl class. The value should be in the same format as the file() function expects, e.g. 'profile/ssl'.

The private keys for your certificates go into Hiera as entries in the ssl::keys hash. We recommend encrypting them with [Hiera eyaml][https://github.com/voxpupuli/hiera-eyaml]. To continue with the example from above:

ssl::cert_source: 'profile/ssl'
ssl::keys:
  'puppet.com': ENC[PKCS7,MIIH...
  'forge.puppet.com': ENC[PKCS7,MIIH...

Deploying certificates and keys

ssl::cert

This is the most generic resource. It stores keys in the default global certificate and key directories for your OS.

On Debian, the puppet.com cert would be deployed as follows:

/etc/ssl/certs/puppet.com.crt
/etc/ssl/certs/puppet.com_inter.crt
/etc/ssl/certs/puppet.com_combined.crt
/etc/ssl/private/puppet.com.key

The _combined.crt file is a concatenation of the primary certificate followed by the intermediate certificate. This is the format used by NGINX and a variety of other applications.

ssl::cert::haproxy

This combines certificates with their key in the format expected by HAProxy. By default, it puts them in /etc/haproxy/certs.d/${key_name}.crt.

Additional usage info

This module is documented via pdk bundle exec puppet strings generate --format markdown. Please see REFERENCE.md for more info.

Changelog

CHANGELOG.md is generated prior to each release via pdk bundle exec rake changelog. This process relies on labels that are applied to each pull request.

Development

Pull requests are welcome!

Reference

Table of Contents

Classes

• ssl: Maintain SSL certs and private keys
• ssl::params: Determine default parameters for ssl

Defined types

• ssl::cert: Deploy SSL certificates and keys in a couple of common formats
• ssl::cert::haproxy: Install key and certs combination for HAProxy
• ssl::cert::nginx: DEPRECATED
• ssl::hashfile: Create certificate hash file

Functions

• ssl::ensure_newline: Ensure there's a trailing newline
• ssl::pem::join: Join certs and keys into a single PEM. Ensure the correct newlines exist.

Classes

ssl

You can store SSL certs in your control repo. Simply create a profile and put the certs in its files directory. (Note that you don't actually have to create a manifest for it.)

Suppose you wanted to use profile::ssl. Set cert_source => 'profile/ssl', and add cert files in site/profile/files/ssl/.

You can also store SSL keys. These should be encrypted, and the simplest solution for that is hiera-eyaml. Simply add keys to the keys parameter on this class in hiera. For example:

ssl::cert_source: 'profile/ssl'
ssl::keys:
  'puppet.com': ENC[PKCS7,MIIH...
  'forge.puppet.com': ENC[PKCS7,MIIH...

Parameters

The following parameters are available in the ssl class:

• cert_source
• keys
• manage_ssl_dir

cert_source

Data type: String[1]

Where to find cert files with the file() function.

keys

Data type: Hash[String[1], String[1]]

Private keys indexed by key names.

Default value: {}

manage_ssl_dir

Data type: Boolean

Enable or disable a file resource for the ssl directory

Default value: true

ssl::params

Determine default parameters for ssl

Defined types

ssl::cert

Deploy SSL certificates and keys in a couple of common formats

See the README for information about how to store certificates and keys for use by this type.

This deploys:

• ${key_dir}/${key_name}.key
• ${cert_dir}/${key_name}.crt
• ${cert_dir}/${key_name}_inter.crt — the intermediate certificate(s)
• ${cert_dir}/${key_name}_combined.crt — the primary certificate followed by the intermediate certificate(s)

Examples

ssl::cert { 'www.example.com': }

Parameters

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

• key_name
• cert_dir
• key_dir
• user
• group
• mode

key_name

Data type: String[1]

The name of the certificate

Default value: $title

cert_dir

Data type: Optional[String[1]]

The directory that certs are stored in. If no values is provided then the value from $ssl::cert_dir is used.

Default value: undef

key_dir

Data type: Optional[String[1]]

The directory that certificate keys are stored in. If no values is provided then the value from $ssl::key_dir is used.

Default value: undef

user

Data type: String[1]

The user to set as the owner of the generated files

Default value: 'root'

group

Data type: String[1]

THe group to set as the owner of the generated files

Default value: '0'

mode

Data type: String[1]

The file mode to be set on each generated file

Default value: '0640'

ssl::cert::haproxy

Install key and certs combination for HAProxy.

See the README for information about how to store certificates and keys for use by this type.

This deploys /etc/haproxy/certs.d/${key_name}.crt, which contains:

1. The primary certificate
2. The private key
3. The intermediate certificate(s)

Examples

Place a cert in the default location

ssl::cert::haproxy { 'www.example.com': }

Place a cert in a custom location

ssl::cert::haproxy { 'www.example.com':
  path => '/opt/custom_haproxy_build/etc/haproxy/certs',
}

Parameters

The following parameters are available in the ssl::cert::haproxy defined type:

• key_name
• path
• user
• group
• mode

key_name

Data type: String[1]

The name of the certificate

Default value: $title

path

Data type: Stdlib::Unixpath

The full path of the certificate, including the certificate's name.

Default value: "/etc/haproxy/certs.d/${key_name}.crt"

user

Data type: String[1]

The user that owns the certificate

Default value: 'root'

group

Data type: String[1]

The group that owns the certificate

Default value: '0'

mode

Data type: String[1]

The file mode of the certificate file

Default value: '0400'

ssl::cert::nginx

This is only here to simplify some of our legacy code.

We recommend using ssl::cert and configuring NGINX to use the _combined.crt file instead of using this resource.

Parameters

The following parameters are available in the ssl::cert::nginx defined type:

• key_name
• cert_dir
• key_dir
• user
• group
• mode

key_name

Data type: String[1]

The name of the certificate

Default value: $title

cert_dir

Data type: Optional[String[1]]

The directory that certs are stored in. If no values is provided then the value from $ssl::cert_dir is used.

Default value: undef

key_dir

Data type: Optional[String[1]]

The directory that certificate keys are stored in. If no values is provided then the value from $ssl::key_dir is used.

Default value: undef

user

Data type: String[1]

The user to set as the owner of the generated files

Default value: 'root'

group

Data type: String[1]

THe group to set as the owner of the generated files

Default value: '0'

mode

Data type: String[1]

The file mode to be set on each generated file

Default value: '0640'

ssl::hashfile

Create certificate hash file

Examples

[ $certfile, $certchainfile, $certinterfile, ].each |$hashfile| {
  ssl::hashfile { $hashfile: certdir => $ssl::cert_dir }
}

Parameters

The following parameters are available in the ssl::hashfile defined type:

• certdir

certdir

Data type: Stdlib::Unixpath

The directory ssl certs are stored in

Functions

ssl::ensure_newline

Type: Puppet Language

Ensure there's a trailing newline

Examples

file { '/tmp/www.example.com.crt':
  ensure  => file,
  content => ssl::ensure_newline($ssl::keys['www.example.com']),
}

ssl::ensure_newline(String[0] $string)

Ensure there's a trailing newline

Returns: String Returns a string that ends with a newline (\n)

Examples

file { '/tmp/www.example.com.crt':
  ensure  => file,
  content => ssl::ensure_newline($ssl::keys['www.example.com']),
}

string

Data type: String[0]

A string to ensure ends with a new line (aka '\n')

ssl::pem::join

Type: Puppet Language

Join certs and keys into a single PEM. Ensure the correct newlines exist.

Examples

Joining a cert with it's intermediate cert

file { '/tmp/www.example.com_combined.crt":
  ensure  => file,
  content => ssl::pem::join([
    file("${ssl::cert_source}/${key_name}.crt"),
    file("${ssl::cert_source}/${key_name}_inter.crt"),
  ]),
}

ssl::pem::join(Array[String[0]] $items)

Join certs and keys into a single PEM. Ensure the correct newlines exist.

Returns: String Returns a string representing the combined certificates.

Examples

Joining a cert with it's intermediate cert

file { '/tmp/www.example.com_combined.crt":
  ensure  => file,
  content => ssl::pem::join([
    file("${ssl::cert_source}/${key_name}.crt"),
    file("${ssl::cert_source}/${key_name}_inter.crt"),
  ]),
}

items

Data type: Array[String[0]]

An array of strings representing PEM files that need to be concatenated together

Change log

All notable changes to this project will be documented in this file. The format is based on Keep a Changelog and this project adheres to Semantic Versioning.

2.0.0 (2021-09-18)

Full Changelog

Changed

• Dropped old Puppet versions, added new ones, sync to current standards #6 (genebean)

1.0.0 (2020-03-02)

Full Changelog

* This Changelog was automatically generated by github_changelog_generator