Push new version to the Forge

OpenSSL Puppet Module

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

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¹.

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

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. ↩

	ini_file = Puppet::Util::IniConfig::PhysicalFile.new(resource[:template])
	if (req_ext = ini_file.get_section('req_ext'))
	if (value = req_ext['subjectAltName']) && (value.delete(' ').gsub(%r{^"\|"$}, '') != alt_name.delete(' ').gsub(%r{^"\|"$}, '').gsub('IPAddress', 'IP'))
	return false
	end
	elsif (req_dn = ini_file.get_section('req_distinguished_name'))
	if (value = req_dn['commonName']) && (value != cdata['CN'])
	return false
	end
	end

voxpupuli / puppet-openssl Goto Github PK

puppet-openssl's Introduction

OpenSSL Puppet Module

Setup

Usage

Create X.509 certificates

Create X.509 certificates from a hash

Export a key pair to PKCS#12

Export certificate(s) to PEM/x509 format

Export a key to PEM format

Create Diffie-Hellman parameters

Create a private key

Create a certificate signing request

Create a certificate

Get a certificate from a remote source

Functions

Accessing the CA issuers URL from a certificate

Contributing

Transfer Notice

Footnotes

puppet-openssl's People

Contributors

Stargazers

Watchers

Forkers

puppet-openssl's Issues

Problem description

Environment

Additional context

Affected Puppet, Ruby, OS and module versions/distributions

How to reproduce (e.g Puppet code you use)

What are you seeing

What behaviour did you expect instead

Output log

Any additional information you'd like to impart

Recommend Projects

Recommend Topics

Recommend Org