141 lines
3.4 KiB
Markdown
141 lines
3.4 KiB
Markdown
# Certificates
|
|
|
|
This module creates and signs Certificates using multiple backends, including letsencrypt.
|
|
|
|
## Parameters
|
|
|
|
All configuration is to be placed inside the `certificates` dict.
|
|
|
|
```
|
|
# configuration for all backends, see below for options for all backends
|
|
backends:
|
|
letsencrypt: *letsencrypt-backend-config*
|
|
selfsigned: *selfsigned-backend-config*
|
|
ownca: *ownca-backend-config*
|
|
|
|
# default options for certificates
|
|
defaults:
|
|
country: "SU"
|
|
province: "CYBER"
|
|
city: "Cyberspace"
|
|
org: "Tyrell Corporation"
|
|
mail: "example@example.com"
|
|
ou: "cyber"
|
|
cn: ~
|
|
san: []
|
|
|
|
# name: certificate name, value: config for a certificate. See below for definition
|
|
certs: *certificate-config*
|
|
```
|
|
|
|
**certificate-config:**
|
|
All settings here overwrite the default setting for a certificate.
|
|
```
|
|
# Country (string)
|
|
country: "SU"
|
|
|
|
# Province (string)
|
|
province: "CYBER"
|
|
|
|
# City (string)
|
|
city: "Cyberspace"
|
|
|
|
# Organisation (string)
|
|
org: "Tyrell Corporation"
|
|
|
|
# Mailaddress (string)
|
|
mail: "example@example.com"
|
|
|
|
# organizational unit name (string)
|
|
ou: "cyber"
|
|
|
|
# common name (string), will be set to first SAN if set to None
|
|
cn: ~
|
|
|
|
# subject alt names (list of strings)
|
|
san: []
|
|
|
|
# services to restart if this certificate changes
|
|
depending_services: []
|
|
|
|
# which backend to use, can be 'selfsigned', 'letsencrypt' or 'ownca''
|
|
backend: 'selfsigned'
|
|
|
|
# overwrite a backend setting for this certificate
|
|
backend_override: {}
|
|
```
|
|
|
|
### Backends
|
|
#### Letsencrypt
|
|
|
|
*letsencrypt-backend-config*
|
|
|
|
```
|
|
# days of validity left on a certificate bevore it is renewed
|
|
remainingdays: 28
|
|
|
|
# challenge type to use, can be:
|
|
# 'dns-01': use the dns challenge and a custom powerdns backend
|
|
# 'dns-01-manual': use the dns challenge and manualy set the dns record
|
|
# 'http-01: use the http challenge and deploy the challenges to a webserver
|
|
challenge: dns-01
|
|
|
|
# servers to deploy a challenge to
|
|
challengeserver: []
|
|
|
|
# Automaticly renew certificates using a cronjob
|
|
# Only supports the following cases:
|
|
# * 'dns-01' challenge with the custom powerdns backend
|
|
# This setting musst be set the first time the certificate is requested, it can not be enabled later without first deleting the certificates.
|
|
# Requires a working mail setup with some sort of sendmail binary to send warnings if a certificate can not be renewed.
|
|
autorenew: False
|
|
```
|
|
|
|
#### Selfsigned
|
|
|
|
*selfsigned-backend-config*
|
|
|
|
```
|
|
# how long should the certificate be valid?
|
|
not_after: "+3650d"
|
|
```
|
|
|
|
#### Own CA
|
|
|
|
*ownca-backend-config*
|
|
|
|
```
|
|
# how long should the certificate be valid?
|
|
not_after: "+3650d"
|
|
|
|
# how long should the ca itself be valid?
|
|
ca_not_after: "+3650d"
|
|
|
|
# delegate the CA to another host. Set to Null to disable and have the ca on the same host this role runs
|
|
remote: Null
|
|
|
|
# base path to store the ca in
|
|
basepatht: "/etc/ssl/ca"
|
|
|
|
# name of the ca, used in paths
|
|
name: "ownca"
|
|
```
|
|
|
|
## Paths
|
|
|
|
Certificates are stored at a defined location:
|
|
|
|
* key: `/etc/ssl/private/<cetname>.key`
|
|
* certificate: `/etc/ssl/<certname>.crt`
|
|
* CSR: `/etc/ssl/<certname>.csr`
|
|
* chain: `/etc/ssl/<certname>.chain.crt`
|
|
* key, certificate and chain combined: `/etc/ssl/private/<certname>.complete.pem`
|
|
|
|
Please note that "chain" contains the ca for self signed and "ownca" certificates to work around some stupid bugs.
|
|
|
|
On the CA host for self signed certs those paths are used:
|
|
|
|
* ca base path: `<ownca.basepath>/<ownca.name>`
|
|
* ca key: `<basepath>/ca.key`
|
|
* ca cert: `<basepath>/ca.crt`
|
|
* all signed certs: `<basepath>/signed/<certname>`
|