OpenSSL Puppet Module

Build Status Release Puppet Forge Puppet Forge - downloads Puppet Forge - endorsement Puppet Forge - scores puppetmodule.info docs AGPL v3 License Donated by Camptocamp

This module enables Puppet to manage PKI entities such as encryption keys, signing requests and X.509 certificates.

Setup

Include this module in a manifest:

contain openssl

By default, this will ensure OpenSSL and ca-certificates are installed.

Change the defaults to pin specific versions of the packages or keep them up to date:

class { 'openssl':
  package_ensure         => latest,
  ca_certificates_ensure => latest,
}

Usage

Create X.509 certificates

One of the most common use-cases is to generate a private key, a certificate signing request and issue a certificate. This can be done using the openssl::certificate::x509 defined type, e.g.:

openssl::certificate::x509 { 'hostcert':
  commonname => $facts['networking']['fqdn'],
}

This will create a series of resources, i.e. the private key in /etc/ssl/certs/hostcert.key, the certificate signing request in /etc/ssl/certs/hostcert.csr for the subject DN: CN=<fqdn> and the self-signed certificate stored in /etc/ssl/certs/hostcert.crt.

Note that openssl::certificate::x509 is a defined type that provides this abstract functionality by leveraging several other resources of the module, which are also available individually for more advanced use cases.

Create X.509 certificates from a hash

Include the openssl::certificates class in a node's manifest and set the certificates parameter - possibly via Hiera - to a hash of certificate definitions:

contain openssl::certificates

openssl::certificates:
  hostcert:
    commonname: "%{facts['networking']['fqdn']}"
  othercert:
    commonname: "other.example.com"
    owner: www-data

This will generate openssl::certificate::x509 instances for each key in the hash.

Export a key pair to PKCS#12

Use the openssl::export::pkcs12 defined type to generate a PKCS#12 file:

openssl::export::pkcs12 { 'foo':
  ensure   => 'present',
  basedir  => '/path/to/dir',
  pkey     => '/here/is/my/private.key',
  cert     => '/there/is/the/cert.crt',
  in_pass  => 'my_pkey_password',
  out_pass => 'my_pkcs12_password',
}

Export certificate(s) to PEM/x509 format

Use the openssl::export::pem_cert type to export PEM certificates from a pkcs12 container:

openssl::export::pem_cert { 'foo':
  ensure   => 'present',
  pfx_cert => '/here/is/my/certstore.pfx',
  pem_cert => '/here/is/my/cert.pem',
  in_pass  => 'my_pkcs12_password',
}

This definition exports PEM certificates from a DER certificate:

openssl::export::pem_cert { 'foo':
  ensure   => 'present',
  der_cert => '/here/is/my/certstore.der',
  pem_cert => '/here/is/my/cert.pem',
}

Export a key to PEM format

Use openssl::export::pem_key to export PEM key from a pkcs12 container:

openssl::export::pem_key { 'foo':
  ensure   => 'present',
  pfx_cert => '/here/is/my/certstore.pfx',
  pem_key  => '/here/is/my/private.key',
  in_pass  => 'my_pkcs12_password',
  out_pass => 'my_pkey_password',
}

Dynamic refresh of exported files

If you want Puppet to refresh the PKCS#12, PEM/x509 or PEM key file in case the input files changed, set the dynamic mode on and list desired resources for subscription:

openssl::export::pkcs12 { 'bar':
  ensure    => 'present',
  basedir   => '/path/to/dir',
  pkey      => '/here/is/my/private.key',
  cert      => '/there/is/the/cert.crt',
  dynamic   => true,
  resources => File['/here/is/my/private.key','/there/is/the/cert.crt'],
}

Create Diffie-Hellman parameters

The openssl::dhparam defined type and its back-end resource type dhparam allow to generate Diffie-Hellman parameters.

Simple usage of the Puppet type:

dhparam { '/path/to/dhparam.pem': }

