Aegis documentation

#SSL and TLS

Two sources of certificates, one API:

SourceWhereWhen
Let's Encrypt (DNS-01 via BIND)<certbot.data_dir>/live/<name>/a domain is configured and DNS is ours
Local self-signed<ssl.dir>/local/<name>/IP addresses, internal names, no ACME

#The API

python
from app.modules import sslcert = ssl.resolve(config, "example.com")      # LE first, local otherwisecert = ssl.resolve(config, "203.0.113.10")     # local for an IPcert = ssl.ensure_domains(config, "example.com",                          ["example.com", "www.example.com", "shop.example.com"])

resolve never issues a Let's Encrypt certificate: it looks for an existing lineage and falls back to local generation.

ensure_domains is the multi-name entry point:

  • one name → resolve;
  • several names → read the SANs of the existing certificate with
  • openssl x509 -ext subjectAltName;

  • if every name is covered, reuse it;
  • otherwise call the certbot cube, which issues one certificate with all names
  • as SANs.

    Certificate carries name, key, chain, source plus helpers:

    python
    cert.days_left(openssl.binary(config), openssl.environment(config))cert.sans(openssl.binary(config), openssl.environment(config))cert.expired(...)

    #Local certificates

    bash
    aegis ssl ensure 203.0.113.10aegis ssl ensure intranet --san=intranet.local --san=10.0.0.5 --san=api.intranet.localaegis ssl ensure intranet --force          # regenerateaegis ssl listaegis ssl show example.com
  • EC key, prime256v1, SHA-256, 825 days by default (ssl.days);
  • SANs are classified automatically: IP:… for addresses, DNS:… for names;
  • files: privkey.pem (0600) and cert.pem (0644);
  • regeneration happens when the certificate is expired or missing.
  • The bundled OpenSSL is used when installed, with LD_LIBRARY_PATH and an OPENSSL_CONF that falls back to /etc/ssl/openssl.cnf because the build installs without its own ssl/ directory.

    #Let's Encrypt

    Issuance belongs to the certbot cube (see cubes/certbot.md):

    bash
    aegis cubes certbot configure        # cli.ini + rfc2136.iniaegis cubes certbot issue example.comaegis cubes certbot issue example.com www.example.com shop.example.comaegis cubes certbot certificates

    DNS-01 requires an authoritative zone for each name, with allow-update bound to our TSIG key — that is what cubes bind produces.

    #SNI, several names, several base domains

    A certificate is just a list of names; they do not have to share a zone:

    bash
    # one certificate, four names, two registrable domainsaegis cubes certbot issue a.com www.a.com b.com shop.b.com# or let the vhost create itaegis cubes nginx vhosts create   --domain=a.com --domain=www.a.com --domain=b.com   --name=multi --location=php-mvc

    Requirements and limits:

  • every name must be resolvable by DNS-01 (zone on our BIND, or a delegated
  • _acme-challenge CNAME);

  • Let's Encrypt allows at most 100 names in one certificate;
  • rate limits apply per registered domain (50 certificates/week, 5 duplicates);
  • wildcards (--domain='*.a.com') work, since DNS-01 is used.
  • nginx receives the resulting certificate automatically:

    nginx
    ssl_certificate     /aegis/data/certbot/live/a.com/fullchain.pem;ssl_certificate_key /aegis/data/certbot/live/a.com/privkey.pem;server_name a.com www.a.com b.com shop.b.com;

    #Using an existing certificate

    bash
    aegis cubes nginx vhosts create --domain=a.com --name=imported   --ssl-cert-path=/etc/ssl/mycert/fullchain.pem   --ssl-cert-key-path=/etc/ssl/mycert/privkey.pem

    Explicit paths win over resolution; nothing is issued and nothing is copied.

    #Not implemented yet

  • certificate renewal scheduling (keeper.cron);
  • a pre-check that every requested domain has an authoritative zone, with a
  • --create-zones shortcut;

  • automatic reload of the services that consume a renewed certificate.