cfssl

Install and configure CFSSL PKI.

Project URL RSS Feed Report issues

Module Stats

551 downloads

197 latest version

5.0 quality score

Version information

released Dec 1st 2022

This version is compatible with:

Puppet Enterprise 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, 2019.8.x
Puppet >= 6.21.0 < 8.0.0

Start using this module

Installation method

Add this module to your Puppetfile:

mod 'adullact-cfssl', '2.1.0'

Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add adullact-cfssl

Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install adullact-cfssl --version 2.1.0

Tags: pki, cfssl

Documentation

adullact/cfssl — version 2.1.0 Dec 1st 2022

cfssl

This module install and configure CFSSL to serve as a PKI.

Description
Setup - The basics of getting started with cfssl
Usage - Configuration options and additional functionality
Limitations - OS compatibility, etc.
Development - Guide for contributing to the module

Description

With this module you can setup a self signed root certificat authority and intermediates authorities signed by the root authority. Then via a API you can serve one of these authorities.

Setup

What cfssl affects

In addition to CFSSL, this module install Go, Goose and PostgreSQL.

Beginning with cfssl

To setup your own self signed root authority, it is as simple as :

class { 'cfssl':
  rootca_manifest => {
    cn      => 'MYEXEMPLE ROOT CA',
    subject => {
      'C' => 'FR',
      'L' => 'MONTPELLIER',
      'O' => 'MYEXEMPLE ORG',
    },
  },
}

From here, you are able to procude certificates from cfssl command line with shell on the host.

Usage

With served self signed root certificate authority

In this example :

self signed root ca is installed.
this root ca is served via HTTP API server for X509 certificates.
a CRL is generated in $cfssl::crldir directory, updated periodicaly as defined by $cfssl::crl_gentimer.
the CRL have a duration of validity defined by cfssl::crl_expiry

class { 'cfssl':
  rootca_manifest => {
    cn      => 'MYEXEMPLE ROOT CA',
    subject => {
      'C' => 'FR',
      'L' => 'MONTPELLIER',
      'O' => 'MYEXEMPLE ORG',
    },
  },
  serve_ca        => 'MYEXEMPLE ROOT CA',
  crl_manage      => true,
}

With served intermediate certificate authority

In this example :

a self signed root authority is installed.
an intermediate authority signed by root authority is installed.
this intermediate authority is served via HTTP API server for X509 certificates.
CRL are generated in $cfssl::crldir directory, updated periodicaly as defined by $cfssl::crl_gentimer.
the CRL have a duration of validity defined by cfssl::crl_expiry

class { 'cfssl':
  rootca_manifest => {
    cn      => 'MYEXEMPLE ROOT CA',
    subject => {
      'C' => 'FR',
      'L' => 'MONTPELLIER',
      'O' => 'MYEXEMPLE ORG',
    },
  },
  intermediatesca => {
    'MYEXEMPLE INTERMDIATE CA' => {
      subject => {
        'C' => 'FR',
        'L' => 'MONTPELLIER',
        'O' => 'MYEXEMPLE ORG',
      },
    },
  },
  serve_ca   => 'MYEXEMPLE INTERMDIATE CA',
  crl_manage => true,
}

Note about authkey

With CFSSL serve, it is possible to restrict acces to end points sign and authsign. In this case a key have to be configured in serve_config parameter. It is possible to generated a key with this command : hexdump -n 16 -e "4/4 \"%08X\" 1 \"\n\"" /dev/random

Reference

Details are in REFERENCE.md file.

Limitations

Supported OSes are given in metadata.json file.

Development

Home at URL https://gitlab.adullact.net/adullact/puppet-cfssl

Issues and MR are welcome.

Release Notes/Contributors/Etc.

Details in CHANGELOG.md.

Copyright (C) 2018 Association des Développeurs et Utilisateurs de Logiciels Libres
                     pour les Administrations et Colléctivités Territoriales.

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published
by the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

You should have received a copy of the GNU Affero General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/agpl.html>.

Reference

Classes

Public Classes

cfssl: Install and configure CFSSL, serve process and CRL generation.
cfssl::ca::gencrls: Creates services to generate CRL for a list of CA
cfssl::ca::intermediates: Creates cfssl::ca::intermediate defined types.
cfssl::ca::root: Init a selfsigned root authority
cfssl::params: A short summary of the purpose of this class

