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.
