diff --git a/REFERENCE.md b/REFERENCE.md new file mode 100644 index 00000000..ac612f05 --- /dev/null +++ b/REFERENCE.md @@ -0,0 +1,1234 @@ +# Reference + + + +## Table of Contents + +### Classes + +* [`openssl`](#openssl): Installs openssl and ensures bundled certificate list is world readable +* [`openssl::certificates`](#openssl--certificates): Generates x509 certificates based on class parameters +* [`openssl::configs`](#openssl--configs): Generates openssl.conf files using defaults +* [`openssl::packages`](#openssl--packages): Sets up packages for openssl + +### Defined types + +* [`openssl::certificate::x509`](#openssl--certificate--x509): Creates a certificate, key and CSR according to datas provided. +* [`openssl::dhparam`](#openssl--dhparam): Creates Diffie Helman parameters. +* [`openssl::export::pem_cert`](#openssl--export--pem_cert): Export certificate(s) to PEM/x509 format +* [`openssl::export::pem_key`](#openssl--export--pem_key): Export a key to PEM format +* [`openssl::export::pkcs12`](#openssl--export--pkcs12): Export a key pair to PKCS12 format + +### Resource types + +* [`cert_file`](#cert_file): Manages X.509 certificate files downloaded from a source location, saved in the specified format. +* [`dhparam`](#dhparam): A Diffie Helman parameter file +* [`ssl_pkey`](#ssl_pkey): An SSL private key +* [`x509_cert`](#x509_cert): An x509 certificate +* [`x509_request`](#x509_request): An x509 certificate signing request + +### Functions + +* [`cert_aia_caissuers`](#cert_aia_caissuers): Extrating the caIssuers entry from Authority Information Access extension of X509 certificate +* [`cert_date_valid`](#cert_date_valid): Checks SSL cetificate date validity. + +## Classes + +### `openssl` + +Installs openssl and ensures bundled certificate list is world readable + +#### Examples + +##### basic usage + +```puppet +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`](#-openssl--package_name) +* [`package_ensure`](#-openssl--package_ensure) +* [`ca_certificates_ensure`](#-openssl--ca_certificates_ensure) + +##### `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 + +```puppet +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`](#-openssl--certificates--x509_certs) + +##### `x509_certs` + +Data type: `Hash` + + + +Default value: `{}` + +### `openssl::configs` + +Generates openssl.conf files using defaults + +#### Examples + +##### basic usage + +```puppet +class { '::openssl::configs': + conffiles => { '/path/to/openssl.conf' => { ensure => 'present', + commonname => 'somewhere.org',}, + '/a/other/openssl.conf' => { ensure => 'present', + commonname => 'somewhere.else.org' }, + } +} +``` + +#### Parameters + +The following parameters are available in the `openssl::configs` class: + +* [`owner`](#-openssl--configs--owner) +* [`group`](#-openssl--configs--group) +* [`mode`](#-openssl--configs--mode) +* [`country`](#-openssl--configs--country) +* [`state`](#-openssl--configs--state) +* [`locality`](#-openssl--configs--locality) +* [`organization`](#-openssl--configs--organization) +* [`unit`](#-openssl--configs--unit) +* [`email`](#-openssl--configs--email) +* [`default_bits`](#-openssl--configs--default_bits) +* [`default_md`](#-openssl--configs--default_md) +* [`default_keyfile`](#-openssl--configs--default_keyfile) +* [`basicconstraints`](#-openssl--configs--basicconstraints) +* [`extendedkeyusages`](#-openssl--configs--extendedkeyusages) +* [`keyusages`](#-openssl--configs--keyusages) +* [`subjectaltnames`](#-openssl--configs--subjectaltnames) +* [`conffiles`](#-openssl--configs--conffiles) + +##### `owner` + +Data type: `String` + +default owner for the configuration files + +Default value: `'root'` + +##### `group` + +Data type: `String` + +default group for the configuration files + +Default value: `'root'` + +##### `mode` + +Data type: `String` + +default mode for the configuration files + +Default value: `'0640'` + +##### `country` + +Data type: `Optional[String]` + +default value for country + +Default value: `undef` + +##### `state` + +Data type: `Optional[String]` + +default value for state + +Default value: `undef` + +##### `locality` + +Data type: `Optional[String]` + +default value for locality + +Default value: `undef` + +##### `organization` + +Data type: `Optional[String]` + +default value for organization + +Default value: `undef` + +##### `unit` + +Data type: `Optional[String]` + +default value for unit + +Default value: `undef` + +##### `email` + +Data type: `Optional[String]` + +default value for email + +Default value: `undef` + +##### `default_bits` + +Data type: `Integer` + +default key size to generate + +Default value: `4096` + +##### `default_md` + +Data type: `String` + +default message digest to use + +Default value: `'sha512'` + +##### `default_keyfile` + +Data type: `String` + +default name for the keyfile + +Default value: `'privkey.pem'` + +##### `basicconstraints` + +Data type: `Optional[Array]` + +version 3 certificate extension basic constraints + +Default value: `undef` + +##### `extendedkeyusages` + +Data type: `Optional[Array]` + +version 3 certificate extension extended key usage + +Default value: `undef` + +##### `keyusages` + +Data type: `Optional[Array]` + +version 3 certificate extension key usage + +Default value: `undef` + +##### `subjectaltnames` + +Data type: `Optional[Array]` + +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 + +```puppet + +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`](#-openssl--certificate--x509--ensure) +* [`country`](#-openssl--certificate--x509--country) +* [`state`](#-openssl--certificate--x509--state) +* [`locality`](#-openssl--certificate--x509--locality) +* [`commonname`](#-openssl--certificate--x509--commonname) +* [`altnames`](#-openssl--certificate--x509--altnames) +* [`extkeyusage`](#-openssl--certificate--x509--extkeyusage) +* [`organization`](#-openssl--certificate--x509--organization) +* [`unit`](#-openssl--certificate--x509--unit) +* [`email`](#-openssl--certificate--x509--email) +* [`days`](#-openssl--certificate--x509--days) +* [`base_dir`](#-openssl--certificate--x509--base_dir) +* [`key_size`](#-openssl--certificate--x509--key_size) +* [`owner`](#-openssl--certificate--x509--owner) +* [`group`](#-openssl--certificate--x509--group) +* [`key_owner`](#-openssl--certificate--x509--key_owner) +* [`key_group`](#-openssl--certificate--x509--key_group) +* [`key_mode`](#-openssl--certificate--x509--key_mode) +* [`password`](#-openssl--certificate--x509--password) +* [`force`](#-openssl--certificate--x509--force) +* [`cnf_tpl`](#-openssl--certificate--x509--cnf_tpl) +* [`cnf_dir`](#-openssl--certificate--x509--cnf_dir) +* [`crt_dir`](#-openssl--certificate--x509--crt_dir) +* [`csr_dir`](#-openssl--certificate--x509--csr_dir) +* [`key_dir`](#-openssl--certificate--x509--key_dir) +* [`cnf`](#-openssl--certificate--x509--cnf) +* [`crt`](#-openssl--certificate--x509--crt) +* [`csr`](#-openssl--certificate--x509--csr) +* [`key`](#-openssl--certificate--x509--key) +* [`encrypted`](#-openssl--certificate--x509--encrypted) + +##### `ensure` + +Data type: `Enum['present', 'absent']` + +ensure wether certif and its config are present or not + +Default value: `present` + +##### `country` + +Data type: `String` + +certificate countryName + +##### `state` + +Data type: `Optional[String]` + +certificate stateOrProvinceName + +Default value: `undef` + +##### `locality` + +Data type: `Optional[String]` + +certificate localityName + +Default value: `undef` + +##### `commonname` + +Data type: `String` + +certificate CommonName + +##### `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: `String` + +certificate organizationName + +##### `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: `2048` + +##### `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: `Optional[Variant[String, Integer]]` + +key owner. User must exist. defaults to $owner + +Default value: `undef` + +##### `key_group` + +Data type: `Optional[Variant[String, Integer]]` + +key group. Group must exist. defaults to $group + +Default value: `undef` + +##### `key_mode` + +Data type: `String` + +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_tpl` + +Data type: `String` + +Specify an other template to generate ".cnf" file. + +Default value: `'openssl/cert.cnf.erb'` + +##### `cnf_dir` + +Data type: `Optional[Stdlib::Absolutepath]` + +where cnf should be placed. +Directory must exist, defaults to $base_dir. + +Default value: `undef` + +##### `crt_dir` + +Data type: `Optional[Stdlib::Absolutepath]` + +where crt should be placed. +Directory must exist, defaults to $base_dir. + +Default value: `undef` + +##### `csr_dir` + +Data type: `Optional[Stdlib::Absolutepath]` + +where csr should be placed. +Directory must exist, defaults to $base_dir. + +Default value: `undef` + +##### `key_dir` + +Data type: `Optional[Stdlib::Absolutepath]` + +where key should be placed. +Directory must exist, defaults to $base_dir. + +Default value: `undef` + +##### `cnf` + +Data type: `Optional[Stdlib::Absolutepath]` + +override cnf path entirely. +Directory must exist, defaults to $cnf_dir/$title.cnf + +Default value: `undef` + +##### `crt` + +Data type: `Optional[Stdlib::Absolutepath]` + +override crt path entirely. +Directory must exist, defaults to $crt_dir/$title.crt + +Default value: `undef` + +##### `csr` + +Data type: `Optional[Stdlib::Absolutepath]` + +override csr path entirely. +Directory must exist, defaults to $csr_dir/$title.csr + +Default value: `undef` + +##### `key` + +Data type: `Optional[Stdlib::Absolutepath]` + +override key path entirely. +Directory must exist, defaults to $key_dir/$title.key + +Default value: `undef` + +##### `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` + +### `openssl::dhparam` + +Creates Diffie Helman parameters. + +#### Parameters + +The following parameters are available in the `openssl::dhparam` defined type: + +* [`path`](#-openssl--dhparam--path) +* [`ensure`](#-openssl--dhparam--ensure) +* [`size`](#-openssl--dhparam--size) +* [`owner`](#-openssl--dhparam--owner) +* [`group`](#-openssl--dhparam--group) +* [`mode`](#-openssl--dhparam--mode) +* [`fastmode`](#-openssl--dhparam--fastmode) + +##### `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: + +* [`ensure`](#-openssl--export--pem_cert--ensure) +* [`pfx_cert`](#-openssl--export--pem_cert--pfx_cert) +* [`der_cert`](#-openssl--export--pem_cert--der_cert) +* [`pem_cert`](#-openssl--export--pem_cert--pem_cert) +* [`in_pass`](#-openssl--export--pem_cert--in_pass) + +##### `ensure` + +Data type: `Enum['present', 'absent']` + +Whether the certificate file should exist + +Default value: `present` + +##### `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`](#-openssl--export--pem_key--pfx_cert) +* [`pem_key`](#-openssl--export--pem_key--pem_key) +* [`ensure`](#-openssl--export--pem_key--ensure) +* [`in_pass`](#-openssl--export--pem_key--in_pass) +* [`out_pass`](#-openssl--export--pem_key--out_pass) + +##### `pfx_cert` + +Data type: `Stdlib::Absolutepath` + +PFX certificate/key container + +##### `pem_key` + +Data type: `Stdlib::Absolutepath` + +PEM certificate + +Default value: `$title` + +##### `ensure` + +Data type: `Enum['present', 'absent']` + +Whether the key file should exist + +Default value: `present` + +##### `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`](#-openssl--export--pkcs12--basedir) +* [`pkey`](#-openssl--export--pkcs12--pkey) +* [`cert`](#-openssl--export--pkcs12--cert) +* [`ensure`](#-openssl--export--pkcs12--ensure) +* [`in_pass`](#-openssl--export--pkcs12--in_pass) +* [`out_pass`](#-openssl--export--pkcs12--out_pass) +* [`chaincert`](#-openssl--export--pkcs12--chaincert) + +##### `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 + +##### `ensure` + +Data type: `Enum['present', 'absent']` + +Whether the PKCS12 file should exist + +Default value: `present` + +##### `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`](#-cert_file--format) +* [`path`](#-cert_file--path) +* [`provider`](#-cert_file--provider) +* [`source`](#-cert_file--source) + +##### `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`](#-dhparam--fastmode) +* [`path`](#-dhparam--path) +* [`provider`](#-dhparam--provider) +* [`size`](#-dhparam--size) + +##### `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`](#-ssl_pkey--authentication) +* [`curve`](#-ssl_pkey--curve) +* [`password`](#-ssl_pkey--password) +* [`path`](#-ssl_pkey--path) +* [`provider`](#-ssl_pkey--provider) +* [`size`](#-ssl_pkey--size) + +##### `authentication` + +Valid values: `rsa`, `dsa`, `ec` + +The authentication algorithm: 'rsa', 'dsa or ec' + +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 + +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. + +* [`authentication`](#-x509_cert--authentication) +* [`days`](#-x509_cert--days) +* [`force`](#-x509_cert--force) +* [`password`](#-x509_cert--password) +* [`path`](#-x509_cert--path) +* [`private_key`](#-x509_cert--private_key) +* [`provider`](#-x509_cert--provider) +* [`req_ext`](#-x509_cert--req_ext) +* [`template`](#-x509_cert--template) + +##### `authentication` + +Valid values: `rsa`, `dsa`, `ec` + +The authentication algorithm: 'rsa', 'dsa or ec' + +Default value: `rsa` + +##### `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` + +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. + +* [`authentication`](#-x509_request--authentication) +* [`encrypted`](#-x509_request--encrypted) +* [`force`](#-x509_request--force) +* [`password`](#-x509_request--password) +* [`path`](#-x509_request--path) +* [`private_key`](#-x509_request--private_key) +* [`provider`](#-x509_request--provider) +* [`template`](#-x509_request--template) + +##### `authentication` + +Valid values: `rsa`, `dsa`, `ec` + +The authentication algorithm: 'rsa', 'dsa' or ec + +Default value: `rsa` + +##### `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 + +### `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](https://tools.ietf.org/html/rfc5280#section-4.2.2). + +Parameter: path to ssl certificate + +#### `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](https://tools.ietf.org/html/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 + +### `cert_date_valid` + +Type: Ruby 4.x API + +Parameter: path to ssl certificate + +#### `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. + diff --git a/lib/puppet/provider/cert_file/posix.rb b/lib/puppet/provider/cert_file/posix.rb index c2cd7275..b25b3fa2 100644 --- a/lib/puppet/provider/cert_file/posix.rb +++ b/lib/puppet/provider/cert_file/posix.rb @@ -3,6 +3,8 @@ require 'pp' Puppet::Type.type(:cert_file).provide :posix do + desc 'POSIX provider for certificate files' + confine feature: :posix def exists? diff --git a/lib/puppet/type/cert_file.rb b/lib/puppet/type/cert_file.rb index 3dc1974f..afb3dfba 100644 --- a/lib/puppet/type/cert_file.rb +++ b/lib/puppet/type/cert_file.rb @@ -22,6 +22,7 @@ end newparam(:source) do + desc 'The source file' validate do |source| begin uri = URI.parse(Puppet::Util.uri_encode(source)) diff --git a/lib/puppet/type/dhparam.rb b/lib/puppet/type/dhparam.rb index bce7bd10..fc2f7522 100644 --- a/lib/puppet/type/dhparam.rb +++ b/lib/puppet/type/dhparam.rb @@ -7,6 +7,7 @@ ensurable newparam(:path, namevar: true) do + desc 'The path of the file' validate do |value| path = Pathname.new(value) raise ArgumentError, "Path must be absolute: #{path}" unless path.absolute? diff --git a/lib/puppet/type/x509_request.rb b/lib/puppet/type/x509_request.rb index 001780a6..cc32dd65 100644 --- a/lib/puppet/type/x509_request.rb +++ b/lib/puppet/type/x509_request.rb @@ -7,6 +7,7 @@ ensurable newparam(:path, namevar: true) do + desc 'The path of the certificate signing request' validate do |value| path = Pathname.new(value) raise ArgumentError, "Path must be absolute: #{path}" unless path.absolute? @@ -24,6 +25,7 @@ end newparam(:template) do + desc 'The template to use' defaultto do path = Pathname.new(@resource[:path]) "#{path.dirname}/#{path.basename(path.extname)}.cnf" @@ -35,6 +37,7 @@ end newparam(:private_key) do + desc 'The path of the private key' defaultto do path = Pathname.new(@resource[:path]) "#{path.dirname}/#{path.basename(path.extname)}.key" diff --git a/manifests/certificate/x509.pp b/manifests/certificate/x509.pp index f1ae47c1..71f4c7fa 100644 --- a/manifests/certificate/x509.pp +++ b/manifests/certificate/x509.pp @@ -1,68 +1,96 @@ -# == Definition: openssl::certificate::x509 +# @summary Creates a certificate, key and CSR according to datas provided. # -# Creates a certificate, key and CSR according to datas provided. +# @param ensure +# ensure wether certif and its config are present or not +# @param country +# certificate countryName +# @param state +# certificate stateOrProvinceName +# @param locality +# certificate localityName +# @param commonname +# certificate CommonName +# @param altnames +# certificate subjectAltName. +# Can be an array or a single string. +# @param extkeyusage +# 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 # -# === Parameters -# [*ensure*] ensure wether certif and its config are present or not -# [*country*] certificate countryName -# [*state*] certificate stateOrProvinceName -# [*locality*] certificate localityName -# [*commonname*] certificate CommonName -# [*altnames*] certificate subjectAltName. -# Can be an array or a single string. -# [*extkeyusage*] 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 +# @param organization +# certificate organizationName +# @param unit +# certificate organizationalUnitName +# @param email +# certificate emailAddress +# @param days +# certificate validity +# @param base_dir +# where cnf, crt, csr and key should be placed. +# Directory must exist +# @param key_size +# Size of the key to generate. +# @param owner +# cnf, crt, csr and key owner. User must exist +# @param group +# cnf, crt, csr and key group. Group must exist +# @param key_owner +# key owner. User must exist. defaults to $owner +# @param key_group +# key group. Group must exist. defaults to $group +# @param key_mode +# key group. +# @param password +# private key password. undef means no passphrase +# will be used to encrypt private key. +# @param force +# whether to override certificate and request +# if private key changes +# @param cnf_tpl +# Specify an other template to generate ".cnf" file. +# @param cnf_dir +# where cnf should be placed. +# Directory must exist, defaults to $base_dir. +# @param crt_dir +# where crt should be placed. +# Directory must exist, defaults to $base_dir. +# @param csr_dir +# where csr should be placed. +# Directory must exist, defaults to $base_dir. +# @param key_dir +# where key should be placed. +# Directory must exist, defaults to $base_dir. +# @param cnf +# override cnf path entirely. +# Directory must exist, defaults to $cnf_dir/$title.cnf +# @param crt +# override crt path entirely. +# Directory must exist, defaults to $crt_dir/$title.crt +# @param csr +# override csr path entirely. +# Directory must exist, defaults to $csr_dir/$title.csr +# @param key +# override key path entirely. +# Directory must exist, defaults to $key_dir/$title.key +# @param encrypted +# 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) # -# [*organization*] certificate organizationName -# [*unit*] certificate organizationalUnitName -# [*email*] certificate emailAddress -# [*days*] certificate validity -# [*base_dir*] where cnf, crt, csr and key should be placed. -# Directory must exist -# [*owner*] cnf, crt, csr and key owner. User must exist -# [*group*] cnf, crt, csr and key group. Group must exist -# [*key_owner*] key owner. User must exist. defaults to $owner -# [*key_group*] key group. Group must exist. defaults to $group -# [*key_mode*] key group. -# [*password*] private key password. undef means no passphrase -# will be used to encrypt private key. -# [*force*] whether to override certificate and request -# if private key changes -# [*cnf_tpl*] Specify an other template to generate ".cnf" file. -# [*cnf_dir*] where cnf should be placed. -# Directory must exist, defaults to $base_dir. -# [*crt_dir*] where crt should be placed. -# Directory must exist, defaults to $base_dir. -# [*csr_dir*] where csr should be placed. -# Directory must exist, defaults to $base_dir. -# [*key_dir*] where key should be placed. -# Directory must exist, defaults to $base_dir. -# [*cnf*] override cnf path entirely. -# Directory must exist, defaults to $cnf_dir/$title.cnf -# [*crt*] override crt path entirely. -# Directory must exist, defaults to $crt_dir/$title.crt -# [*csr*] override csr path entirely. -# Directory must exist, defaults to $csr_dir/$title.csr -# [*key*] override key path entirely. -# Directory must exist, defaults to $key_dir/$title.key -# [*encrypted*] 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) -# -# === Example +# @example basic usage # # openssl::certificate::x509 { 'foo.bar': # ensure => present, @@ -73,19 +101,15 @@ # 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'. +# 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". # -# === Requires +# Those files can be used as is for apache, openldap and so on. # -# - `puppetlabs/stdlib` +# 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'. # define openssl::certificate::x509 ( String $country, diff --git a/manifests/certificates.pp b/manifests/certificates.pp index 6f7e9a0d..a56cab7e 100644 --- a/manifests/certificates.pp +++ b/manifests/certificates.pp @@ -1,12 +1,8 @@ -# == Class: openssl::certificates +# @summary Generates x509 certificates based on class parameters # -# Generates x509 certificates based on class parameters -# -# === Parameters -# [*x509_certs*] -# -# === Example +# @param x509_certs # +# @example basic usage # class { '::openssl::certificate': # x509_certs => { '/path/to/certificate.crt' => { ensure => 'present', # password => 'j(D$', diff --git a/manifests/configs.pp b/manifests/configs.pp index 954c52af..5838ee92 100644 --- a/manifests/configs.pp +++ b/manifests/configs.pp @@ -1,46 +1,42 @@ -# == Class: openssl::configs +# @summary Generates openssl.conf files using defaults # -# Generates openssl.conf files using defaults -# -# === Parameters -# [*owner*] +# @param owner # default owner for the configuration files -# [*group*] +# @param group # default group for the configuration files -# [*mode*] +# @param mode # default mode for the configuration files -# [*country*] +# @param country # default value for country -# [*state*] +# @param state # default value for state -# [*locality*] +# @param locality # default value for locality -# [*organization*] +# @param organization # default value for organization -# [*unit*] +# @param unit # default value for unit -# [*email*] +# @param email # default value for email -# [*default_bits*] +# @param default_bits # default key size to generate -# [*default_md*] +# @param default_md # default message digest to use -# [*default_keyfile*] +# @param default_keyfile # default name for the keyfile -# [*basicconstraints*] +# @param basicconstraints # version 3 certificate extension basic constraints -# [*extendedkeyusages*] +# @param extendedkeyusages # version 3 certificate extension extended key usage -# [*keyusages*] +# @param keyusages # version 3 certificate extension key usage -# [*subjectaltnames*] +# @param subjectaltnames # version 3 certificate extension for alternative names # currently supported are IP (v4) and DNS -# [*conffiles*] +# @param conffiles # config files to generate # -# === Example -# +# @example basic usage # class { '::openssl::configs': # conffiles => { '/path/to/openssl.conf' => { ensure => 'present', # commonname => 'somewhere.org',}, diff --git a/manifests/dhparam.pp b/manifests/dhparam.pp index dc94cf34..fe119dd9 100644 --- a/manifests/dhparam.pp +++ b/manifests/dhparam.pp @@ -1,19 +1,19 @@ -# == Definition: openssl::dhparam -# -# Creates Diffie Helman parameters. -# -# === Parameters -# [*path*] path to write DH parameters to -# [*ensure*] ensure whether DH paramers file is present or absent -# [*size*] number of bits for the parameter set -# [*owner*] file owner. User must exist -# [*group*] file group. Group must exist -# [*mode*] file mode. -# -# === Requires -# -# - `puppetlabs/stdlib` +# @summary Creates Diffie Helman parameters. # +# @param path +# path to write DH parameters to +# @param ensure +# ensure whether DH paramers file is present or absent +# @param size +# number of bits for the parameter set +# @param owner +# file owner. User must exist +# @param group +# file group. Group must exist +# @param mode +# file mode. +# @param fastmode +# Use "fastmode" for dhparam generation define openssl::dhparam ( Stdlib::Absolutepath $path = $name, Enum['present', 'absent'] $ensure = present, diff --git a/manifests/export/pem_cert.pp b/manifests/export/pem_cert.pp index a73937ef..26ba3d36 100644 --- a/manifests/export/pem_cert.pp +++ b/manifests/export/pem_cert.pp @@ -1,12 +1,15 @@ -# == Definition: openssl::export::pem_cert +# @summary Export certificate(s) to PEM/x509 format # -# Export certificate(s) to PEM/x509 format -# -# == Parameters -# [*pfx_cert*] - PFX certificate/key container -# [*der_cert*] - DER certificate -# [*pem_cert*] - PEM/x509 certificate -# [*in_pass*] - PFX password +# @param ensure +# Whether the certificate file should exist +# @param pfx_cert +# PFX certificate/key container +# @param der_cert +# DER certificate +# @param pem_cert +# PEM/x509 certificate +# @param in_pass +# PFX password # define openssl::export::pem_cert ( Enum['present', 'absent'] $ensure = present, diff --git a/manifests/export/pem_key.pp b/manifests/export/pem_key.pp index e05e12c3..514dd73a 100644 --- a/manifests/export/pem_key.pp +++ b/manifests/export/pem_key.pp @@ -1,12 +1,15 @@ -# == Definition: openssl::export::pem_key +# @summary Export a key to PEM format # -# Export a key to PEM format -# -# == Parameters -# [*pfx_cert*] - PFX certificate/key container -# [*pem_key*] - PEM certificate -# [*in_pass*] - PFX container password -# [*out_pass*] - PEM key password +# @param pfx_cert +# PFX certificate/key container +# @param pem_key +# PEM certificate +# @param ensure +# Whether the key file should exist +# @param in_pass +# PFX container password +# @param out_pass +# PEM key password # define openssl::export::pem_key ( Stdlib::Absolutepath $pfx_cert, diff --git a/manifests/export/pkcs12.pp b/manifests/export/pkcs12.pp index 05c874db..69ef26e2 100644 --- a/manifests/export/pkcs12.pp +++ b/manifests/export/pkcs12.pp @@ -1,14 +1,19 @@ -# == Definition: openssl::export::pkcs12 +# @summary Export a key pair to PKCS12 format # -# Export a key pair to PKCS12 format -# -# == Parameters -# [*basedir*] - directory where you want the export to be done. Must exists -# [*pkey*] - private key -# [*cert*] - certificate -# [*in_pass*] - private key password -# [*out_pass*] - PKCS12 password -# [*chaincert*] - chain certificate to include in pkcs12 +# @param basedir +# Directory where you want the export to be done. Must exists +# @param pkey +# Private key +# @param cert +# Certificate +# @param ensure +# Whether the PKCS12 file should exist +# @param in_pass +# Private key password +# @param out_pass +# PKCS12 password +# @param chaincert +# Chain certificate to include in pkcs12 # define openssl::export::pkcs12 ( Stdlib::Absolutepath $basedir, diff --git a/manifests/packages.pp b/manifests/packages.pp index 6b8b010f..5e29c1e9 100644 --- a/manifests/packages.pp +++ b/manifests/packages.pp @@ -1,6 +1,4 @@ -# == Class: openssl::packages -# -# Sets up packages for openssl +# @summary Sets up packages for openssl class openssl::packages { assert_private()