Aegis documentation

#ssl

aegis ssl inspects and generates the certificates Aegis services ask for by name. There are two sources and one rule: a valid Let's Encrypt lineage is preferred, and a self-signed certificate is generated locally when no issued one covers the name.

sourcelocationused for
letsencrypt<certbot.data_dir>/live/<name>/{fullchain.pem,privkey.pem}domains with a public name
local<ssl.dir>/local/<name>/{cert.pem,privkey.pem}IP addresses, internal names, a fallback

Defaults are /aegis/data/certbot and /aegis/config/ssl. The group has three commands and prints human lines; the global --json flag has no effect here.

exit codemeaning
0the command finished
1openssl failed, or the name could not be resolved
2argparse rejected the arguments

#Commands

#aegis ssl list

Lists the certificates this host generated locally, with the remaining days and the certificate path. Let's Encrypt lineages are not listed by this command.

bash
aegis ssl list
argumentdefaultmeaning
——the command takes no options
bash
aegis ssl listaegis ssl list   # after `ssl ensure`
text
name          left  certificate────────────  ────  ─────────────────────────────────────────────203.0.113.10  825d  /aegis/config/ssl/local/203.0.113.10/cert.pemintranet      812d  /aegis/config/ssl/local/intranet/cert.pem

left is the number of days until notAfter, computed by openssl x509 against the current time. -1d means the check failed, which is what an expired certificate and an unreadable file both look like. A host with nothing generated prints ℹ no local certificates yet and exits 0.

#aegis ssl ensure

Creates a self-signed certificate for a name, or returns the existing one when it is still valid. The key is EC P-256; the certificate is SHA-256, valid for ssl.days (825 by default), with CN set to the first name and one SAN entry per name.

bash
aegis ssl ensure <name> --san=<name>... --force
argumentdefaultmeaning
<name>—directory name; with no --san it is also the CN and the only SAN
--santhe name itselfrepeatable; when given, it replaces the default list, so repeat the main name if it must be covered
--forceoffregenerate even when a valid certificate exists

Names are classified for the SAN field: anything that parses as an IP address becomes IP:…, everything else DNS:…. The directory is the name with every character outside letters, digits, . and - replaced by _.

bash
aegis ssl ensure 203.0.113.10aegis ssl ensure intranet --san=intranet --san=intranet.local --san=10.0.0.5aegis ssl ensure intranet --force
text
✔ intranet: /aegis/config/ssl/local/intranet/cert.pem (key /aegis/config/ssl/local/intranet/privkey.pem)

An existing certificate that has not expired is returned without touching the files; --force regenerates it. Files are written with 0600 on the key and 0644 on the certificate. When openssl refuses, the command prints the last lines of its output and exits 1:

text
✖ openssl could not create the certificate

The last lines of the openssl output follow on stderr.

#aegis ssl show

Prints the certificate a service would receive for one name: where it comes from, the two paths, and the remaining days.

bash
aegis ssl show <name>
argumentdefaultmeaning
<name>—the name a service asks for: a domain, a host name or an IP
bash
aegis ssl show example.comaegis ssl show 203.0.113.10

Issued certificate:

text
name:    example.comsource:  letsencryptchain:   /aegis/data/certbot/live/example.com/fullchain.pemkey:     /aegis/data/certbot/live/example.com/privkey.pemexpires: 62 days

Local certificate:

text
name:    203.0.113.10source:  localchain:   /aegis/config/ssl/local/203.0.113.10/cert.pemkey:     /aegis/config/ssl/local/203.0.113.10/privkey.pemexpires: 825 days

Resolution order:

  • a Let's Encrypt lineage whose directory is exactly this name;
  • a local certificate whose directory is exactly this name;
  • ssl.resolve: an issued lineage whose SANs cover the name — including a
  • one-label wildcard such as *.example.com — otherwise generate a local certificate for the name.

    Two consequences worth knowing:

  • show is not completely read-only. When steps 1 and 2 find nothing and no
  • issued certificate covers the name, step 3 creates the local certificate and prints its path.

  • An existing but expired Let's Encrypt lineage is still found at step 1 and is
  • printed with expires: -1 days; show does not fall through to the local certificate for it. Services use resolve, which skips an expired issued certificate, so check the expires line rather than assuming the two agree.

    expires: -1 days means openssl x509 -checkend 0 failed for the file, which is what both an expired certificate and an unreadable one look like. A name whose resolution fails prints the error and exits 1.