Private Classes

cfssl::goose: Installs Goose, a database migration tool used by CFSSL

Defined types

Public Defined types

cfssl::ca::intermediate: Creates an intermediate authority signed by root authority

Private Defined types

cfssl::ca::gencrl: Creates a service to generate CRL for a CA

Creates a service to generate CRL for a CA

Data types

Cfssl::Authkey: Struct representing authentication key used by CFSSL serve during sign requests
Cfssl::Ca::Key: Cryptographic algorithm used for creating key pairs.
Cfssl::Serveconfig: Struct representing CFSSL serve configuration
Cfssl::Signing::Profile: Struct describing a profile in CFSSL serve config file.
Cfssl::Usage: List of usages accepted by CFSSL for X509 certificat

Classes

`cfssl`

Install and configure CFSSL, serve process and CRL generation.

Examples

class { 'cfssl':
  rootca_manifest => {
    cn      => 'MYEXEMPLE ROOT CA',
    subject => {
      'C' => 'FR',
      'L' => 'MONTPELLIER',
      'O' => 'MYEXEMPLE ORG',
    },
  },
  intermediatesca => {
    'MYEXEMPLE INTERMDIATE CA' => {
      subject => {
        'C' => 'FR',
        'L' => 'MONTPELLIER',
        'O' => 'MYEXEMPLE ORG',
      },
    },
  },
  serve_ca   => 'MYEXEMPLE INTERMDIATE CA',
  crl_manage => true,
}

Parameters

The following parameters are available in the cfssl class:

downloadurl
version
downloadchecksum
checksum_type
sysuser_manage
sysuser
sysgroup
binding_ip
port
log_level
logdir
dbname
dbuser
dbpassword
confdir
binpath
rootca_manifest
intermediatesca
serve_config
crl_manage
crldir
crldir_manage
crl_expiry
crl_gentimer
crl_extension
serve_ca

`downloadurl`

Data type: Stdlib::HTTPSUrl

CFSSL download URL

Default value: 'https://github.com/cloudflare/cfssl/releases/download'

`version`

Data type: String[1]

Downloaded version of CFSSL binary

Default value: '1.6.3'

`downloadchecksum`

Data type: String[1]

Checksum of CFSSL binary

Default value: '16b42bfc592dc4d0ba1e51304f466cae7257edec13743384caf4106195ab6047'

`checksum_type`

Data type: Enum['md5', 'sha1', 'sha2','sha256', 'sha384', 'sha512']

Type of checksum used

Default value: 'sha256'

`sysuser_manage`

Data type: Boolean

To enable/disable the creation of sysuser and sysgroup. To permit manage users by external process.

Default value: true

`sysuser`

Data type: String[1]

Operating system user account owner of CFSSL files

Default value: 'cfssl'

`sysgroup`

Data type: String[1]

Operating system group owner of CFSSL files

Default value: 'cfssl'

`binding_ip`

Data type: Stdlib::IP::Address

IP adresse binded by CFSSL serve process.

Default value: '127.0.0.1'

`port`

Data type: Stdlib::Port

The port used by CFSSL serve process.

Default value: 8080

`log_level`

Data type: Enum['0','1','2','3','4']

The loglevel defined for CFSSL serve process.

Default value: '1'

`logdir`

Data type: Stdlib::Absolutepath

The directory where log are written.

Default value: '/var/log/cfssl'

`dbname`

Data type: String[1]

The name of database used by CFSSL.

Default value: 'db_cfssl'

`dbuser`

Data type: String[1]

A Postgresql role used by CFSSL to connect the database.

Default value: 'u_cfssl'

`dbpassword`

Data type: Variant[String[1], Sensitive[String]]

A password of the dbuser.

Default value: ('changeme')

`confdir`

Data type: Stdlib::Absolutepath

The directory where configurations are written.

Default value: '/etc/cfssl'

`binpath`

Data type: Stdlib::Absolutepath

The path when CFSSL binaries are.

Default value: '/usr/local/bin'

`rootca_manifest`

Data type: Hash

Manifest defining the root autority.

