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.

Note: certmgr requires Go 1.11 or later due to 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.

certmgr.yaml

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

An example certmgr.yaml file is:

dir: /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"
    },
    "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"
    }
}

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 htis 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.

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 certiifcate 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 interpretted as a shell snippet to invoke via bash -c. Bash is preferred since it allows parse checks to be ran- 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_CHANGE_TYPE: either 'CA' or 'key'. This indicates if the CA changes, or if it's just a cert renewal.
• 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.
• CERTMGR_SPEC_PATH: This is the path to the cert spec definition that was just refreshed.

Subcommands

In addition to the certificate manager, there are a few utility 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, the underlying logic of certmgr, uses cgo.