# 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>`

## Examples

### Ownca with CA host and certificates on multiple servers

The certificate name can be different on all hosts.
You can set more options like `san` as well.
The CA name musst be the same on all hosts.
<ca-host> musst be the inventory_hostname of the ca-host.

**ca-host**
```
certificates:
  certs:
    "<certificate name on ca host>":
      backend: ownca
      cn: "{{ inventory_hostname }}"
      backend_override:
        name: <ca name>
```

**server01**
```
certificates:
  certs:
    "<certificate name on server01>":
      backend: ownca
      cn: "{{ inventory_hostname }}"
      backend_override:
        name: <ca name>
        remote: <ca-host>
```

**server02**
```
certificates:
  certs:
    "<certificate name on server02>":
      backend: ownca
      cn: "{{ inventory_hostname }}"
      backend_override:
        name: <ca name>
        remote: <ca-host>
```