SSL Certificate module for Puppet

Table of Contents

1. Overview
2. Module Description - What the module does and why it is useful
3. Setup - The basics of getting started with sslcertificate
   • What sslcertificate affects
   • Beginning with sslcertificate
4. Usage - Configuration options and additional functionality
   • Parameters
   • Examples
5. Reference - An under-the-hood peek at what the module is doing and how
6. Limitations - OS compatibility, etc.
7. Development - Guide for contributing to the module

Overview

Puppet Module to manage Windows certificates.

Module Description

This sslcertificate module will allow you to install and remove your certificates on Windows machines. It can manage pfx, cer, crt and pem certificates.

The module is based/uses code from the following module:

• voxpupuli-puppet-sslcertificate: https://github.com/voxpupuli/puppet-sslcertificate

Although we borrowed the powershell scripts from voxpupuli, this module does not yet support all certificate types that voxpupuli does. This module uses Hiera to install certificates so you will have to convert your certificate file to a Base64 string.

It is also possible to list all Local Machine certificates using:

• puppet resource sslcertificate
• puppet resource sslcertificate

Setup

Setup Requirements

This module requires:

• puppetlabs-stdlib
• puppetlabs-powershell

If you want to manage pem certificates, you will need OpenSSL. OpenSSL.Light can be installed from this module by including the following code: include sslcertificate.

What sslcertificate affects

This module will install certificates into your Windows key stores. It is also possible to remove certificates.

Beginning with sslcertificate

To install a certificate in the My directory of the LocalMachine root store:

    sslcertificate { '<certificate_name>' :
      ensure              => 'present'
      path                => 'LocalMachine\<store>\<thumbprint>',
      password            => '<password>',
      format              => '<format>',
      exportable          => true,
      certificate_content => '<certificate_content>'
    }

Usage

Parameters

This module accepts the following parameters:

ensure

Type: string Default: 'present' Values: 'present' or 'absent' Description: This is to determine if a certifcate needs to be installed or removed.

path

Type: string Default: nil Values: Any valid certificate path but always starts with LocalMachine. (LocalMachine\\ Description: This is the path where the certifcate will be installed. The thumbprint is always 40 hexidecimal uppercase characters.

password

Type: string Default: 'dummy' Values: Any valid password or passphrase, including spaces. Description: Only use a password if the certificate is password protected.

format

Type: string Default: nil Values: 'cer', 'crt' or 'pfx' Description: This is the format of the certificate.

exportable

Type: boolean Default: true Values: true or false Description: Sets the key to be exportable.

certificate_content

Type: string Default: nil Values: Plaintext value to create the certificate Description: This contains the certifcate content to create the certificate file that will be imported.

Examples

To install a certificate in an alternative directory:

    sslcertificate { 'certificate_pfx:' :
      ensure     => 'present',
      path       => 'LocalMachine\CA\C50BE50FCF7AF3E7D42C21A349D6153551D50F2A',
      format     => 'pfx',
      password   => 'the cow jumped over the moon',
      certificate_content => 'MIIGzzCCBLegAwIBAgIEATE3FzANBgkqhkiG9w0BAQsFADBhMQswCQYDVQQGEwJO
            ovEj8FQY2pHm4qISNjQcSF86aNzIGn84hbsCDmJ8VeeoUAOhUaCwn38kquDSCaeQ
            Y3EVQGaRWS5eLJEFireJ8ABWmVKNOf2q+p9DZIhU2KefmKmeED9icW8sUMy9Mfpz
            B8lFPm+xqlsIm0LbGTuzN6g5fNgy+73PiME6qnYDkmXeZ3+qDpn/pTGHj986cR7Z
            /dgPkADVTzhhPOgUSaUW2/AEgOMPJyOmw5YpxgjxkIdcnvzgQc3y3zqj56vGx7Sa
            xLtMvKTEtFFMDMBZHUkiBOfyOaTEA5Bmbn0p6DyGNMu1a4MgDun7hxtG74Ao8DDe
            ejkB6QA+v4qzlHk+clOyHFyNJ9BUc70kmv9AWM4DLYX5cUGgMiJObh07DjGQrcRo
            XHpiIw4GzrOv7zZrpZ2Y5Roi86cJyrsaAENr69NZ56Heqamsv4jvyJMVOUyWw+qb
            l409YpY9zs9PyeP2WLK3rIH3hQ=='
    }

To remove a certificate:

    sslcertificate { 'any_certificate' :
      ensure        => 'absent',
      path          => 'LocalMachine\CA\C50BE50FCF7AF3E7D42C21A349D6153551D50F2A
    }

Reference

Provider

• sslcertificate

Limitations

This module works on:

• Windows 2008 R2
• Windows 2012 R2
• Windows 2016
• Windows 2019

Development

You can contribute by submitting issues, providing feedback and joining the discussions.

Go to: https://github.com/kpn-puppet/puppet-kpn-sslcertificate

If you want to fix bugs, add new features etc:

• Fork it
• Create a feature branch ( git checkout -b my-new-feature )
• Apply your changes and update rspec tests
• Run rspec tests ( bundle exec rake spec )
• Commit your changes ( git commit -am 'Added some feature' )
• Push to the branch ( git push origin my-new-feature )
• Create new Pull Request

2021-01-22 Release 4.1.5

• bugfix to use the specified cert-store folder instead of assuming the personal (my) store
• bugfix for windows private key import to persistent machine store
• fix importing a root cert into the trusted root store instead of the personal store (if present in a pfx file)
• fix importing an intermediate cert into the trusted intermediates store instead of the personal store (if present in a pfx file)
• change certificate install powershell script to not use string evaluation where not needed.
  • This allows e.g. a $ character in the password (a single quote still causes problems as it terminates the string)
• add windows 2019 as a supported platform
• fix rspec and beaker tests
• add support for PEM certificates

2018-03-21 Release 1.0.2

• add support for Puppet 5

2018-03-15 Release 1.0.1

• updated README.md

2018-03-13 Release 1.0.0

• sslcertificate has been rewriten als a provider.
• sslcertificate now has new/different parameters. Please check the README.MD
• a certificate can now be (ensure) present or absent
• sslcertificate no longer uses certificate files as source for the import. This also means that certificate files are not left behind on the client.