Skip to content

Latest commit

 

History

History
1505 lines (862 loc) · 35.7 KB

REFERENCE.md

File metadata and controls

1505 lines (862 loc) · 35.7 KB

Reference

Table of Contents

Classes

  • openssl: Installs openssl and ensures bundled certificate list is world readable
  • openssl::certificates: Generates x509 certificates based on class parameters
  • openssl::configs: Generates openssl.conf files using manually set defaults or defaults from openssl::config
  • openssl::packages: Sets up packages for openssl

Defined types

Resource types

  • cert_file: Manages X.509 certificate files downloaded from a source location, saved in the specified format.
  • dhparam: A Diffie Helman parameter file
  • ssl_pkey: An SSL private key
  • x509_cert: An x509 certificate
  • x509_request: An x509 certificate signing request

Functions

Classes

openssl

Installs openssl and ensures bundled certificate list is world readable

Examples

basic usage
class { 'openssl':
  package_name           => 'openssl-othername',
  package_ensure         => latest,
  ca_certificates_ensure => latest,
}

Parameters

The following parameters are available in the openssl class:

package_name

Data type: Optional[String[1]]

openssl package name

Default value: undef

package_ensure

Data type: String[1]

openssl package ensure

Default value: installed

ca_certificates_ensure

Data type: String[1]

ca-certificates package ensure

Default value: installed

openssl::certificates

Generates x509 certificates based on class parameters

Examples

basic usage
class { 'openssl::certificate':
  x509_certs => { '/path/to/certificate.crt' => {  ensure      => 'present',
                                                   password    => 'j(D$',
                                                   template    => '/other/path/to/template.cnf',
                                                   private_key => '/there/is/my/private.key',
                                                   days        => 4536,
                                                   force       => false,},
                  '/a/other/certificate.crt' => {  ensure      => 'present', },
                }
}

Parameters

The following parameters are available in the openssl::certificates class:

x509_certs

Data type: Hash

Default value: {}

openssl::configs

Generates openssl.conf files using manually set defaults or defaults from openssl::config

Examples

basic usage
class { 'openssl::configs':
  country   => 'mycountry',
  conffiles => { '/path/to/openssl.conf' => { ensure       => 'present',
                                              commonname   => 'somewhere.org',
                                              organization => 'myorg' },
                 '/a/other/openssl.conf' => { ensure       => 'present',
                                              commonname   => 'somewhere.else.org',
                                              organization => 'myotherorg' },
                }
}

Parameters

The following parameters are available in the openssl::configs class:

owner

Data type: Optional[String[1]]

default owner for the configuration files

Default value: undef

group

Data type: Optional[String[1]]

default group for the configuration files

Default value: undef

mode

Data type: Optional[String[1]]

default mode for the configuration files

Default value: undef

country

Data type: Optional[String[1]]

default value for country

Default value: undef

state

Data type: Optional[String[1]]

default value for state

Default value: undef

locality

Data type: Optional[String[1]]

default value for locality

Default value: undef

organization

Data type: Optional[String[1]]

default value for organization

Default value: undef

unit

Data type: Optional[String[1]]

default value for unit

Default value: undef

email

Data type: Optional[String[1]]

default value for email

Default value: undef

default_bits

Data type: Optional[Integer]

default key size to generate

Default value: undef

default_md

Data type: Optional[String[1]]

default message digest to use

Default value: undef

default_keyfile

Data type: Optional[String[1]]

default name for the keyfile

Default value: undef

basicconstraints

Data type: Optional[Array]

default version 3 certificate extension basic constraints

Default value: undef

extendedkeyusages

Data type: Optional[Array]

default version 3 certificate extension extended key usage

Default value: undef

keyusages

Data type: Optional[Array]

default version 3 certificate extension key usage

Default value: undef

subjectaltnames

Data type: Optional[Array]

default version 3 certificate extension for alternative names currently supported are IP (v4) and DNS

Default value: undef

conffiles

Data type: Hash

config files to generate

Default value: {}

openssl::packages

Sets up packages for openssl

Defined types

openssl::certificate::x509

Creates a certificate, key and CSR according to datas provided.

Examples

basic usage
openssl::certificate::x509 { 'foo.bar':
  ensure       => present,
  country      => 'CH',
  organization => 'Example.com',
  commonname   => $fqdn,
  base_dir     => '/var/www/ssl',
  owner        => 'www-data',
}

