Certificates

The hub publishes one port, 443. Its terminator ends TLS for the hub’s own two names, the admin UI’s address and the published leaf address, and passes every other name unopened to the API gateway, which ends TLS for each gateway hostname with that gateway’s certificate. Both accept TLS 1.2 and 1.3 only, and on TLS 1.2 only the AES-GCM and ChaCha20 suites. Current browsers, systems and HTTP libraries connect, and a client that knows only the older CBC suites, such as Safari 8, can’t.

Which source signs a name#

The platform obtains and renews the certificate of every gateway hostname by itself. For each name the first of these that fits signs it:

1. A name on the public entrance whose DNS records point at the hub is proved to Let’s Encrypt over TLS on port 443.
2. A name your own certificate authority covers, added with weikio certificates authority add, is signed by that authority.
3. A name in a zone a DNS connection writes, and that public DNS shows, is proved to Let’s Encrypt through DNS, wildcards included.
4. Any other name, such as an .internal one or a name on an internal entrance with no DNS connection, is signed by the platform’s own authority.

A public name that points elsewhere and has no DNS connection waits, and the gateway’s reply says where it points. A certificate you upload on a gateway is served in place of the platform’s for the names it covers:

$ weikio gateway set partner --server-certificate partner=chain.pem,key.pem

Only a gateway created with --certificate-source uploaded needs one.

The hub’s own names#

The platform obtains the certificates of the hub’s two names from Let’s Encrypt and renews them, and the terminator loads each new one without a restart. Until the first one is issued, about a minute after the start once the names’ DNS records point at the hub, the terminator serves a temporary self-signed certificate and browsers warn on the admin UI’s address. Settings › Installation says why a name still waits.

The first init accepts the choices for every certificate the platform obtains, and a platform administrator changes them later on Settings › Installation:

• --certificates uploaded turns the platform’s own certificates off.
• --certificate-authority gives an ACME directory other than Let’s Encrypt’s.
• --certificate-contact is the address the authority writes to.
• --public-address, repeated, gives the addresses callers reach port 443 on when the admin UI’s name resolves to others.

The names are set at install. A hub moves to new names with a backup, a first start with the new names on a new home and a restore.

Use your own certificate#

A certificate from your own certificate authority, or the origin certificate of a CDN in front of the hub, is uploaded once on Settings › Installation and served in place of the platform’s. When the admin UI can’t be reached without it, for example behind a CDN that refuses the temporary certificate, give it to the first init, which accepts only files under the home:

$ install -d -o 1654 -g 1654 -m 0700 /opt/weikio/import
$ install -o 1654 -g 1654 -m 0600 hub.crt hub.key /opt/weikio/import/

The first start’s docker run then ends in init ... --hub-certificate company=/opt/weikio/import/hub.crt,/opt/weikio/import/hub.key. hub.crt has the chain with the server’s certificate first, and one certificate may cover both names. Delete /opt/weikio/import after the first start, because the platform keeps the certificate in its sealed store. Such a certificate renews when you upload the next one, and the platform warns 30 and 7 days before it expires.

With a certificate from your own authority, doctor checks the public address against that authority when you give it the authority’s certificate:

$ docker compose run --rm -e SSL_CERT_FILE=/etc/weikio-ca.crt -v /path/to/ca.crt:/etc/weikio-ca.crt:ro infra weikio-backend doctor

The sites trust only the authorities of their own system unless the installation gives them its own. Add --leaf-ca-file /opt/weikio/leaf-ca.crt to the first init line, and every site bundle then has that authority’s certificate as hub-ca.crt.

Prove names through DNS#

A name that doesn’t point at the hub, such as one proxied by a CDN or one on an internal network, is proved to Let’s Encrypt through a TXT record the platform writes in the name’s zone. A platform administrator adds one DNS connection per zone with a credential that may write records there, such as a Cloudflare token with Zone Read and DNS Write on that one zone:

$ weikio platform secret set cf-token
$ weikio certificates dns add cf --provider cloudflare --zone acme.example --secret cf-token

The command writes a probe record, reads it from the zone’s public name servers, removes it and prints the result, such as DNS connection cf added (public view public). Hetzner, Azure DNS and RFC 2136 servers work the same way with their own --provider and options. The first init can take a connection too, with --dns-provider cloudflare --dns-zone acme.example --dns-token-file /opt/weikio/import/cf.token, so the hub’s names get their first certificate before anyone signs in.

The narrowest credential writes a zone that has nothing else. Point the challenge name of each name at it with a CNAME record, such as _acme-challenge.api.acme.example. CNAME api.acme.example.challenges.acme.example., and give the platform the token of challenges.acme.example only. The platform follows the CNAME and writes its records there, and Let’s Encrypt follows the same CNAME when it checks.

Your own ACME authority#

A certificate authority of your own that speaks ACME signs the names under the suffixes you give it:

$ weikio certificates authority add corp --acme https://ca.acme.example/acme/directory --names corp.example --trust ca.pem

certificate authority corp added (signs corp.example)

--eab-key-id and --eab-secret give the account binding the authority hands out, where --eab-secret is the name of a platform secret that contains its key, and --orders site lets the site gateways order from an authority that only the site reaches.

The platform’s own authority#

The first start makes the installation’s own certificate authority, which signs names no public authority signs, such as .internal ones, and the client certificates a gateway presents to an upstream. A machine that trusts the authority trusts every name it signs, and weikio platform authority get gives you its certificate to install there. --authority-names corp.example,factory.local on the first init limits it to names under those suffixes. The limit is fixed at the first start, so choose the suffixes before it. For a hub with no public DNS, --hub-names-authority platform on the first init signs the hub’s own names from this authority instead of Let’s Encrypt, and every site bundle then has the authority’s certificate.

See and renew certificates#

$ weikio get certificates

The list has one row per certificate the platform manages, with the columns NAME, USED BY, SOURCE, STATE, EXPIRES and RENEWS: the hub’s own names, each gateway hostname, a site gateway’s own, the client certificates the gateway presents to upstreams and the platform’s root. SOURCE says who signed it and how, such as Let's Encrypt through TLS on port 443 or the platform's authority. Settings › Certificates shows the same, and the problem list says when a request keeps failing or a certificate nears its expiry.

Renewal is automatic. To replace a certificate sooner than its own renewal, ask for it again:

$ weikio certificates renew api.acme.example

A public authority issues only a few certificates for one exact set of names in a week. After 5 certificates for the same names in 7 days the platform refuses a renewal and says when the name may be asked for again, so renew by hand only when you need to.