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 default1.
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 storedensure
:present
orabsent
source
: the URL the certificate should be downloaded fromformat
: the storage format for the certificate file (pem
order
)
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
Footnotes
-
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. ↩