Default value: { cn => 'EXEMPLE ROOT CA', subject => { 'C' => 'FR', 'L' => 'MONTPELLIER', 'O' => 'EXEMPLE ORG', } }

`intermediatesca`

Data type: Hash

Manifests defining intermediat autorities signed by root autority.

Default value: {}

`serve_config`

Data type: Cfssl::Serveconfig

The configuration of CFSSL serve process.

Default value: { signing => { 'default' => { expiry => '1h', usages => ['client auth'] } } }

`crl_manage`

Data type: Boolean

If true a CRL file is generated from the served autority.

Default value: false

`crldir`

Data type: Stdlib::Absolutepath

A directory where the CRL file is written.

Default value: '/var/cfssl'

`crldir_manage`

Data type: Boolean

Determines whether Puppet manages the crldir directory.

Default value: true

`crl_expiry`

Data type: Integer

A value, in seconds, after which the CRL should expire from the moment of the request

Default value: 604800

`crl_gentimer`

Data type: String[1]

Systemd timer https://www.freedesktop.org/software/systemd/man/systemd.time.html

Default value: '*:00:00'

`crl_extension`

Data type: String[1]

The filename extension suffix used form generated CRL.

Default value: 'pem'

`serve_ca`

Data type: Optional[String[1]]

The Certificate authority served with CFSSL serve

Default value: undef

`cfssl::ca::gencrls`

Creates services to generate CRL for a list of CA

Examples

class { 'cfssl::ca::gencrls':
  authorities => [
    'MYEXEMPLE ROOT CA',
    'MYEXEMPLE INTERMDIATE CA',
  ],
}

Parameters

The following parameters are available in the cfssl::ca::gencrls class:

authorities

`authorities`

Data type: Array[String]

A list of authority CN's, already defined.

Default value: []

`cfssl::ca::intermediates`

Creates cfssl::ca::intermediate defined types.

Examples

class { 'cfssl::ca::intermediates':
  'MYEXEMPLE INTERMDIATE CA' => {
    subject => {
      'C' => 'FR',
      'L' => 'MONTPELLIER',
      'O' => 'MYEXEMPLE ORG',
    },
    key     => {
      algo => 'ecdsa',
      size => 256,
    },
  },
}

Parameters

The following parameters are available in the cfssl::ca::intermediates class:

intermediates

`intermediates`

Data type: Hash

A hash wherethe key is the common name and the value represents a hash of cfssl::ca::intermediate defined type's parameters.

Default value: {}

`cfssl::ca::root`

Init a selfsigned root authority

Examples

class { 'cfssl::ca::root':
  cn      => 'MYEXEMPLE ROOT CA',
  subject => {
    'C' => 'FR',
    'L' => 'MONTPELLIER',
    'O' => 'MYEXEMPLE ORG',
  },
}

Parameters

The following parameters are available in the cfssl::ca::root class:

subject
cn
expiry
key

`subject`

Data type: Hash

Hash like Subject in X509 that identifies the entity associated

`cn`

Data type: String[1]

Common name of authority

`expiry`

Data type: String[1]

Duration of authority

Default value: '43800h'

`key`

Data type: Cfssl::Ca::Key

Cryptographic algorithm used for creating key pairs.

Default value: { algo => 'rsa', size => 2048 }

`cfssl::params`

A description of what this class does

Examples

include cfssl::params

Defined types

`cfssl::ca::intermediate`

Creates an intermediate authority signed by root authority

Examples

cfssl::ca::intermediate { 'MYEXEMPLE INTERMDIATE CA':
  subject => {
    'C'   => 'FR',
    'L'   => 'MONTPELLIER',
    'O'   => 'MYEXEMPLE ORG',
  },
}

Parameters

The following parameters are available in the cfssl::ca::intermediate defined type:

subject
expiry
key
crl_url
ocsp_url

`subject`

Data type: Hash

Hash like Subject in X509 that identifies the entity associated

Default value: { 'C' => 'FR', 'L' => 'MONTPELLIER', 'O' => 'EXEMPLE ORG', }

`expiry`

Data type: String[1]

Duration of authority

Default value: '26280h'

`key`

Data type: Cfssl::Ca::Key

Cryptographic algorithm used for creating key pairs.

Default value: { algo => 'rsa', size => 2048 }

`crl_url`

