simp-pki

Table of Contents

1. Description
   • This is a SIMP module
2. Setup - The basics of getting started with simp-pki
   • What simp-pki affects
   • Setup requirements
   • Beginning with simp-pki
3. Usage - Configuration options and additional functionality
4. Reference - An under-the-hood peek at what the module is doing and how
5. Limitations - OS compatibility, etc.
6. Development - Guide for contributing to the module

Description

This module provides the capability to manage non-Puppet PKI keys that are hosted on the Puppet server.

The keydist directory must have the following structure:

  Under `${codedir}/${environment}/modules/#{module_name}/files/keydist/`:
  - cacerts
    - Any X.509 PEM formatted CA certificates that you want to serve to your
      clients. Do NOT hash these certificates. This will be done on the client
      side.
  - <fqdn>
    - cacerts
      - Any X.509 PEM formatted CA certificates that you want to serve to your
        clients. Do NOT hash these certificates. This will be done on the
        client side.
    - <fqdn>.pem -> Client Private Key
    - <fqdn>.pub -> Client Public Key

If $pki is set to 'simp', the keydist directory will have the same structure, however it will be located in a separate module path so keys don't get clobbered when using r10k:

• /var/simp/environments/${environment}/site_files/pki_files/files/keydist

This is a SIMP module

This module is a component of the System Integrity Management Platform, a compliance-management framework built on Puppet.

If you find any issues, they can be submitted to our JIRA.

Setup

What simp-pki affects

This module both adds your client X.509 PKI keys to the system at /etc/pki/simp/x509/{cacerts,private,public} and provides the ability to copy those certificates (or other certificates in the same directory format) into application spaces.

Setup Requirements

The main functionality of this module is supported by the use of a Puppet Server. However, the pki::copy functionality may be used without connectivity to the Puppet Server.

To use the server side functionality, you must have a special keydist Puppet share.

The following is the recommended addition to auth.conf for realizing this share:

# Everyone gets access to the cacerts
path ~ ^/file_(metadata|content)/modules/pki/keydist/cacerts
allow *


# Allow access to the keydist space for only the nodes that match via
# certificate name
path ~ ^/file_(metadata|content)/modules/pki/keydist/([^/]+)
allow $2

Beginning with simp-pki

Usage

To sync certificates to your system, simply include the pki class.

include '::pki'

To copy the certificates into your application space, use the pki::copy define. By default, the cert source is set to /etc/pki/simp. Three basic use-cases are described below.

If $pki is true or simp:

• The simp-pki class will be included
• Certificates will be centrally managed, in /etc/pki/simp_apps

For example:

pki::copy { 'httpd': }

This will result in the directory /etc/pki/simp_apps/httpd/x509 being created with the cacerts, public, and private subdirectories as specified in the keydist directory.

If $pki is false:

• The simp-pki class will not be included
• Certificates will not be centrally managed, and you must specify a $destination
• You must ensure the parent directories of $destination exist

For example:

pki::copy { 'httpd':
  $pki         => false,
  $destination => '/foo/bar'
}

This will result in the directory /foo/bar/pki being created with the cacerts, public, and private subdirectories as specified in the /etc/pki/simp/x509 directory.

To change the source of certificates to be distributed, use the global pki::source catalyst.

• You must ensure the source directory contains the proper cacerts, public, and private subdirectories, in the correct format. Nothing else will get copied.

In some_hieradata.yaml

simp_options::pki::source: /some/other/certs

In a manifest

pki::copy { 'httpd': }

This will result in the directory /etc/pki/simp_apps/httpd/x509 being created with the cacerts, public, and private subdirectories as specified in the /some/other/certs directory.

Reference

Please refer to the REFERENCE.md, generated by Puppet strings.

Development

Please read our Contribution Guide.