selfhostblocks/modules/blocks/ssl/docs/default.md

SSL Generator Block

This NixOS module is a block that implements the SSL certificate generator contract.

It is implemented by:

• shb.certs.cas.selfsigned and shb.certs.certs.selfsigned: Generates self-signed certificates, including self-signed CA thanks to the certtool package.
• shb.certs.certs.letsencrypt: Requests certificates from Let's Encrypt.

Self-Signed Certificates

Defined in /modules/blocks/ssl.nix.

To use self-signed certificates, we must first generate at least one Certificate Authority (CA):

shb.certs.cas.selfsigned.myca = {
  name = "My CA";
};

Every CA defined this way will be concatenated into the file /etc/ssl/certs/ca-certificates.cert which means those CAs and all certificates generated by those CAs will be automatically trusted.

We can then generate one or more certificates signed by that CA:

shb.certs.certs.selfsigned = {
  "example.com" = {
    ca = config.shb.certs.cas.selfsigned.myca;

    domain = "example.com";
    group = "nginx";
    reloadServices = [ "nginx.service" ];
  };
  "www.example.com" = {
    ca = config.shb.certs.cas.selfsigned.myca;

    domain = "www.example.com";
    group = "nginx";
  };
};

The group has been chosen to be nginx to be consistent with the examples further down in this document.

Let's Encrypt

Defined in /modules/blocks/ssl.nix.

We can ask Let's Encrypt to generate a certificate with:

shb.certs.certs.letsencrypt."example.com" = {
  domain = "example.com";
  group = "nginx";
  dnsProvider = "linode";
  adminEmail = "admin@example.com";
  credentialsFile = /path/to/secret/file;
  additionalEnvironment = {
    LINODE_HTTP_TIMEOUT = "10";
    LINODE_POLLING_INTERVAL = "10";
    LINODE_PROPAGATION_TIMEOUT = "240";
  };
};

The credential file's content would be a key-value pair:

LINODE_TOKEN=XYZ...

For other providers, see the official instruction.

Usage

To use either a self-signed certificates or a Let's Encrypt generated one, we can reference the path where the certificate and the private key are located:

config.shb.certs.certs.<implementation>.<name>.paths.cert
config.shb.certs.certs.<implementation>.<name>.paths.key
config.shb.certs.certs.<implementation>.<name>.systemdService

For example:

config.shb.certs.certs.selfsigned."example.com".paths.cert
config.shb.certs.certs.selfsigned."example.com".paths.key
config.shb.certs.certs.selfsigned."example.com".systemdService

The full CA bundle is generated by the following Systemd service, running after each individual generator finished:

config.shb.certs.systemdService

See also the SSL certificate generator usage for a more detailed usage example.

Debug

Each CA and Cert is generated by a systemd service whose name can be seen in the systemdService option. You can then see the latest errors messages using journalctl.

Tests

The self-signed implementation is tested in /tests/vm/ssl.nix.

Options Reference

id-prefix: blocks-ssl-options-
list-id: selfhostblocks-options
source: @OPTIONS_JSON@