OpenSSL Puppet Module
This module manages OpenSSL.
Class openssl
Make sure openssl is installed:
include ::openssl
Specify openssl and ca-certificates package versions:
class { '::openssl':
package_ensure => latest,
ca_certificates_ensure => latest,
}
Create certificates (see the x509 defined type):
class { '::openssl::certificates':
x509_certs => { '/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,},
'/a/other/certificate.crt' => { ensure => 'present', },
}
}
Specify openssl and compat package
class { '::openssl':
package_name => ['openssl', 'openssl-compat', ],
}
Types and providers
This module provides three types and associated providers to manage SSL keys and certificates.
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 completely unprotected.
dhparam
This type allows to generate Diffie Hellman parameters.
Simple usage:
openssl::dhparam { '/path/to/dhparam.pem': }
Advanced options:
openssl::dhparam { '/path/to/dhparam.pem':
size => 2048,
}
ssl_pkey
This type allows to generate SSL private keys.
Simple usage:
ssl_pkey { '/path/to/private.key': }
Advanced options:
ssl_pkey { '/path/to/private.key':
ensure => 'present',
password => 'j(D$',
}
x509_cert
This type allows to generate SSL certificates from a private key. You need to deploy a template
file (templates/cert.cnf.erb
is an example).
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',
}
x509_request
This type allows to generate SSL certificate signing requests from a private key. You need to deploy a template
file (templates/cert.cnf.erb
is an example).
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',
}
cert_file
This 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
orabsent
-
source
: the URL the certificate should be downloaded from -
format
: the storage format for the certificate file (pem
order
)
Definitions
openssl::certificate::x509
This definition is a wrapper around the ssl_pkey
, x509_cert
and x509_request
types. It generates a certificate template, then generates the private key, certificate and certificate signing request and sets the owner of the files.
Simple usage:
openssl::certificate::x509 { 'foo':
country => 'CH',
organization => 'Example.com',
commonname => $fqdn,
}
Advanced options:
openssl::certificate::x509 { 'foo':
ensure => present,
country => 'CH',
organization => 'Example.com',
commonname => $fqdn,
state => 'Here',
locality => 'Myplace',
unit => 'MyUnit',
altnames => ['a.com', 'b.com', 'c.com'],
extkeyusage => ['serverAuth', 'clientAuth', 'any_other_option_per_openssl'],
email => 'contact@foo.com',
days => 3456,
base_dir => '/var/www/ssl',
owner => 'www-data',
group => 'www-data',
password => 'j(D$',
force => false,
cnf_tpl => 'my_module/cert.cnf.erb'
}
openssl::export::pkcs12
This definition generates a pkcs12 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',
}
openssl::export::pem_cert
This definition exports 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',
}
openssl::export::pem_key
This definition exports 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',
}
openssl::dhparam
This definition creates a dhparam PEM file:
Simple usage:
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',
}
Functions
cert_aia_caissuers
The function parses a X509 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('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.