broadinstitute / puppet-certs

SSL Certificate File Management for Puppet

certs

Table of Contents

• [Notice] (#notice)
• Overview
• Module Description
• Setup
  • Setup requirements
• Usage
  • Installation
  • Examples
• Reference
• Limitations - OS compatibility, etc.
• Contributors

Notice

This module has been renamed to puppet-certificates due to naming conflicts and as such is being deprecated. You can find a fork of this module at puppet-certificates.

Overview

Configures SSL certificates and keys.

Module Description

This module provides SSL certificate files required by Apache or other services via the certs::site define. It can be used in conjunction with puppetlabs/apache's apache::vhost definitions to provide the ssl_cert and ssl_key files or any other service requiring SSL certificates.

It can also be used independent of any Puppet-defined service that requires the files to exist on a managed node.

Setup

Setup Requirements

The certificate files must come from an external store. Recommended stores are a site-specific (and private) module containing SSL files or a network-accessible filesystem, such as NFS, that the managed node can access. Once a file store is determined, include at least one certs::site define and specify the file store location as the source_path.

By default, this module will place certificates and keys in their relative locations and restart the specified service, provided it is defined in the catalog.

• RedHat

  • certificates directory: /etc/pki/tls/certs
  • keys directory: /etc/pki/tls/private
  • service: httpd

• Debian & Suse

  • certificates directory: /etc/ssl/certs
  • keys directory: /etc/ssl/private
  • service: apache2

• FreeBSD

  • certificates directory: /usr/local/etc/apache24
  • keys directory: /usr/local/etc/apache24
  • service: apache24

• Gentoo

  • certificates directory: /etc/ssl/apache2
  • keys directory: /etc/ssl/apache2
  • service: apache2

Usage

No trailing slashes should be provided for any paths.

Installation

Puppet Forge:

puppet module install broadinstitute-certs

Puppetfile:

mod 'broadinstitute/certs'

Examples

Puppet Manifest

manifest.pp

  include certs
  $domain = 'www.example.com'
  certs::site { $domain:
    source_path    => 'puppet:///site_certificates',
    ca_cert        => true,
    ca_name        => 'caname',
    ca_source_path => 'puppet:///ca_certs',
  }

With Hiera

node.yaml

  classes:
    - certs
  certs::sites:
    'www.example.com':
      source_path: 'puppet:///site_certificates'
      ca_cert: true
      ca_name: 'caname'
      ca_source_path: 'puppet:///ca_certs'

Resource Chaining with Apache Module

manifest.pp

  Certs::Site<| |> -> Apache::Vhost<| |>

Global Defaults

You can also reset some of the settings in params.pp globally via the certs base class which will be inherited by all certs::site defines used that are later defined. In this example, we can reset the default certificate and key paths for all instantiated sites so that we don't have to manually set the custom path in each site:

  $domain1 = 'www.example.com'
  $domain2 = 'foo.example.com'

  class { 'certs':
    cert_path => '/path/to/certs',
    key_path  => '/path/to/keys',
  }

  certs::site { $domain1:
    source_path    => 'puppet:///site_certificates',
    ca_cert        => true,
    ca_name        => 'caname',
    ca_source_path => 'puppet:///ca_certs',
  }

  certs::site { $domain2:
    source_path    => 'puppet:///site_certificates',
    ca_cert        => true,
    ca_name        => 'caname',
    ca_source_path => 'puppet:///ca_certs',
  }

Reference

REFERENCE.md (generated with Puppet Strings)

Limitations

This module is CI tested against open source Puppet on:

• CentOS 6, 7, 8
• RHEL 6, 7, 8

This module also provides functions for other distributions and operating systems, such as FreeBSD and Gentoo, but is not formally tested on them and are subject to regressions.

Contributors

Riccardo Calixte (@rcalixte)

Andrew Teixeira (@coreone)

More contributors.

puppet-certs's Issues

DHParam

Allow for the delivery of Diffie-Helman parameters files. The files are expected to be generated with something like:

openssl dhparam -out dh2048.pem 2048

The module should then allow someone to enable DH parameters and provide the filename where those parameters are stored. We should assume the file is located under source_path.

erros during puppet agent run

Hi
Any hints on resolving this error:
Info: Using configured environment 'production'
Info: Retrieving pluginfacts
Info: Retrieving plugin
Info: Retrieving locales
Info: Loading facts
Error: Could not retrieve catalog from remote server: Error 500 on SERVER: Server Error: Could not find resource 'Service[httpd]' in parameter 'notify' (file: /etc/puppetlabs/code/environments/production/modules/certs/manifests/site.pp, line: 457) on node agent.example.com
Warning: Not using cache on failed catalog
Error: Could not retrieve catalog; skipping run

httpd is installed on this agent

Thank you!

OCSP

Add the ability to have the module configure OCSP stapling:

• http://www.jinnko.org/2015/03/ocsp-stapling-with-haproxy.html
• https://www.digicert.com/ssl-support/apache-enable-ocsp-stapling-on-server.htm
• https://www.digicert.com/ssl-support/nginx-enable-ocsp-stapling-on-server.htm

This may only be helpful for HAProxy right now, but worth looking into

validate_x509 does not work if passing certificate and/or key by content

The call to validate_x509_rsa_key_pair on line 269 of site.pp assumes that that certificates are being passed in as paths rather than by content. If the certificate and content is being retrieved from hiera-eyaml and does not exist on disk on the puppet server, then the call to validate_x509_rsa_key_pair is guaranteed to fail.

Actually, looking at the code for validate_x509_rsa_key_pair in Stdlib, and subsequently looking at the Ruby documentation for OpenSSL::X509::Certificate and OpenSSL::PKey::RSA, it looks like you need to pass in the certificate and key content regardless, not the path to them.

Outdated depencency puppetlabs/concat blocks upgrading

Hi!

The Certs module requires a puppetlabs/concat module of version less than 3. Any chance of bumping this up to a current concat (now 4.2.1)?

I could force-upgrade, but that feels rather brutish... and anything i break is then mine to fix :)

