From a9265f33690ebdc4a7eed5afcc6d89b76a52aa0c Mon Sep 17 00:00:00 2001
From: Fabien COMBERNOUS <fabien.combernous@adullact.org>
Date: Thu, 10 Nov 2022 15:32:36 +0100
Subject: [PATCH] introduce CFSSL module
---
README.md | 163 +++++++++++++++++++++++++++++++-----------------------
1 file changed, 93 insertions(+), 70 deletions(-)
diff --git a/README.md b/README.md
index cbfd7d5..55ae1d4 100644
--- a/README.md
+++ b/README.md
@@ -1,10 +1,6 @@
# cfssl
-Welcome to your new module. A short overview of the generated parts can be found
-in the [PDK documentation][1].
-
-The README template below provides a starting point with details about what
-information to include in your README.
+This module install and configure [CFSSL](https://github.com/cloudflare/cfssl) to serve as a PKI.
## Table of Contents
@@ -19,99 +15,126 @@ information to include in your README.
## Description
-Briefly tell users why they might want to use your module. Explain what your
-module does and what kind of problems users can solve with it.
-
-This should be a fairly short description helps the user decide if your module
-is what they want.
+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 **OPTIONAL**
+### What cfssl affects
-If it's obvious what your module touches, you can skip this section. For
-example, folks can probably figure out that your mysql_instance module affects
-their MySQL instances.
+In addition to CFSSL, this module install Go, Goose and PostgreSQL.
-If there's more that they should know about, though, this is the place to
-mention:
+### Beginning with cfssl
-* Files, packages, services, or operations that the module will alter, impact,
- or execute.
-* Dependencies that your module automatically installs.
-* Warnings or other important notices.
+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',
+ },
+ },
+}
+```
-### Setup Requirements **OPTIONAL**
+From here, you are able to procude certificates from `cfssl` command line with shell on the host.
-If your module requires anything extra before setting up (pluginsync enabled,
-another module, etc.), mention it here.
+## Usage
-If your most recent release breaks compatibility or requires particular steps
-for upgrading, you might want to include an additional "Upgrading" section here.
+### With served self signed root certificate authority
-### Beginning with cfssl
+In this example :
+* self signed root ca is installed.
+* this root ca is served via [HTTP API server](https://github.com/cloudflare/cfssl/tree/master/doc/api) for X509 certificates.
+* a CRL is generated is `$cfssl::crldir` directory, updated periodicaly.
-The very basic steps needed for a user to get the module up and running. This
-can include setup steps, if necessary, or it can be an example of the most basic
-use of the module.
+```
+class { 'cfssl':
+ rootca_manifest => {
+ cn => 'MYEXEMPLE ROOT CA',
+ subject => {
+ 'C' => 'FR',
+ 'L' => 'MONTPELLIER',
+ 'O' => 'MYEXEMPLE ORG',
+ },
+ },
+ serve_ca => 'MYEXEMPLE ROOT CA',
+ crl_manage => true,
+}
-## Usage
+```
-Include usage examples for common use cases in the **Usage** section. Show your
-users how to use your module to solve problems, and be sure to include code
-examples. Include three to five examples of the most important or common tasks a
-user can accomplish with your module. Show users how to accomplish more complex
-tasks that involve different types, classes, and functions working in tandem.
+### With served intermediate certificate authority
-## Reference
+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](https://github.com/cloudflare/cfssl/tree/master/doc/api) for X509 certificates.
+* a CRL is generated is `$cfssl::crldir` directory, updated periodicaly.
-This section is deprecated. Instead, add reference information to your code as
-Puppet Strings comments, and then use Strings to generate a REFERENCE.md in your
-module. For details on how to add code comments and generate documentation with
-Strings, see the [Puppet Strings documentation][2] and [style guide][3].
+```
+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,
+}
+```
-If you aren't ready to use Strings yet, manually create a REFERENCE.md in the
-root of your module directory and list out each of your module's classes,
-defined types, facts, functions, Puppet tasks, task plans, and resource types
-and providers, along with the parameters for each.
+### Note about authkey
-For each element (class, defined type, function, and so on), list:
+With CFSSL serve, it is possible to restrict acces to end points `sign` and `authsign`. In this case a [key](https://gitlab.adullact.net/adullact/puppet-cfssl/-/blob/main/REFERENCE.md#cfsslserveconfig) have to be
+configured in [serve_config](https://gitlab.adullact.net/adullact/puppet-cfssl/-/blob/main/REFERENCE.md#serve_config) parameter.
+It is possible to generated a key with this command : `hexdump -n 16 -e "4/4 \"%08X\" 1 \"\n\"" /dev/random`
-* The data type, if applicable.
-* A description of what the element does.
-* Valid values, if the data type doesn't make it obvious.
-* Default value, if any.
+## Reference
-For example:
+Details are in [REFERENCE.md](https://gitlab.adullact.net/adullact/puppet-cfssl/-/blob/main/REFERENCE.md) file.
-```
-### `pet::cat`
+## Limitations
-#### Parameters
+Supported OSes are given in [metadata.json](https://gitlab.adullact.net/adullact/puppet-cfssl/-/blob/main/metadata.json) file.
-##### `meow`
+## Development
-Enables vocalization in your cat. Valid options: 'string'.
+Home at URL https://gitlab.adullact.net/adullact/puppet-cfssl
-Default: 'medium-loud'.
-```
+Issues and MR are welcome.
-## Limitations
+## Release Notes/Contributors/Etc.
-In the Limitations section, list any incompatibilities, known issues, or other
-warnings.
+Details in [CHANGELOG.md](https://gitlab.adullact.net/adullact/puppet-cfssl/-/blob/main/CHANGELOG.md).
-## Development
+```
+Copyright (C) 2018 Association des Développeurs et Utilisateurs de Logiciels Libres
+ pour les Administrations et Colléctivités Territoriales.
-In the Development section, tell other users the ground rules for contributing
-to your project and how they should submit their work.
+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.
-## Release Notes/Contributors/Etc. **Optional**
+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>.
-If you aren't using changelog, put your release notes here (though you should
-consider using changelog). You can also add any additional sections you feel are
-necessary or important to include here. Please use the `##` header.
+```
-[1]: https://puppet.com/docs/pdk/latest/pdk_generating_modules.html
-[2]: https://puppet.com/docs/puppet/latest/puppet_strings.html
-[3]: https://puppet.com/docs/puppet/latest/puppet_strings_style.html
--
GitLab