This will create files "foo.bar.cnf", "foo.bar.crt", "foo.bar.key"
and "foo.bar.csr" in /var/www/ssl/.
All files will belong to user "www-data".

Those files can be used as is for apache, openldap and so on.

If you wish to ensure a key is read-only to a process:
set $key_group to match the group of the process,
and set $key_mode to '0640'.

Parameters

The following parameters are available in the openssl::certificate::x509 defined type:

ensure

Data type: Enum['present', 'absent']

ensure wether certif and its config are present or not

Default value: present

country

Data type: Optional[String]

certificate countryName

Default value: undef

state

Data type: Optional[String]

certificate stateOrProvinceName

Default value: undef

locality

Data type: Optional[String]

certificate localityName

Default value: undef

commonname

Data type: Optional[String]

certificate CommonName

Default value: undef

altnames

Data type: Array

certificate subjectAltName. Can be an array or a single string.

Default value: []

extkeyusage

Data type: Array

certificate extended key usage

Value Meaning
serverAuth SSL/TLS Web Server Authentication.
clientAuth SL/TLS Web Client Authentication.
codeSigning Code signing.
emailProtection E-mail Protection (S/MIME).
timeStamping Trusted Timestamping
OCSPSigning OCSP Signing
ipsecIKE ipsec Internet Key Exchange
msCodeInd Microsoft Individual Code Signing (authenticode)
msCodeCom Microsoft Commercial Code Signing (authenticode)
msCTLSign Microsoft Trust List Signing
msEFS Microsoft Encrypted File System

Default value: []

organization

Data type: Optional[String]

certificate organizationName

Default value: undef

unit

Data type: Optional[String]

certificate organizationalUnitName

Default value: undef

email

Data type: Optional[String]

certificate emailAddress

Default value: undef

days

Data type: Integer

certificate validity

Default value: 365

base_dir

Data type: Stdlib::Absolutepath

where cnf, crt, csr and key should be placed. Directory must exist

Default value: '/etc/ssl/certs'

key_size

Data type: Integer

Size of the key to generate.

Default value: 3072

owner

Data type: Variant[String, Integer]

cnf, crt, csr and key owner. User must exist

Default value: 'root'

group

Data type: Variant[String, Integer]

cnf, crt, csr and key group. Group must exist

Default value: 'root'

key_owner

Data type: Variant[String, Integer]

key owner. User must exist. defaults to $owner

Default value: $owner

key_group

Data type: Variant[String, Integer]

key group. Group must exist. defaults to $group

Default value: $group

key_mode

Data type: Stdlib::Filemode

key group.

Default value: '0600'

password

Data type: Optional[String]

private key password. undef means no passphrase will be used to encrypt private key.

Default value: undef

force

Data type: Boolean

whether to override certificate and request if private key changes

Default value: true

cnf_dir

Data type: Stdlib::Absolutepath

where cnf should be placed. Directory must exist, defaults to $base_dir.

Default value: $base_dir

crt_dir

Data type: Stdlib::Absolutepath

where crt should be placed. Directory must exist, defaults to $base_dir.

Default value: $base_dir

csr_dir

Data type: Stdlib::Absolutepath

where csr should be placed. Directory must exist, defaults to $base_dir.

Default value: $base_dir

key_dir

Data type: Stdlib::Absolutepath

where key should be placed. Directory must exist, defaults to $base_dir.

Default value: $base_dir

cnf

Data type: Stdlib::Absolutepath

override cnf path entirely. Directory must exist, defaults to $cnf_dir/$title.cnf

Default value: "${cnf_dir}/${name}.cnf"

crt

Data type: Stdlib::Absolutepath

override crt path entirely. Directory must exist, defaults to $crt_dir/$title.crt

Default value: "${crt_dir}/${name}.crt"

csr

Data type: Stdlib::Absolutepath

override csr path entirely. Directory must exist, defaults to $csr_dir/$title.csr

Default value: "${csr_dir}/${name}.csr"

key

Data type: Stdlib::Absolutepath

override key path entirely. Directory must exist, defaults to $key_dir/$title.key

Default value: "${key_dir}/${name}.key"

encrypted

Data type: Boolean

Flag requesting the exported key to be unencrypted by specifying the -nodes option during the CSR generation. Turning off encryption is needed by some applications, such as OpenLDAP. Defaults to true (key is encrypted)

Default value: true

ca

Data type: Optional[Stdlib::Absolutepath]