Problem:

puppet-certs/metadata.json

Line 65 in 92544b7

{ "name":"puppetlabs/concat","version_requirement":">= 1.1.1 < 3.0.0" }

Suggested fix:

    { "name":"puppetlabs/concat","version_requirement":">= 1.1.1 < 5.0.0" }

Thanks,
~rL

Multiple Services

Right now, the module supports restarting a single service. There needs to be support for multiple services.

Hiera (deep) merge

hi,

we have to change our main certificate and we found an issue with Hiera.

We have something in comon.yaml for all nodes:

certs::sites:
  'example.com':
    service: false
    dhparam: true
    dhparam_content: "%{hiera('example_dh_2048')}"
    dhparam_file: 'dh_2048.pem'
    ca_name: "thawte_tls_ca_g1"
    ca_cert: true
    ca_content: "%{hiera('thawte_digicert_ca_bundle')}"
    cert_chain: true
    chain_path: '/etc/ssl/private'
    chain_name: "example_chain"
    chain_content: "%{hiera('wildcard_example_cert')}%{hiera('thawte_digicert_ca_bundle')}%{hiera('wildcard_example_key')}"
    cert_content: "%{hiera('wildcard_example_cert')}"
    cert_mode: '0640'
    group: 'ssl-cert'
    key_content: "%{hiera('wildcard_example_key')}"
    key_mode: '0640'
    validate_x509: false

Now we also the same cert on a different path :

• hieradata/role/pmox.yaml

certs::sites:
  'pveproxy-ssl':
    service: false
    cert_chain: true
    chain_path: "/etc/pve/nodes/%{::hostname}"
    key_path: "/etc/pve/nodes/%{::hostname}"
    chain_name: "pveproxy-ssl"
    cert_ext: ".pem"
    chain_ext: ".pem"
    ca_ext: ".pem"
    key_mode: '0640'
    cert_mode: '0640'
    owner: 'root'
    group: 'www-data'
    chain_content: "%{hiera('wildcard_example_cert')}%{hiera('thawte_digicert_ca_bundle')}%{hiera('wildcard_example_key')}"
    cert_content: "%{hiera('wildcard_example_cert')}"
    key_content: "%{hiera('wildcard_example_key')}"

Now we get an duplication declaration for /etc/ssl/certs:

Error: Could not retrieve catalog from remote server: Error 500 on SERVER: Server Error: Evaluation Error: Error while evaluating a Resource Statement, Evaluation Error: Error while evaluating a Function Call, Duplicate declaration: File[/etc/ssl/certs] is already declared at (file: /opt/puppet/environments/newmod/modules/certs/manifests/site.pp, line: 340); cannot redeclare (file: /opt/puppet/environments/newmod/modules/certs/manifests/site.pp, line: 340) (file: /opt/puppet/environments/newmod/modules/certs/manifests/site.pp, line: 340, column: 3) (file: /opt/puppet/environments/newmod/modules/certs/manifests/init.pp, line: 202) on node fc-r02-ceph-osd-03

