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. It requires keys to be managed under the PKI module at ${environmant}/modules/pki/files/keydist.

The keydist directory must have the following structure:

${environment}/modules/pki/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

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 or you can find us on HipChat.

Setup

What simp-pki affects

This module both adds your client X.509 PKI keys to the system at /etc/pki/{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 and mcollective
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.

This will automatically include the simp-pki class unless told otherwise.

pki::copy { '/etc/httpd': }

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

Development

Please read our Contribution Guide and visit our developer wiki.

• Fri Sep 30 2016 Chris Tessmer chris.tessmer@onyxpoint.com - 4.2.4-0

• Fixed dependencies in metadata.json prior to a Forge push.

• Wed Jul 06 2016 Trevor Vaughan tvaughan@onyxpoint.com - 4.2.3-0

• Fixed a permissions flapping issue between a file resource and the 'sync' provider.

• Tue Apr 12 2016 Kendall Moore kendall.moore@onyxpoint.com - 4.2.2-0

• Removed custom type deprecation warning

• Mon Mar 28 2016 Trevor Vaughan tvaughan@onyxpoint.com - 4.2.1-0

• Removed extraneous cacerts keys
• Updated the README
• Fixed code comments

• Sat Mar 19 2016 Trevor Vaughan tvaughan@onyxpoint.com - 4.2.0-0

• Added the ability to copy from arbitrary OS locations for pki::copy. This was mainly to support stunnel.

• Tue Feb 23 2016 Ralph Wright ralph.wright@onyxpoint.com - 4.1.0-9

• Added compliance function support

• Mon Jan 18 2016 Carl Caum carl@puppetlabs.com - 4.1.0-8

• Allow PKI file content source to be modified.

• Mon Dec 14 2015 Trevor Vaughan tvaughan@onyxpoint.com - 4.1.0-7

• Remove erroneous test5.simp.vm key from the keydist directory

• Mon Nov 09 2015 Chris Tessmer chris.tessmer@onyxpoint.com - 4.1.0-6

• Migration to simplib and simpcat (lib/ only)

• Tue Oct 13 2015 Nick Markowski nmarkowski@keywcorp.com - 4.1.0-5

• If a directory is placed in keydist/cacerts, the directory structure is copied to pki/cacerts, and all certs in subdirectories are appended to cacerts.pem.
• If a directory is removed from keydist/cacerts, it is now forcibly removed from .cacerts_ingress.

• Thu Feb 12 2015 Trevor Vaughan tvaughan@onyxpoint.com - 4.1.0-4

• Moved things to the new 'simp' environment
• Ensure the requirements on packages are appropriately defined

• Mon Feb 09 2015 Nick Markowski nmarkowski@keywcorp.com - 4.1.0-3

• A public RSA key is now generated off off the system private key, and placed in /etc/pki/public/fqdn_rsa.pem

• Sun Jun 22 2014 Kendall Moore kmoore@keywcorp.com - 4.1.0-2

• Removed MD5 file checksums for FIPS compliance.

• Fri Jun 20 2014 Trevor Vaughan tvaughan@onyxpoint.com - 4.1.0-2

• Modified code in the pki_cert_sync provider for Ruby 2 compatibility.

• Thu May 15 2014 Kendall Moore kmoore@keywcorp.com - 4.1.0-1

• Updated pki_cert_sync to (re)build a concatenated cacerts.pem file which is a bundled file of all valid CA certs in /etc/pki/cacerts.

• Tue Apr 08 2014 Kendall Moore kmoore@keywcorp.com - 4.1.0-0

• Updated manifests for puppet 3 and hiera compatibility.
• Refactored manifests to pass all lint tests.
• Removed the pki::pre class as all functionality now exists in the pki class.
• Added spec tests.

• Mon Mar 17 2014 Trevor Vaughan tvaughan@onyxpoint.com - 3.0.0-0

• Added a pki::copy define for properly copying the entire PKI set to an alternate location on the system with proper ordering.
• Rolled the pki::pre class into the main pki class.

• Mon Feb 17 2014 Kendall Moore kmoore@keywcorp.com - 2.0.0-6

• Added autorequire to pki_cert_sync for file destination.

• Fri May 31 2013 Trevor Vaughan tvaughan@onyxpoint.com - 2.0.0-5

• Created a native type to replace the hack set of execs for CA certificate synchronization. This is not perfect but it is far faster and better. Ideally, the type would be able to pull the files from the Puppet server itself. Also, the file resource for '/etc/pki/cacerts' was preserved for legacy code notification compatibility.

• Wed Apr 11 2012 Trevor Vaughan tvaughan@onyxpoint.com - 2.0.0-4

• Moved mit-tests to /usr/share/simp...
• Updated pp files to better meet Puppet's recommended style guide.

• Fri Mar 02 2012 Trevor Vaughan tvaughan@onyxpoint.com - 2.0.0-3

• Improved test stubs.

• Wed Dec 14 2011 Trevor Vaughan tvaughan@onyxpoint.com - 2.0.0-2

• Added an initial suite of tests
• Fixed the creation of certificate hashes and now hash on 'subject' not 'issuer'.
• Updated the spec file to not require a separate file list.
• The certificate hash script had errors with cert hashes beginning with a '0' as well as hashing on the issuer not the subject. Also, cleaned up the way the intermediate directory cleanup is handled.

• Thu Oct 27 2011 Trevor Vaughan tvaughan@onyxpoint.com - 2.0.0-1

• Updated the PKI module to create a two-step certificate placement so that the certificate hashes can be generated on the client. This is done due to RHEL6 using a different hashing algorithm than RHEL5

• Tue Jan 11 2011 Trevor Vaughan tvaughan@onyxpoint.com - 2.0.0-0

• Refactored for SIMP-2.0.0-alpha release

• Tue Oct 26 2010 Trevor Vaughan tvaughan@onyxpoint.com - 1-2

• Converting all spec files to check for directories prior to copy.

• Thu Jun 10 2010 Trevor Vaughan tvaughan@onyxpoint.com - 1.0-1

• No templates to copy in caused an RPM build failure.

• Mon May 24 2010 Trevor Vaughan tvaughan@onyxpoint.com - 1.0-0

• Code refactor and doc updates.