Path to CA certificate for signing. Undef means no CA will be provided for signing the certificate.

Default value: undef

cakey

Data type: Optional[Stdlib::Absolutepath]

Path to CA private key for signing. Undef mean no CAkey will be provided.

Default value: undef

cakey_password

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

Optional password that has encrypted the CA key.

Default value: undef

openssl::config

Generates an openssl.conf file using defaults

Examples

basic usage
openssl::config {'/path/to/openssl.conf':
  ensure       => 'present',
  commonname   => 'somewhere.org',
  country      => 'mycountry',
  organization => 'myorg',
}

Parameters

The following parameters are available in the openssl::config defined type:

ensure

Data type: Enum['absent','present']

ensure parameter for configfile; defaults to present

Default value: 'present'

commonname

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

commonname for config file

Default value: undef

country

Data type: Optional[String[1]]

value for country

Default value: undef

organization

Data type: Optional[String[1]]

value for organization

Default value: undef

owner

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

owner for the configuration file

Default value: 'root'

group

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

group for the configuration file

Default value: 'root'

mode

Data type: Stdlib::Filemode

mode for the configuration file

Default value: '0640'

state

Data type: Optional[String[1]]

value for state

Default value: undef

locality

Data type: Optional[String[1]]

value for locality

Default value: undef

unit

Data type: Optional[String[1]]

value for unit

Default value: undef

email

Data type: Optional[String[1]]

value for email

Default value: undef

default_bits

Data type: Integer

key size to generate

Default value: 4096

default_md

Data type: String[1]

message digest to use

Default value: 'sha512'

default_keyfile

Data type: String[1]

name for the keyfile

Default value: 'privkey.pem'

basicconstraints

Data type: Array

version 3 certificate extension basic constraints

Default value: []

extendedkeyusages

Data type: Array

version 3 certificate extension extended key usage

Default value: []

keyusages

Data type: Array

version 3 certificate extension key usage

Default value: []

subjectaltnames

Data type: Array

version 3 certificate extension for alternative names currently supported are IP (v4) and DNS

Default value: []

openssl::dhparam

Creates Diffie Helman parameters.

Parameters

The following parameters are available in the openssl::dhparam defined type:

path

Data type: Stdlib::Absolutepath

path to write DH parameters to

Default value: $name

ensure

Data type: Enum['present', 'absent']

ensure whether DH paramers file is present or absent

Default value: present

size

Data type: Integer[1]

number of bits for the parameter set

Default value: 2048

owner

Data type: Variant[String, Integer]

file owner. User must exist

Default value: 'root'

group

Data type: Variant[String, Integer]

file group. Group must exist

Default value: 'root'

mode

Data type: String

file mode.

Default value: '0644'

fastmode

Data type: Boolean

Use "fastmode" for dhparam generation

Default value: false

openssl::export::pem_cert

Export certificate(s) to PEM/x509 format

Parameters

The following parameters are available in the openssl::export::pem_cert defined type:

dynamic

Data type: Boolean

dynamically renew certificate file

Default value: false

ensure

Data type: Enum['present', 'absent']

Whether the certificate file should exist

Default value: present

resources

Data type: Variant[Type, Array[Type]]

List of resources to subscribe to for certificate file renewal

Default value: []

pfx_cert

Data type: Optional[Stdlib::Absolutepath]

PFX certificate/key container

Default value: undef

der_cert

Data type: Optional[Stdlib::Absolutepath]

DER certificate

Default value: undef

pem_cert

Data type: Stdlib::Absolutepath

PEM/x509 certificate

Default value: $title

in_pass

Data type: Optional[String]

PFX password

Default value: undef

openssl::export::pem_key

Export a key to PEM format

Parameters

The following parameters are available in the openssl::export::pem_key defined type:

pfx_cert

Data type: Stdlib::Absolutepath

PFX certificate/key container

pem_key

Data type: Stdlib::Absolutepath

PEM certificate

Default value: $title

dynamic

Data type: Boolean

dynamically renew key file

Default value: false

ensure

Data type: Enum['present', 'absent']

Whether the keyfile should exist

Default value: present

resources

Data type: Variant[Type, Array[Type]]

List of resources to subscribe to for key renewal

Default value: []

in_pass

Data type: Optional[String]

PFX container password

Default value: undef

out_pass

Data type: Optional[String]

PEM key password

Default value: undef

openssl::export::pkcs12

Export a key pair to PKCS12 format

Parameters

