REFERENCE.md

Reference

Table of Contents

Classes

• tlsinfo: A short summary of the purpose of this class
• tlsinfo::params
• tlsinfo::tools::cfssl: CFSSL toolkit installation

Defined types

• tlsinfo::certificate: SSL certificate setup
• tlsinfo::certpair: Certificate pair.

Resource types

• sslcertificate: Certificate subject hash (read only)
• sslkey: Encrypted private key password

Functions

• tlsinfo::certpath
• tlsinfo::keypath
• tlsinfo::lookup
• tlsinfo::normalize

Plans

• tlsinfo::update: Update certificate and private key

Classes

tlsinfo

A description of what this class does

Examples

include tlsinfo

Parameters

The following parameters are available in the tlsinfo class.

certbase

Data type: Optional[Stdlib::Unixpath]

Directory where certificate files are stored in the system (RedHat and Debian based systems are predefined)

keybase

Data type: Optional[Stdlib::Unixpath]

Directory where private key files are stored in the system (RedHat and Debian based systems are predefined)

cfssl_version

Data type: Optional[String]

Version of CF SSL toolkit to install using tlsinfo::tools::cfssl see https://github.com/cloudflare/cfssl/releases

tlsinfo::params

The tlsinfo::params class.

tlsinfo::tools::cfssl

CFSSL toolkit installation

Examples

include tlsinfo::tools::cfssl

Parameters

The following parameters are available in the tlsinfo::tools::cfssl class.

version

Data type: Optional[Pattern[/^1\.[4-9][1-9]?\./]]

Default value: $tlsinfo::cfssl_version

download_source

Data type: String

Default value: $tlsinfo::params::cfssl_download_source

tmpdir

Data type: Stdlib::Absolutepath

Default value: $tlsinfo::params::download_tmpdir

Defined types

tlsinfo::certificate

SSL certificate setup

Examples

Considering 'basepath' as '/etc/pki/tls/certs' (default to CentOS)
this will create certificate file '/etc/pki/tls/certs/<subject_hash>.pem' as well
as will create file '/etc/pki/tls/certs/4f06f81d.crt' and also will create symlink
'/etc/pki/tls/certs/LetsEncryptAuthorityX3.pem' which points to '<subject_hash>.pem'
Also it will push content of Intermediate CA certificate into certificate
file as well as Root CA certificate

tlsinfo::certificate { "/C=US/O=Let's Encrypt/CN=Let's Encrypt Authority X3":
  cert   => file('profile/certs/4f06f81d.crt'),
  link   => 'LetsEncryptAuthorityX3.pem',
  path   => '4f06f81d.crt',
  cacert => true,
  rootca => true,
}

Example of intermediate certificates chain:

tlsinfo::certificate { '/C=GB/ST=Greater Manchester/L=Salford/O=COMODO CA Limited/CN=COMODO High Assurance Secure Server CA':
  cert => file('profile/certs/ComodoHighAssuranceSecureServerCA.crt'),
  link => 'ComodoHighAssuranceSecureServerCA.pem',
  path => 'ComodoHighAssuranceSecureServerCA.crt',
}

tlsinfo::certificate { '/C=GB/ST=Greater Manchester/L=Salford/O=COMODO CA Limited/CN=COMODO RSA Domain Validation Secure Server CA':
  cert   => file('profile/certs/COMODORSADomainValidationSecureServerCA.crt'),
  link   => 'COMODORSADomainValidationSecureServerCA.pem',
  path   => 'COMODORSADomainValidationSecureServerCA.crt',
  cacert => true,
}

Parameters

The following parameters are available in the tlsinfo::certificate defined type.

cert

Data type: Optional[String]

Certificate data to use for verification and processing. If not provided tlsinfo::certificate will look for Hiera key "#{name}_certificate" with "name" normalized with next rules (string replacement):

1. '*' -> 'wildcard'
2. '.' -> '_'
3. '-' -> '_'
4. "'" -> '_'
5. ' ' -> '_'

Default value: undef

basepath

Data type: Optional[Stdlib::Unixpath]

System path where certificate data usually stored (eg /etc/pki/tls/certs on CentOS)

