From 4cc07600544959132fa916c46f15115ef83f3c06 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tibor=20R=C3=A9p=C3=A1si?= Date: Tue, 30 Apr 2024 09:47:00 +0200 Subject: [PATCH] doc improvements --- README.md | 300 ++++++++++++++++++++++++------------------------------ 1 file changed, 133 insertions(+), 167 deletions(-) diff --git a/README.md b/README.md index 5cb4063..5aa434e 100644 --- a/README.md +++ b/README.md @@ -10,17 +10,19 @@ [![AGPL v3 License](https://img.shields.io/github/license/voxpupuli/puppet-openssl.svg)](LICENSE) [![Donated by Camptocamp](https://img.shields.io/badge/donated%20by-camptocamp-fb7047.svg)](#transfer-notice) -**This module manages OpenSSL.** +**This module enables Puppet to manage PKI entities such as encryption keys, signing requests and X.509 certificates.** -## Class openssl +## Setup -Make sure openssl is installed: +Include this module in a manifest: ```puppet -include openssl +contain openssl ``` -Specify openssl and ca-certificates package versions: +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: ```puppet class { 'openssl': @@ -29,275 +31,240 @@ class { 'openssl': } ``` -Create certificates (see the x509 defined type): +## Usage -```puppet -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', }, - } -} -``` +### Create X.509 certificates -Specify openssl and compat package +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](REFERENCE.md#opensslcertificatex509) defined type, e.g.: ```puppet -class { 'openssl': - package_name => ['openssl', 'openssl-compat', ], +openssl::certificate::x509 { 'hostcert': + commonname => $facts['networking']['fqdn'], } ``` -## Types and providers - -This module provides three types and associated providers to manage SSL keys and certificates. +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=` and the self-signed certificate stored in `/etc/ssl/certs/hostcert.crt`. -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__. +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. -### dhparam +### Create X.509 certificates from a hash -This type allows to generate Diffie Hellman parameters. - -Simple usage: +Include the [openssl::certificates](REFERENCE.md#opensslcertificates) class in a node's manifest and set the `certificates` parameter - possibly via Hiera - to a hash of certificate definitions: ```puppet -openssl::dhparam { '/path/to/dhparam.pem': } +contain openssl::certificates ``` -Advanced options: +```yaml +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](REFERENCE.md#opensslexportpkcs12) defined type to generate a PKCS#12 file: ```puppet -openssl::dhparam { '/path/to/dhparam.pem': - size => 2048, +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', } ``` -### ssl\_pkey +### Export certificate(s) to PEM/x509 format -This type allows to generate SSL private keys. +Use the [openssl::export::pem_cert](REFERENCE.md#opensslexportpem_cert) type to export PEM certificates from a pkcs12 container: -Simple usage: +```puppet +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: ```puppet -ssl_pkey { '/path/to/private.key': } +openssl::export::pem_cert { 'foo': + ensure => 'present', + der_cert => '/here/is/my/certstore.der', + pem_cert => '/here/is/my/cert.pem', +} ``` -Advanced options: +### Export a key to PEM format + +Use [openssl::export::pem_key](REFERENCE.md#opensslexportpem_key) to export PEM key from a pkcs12 container: ```puppet -ssl_pkey { '/path/to/private.key': +openssl::export::pem_key { 'foo': ensure => 'present', - password => 'j(D$', + pfx_cert => '/here/is/my/certstore.pfx', + pem_key => '/here/is/my/private.key', + in_pass => 'my_pkcs12_password', + out_pass => 'my_pkey_password', } ``` -### x509\_cert +### Create Diffie-Hellman parameters -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). +The [openssl::dhparam](REFERENCE.md#openssldhparam) defined type and its back-end resource type [dhparam](REFERENCE.md#dhparam) allow to generate Diffie-Hellman parameters. -Simple usage: +Simple usage of the Puppet type: ```puppet -x509_cert { '/path/to/certificate.crt': } +dhparam { '/path/to/dhparam.pem': } ``` Advanced options: ```puppet -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', +dhparam { '/path/to/dhparam.pem': + size => 2048, } ``` -### 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: +Or alternatively, using the defined type: ```puppet -x509_request { '/path/to/request.csr': } +openssl::dhparam { '/path/to/dhparam.pem': } ``` -Advanced options: +which is equivalent to: ```puppet -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', +openssl::dhparam { '/path/to/dhparam.pem': + ensure => 'present', + size => 512, + owner => 'root', + group => 'root', + mode => '0644', } ``` -### 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. +Advanced usage: ```puppet -cert_file { '/path/to/certs/cacert_root1.pem': - ensure => present, - source => 'http://www.cacert.org/certs/root_X0F.der', - format => pem, +openssl::dhparam { '/path/to/dhparam.pem': + ensure => 'present', + size => 2048, + owner => 'www-data', + group => 'adm', + mode => '0640', } ``` -Attributes: +### Create a private key -* `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`) - -## Definitions +Using the [ssl_pkey](REFERENCE.md#ssl_pkey) type allows to generate SSL private keys. -### openssl::certificate::x509 +Note, that the private key is not encrypted by default[^1]. -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. +[^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: ```puppet -openssl::certificate::x509 { 'foo': - country => 'CH', - organization => 'Example.com', - commonname => $fqdn, -} +ssl_pkey { '/path/to/private.key': } ``` Advanced options: ```puppet -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: - -```puppet -openssl::export::pkcs12 { 'foo': +ssl_pkey { '/path/to/private.key': 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', + password => 'j(D$', } ``` -### openssl::export::pem_cert +### Create a certificate signing request -This definition exports PEM certificates from a pkcs12 container: +The [x509_request](REFERENCE.md#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](REFERENCE.md#opensslconfig) defined type. -```puppet -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: +Simple usage: ```puppet -openssl::export::pem_cert { 'foo': - ensure => 'present', - der_cert => '/here/is/my/certstore.der', - pem_cert => '/here/is/my/cert.pem', -} +x509_request { '/path/to/request.csr': } ``` - -### openssl::export::pem_key - -This definition exports PEM key from a pkcs12 container: +Advanced options: ```puppet -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', +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', } ``` -### openssl::dhparam - -This definition creates a dhparam PEM file: +### Create a certificate +Using the [x509_cert](REFERENCE.md#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: ```puppet -openssl::dhparam { '/path/to/dhparam.pem': } +x509_cert { '/path/to/certificate.crt': } ``` -which is equivalent to: +Advanced options: ```puppet -openssl::dhparam { '/path/to/dhparam.pem': - ensure => 'present', - size => 512, - owner => 'root', - group => 'root', - mode => '0644', +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', } ``` -Advanced usage: +### Get a certificate from a remote source + +The [cert_file](REFERENCE.md#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. ```puppet -openssl::dhparam { '/path/to/dhparam.pem': - ensure => 'present', - size => 2048, - owner => 'www-data', - group => 'adm', - mode => '0640', +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 -### cert_aia_caissuers +### Accessing the CA issuers URL from a certificate -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: +If a certificate contains the authorityInfoAccess extension, the [openssl::cert_aia_caissuers](REFERENCE.md#opensslcert_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: ```puppet file { '/ssl/certs/caissuer.crt': ensure => file, - source => Deferred('cert_aia_caissuers', ["/etc/ssl/certs/${facts['networking']['fqdn']}.crt"]), + source => Deferred('openssl::cert_aia_caissuers', ["/etc/ssl/certs/${facts['networking']['fqdn']}.crt"]), } ``` @@ -310,7 +277,6 @@ For pull requests, it is very much appreciated to check your Puppet manifest with [puppet-lint](https://github.com/puppetlabs/puppet-lint) to follow the recommended Puppet style guidelines from the [Puppet Labs style guide](http://docs.puppetlabs.com/guides/style_guide.html). - ## Transfer Notice This plugin was originally authored by [Camptocamp](http://www.camptocamp.com).