I think, the problem is the merge. Because the node has the comon.eyaml (with the default cert) and also the other one from the role/pmox.yaml.
It works, If I remove the certs from the comon.eyaml and put the pveproxy-ssl and example.com in one yaml file.
In that case, I have many duplicates in many files, because I can't use the global comon.eyaml for all.
Is there a way to get around that problem ?

I tried something like:

  "^certs::.*":
    merge:
      strategy: deep
      merge_hash_arrays: true

but that wasn't working.

cu denny

Add ability to define certificate contents via YAML files

It would be nice to be able to create the public and private cert/key files via a definition in Hiera. The public key can be defined in clear text and the private key could be defined via eyaml encryption.

merge_key ; merge_chain -> /etc/ssl/private/

Hello,

first, very big thanks for this awesome module, as I was able to remove my own files and use your module.

My next thing is either a question or a feature request. We use haproxy which requires the key into the cert file and I know, that there is a merge_key = true, but than the key is placed into /etc/ssl/certs/, which isnt' quite good ;-) I know, that I can change the path too, but everytime where the key is used, it should go to /etc/ssl/private per default, so the merge_key should create a file /etc/ssl/private/foo.merge_cert.pem which holds the cert and the private key.

And here we come to the next point, which is a bit unclear for me: ca vs. chain.

We have a Root CA cert (for example Thawte thawte_256_ca_bundle) and our own cert www.example.com.crt, which is signed by Thawte. So we want the "chain" out of the CA (thawte_256_ca_bundle) from Thawte and our www.example.com.crt. What is the correct Hiera syntax ?

What we have:

    ca_name: "thawte_256_ca"
    ca_cert: true
    ca_content: "%{hiera('thawte_256_ca_bundle')}"
    cert_chain: true
    merge_chain: true
    merge_key: true
    chain_path: '/etc/ssl/private'
    chain_name: "example.com_chain"
    chain_content: "%{hiera('wildcard_example.com_cert')}%{hiera('thawte_256_ca_bundle')}"
    cert_content: "%{hiera('wildcard_example.com_cert')}"
    key_content: "%{hiera('wildcard_example.com_key')}"

As you can see, we get the /etc/ssl/certs/example.com.crt out of our cert and Thawte CA and the private key. The /etc/ssl/private/example.com_chain has Thawte CA and our cert, but private key is missing. Sure, I can add it:

chain_content: "%{hiera('wildcard_example.com_cert')}%{hiera('thawte_256_ca_bundle')}%{hiera('wildcard_example.com_key')}"

But it looks like even more wrong, because then I don't need the merge_key: true :-)

Can you bring some light into it?

Thanks so much :-)

Show Diffs

We shouldn't show diffs for certain files changes or at least make it an option.

Puppet 4 and 5

We should move the version to 2.0 and remove support for Puppet 3 while moving to Puppet 4/5 DSL.

Rename module

To prevent conflicts with other Forge modules named certs, we should rename this module to something like tls_certs or some other name that doesn't already have a module by that name in the forge. I think the right thing to do here would be to:

• Fork this repo to a new name
• Decide on what GitHub issues we would want to move to the new repo.
• Prepare a new release in this repo declaring it is being deprecated and moving to the new module name
• Build and release the first release of the new module (with a release one major version after the deprecation release of this repo) so that it is in the Forge.
• Build and release the last release for this repo so the deprecation notice shows up in the forge.
• Archive this repo so it is read-only

Purge directories of unmanaged files

In keeping with Puppet philosophy of cleaning out unmanaged files, it would be nice if the module would do exactly that.

Much like /etc/sudoers.d, I've found that my servers are littered with unmanaged crt and key files in /etc/pki/tls/{certs,private}.

We'd have to be very careful, though. There are some symlinks (RHEL variants) that point to /etc/pki/ca-trust/extracted....

dhparm need path on Debian, or update-ca-certificates complains invalid file

Hello,

At the moment, the dhparm file is located in "cert_path", e.g. /etc/ssl/certs, but the Debian script "update-ca-certificates" complains, that this file is invalid (ignores the file).
So, it would be good, to change it to key_path.

Adding test cases and some rspec tests would be nice...

todo

Notification for Services

Currently the module supports passing in services with the object type of String. We should support other types of objects such as Class and Exec for notifications.

Does cert auto-renew?

I am looking into possibly using this module to generate certs and was wondering if this module auto renews the certs when it is about to expire? Please let me know what your thoughts are on this. Also, are the certs self-signed?

Thank you.