{"id":20622315,"url":"https://github.com/smoeding/puppet-openssl","last_synced_at":"2025-04-15T12:33:32.280Z","repository":{"id":57664962,"uuid":"121785413","full_name":"smoeding/puppet-openssl","owner":"smoeding","description":"Use Puppet to manage X.509 certificates, keys and parameter files","archived":false,"fork":false,"pushed_at":"2025-01-24T13:58:08.000Z","size":537,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-07T21:07:20.073Z","etag":null,"topics":["openssl","openssl-certs","puppet"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/smoeding.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-02-16T18:27:10.000Z","updated_at":"2025-01-24T13:58:11.000Z","dependencies_parsed_at":"2025-01-24T09:20:19.895Z","dependency_job_id":"a29a7ccb-675e-4ed8-8380-0bcfbc5f8f17","html_url":"https://github.com/smoeding/puppet-openssl","commit_stats":{"total_commits":202,"total_committers":1,"mean_commits":202.0,"dds":0.0,"last_synced_commit":"86d65fc6d49d5c2eda53f2a11922fdefd866629c"},"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smoeding%2Fpuppet-openssl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smoeding%2Fpuppet-openssl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smoeding%2Fpuppet-openssl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/smoeding%2Fpuppet-openssl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/smoeding","download_url":"https://codeload.github.com/smoeding/puppet-openssl/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249072323,"owners_count":21208171,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["openssl","openssl-certs","puppet"],"created_at":"2024-11-16T12:22:08.443Z","updated_at":"2025-04-15T12:33:32.259Z","avatar_url":"https://github.com/smoeding.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OpenSSL\n\n[![Build Status](https://github.com/smoeding/puppet-openssl/actions/workflows/CI.yaml/badge.svg)](https://github.com/smoeding/puppet-openssl/actions/workflows/CI.yaml)\n[![Puppet Forge](http://img.shields.io/puppetforge/v/stm/openssl.svg)](https://forge.puppetlabs.com/stm/openssl)\n[![License](https://img.shields.io/github/license/smoeding/puppet-openssl.svg)](https://raw.githubusercontent.com/smoeding/puppet-openssl/master/LICENSE)\n\n#### Table of Contents\n\n1. [Overview](#overview)\n2. [Module Description - What does the module do?](#module-description)\n3. [Setup - The basics of getting started with openssl](#setup)\n    * [What openssl affects](#what-openssl-affects)\n    * [Setup requirements](#setup-requirements)\n4. [Usage - Configuration options and additional functionality](#usage)\n5. [Reference - An under-the-hood peek at what the module is doing and how](#reference)\n5. [Limitations - OS compatibility, etc.](#limitations)\n6. [Development - Guide for contributing to the module](#development)\n\n## Overview\n\nCreate and manage X.509 keys, requests, certificates and Diffie-Hellman parameter files.\n\n## Module Description\n\nThe `openssl` module manages files containing X.509 certificates and keys.\n\nThis module can not only generate keys, requests and certificates but also use a directory on the Puppet server to fetch and deploy the certificates and keys from. So you can run your own CA or take certificates received from a public CA and have them managed by Puppet.\n\n## Setup\n\n### What OpenSSL affects\n\nThe modules installs the OpenSSL package and provides custom types and defined types to manage certificates, keys and Diffie-Hellman parameter files on the nodes.\n\n### Setup Requirements\n\nThe module requires the Puppetlabs modules `stdlib` and `concat`. The `openssl` executable must be installed for some functions to work. On RedHat based distributions the `certutil` executable is also needed.\n\n### Beginning with OpenSSL\n\nThe module has two distinct use cases. First of all you can create OpenSSL keys, requests and certificates with this module (see some examples below). Then you can use this module to deploy certificates and keys (not necessarily generated by this module) from the Puppetserver to your client nodes.\n\nThe module must be initialized before you can use the deployment functionality:\n\n``` puppet\nclass { 'openssl':\n  cert_source_directory =\u003e '/etc/puppetlabs/code/private/certs',\n}\n```\n\nThe parameter `cert_source_directory` is mandatory and has no default value. This is a directory on the Puppet server where you keep your certificates and keys. This directory does not need to be inside a Puppet environment directory. It can be located anywhere on the Puppet server. But the content must by readable by the user running the Puppetserver application (normally `puppet`). So make sure the file permissions are set correctly.\n\nThe module expects to find certificate and key files in this directory on the Puppet server. As an example the directory used above might look like this listing:\n\n``` text\n# ls -l /etc/puppetlabs/code/private/certs/\ntotal 236\n-r-------- 1 puppet root 1509 May 25  2017 cloud.crt\n-r-------- 1 puppet root 1675 May 25  2017 cloud.key\n-r-------- 1 puppet root 1570 Mar  1 20:06 imap.crt\n-r-------- 1 puppet root 1679 Mar  1 20:06 imap.key\n-r-------- 1 puppet root 1647 May 27 05:17 letsencrypt-ca.crt\n-r-------- 1 puppet root 1472 Mar 18  2016 vortex.crt\n-r-------- 1 puppet root 1671 Mar 18  2016 vortex.key\n```\n\n## Usage\n\n### Generate OpenSSL key with defaults\n\nBy default the generated key will be an RSA key with 2048 bits.\n\n``` puppet\nopenssl_key { '/etc/ssl/rsa-2048.key': }\n```\n\n### Generate 4096 bits RSA key owned by another user\n\nOwner, group and mode may be specified when a key is generated. The number of bits can be `1024`, `2048` (default), `3072`, `4096`, `5120`, `6144`, `7168` or `8192` for an RSA key.\n\n``` puppet\nopenssl_key { '/etc/apache/ssl/rsa-2048.key':\n  bits  =\u003e 4096,\n  owner =\u003e 'www-data',\n  group =\u003e 'www-data',\n  mode  =\u003e '0640',\n}\n```\n\n### Generate encrypted EC key with defaults\n\nYou can also generate Elliptic-Curve keys (`secp384r1` is the default curve) and a key may also be protected by a password.\n\n``` puppet\nopenssl_key { '/etc/ssl/ec-secp384r1.key':\n  algorithm =\u003e 'EC',\n  cipher    =\u003e 'aes128',\n  password  =\u003e 'rosebud',\n}\n```\n\n### Generate a CA key and certificate\n\nFirst generate an encrypted EC key using the `openssl_key` type provided by this module.\n\n``` puppet\nopenssl_key { '/etc/ssl/ca.key':\n  algorithm =\u003e 'EC',\n  cipher    =\u003e 'aes128',\n  password  =\u003e 'rosebud',\n}\n```\n\nThen generate a certificate request using the key and its password. The X.509 Common Name is mandatory. Other X.509 attributes may also be used. Here the request will be also be regenerated if the subscribed key changes.\n\n``` puppet\nopenssl_request { '/etc/ssl/ca.csr':\n  key              =\u003e '/etc/ssl/ca.key',\n  key_password     =\u003e 'rosebud',\n  common_name      =\u003e 'ACME Demo CA',\n  domain_component =\u003e ['example', 'com'],\n  subscribe        =\u003e Openssl_key['/etc/ssl/ca.key'],\n  notify           =\u003e Openssl_cert['/etc/ssl/ca.crt'],\n}\n```\n\nFinally the certificate is signed using the same key used for the request (so it will be a self-signed certificate). Some extensions line _KeyUsage_ and _BasicConstraints_ are defined.\n\n``` puppet\n\nopenssl_cert { '/etc/ssl/ca.crt':\n  request                       =\u003e '/etc/ssl/ca.csr',\n  issuer_key                    =\u003e '/etc/ssl/ca.key',\n  issuer_key_password           =\u003e 'rosebud',\n  key_usage                     =\u003e ['keyCertSign', 'cRLSign'],\n  key_usage_critical            =\u003e true,\n  basic_constraints_ca          =\u003e true,\n  basic_constraints_ca_critical =\u003e true,\n  subject_key_identifier        =\u003e 'hash',\n  authority_key_identifier      =\u003e ['issuer', 'keyid:always'],\n  days                          =\u003e 2922,\n}\n```\n\n### Create a certificate for an application\n\nCreate an Elliptic Curve key using a specific curve.\n\n``` puppet\nopenssl_key { '/etc/ssl/ec-prime256v1.key':\n  algorithm =\u003e 'EC',\n  curve     =\u003e 'prime256v1',\n}\n```\n\nGenerate a request for an application specific certificate. Some extensions are already set in the request and can be copied into the certificate by the CA.\n\n``` puppet\nopenssl_request { \"/etc/ssl/app.example.com.csr\":\n  key                         =\u003e '/etc/ssl/ec-prime256v1.key',\n  common_name                 =\u003e 'app.example.com',\n  key_usage                   =\u003e ['keyEncipherment', 'digitalSignature'],\n  extended_key_usage          =\u003e ['serverAuth', 'clientAuth'],\n  subject_alternate_names_dns =\u003e ['app.example.com'],\n  subscribe                   =\u003e Openssl_key['/etc/ssl/ec-prime256v1.key'],\n  notify                      =\u003e Openssl_cert[\"/etc/ssl/app.example.com.crt\"],\n}\n```\n\nSign the request using a CA certificate and key. The X.509 _subjectAltName_ and _keyUsage_ extenstions will be copied from the request if they are set.\n\n``` puppet\nopenssl_cert { \"/etc/ssl/app.example.com.crt\":\n  request                  =\u003e \"/etc/ssl/app.example.com.csr\",\n  issuer_key               =\u003e '/etc/ssl/ca.key',\n  issuer_cert              =\u003e '/etc/ssl/ca.crt',\n  subject_key_identifier   =\u003e 'hash',\n  authority_key_identifier =\u003e ['keyid', 'issuer'],\n  copy_request_extensions  =\u003e ['subjectAltName', 'keyUsage'],\n  days                     =\u003e 2000,\n}\n```\n\n### Install Root CA certificates by default\n\nIf you want to provide certain Root or intermediate CA certificates by default, you can add a class parameter containing the list of certificate names:\n\n``` puppet\nclass { 'openssl':\n  cert_source_directory =\u003e '/etc/puppetlabs/code/private/certs',\n  ca_certs              =\u003e [ 'letsencrypt-ca' ],\n}\n```\n\nInternally the `openssl::cacert` defined type (see next section) is used.\n\n### Install a root CA certificate\n\nThe defined type `openssl::cacert` installs a trusted CA certificate:\n\n``` puppet\nopenssl::cacert { 'letsencrypt-ca': }\n```\n\nThis would install the Let's Encrypt certificate stored in the `letsencrypt-ca.crt` file. For the certificate the module automatically adds a trust attribute.\n\nOn Debian based distributions the certificate is stored in `/usr/local/share/ca-certificates` using a `.crt` extension. The module uses the `update-ca-certificates` script (included in the `ca-certificates` package) to include the certificate in `/etc/ssl/certs/ca-certificates.crt` and also create a symbolic link in `/etc/ssl/certs` pointing to the installed file:\n\n``` text\nlrwxrwxrwx 1 root root   18 Jul 14 13:27 /etc/ssl/certs/4f06f81d.0 -\u003e /usr/local/share/ca-certificates/letsencrypt-ca.crt\n```\n\nOn RedHat based distributions certificate is stored in `/etc/pki/ca-trust/source/anchors` using a `.crt` extension. The module uses the `update-ca-trust` script (included in the `ca-certificates` package) and also the `certutil` binary to add the certificate to the system-wide NSS database in `/etc/pki/nssdb`.\n\n### Install a certificate and key using defaults\n\nThe two defined types `openssl::cert` and `openssl::key` can be used to install a certificate and key using all defaults:\n\n``` puppet\nopenssl::cert { 'imap': }\nopenssl::key { 'imap': }\n```\n\nThis would take the files from the directory on the Puppet server (e.g. `/etc/puppetlabs/code/private/certs` if you set that using the `cert_source_directory` parameter). On the client the two files are created with restrictive permissions and ownership:\n\n``` text\nr-------- 1 root root 1679 Jan  3  2017 /etc/ssl/private/imap.key\nr--r--r-- 1 root root 1570 Mar  1 20:07 /etc/ssl/certs/imap.crt\n```\n\nThe default destination directories are distribution specific and can be configured using the class parameters `default_key_dir` and `default_cert_dir`.\n\n### Install a certificate and key for a specific application\n\nThe following code shows how to install a certificate and key in an application specific directory using application specific owner, group and mode:\n\n``` text\nopenssl::key { 'postgresql':\n  key     =\u003e $facts['networking']['hostname'],\n  owner   =\u003e 'root',\n  group   =\u003e 'postgres',\n  mode    =\u003e '0440',\n  key_dir =\u003e '/etc/postgresql',\n  source  =\u003e $facts['networking']['hostname'],\n}\n\nopenssl::cert { 'postgresql':\n  cert     =\u003e $facts['networking']['hostname'],\n  owner    =\u003e 'root',\n  group    =\u003e 'postgres',\n  mode     =\u003e '0444',\n  cert_dir =\u003e '/etc/postgresql',\n  source   =\u003e $facts['networking']['hostname'],\n}\n```\n\nThis example uses the hostname fact as the name of the key and therefore installs the cert and key on the host of the same name. If we assume that node `vortex` is your PostgreSQL server running Debian, then the following two files would be created by the manifest:\n\n``` text\nr--r----- 1 root postgres 1704 Jan  3  2017 /etc/postgresql/vortex.key\nr--r--r-- 1 root postgres 1464 Jan  3  2017 /etc/postgresql/vortex.crt\n```\n\n### Create a Diffie-Hellman parameter file\n\nTo use perfect forward secrecy cipher suites, you must set up Diffie-Hellman parameters on the server. Most applications allow including these parameters using a file. You can generate such a file using the `openssl_dhparam` custom type.\n\nUsing all the defaults (2048 bits):\n\n``` text\nopenssl_dhparam { '/etc/nginx/ssl/dh2048.pem': }\n```\n\nUsing 4096 bits and a different file group:\n\n``` text\nopenssl_dhparam { '/etc/mail/tls/dh2048.pem':\n  bits  =\u003e 4096,\n  group =\u003e 'smmsp',\n}\n```\n\n## Reference\n\nSee [REFERENCE.md](https://github.com/smoeding/puppet-openssl/blob/master/REFERENCE.md)\n\n## Development\n\nFeel free to send pull requests for new features.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmoeding%2Fpuppet-openssl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsmoeding%2Fpuppet-openssl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsmoeding%2Fpuppet-openssl/lists"}