Data type: Optional[Stdlib::HTTPUrl]

The CRL url of the Root CA that issued intermediate CA.

Default value: undef

`ocsp_url`

Data type: Optional[Stdlib::HTTPUrl]

The OCSP responder of the Root CA that issued intermediate CA.

Default value: undef

Data types

`Cfssl::Authkey`

Struct representing authentication key used by CFSSL serve during sign requests

Alias of

Struct[{
    type => Enum['standard'],
    key  => String[1],
}]

`Cfssl::Ca::Key`

Cryptographic algorithm used for creating key pairs.

Alias of

Struct[{
    algo => Enum['rsa','ecdsa'],
    size => Integer,
}]

`Cfssl::Serveconfig`

Struct representing CFSSL serve configuration

Alias of

Struct[{
    auth_keys => Optional[Hash[String,Cfssl::Authkey]],
    signing   => Struct[{
        'default' => Cfssl::Signing::Profile,
        profiles  => Optional[Hash[String,Cfssl::Signing::Profile]],
    }],
}]

`Cfssl::Signing::Profile`

Struct describing a profile in CFSSL serve config file.

Alias of

Struct[{
    expiry         => String[1],
    usages         => Array[Cfssl::Usage],
    crl_url        => Optional[Stdlib::HTTPUrl],
    ocsp_url       => Optional[Stdlib::HTTPUrl],
    not_before     => Optional[String[1]],
    not_after      => Optional[String[1]],
    name_whitelist => Optional[String[1]],
    auth_key       => Optional[String[1]],
}]

`Cfssl::Usage`

List of usages accepted by CFSSL for X509 certificat

Alias of

Enum['signing', 'digital signature', 'content commitment', 'key encipherment', 'key agreement', 'data encipherment', 'cert sign', 'crl sign', 'encipher only', 'decipher only', 'any', 'server auth', 'client auth', 'code signing', 'email protection', 's/mime', 'ipsec end system', 'ipsec tunnel', 'ipsec user', 'timestamping', 'ocsp signing', 'microsoft sgc', 'netscape sgc']

Modules

Discover

Contribute

Topics

How-to Guides

Collections

Resources

About Forge

Getting Started

cfssl

Version information

This version is compatible with:

Start using this module

Documentation

cfssl

Table of Contents

Description

Setup

What cfssl affects

Beginning with cfssl

Usage

With served self signed root certificate authority

With served intermediate certificate authority

Note about authkey

Reference

Limitations

Development

Release Notes/Contributors/Etc.

Reference

Table of Contents

Classes

Public Classes

Private Classes

Defined types

Public Defined types

Private Defined types

Data types

Classes

cfssl

Examples

Parameters

downloadurl

version

downloadchecksum

checksum_type

sysuser_manage

sysuser

sysgroup

binding_ip

port

log_level

logdir

dbname

dbuser

dbpassword

confdir

binpath

rootca_manifest

intermediatesca

serve_config

crl_manage

crldir

crldir_manage

crl_expiry

crl_gentimer

crl_extension

serve_ca

cfssl::ca::gencrls

Examples

Parameters

authorities

cfssl::ca::intermediates

Examples

Parameters

intermediates

cfssl::ca::root

Examples

Parameters

subject

cn

`cfssl`

`downloadurl`

`version`

`downloadchecksum`

`checksum_type`

`sysuser_manage`

`sysuser`

`sysgroup`

`binding_ip`

`port`

`log_level`

`logdir`

`dbname`

`dbuser`

`dbpassword`

`confdir`

`binpath`

`rootca_manifest`

`intermediatesca`

`serve_config`

`crl_manage`

`crldir`

`crldir_manage`

`crl_expiry`

`crl_gentimer`

`crl_extension`

`serve_ca`

`cfssl::ca::gencrls`

`authorities`

`cfssl::ca::intermediates`

`intermediates`

`cfssl::ca::root`

`subject`

`cn`

`expiry`

`key`

`cfssl::params`

`cfssl::ca::intermediate`

`subject`

`expiry`

`key`

`crl_url`

`ocsp_url`

`Cfssl::Authkey`

`Cfssl::Ca::Key`

`Cfssl::Serveconfig`

`Cfssl::Signing::Profile`

`Cfssl::Usage`