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

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,
}

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.

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.

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',
}

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',
}

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',
}

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'],
}

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',
}

Using the ssl_pkey type allows to generate SSL private keys.

Note, that the private key is not encrypted by default¹.

Simple usage:

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

Advanced options:

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

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',
}

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',
}

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)

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"]),
  }

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.

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