cfssl

Table of Contents

1. Description
2. Setup - The basics of getting started with cfssl
   • What cfssl affects
   • Setup requirements
   • Beginning with cfssl
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

cfssl is an api driven pki server written in go. This puppet module enables puppet to request certificates from cfssl.

Setup

What cfssl affects

This module will request a certificate based on the parameters you specify then save the signed certificate in the directory you specify.

Setup Requirements

This module uses built in ruby libraries and has no extra dependancies

Beginning with cfssl

The very basic steps needed for a user to get the module up and running. This can include setup steps, if necessary, or it can be an example of the most basic use of the module.

Usage

At minimum you require the following

cfssl{'mycert':
    ensure   => present,
    server   => 'http://127.0.0.1:9000',
    manifest => {
        'hosts' => ['jpst1.dink.io', 'san.dink.io'],
        'key'   => { 'algo' => 'rsa', 'size' => 4096 },
        'CN'    => 'host1.dink.io',
        'names' => [
            {
                'C'  => 'County',
                'ST' => 'State',
                'L'  => 'Locality',
                'O'  => 'Organisation'
            }
        ]
    }
}

The provided manifest is passed directly to the cfssl API. The documentation can be found here....

https://github.com/cloudflare/cfssl/tree/master/doc/api

Reference

To create a certificate

• ensure, Shall we create or remove the certificate
• server, The URI to the cfssl server
• certpath, Where will the certificate be saved (default: /etc/ssl)
• authkey, What key will be used. Only required for authenticated profiles. (optional)
• profile, What signing profile will be used (optional)
• label, What label will be used (optional)
• manifest, The particulars of the certificate to be signed

For example:

cfssl{'mycert':
    ensure   => present,
    server   => 'http://127.0.0.1:9000',
    certpath => '/etc/ssl',
    authkey  => 'ababababababababababababababab',
    profile  => 'endpoint',
    label    => 'label',
    manifest => {
        'hosts' => ['silly.dink.io'],
        'key'   => { 'algo' => 'rsa', 'size' => 4096 },
        'CN'    => 'Some CN',
        'names' => [
            {
                'C'  => 'Farnborough',
                'ST' => 'Hampshire',
                'L'  => 'Locality',
                'O'  => 'Organisation'
            }
        ]
    }
}

Limitations

This has been tested on linux, it will likely work on windows since we are using the builtin types

Ensuring absent will not revoke the certificate on the server

CFSSL has a gaping security hole where authentication on profiles can be ignored by using the 'newcert' endpoint. I am expecting that this functionality will change at some point so this code only uses the sign and authsign endpoints and switches based on weather you provide an authkey or not.

Development

TODO: Move the cfssl library out in to its own gem