The following parameters are available in the openssl::export::pkcs12 defined type:

basedir

Data type: Stdlib::Absolutepath

Directory where you want the export to be done. Must exists

pkey

Data type: Stdlib::Absolutepath

Private key

cert

Data type: Stdlib::Absolutepath

Certificate

dynamic

Data type: Boolean

dynamically renew PKCS12 file

Default value: false

ensure

Data type: Enum['present', 'absent']

Whether the PKCS12 file should exist

Default value: present

resources

Data type: Variant[Type, Array[Type]]

List of resources to subscribe to for PKCS12 renewal

Default value: []

in_pass

Data type: Optional[String]

Private key password

Default value: undef

out_pass

Data type: Optional[String]

PKCS12 password

Default value: undef

chaincert

Data type: Optional[String]

Chain certificate to include in pkcs12

Default value: undef

Resource types

cert_file

Manages X.509 certificate files downloaded from a source location, saved in the specified format.

Properties

The following properties are available in the cert_file type.

ensure

Valid values: present, absent

The basic property that the resource should be in.

Default value: present

Parameters

The following parameters are available in the cert_file type.

format

Valid values: der, pem

Format in which the loaded certificate should be written to file.

Default value: pem

path

Path to the file to manage

provider

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

source

The source file

dhparam

A Diffie Helman parameter file

Properties

The following properties are available in the dhparam type.

ensure

Valid values: present, absent

The basic property that the resource should be in.

Default value: present

Parameters

The following parameters are available in the dhparam type.

fastmode

Enable fast mode

Default value: false

path

The path of the file

provider

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

size

Valid values: %r{\d+}

The key size

Default value: 512

ssl_pkey

An SSL private key

Properties

The following properties are available in the ssl_pkey type.

ensure

Valid values: present, absent

The basic property that the resource should be in.

Default value: present

Parameters

The following parameters are available in the ssl_pkey type.

authentication

Valid values: rsa, ec

The authentication algorithm

Default value: rsa

curve

The EC curve

Default value: secp384r1

password

The optional password for the key

path

The path to the key

provider

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

size

Valid values: %r{\d+}

The key size for RSA keys

Default value: 2048

x509_cert

An x509 certificate

Properties

The following properties are available in the x509_cert type.

ensure

Valid values: present, absent

The basic property that the resource should be in.

Default value: present

Parameters

The following parameters are available in the x509_cert type.

ca

The optional ca certificate filepath

cakey

The optional ca private key filepath

cakey_password

The optional CA key password

csr

The optional certificate signing request path

days

Valid values: %r{\d+}

The validity of the certificate

Default value: 3650

force

Valid values: true, false

Whether to replace the certificate if the private key mismatches

Default value: false

password

The optional password for the private key

path

The path to the certificate

private_key

The path to the private key

provider

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

req_ext

Valid values: true, false, yes, no

Whether adding v3 SAN from config

Default value: false

template

The template to use

x509_request

An x509 certificate signing request

Properties

The following properties are available in the x509_request type.

ensure

Valid values: present, absent

The basic property that the resource should be in.

Default value: present

Parameters

The following parameters are available in the x509_request type.

encrypted

Valid values: true, false

Whether to generate the key unencrypted. This is needed by some applications like OpenLDAP

Default value: true

force

Valid values: true, false

Whether to replace the certificate if the private key mismatches

Default value: false

password

The optional password for the private key

path

The path of the certificate signing request

private_key

The path of the private key

provider

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

template

The template to use

Functions

openssl::cert_aia_caissuers

Type: Ruby 4.x API

Extract a X509 certificate for x509v3 extensions, search for Authority Information Access extension and return the contents caIssuers access method. For details see rfc5280#section-4.2.2.

Parameter: path to ssl certificate

openssl::cert_aia_caissuers(String $certfile)

Extract a X509 certificate for x509v3 extensions, search for Authority Information Access extension and return the contents caIssuers access method. For details see rfc5280#section-4.2.2.

Parameter: path to ssl certificate

Returns: Any contents of the caIssuers access method of authorityInfoAccess extension, or nil if not found

certfile

Data type: String

Path to the certificate to inspect

openssl::cert_date_valid

Type: Ruby 4.x API

Parameter: path to ssl certificate

openssl::cert_date_valid(String $certfile)

Parameter: path to ssl certificate

Returns: Any false if the certificate is expired or not yet valid,

certfile

Data type: String

The certificate file to check.