# certmgr

[![Build Status](https://travis-ci.org/cloudflare/certmgr.svg?branch=master)](https://travis-ci.org/cloudflare/certmgr)
[![godoc](https://godoc.org/github.com/cloudflare/certmgr?status.svg)](https://godoc.org/github.com/cloudflare/certmgr)

certmgr is a tool for managing certificates using CFSSL. It does the
following:

* Ensures certificates are present.
* Renews certificates before they expire.
* Triggering a service reload or restart on certificate updates.

It operates on **certificate specs**, which are JSON files containing
the information needed to generate a certificate.

At regular intervals, `certmgr` will check that the parameters set in a certificate spec match the PKI material on disk. `certmgr` will take actions as needed in ensuring and regenerating PKI material as needed. If there's an error, a material refresh will happen at a later time.

When run without any subcommands, certmgr will start monitoring
certificates. The configuration and specifications can be validated
using the `check` subcommand.

If you want to further understand the package logic, take a look at the [godocs](https://godoc.org/github.com/cloudflare/certmgr).

**Note**: `certmgr` requires Go 1.11 or later due to [cfssl](https://github.com/cloudflare/cfssl) dependency.


## Web server

When appropriately configured, `certmgr` will start a web server that
has the following endpoints:

* `/` just contains certmgr start time and current address.
* `/metrics` is the Prometheus endpoint (see the Metrics section).

## Metrics

Prometheus is used to collect some useful `certmgr` metrics. You can find them in the [godoc](https://godoc.org/github.com/cloudflare/certmgr/metrics).

## certmgr.yaml

The configuration file must be a YAML file; it is expected to be in
`/usr/local/etc/certmgr/certmgr.yaml`. The location can be changed using the
`-f` flag.

An example `certmgr.yaml` file is:

```
dir: /usr/local/etc/certmgr.d
default_remote: ca.example.net:8888
svcmgr: systemd
before: 72h
interval: 30m

metrics_port: 8080
metrics_address: localhost
```

This contains all of the currently available parameters:

* `dir`: this specifies the directory containing the certificate specs
* `svcmgr`: this specifies the service manager to use for restarting
  or reloading services. This can be `systemd` (using `systemctl`),
  `sysv` (using `service`), `circus` (using `circusctl`), `openrc` (using `rc-service`),
  `dummy` (no restart/reload behavior), or `command` (see the command svcmgr section
  for details of how to use this).
* `before`: optional: this is the default duration before a certificate expiry that certmgr starts attempting to
  renew PKI.  This defaults to 72 hours.
* `interval`: optional: this is the default for how often `certmgr` will check certificate expirations
  and update PKI material on disk upon any changes (if necessary).  This defaults to one hour.
* `interval_splay`: optional: this is used to vary the interval period.  A random time between 0
  and this value is added to `interval` if specified.  This defaults to 0.
* `initial_splay`: if specified, a random sleep period between 0 and this value is used
  for the initial sleep after startup of a spec.  This provides a way to ensure that
  if a fleet of certmgr are restarted at the same time, their period of wakeup is randomized
  to avoid said fleet waking up and doing interval checks at the same time for a given spec.
  This defaults to 0.
* `metrics_address`: specifies the address for the Prometheus HTTP
  endpoint.
* `metrics_port`: specifies the port for the Prometheus HTTP endpoint.
* `take_actions_only_if_running`: boolean, if true, only fire a spec's action if the service is actually running.
  If this is set to false (the default for historical reasons), this can lead to certmgr starting a downed service
  when PKI expiry occurs.


## PKI Specs

A spec is used to manage PKI material for a consuming app.  A spec does not have to request a certificate/key, and does not have to request a CA; it must request at least one of those two modes, however.

Said another way; you can use this to maintain a CA on disk.  You can use this to maintain certificate/key pair signed by the given authority; you can do both modes if you wish, but one must be specified by the spec.

An example spec that writes both a CA and certificate key pair defined in JSON:

```
{
    "service": "nginx",
    "action": "restart",
    "request": {
        "CN": "www.example.net",
        "hosts": [
            "example.net",
            "www.example.net"
        ],
        "key": {
            "algo": "ecdsa",
            "size": 521
        },
        "names": [
            {
                "C": "US",
                "ST": "CA",
                "L": "San Francisco",
                "O": "Example, LLC"
            }
        ]
    },
    "private_key": {
        "path": "/etc/ssl/private/www.key",
        "owner": "www-data",
        "group": "www-data",
        "mode": "0600"
    },
    "certificate": {
        "path": "/home/kyle/tmp/certmgr/certs/test1.pem",
        "owner": "www-data",
        "group": "www-data"
    },
    "ca": {
        "path": "/etc/myservice/ca.pem",
        "owner": "www-data",
        "group": "www-data"
    },
    "authority": {
        "remote": "ca.example.net:8888",
        "auth_key": "012345678012345678",
        "label": "www_ca",
        "profile": "three-month",
        root_ca: "/etc/cfssl/api_server_ca.pem"
    }
}
```

And this is an example that writes just the CA to disk:
```
{
    "service": "nginx",
    "action": "restart",
    "authority": {
        "remote": "ca.example.net:8888",
        "auth_key": "012345678012345678",
        "label": "www_ca",
        "profile": "three-month",
        "file": {
            "path": "/etc/myservice/ca.pem",
            "owner": "www-data",
            "group": "www-data"
        },
        root_ca: "/etc/cfssl/api_server_ca.pem"
    }
}
```

A certificate spec has the following fields:

* `service`: this is optional, and names the service that the `action`
  should be applied to.
* `action`: this is optional, and may be one of "restart", "reload",
  or "nop".
* `svcmgr`: this is optional, and defaults to whatever the global
  config defines.  This allows fine-grained control for specifying the
  svcmgr per cert.  If you're using this in a raw certificate definition,
  you likely want the 'command' svcmgr- see that section for details of
  how to use it.
* `request`: a CFSSL certificate request (see below).  If this is specified, a `certificate` and `private_key` field is required.
* `private_key` and `certificate`: file specifications (see below) for
  the private key and certificate.  Both must be specified- as must `request`- if you wish to manage a certificate/key pair.
* `authority`: contains the CFSSL CA configuration (see below).
* `before`: optional: this is the default duration before a certificate expiry that certmgr starts attempting to
  renew PKI.  This defaults to the managers default, which defaults to 72 hours if unspecified.
* `interval`: optional: this is the default for how often `certmgr` will check certificate expirations
  and update PKI material on disk upon any changes (if necessary).  This defaults to the managers default, which
  defaults to one hour if unspecified.
* `interval_splay`: optional: this is used to vary the interval period.  A random time between 0
  and this value is added to `interval` if specified.  This defaults to the managers default, which defaults to 0
  if unspecified.
* `initial_splay`: if specified, a random sleep period between 0 and this value is used
  for the initial sleep after startup of a spec.  This provides a way to ensure that
  if a fleet of certmgr are restarted at the same time, their period of wakeup is randomized
  to avoid said fleet waking up and doing interval checks at the same time for a given spec.
  This defaults to the managers default, which defaults to 0 if unspecified.
* `take_actions_only_if_running`: boolean, if true, only fire a spec's action if the service is actually running.
  If this is set to false (the default for historical reasons), this can lead to certmgr starting a downed service
  when PKI expiry occurs.
* `key_usages`: optional: An array of strings defining what this key should be used for. Certmgr will consider a cert invalid
   if it does not contain these key usages. Possible values are from cfssl's [ExtKeyUsage map](https://github.com/cloudflare/cfssl/blob/1.3.3/config/config.go#L568)



**Note**: `certmgr` will throw a warning if `svcmgr` is `dummy` _AND_ `action` is "nop" or undefined. This is because such a setup will not properly restart or reload a service upon certificate renewal, which will likely cause your service to crash. Running `certmgr` with the `--strict` flag will not even load a certificate spec with a `dummy svcmgr` and undefined/nop `action` configuration.


File specifications contain the following fields:

* `path`: this is required, and is the path to store the file.
* `owner`: this is optional; if it's not provided, the current user is
  used.
* `group`: this is optional; if it's not provided, the primary group
  of the current user is used.
* `mode`: this is optional; if it's not provided, "0644" will be
  used. It should be a numeric file mode.

CFSSL certificate requests have the following fields:

* `CN`: this contains the common name for the certificate.
* `hosts`: this is a list of SANs and/or IP addresses for the
  certificate.
* `key`: this is optional; it should contain an "algo" of either "rsa"
  or "ecdsa" and a "size" appropriate for the chosen
  algorithm. Recommendations are "rsa" and 2048 or "ecdsa"
  and 256. The default is "ecdsa" and 256.
* `names`: contains PKIX name information, including the "C"
  (country), "ST" (state), "L" (locality/city), "O" (organisation),
  and "OU" (organisational unit) fields.

The CA specification contains the following fields:

* `remote`: the CA to use. If not provided, the default remote from
  the config file is used.
* `auth_key`: the authentication key used to request a certificate.
* `auth_key_file`: optional, if defined read the auth_key from this. If
  `auth_key` and `auth_key_file` is defined, `auth_key` is used.
* `label`: the CA to use for the certificate.
* `profile`: the CA profile that should be used.
* `file`: if this is included, the CA certificate will be saved here. It
  follows the same file specification format above. Use this if you want to save your CA cert to disk.
* `root_ca`: optionally, a path to a certificate to trust as CA for the
  cfssl API server certificate. Usable if the "remote" is tls enabled
  and configured with a self-signed certificate. By default,
  the system root CA chain is trusted.

## `command svcmgr` and how to use it

If the svcmgr is set to `command`, then `action` is interpreted as a
shell snippet to invoke via  `bash -c`.  Bash is preferred since
it allows parse checks to run. If Bash isn't available, parse checks
are skipped and `sh -c` is used.  If `sh` can't be found, then this svcmgr
is disabled. The `command svcmgr` is useful in Marathon environments.

Environment variables are set as follows:

* CERTMGR_CA_PATH: if CA was configured for the spec, this is the path
  to the CA ondisk that was changed.
* CERTMGR_CERT_PATH: This is the path to the cert that was written.
* CERTMGR_KEY_PATH: This is the path to the key that was written.

## Subcommands

In addition to the certificate manager, there are a few utilities
functions specified:

* `check`: validates the configuration file and all the certificate
  specs available in the certificate spec directory.  Note that if you
  wish to operate on just one spec, you can use `-d /path/to/that/spec`
  to accomplish it.
* `clean`: removes all of the certificates and private keys specified
  by the certificate specs.  Note that if you wish to operate on just one spec,
  you can use `-d /path/to/that/spec` to accomplish it.
* `ensure`: attempts to load all certificate specs, and ensure that
  the TLS key pairs they identify exist, are valid, and that they are
  up-to-date.  Note that if you wish to operate on just one spec, you
  can use `-d /path/to/that/spec` to accomplish this.
* `genconfig`: generates a default configuration file and ensures the
  default service directory exists.
* `version`: prints certificate manager's version, the version of Go
  it was built with, and shows the current configuration.

## See also

The `certmgr` spec is included as `SPEC.rst`.


## Contributing

To contribute, fork this repo and make your changes. Then, make a PR to this repo. A PR requires at least one approval from a repo admin and successful CI build.

### Unit Testing
Unit tests can be written locally. This should be straightforward in a Linux environment.
To run them in a non-Linux environment, have Docker up and run `make test`. This will spin up a container with your local build. From here you can `go test -v ./...` your files. This unconventional setup is because [cfssl](https://github.com/cloudflare/cfssl), the underlying logic of `certmgr`, uses [cgo](https://golang.org/cmd/cgo/).