Advanced options:

dhparam { '/path/to/dhparam.pem':
  size => 2048,
}

Or alternatively, using the defined type:

openssl::dhparam { '/path/to/dhparam.pem': }

which is equivalent to:

openssl::dhparam { '/path/to/dhparam.pem':
  ensure => 'present',
  size   => 512,
  owner  => 'root',
  group  => 'root',
  mode   => '0644',
}

Advanced usage:

openssl::dhparam { '/path/to/dhparam.pem':
  ensure => 'present',
  size   => 2048,
  owner  => 'www-data',
  group  => 'adm',
  mode   => '0640',
}

Create a private key

Using the ssl_pkey type allows to generate SSL private keys.

Note, that the private key is not encrypted by default[^1].

[^1]: In every case, not providing the password (or setting it to undef, which is the default) means that the private key won't be encrypted with any symmetric cipher so it is protected by filesystem access mode only.

Simple usage:

ssl_pkey { '/path/to/private.key': }

Advanced options:

ssl_pkey { '/path/to/private.key':
  ensure   => 'present',
  password => 'j(D$',
}

Create a certificate signing request

The x509_request type allows to generate SSL certificate signing requests from a private key. You need to deploy an OpenSSL configuration file containing a section for the request engine and reference it in template. You manage configuration files using the openssl::config defined type.

Simple usage:

x509_request { '/path/to/request.csr': }

Advanced options:

x509_request { '/path/to/request.csr':
  ensure      => 'present',
  password    => 'j(D$',
  template    => '/other/path/to/template.cnf',
  private_key => '/there/is/my/private.key',
  force       => false,
  subscribe   => '/other/path/to/template.cnf',
}

Create a certificate

Using the x509_cert type allows to generate SSL certificates. The default provider to this type can create self-signed certificates or use a certification authority - also deployed on the same host - to sign the certificate signing request.

Simple usage:

x509_cert { '/path/to/certificate.crt': }

Advanced options:

x509_cert { '/path/to/certificate.crt':
  ensure      => 'present',
  password    => 'j(D$',
  template    => '/other/path/to/template.cnf',
  private_key => '/there/is/my/private.key',
  days        => 4536,
  force       => false,
  subscribe   => '/other/path/to/template.cnf',
}

Get a certificate from a remote source

The cert_file type controls a file containing a serialized X.509 certificate. It accepts the source in either PEM or DER format and stores it in the desired serialization format to the file.

cert_file { '/path/to/certs/cacert_root1.pem':
  ensure => present,
  source => 'http://www.cacert.org/certs/root_X0F.der',
  format => pem,
}

Attributes:

  • path (namevar): path to the file where the certificate should be stored
  • ensure: present or absent
  • source: the URL the certificate should be downloaded from
  • format: the storage format for the certificate file (pem or der)

Functions

Accessing the CA issuers URL from a certificate

If a certificate contains the authorityInfoAccess extension, the openssl::cert_aia_caissuers function can be used to parse hte certificate for the authorityInfoAccess extension and return with the URL found as caIssuers, or nil if no URL or extension found. Invoking as deferred function, this can be used to download the issuer certificate:

  file { '/ssl/certs/caissuer.crt':
    ensure => file,
    source => Deferred('openssl::cert_aia_caissuers', ["/etc/ssl/certs/${facts['networking']['fqdn']}.crt"]),
  }

Contributing

Please report bugs and feature request using GitHub issue tracker.

For pull requests, it is very much appreciated to check your Puppet manifest with puppet-lint to follow the recommended Puppet style guidelines from the Puppet Labs style guide.

Transfer Notice

This plugin was originally authored by Camptocamp. The maintainer preferred that Puppet Community take ownership of the module for future improvement and maintenance. Existing pull requests and issues were transferred over, please fork and continue to contribute here instead of Camptocamp.

Previously: https://github.com/camptocamp/puppet-openssl