Forge Home

Modules

Puppet

Resources

PuppetEcosystemPuppet CommunityUpdates

ca_trust

Installs trusted PEM anchors into the system bundle.
Project URLRSS FeedReport issues

9,408 downloads

937 latest version

5.0 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

  • 1.1.7 (latest)
  • 1.1.6
  • 1.1.5
  • 1.1.4
  • 1.1.3
  • 1.1.2
  • 1.1.1
  • 1.1.0
  • 1.0.1
  • 1.0.0
released Apr 26th 2021
This version is compatible with:
  • Puppet Enterprise 2019.8.x, 2019.7.x, 2019.5.x, 2019.4.x, 2019.3.x, 2019.2.x, 2019.1.x, 2019.0.x, 2018.1.x
  • Puppet >= 5.5.0 < 7
  • , , , , , ,
Tasks:
  • rebuild

Start using this module

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

Add this module to your Puppetfile:

mod 'phoenixnap-ca_trust', '1.1.7'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add phoenixnap-ca_trust
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install phoenixnap-ca_trust --version 1.1.7

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

Documentation

phoenixnap/ca_trust — version 1.1.7 Apr 26th 2021

ca_trust

Table of Contents

Overview

Manage CA Trust anchors within the ca-certificates framework.

Supported Platforms

  • RedHat & Derivatives >= 6.x
  • Debian & Derivatives >= 8.x
  • Fedora >= 25

Note: RedHat 6, and deriviates, alongside Debian 8 are now depricated. The EOL of these products is less than a year away. Support for these products will be removed when they reach end of life.

CentOS 8 and Ubuntu 20 do not yet undergo acceptance testing. All other testing applies, but beaker is not yet ready to support these platforms.

Module Description

The ca_trust module is for managing additions to the root CA bundle supplied by OS vendors. Used by applications to establish trust, the root CA bundle is usually shipped containing only 3rd party or commercial CA certificates. Administrators are expected to add their own internal or self signed certificates to the OS vendor supplied bundles as needed.

The module currently supports adding PEM encoded CA anchors.

Setup

To prepare supported operating systems to receive new trusted CA anchors.

include ca_trust

To do the same, but include non-standard options.

class { '::ca_trust':
  cert_dir => '/some/other/directory',
}

See [Reference](REFERENCE#ca_trust) for all options supported by the main class.

Usage

On supported operating systems, the [Setup](#setup) process is entirely unnecessary, simply begin by declaring any [ca_trust::pem::anchors](#pem-anchors) necessary.

If things need to be customized, then the ca_trust main class can be specified explicitly, like it is in the [Setup](#setup) section. Alternatively, the ca_trust main class may be customized via hiera.

---
# Hiera YAML file.
# Use some other command to update root bundle certificates instead of
# OS default.
ca_trust::update_cmd: /some/other/binary

# Puppet profile.

include ca_trust

Legacy PEM Anchors

To install new CA certificates into the operating system's trusted bundle, use the ca_trust::pem::anchor type. When specifying anchors, do not specify the filename extension (.crt, .pem, etc.). Some platforms are picky about the extension used, so the module will choose the appropriate default for the platform. For instance, Debian expects the certificates to end in .crt.

ca_trust::pem::anchor { 'self-signed':
  source => 'puppet:///modules/profile/node-one/self-signed-cert.pem',
}

ca_trust::pem::anchor { 'expired-cert':
  ensure => 'absent',
}

ca_trust::pem::anchor { 'My Company\'s Internal CA':
  source   => 'puppet:///modules/profile/organization-ca.pem',
  filename => 'org-ca',
}

$cert_data = @(EOT)
----- BEGIN CERTIFICATE -----
...blah blah blah, PEM encoded certificate here....
----- END CERTIFICATE -----
| EOT

ca_trust::pem::anchor { 'Org-CA':
  content => $cert_data,
}

For convienience you may also specify any anchors you'd like when you declare the ca_trust class, if you are doing so explicitly.

class { '::ca_trust':
  update_cmd => 'my-custom-command.sh',
  anchors    => {
    'org-ca' => {
      'source' => 'puppet:///modules/profile/my-company-ca.pem',
    },
    'expired-ca' => {
      'ensure' => 'absent',
    },
  },
}

Anchors from Hiera

The class ca_trust::pem::anchors is included for hiera convienience. With it, you may pass in a hash of ca_trust::pem::anchor resources to manage.

---
# Node's hiera yaml.
ca_trust::pem::anchors::resources:
  org-ca: 
    source: puppet:///modules/profile/my-company-ca.pem
  expired-ca:
    ensure: absent
  my-ca:
    content: >
      ----- BEGIN CERTIFICATE ------
      .... cert data here .....
      ----- END CERTIFICATE -----

Facts

The following facts are exposed.

trust_bundle - On supported operating systems this fact resolves to the path of the system-wide trusted CA bundle. bundled_authorities - This fact exposes pertinent information for each certificate in the bundle. It returns a hash, keyed on fingerprint.

e.g.

$:facts['bundled_authorities'] = {
  b561ebeaa4dee4254b691a98a55747c234c7d971 => {
    subject => "/C=SK/L=Bratislava/O=Disig a.s./CN=CA Disig Root R2",
    issuer => "/C=SK/L=Bratislava/O=Disig a.s./CN=CA Disig Root R2",
    not_before => "2012-07-19 09:15:30 UTC",
    not_after => "2042-07-19 09:15:30 UTC"
  },
  ...,
  e2b8294b5584ab6b58c290466cac3fb8398f8483 => {
    subject => "/C=CN/O=China Financial Certification Authority/CN=CFCA EV ROOT",
    issuer => "/C=CN/O=China Financial Certification Authority/CN=CFCA EV ROOT",
    not_before => "2012-08-08 03:07:01 UTC",
    not_after => "2029-12-31 03:07:01 UTC"
  }

Tasks

ca_trust::rebuild - Rebuilds the system's CA trust bundle using the operating system's prescribed manner. Note that this rebuild will include any ca_trust::pem::anchors already installed on the system. This will not reset the bundle to system default.

Development

This module has been converted to use the [Puppet Development Kit](https://puppet.com/docs/pdk/1.x/pdk.html).

Source Validation

pdk validate

Unit Testing

pdk test unit

For better output, or to debug a specific spec, the old standby bundle exec rake spec_prep and bundle exec rspec <filename> still functions flawlessly. Be sure to run bundle exec rake spec_clean before going back to pdk test unit though.

TODO

  • When beaker is ready to support CentOS 8 and Ubuntu 20, add them to nodesets.
  • Eventually support should be added for Windows platforms, to install new CA's into the system or user Certificate databases.

Changes

See the [change log](CHANGELOG).