Forge Home

pki

Manages non-Puppet PKI keys and certificates

21,523 downloads

179 latest version

4.7 quality score

We run a couple of automated
scans to help you access a
module's quality. Each module is
given a score based on how well
the author has formatted their
code and documentation and
modules are also checked for
malware using VirusTotal.

Please note, the information below
is for guidance only and neither of
these methods should be considered
an endorsement by Puppet.

Version information

  • 6.7.1 (latest)
  • 6.7.0
  • 6.6.0
  • 6.4.0
  • 6.3.0
  • 6.2.1
  • 6.2.0
  • 6.1.1
  • 6.1.0
  • 6.0.4
  • 6.0.3
  • 6.0.2
  • 6.0.1
  • 6.0.0
  • 4.2.5
  • 4.2.4
  • 4.2.3
released Jul 10th 2024
This version is compatible with:
  • Puppet Enterprise 2023.8.x, 2023.7.x, 2023.6.x, 2023.5.x, 2023.4.x, 2023.3.x, 2023.2.x, 2023.1.x, 2023.0.x, 2021.7.x, 2021.6.x, 2021.5.x, 2021.4.x, 2021.3.x, 2021.2.x, 2021.1.x, 2021.0.x
  • Puppet >= 7.0.0 < 9.0.0
  • , , , ,

Start using this module

  • r10k or Code Manager
  • Bolt
  • Manual installation
  • Direct download

Add this module to your Puppetfile:

mod 'simp-pki', '6.7.1'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add simp-pki
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install simp-pki --version 6.7.1

Direct download is not typically how you would use a Puppet module to manage your infrastructure, but you may want to download the module in order to inspect the code.

Download
Tags: certs, key, pki, simp, cert

Documentation

simp/pki — version 6.7.1 Jul 10th 2024

License CII Best Practices Puppet Forge Puppet Forge Downloads Build Status

simp-pki

Table of Contents

  1. Description
  2. Setup - The basics of getting started 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.