Default value: $tlsinfo::certbase

cacert

Data type: Optional[ Variant[ Boolean, Stdlib::Unixpath, Array[Stdlib::Unixpath] ] ]

Could be Boolean true or false:

• true means CA Intermediate certificate already MUST be defined in catalog
• false means we do not manage CA Intermediate certificate (therefore validation over CA will not happen) Also could be a Full path to certificate or array of paths (for example, if certificate chain has 2 or more Intermediate CA)

Default value: undef

path

Data type: Optional[ Variant[ Stdlib::Unixpath, Pattern[/^[^\/]+\.(pem|crt|cer|cert)$/] # basename (relative to basepath/certbase) ] ]

Absolute path or relative to system certificate base directory where certificate data either provided with parameter cert or found using Hiera key #{name}_certificate should be stored. It will be saved "as is" without verification and processing

Default value: undef

rootca

Data type: Boolean

Whether to place Root CA certificate into certificate file or not

Default value: false

chain

Data type: Boolean

Whether to place Intermediate certificate into certificate file or not

Default value: true

link

Data type: Optional[ Variant[ Stdlib::Unixpath, Pattern[/^[^\/]+\.pem$/] # basename (relative to basepath/certbase) ] ]

If provided - will create human symbolic link to certificate file (with link name provided)

Default value: undef

tlsinfo::certpair

Certificate pair

Description

Name of resource must match TLS certificate Common Name subject field. Both TLS certificate and private keys must be defined or available in Hiera

Parameters

Examples

tlsinfo::certpair { $server_name:
  identity => true,
  cert     => $ssl_cert,
  pkey     => $ssl_key,
  # in case of self signed CA
  strict   => false,
}

Parameters

The following parameters are available in the tlsinfo::certpair defined type.

name

It is used as lookup key if not provided and as identity unless identity parameter is false

cert

Data type: Optional[String]

Certificate PEM encoded data. If not provided, Puppet will look for certificate data into Hiera using function lookup() by key ${name}_certificate. Otherwise it will use provided value

Default value: undef

pkey

Data type: Optional[String]

Private key PEM encoded data. If not provided, Puppet will look for certificate data into Hiera using function lookup() by key ${name}_private. Otherwise it will use provided value

Default value: undef

cacert

Data type: Optional[ Variant[ Boolean, Stdlib::Unixpath, Array[Stdlib::Unixpath] ] ]

If String provided it will be used as one of (with same priority by looking through Puppet catalog):

• path to TLS certificate
• certificate subject hash
• Puppet Sslcertificate resource title If Boolean true provided, Puppet will look for CA intermediate certificate through resources catalog using Issuer field hash from cert parameter. If Boolean false provided - we don't care about CA intermediate certificate If Array of String provided - each String would be handled separately as part of CA chain

Default value: true

lookupkey

Data type: Optional[String]

If cert is not provided Puppet will use lookup() function with lookup key <lookupkey>_certifiacte for SSL certificate and lookup key <lookupkey>_private for SSL privae key If lookupkey is undef it will use $name as lookupkey

Default value: undef

secret

Data type: Optional[String]

Password for encrypted private key

Default value: undef

certbase

Data type: Optional[Stdlib::Unixpath]

Directory where certificate files are stored in the system (RedHat and Debian based systems are predefined)

Default value: $tlsinfo::certbase

keybase

Data type: Optional[Stdlib::Unixpath]

Directory where private key files are stored in the system (RedHat and Debian based systems are predefined)

Default value: $tlsinfo::keybase

identity

Data type: Optional[ Variant[ Boolean, String, Array[String, 1] ] ]

Identtity which certificate should represent (eg domain name). Certificate Common Name or any of DNS names must match identity field If Boolean true - resource $name is used as identity If String - it will be used as identity alon with $name If Array - it will be used as array of identities along with $name

Default value: undef

rootca

Data type: Boolean

Whether to place Root CA certificate into certificate file or not

Default value: false

validate

Data type: Boolean

Whether to validate certificate expiration (Allow to define expired certificates in Puppet catalog to not fail catalog compilation)

Default value: true

strict

Data type: Boolean

Whether to validate Root CA validity

Default value: true

Resource types

sslcertificate

Certificate subject hash (read only)

Properties

The following properties are available in the sslcertificate type.

content

Certificate content

ensure

Valid values: absent, present

The basic property that the resource should be in.

Default value: present

Parameters

The following parameters are available in the sslcertificate type.

cacert

Could be Boolean true or false:

• true means CA Intermediate certificate already MUST be defined in catalog
• false means we do not manage CA Intermediate certificate (therefore validation over CA will not happen) Also could be a Full path to certificate or array of paths (for example, if certificate chain has 2 or more Intermediate CA)

chain

Valid values: true, false, yes, no

Whether to place Intermediate certificate into certificate file or not

Default value: true

expiration

Valid values: true, false, yes, no

Validate certificate validity period

Default value: true

identity

Identtity which certificate should represent (eg domain name). Certificate Common Name or any of DNS names must match identity field

path

namevar

The path to the certificate to manage. Must be fully qualified.

pkey

The path to the private key to use. Must be fully qualified.

provider

The specific backend to use for this sslcertificate resource. You will seldom need to specify this --- Puppet will usually discover the appropriate provider for your platform.

replace

Valid values: true, false, yes, no

Whether to replace a certificate file that already exists on the local system but which content doesn't match what the content attribute specifies. Set this to false allows Sslcertificate resources to initialize certificate file without overwriting it (for example, by updating it with IM CA). Note that this only affects content; Puppet will still manage ownership and permissions. Defaults to true.

Default value: true

rootca

Valid values: true, false, yes, no

Whether to place Root CA certificate into certificate file or not

Default value: false

strict

Valid values: true, false, yes, no

Strictly validate over root CA bundle

Default value: true

subject_hash

Certificate subject hash (read only)

subject_hash_old

Certificate subject hash for old algorithm (read only)

sslkey

Encrypted private key password

Properties

The following properties are available in the sslkey type.

content

Private Key content

ensure

Valid values: absent, present

The basic property that the resource should be in.

Default value: present

password

Encrypted private key password

Parameters

The following parameters are available in the sslkey type.

path

namevar

The path to the private key to manage. Must be fully qualified.

provider

The specific backend to use for this sslkey resource. You will seldom need to specify this --- Puppet will usually discover the appropriate provider for your platform.

replace

Valid values: true, false, yes, no

Whether to replace a private key file that already exists on the local system but whose content doesn't match what the content attribute specifies. Setting this to false allows Sslkey resources to initialize private key file without overwriting already existing. Note that this only affects content; Puppet will still manage ownership and permissions. Defaults to true.

Default value: true

Functions

tlsinfo::certpath

Type: Ruby 4.x API

The tlsinfo::certpath function.

tlsinfo::certpath(String $cert, Optional[Stdlib::Unixpath] $basepath)

The tlsinfo::certpath function.

Returns: Any

cert

Data type: String

basepath

Data type: Optional[Stdlib::Unixpath]

tlsinfo::keypath

Type: Ruby 4.x API

The tlsinfo::keypath function.

tlsinfo::keypath(String $cert, Optional[Stdlib::Unixpath] $basepath)

The tlsinfo::keypath function.

Returns: Any

cert

Data type: String

basepath

Data type: Optional[Stdlib::Unixpath]

tlsinfo::lookup

Type: Ruby 4.x API

The tlsinfo::lookup function.

tlsinfo::lookup(String $key, Optional[Boolean] $private)

The tlsinfo::lookup function.

Returns: Any

key

Data type: String

private

Data type: Optional[Boolean]

tlsinfo::normalize

Type: Ruby 4.x API

The tlsinfo::normalize function.

tlsinfo::normalize(String $name)

The tlsinfo::normalize function.

Returns: Any

name

Data type: String

Plans

tlsinfo::update

Update certificate and private key. Works only in conjuction with Hiera

Parameters

The following parameters are available in the tlsinfo::update plan.

targets

Data type: TargetSpec

Nodes on which certificate should be installed

lookupkey

Data type: String

Certificate for which lookup inside Hiera. In most cases it is subject common name

restart_nginx

Data type: Boolean

Flag whether to restart Nginx or not

Default value: false