Certificates and certificate authorities

This page explains the certificates the course builds, checks and backs up. You don’t need to write code to follow it, and there’s no math.

In OpenZiti, the controller is the program that manages the network and keeps the rules about who may reach what. Routers carry the traffic. In the course, both run on Ubuntu Linux machines.

Two keys that belong together

A computer that has to prove who it is uses a key pair: two matching pieces of data, created together.

• The private key is the secret half. Its owner keeps it and never sends it to anyone.
• The public key is the half you can hand to anyone.

To encrypt data is to scramble it so only the holder of the right key can read it; to decrypt is to turn it back. Data encrypted with a public key can only be decrypted with the matching private key.

To sign data, a program uses a private key to make a value from it, called a signature. Anyone with the matching public key can check two things: which key made the signature, and that the data hasn’t changed since.

What a certificate says

A certificate is a small file that ties a public key to a name. In plain words it says: this public key belongs to this machine or person, from this date until that date. Someone who vouches for that statement signs it. The common format is called X.509, and you’ll see that name in commands.

The main parts of a certificate are:

• the subject: who or what the certificate is about
• the subject’s public key
• the issuer: who signed it
• the validity period: a start date and an end date
• extra names the certificate is valid for, called the SAN (explained below)

A certificate isn’t secret: it carries only the public key.

Certificate authorities and the chain

A certificate authority (CA) is the party that issues certificates: it checks a request, then signs the new certificate with its own private key. The whole set of CAs, certificates and keys a system relies on is called its public key infrastructure (PKI).

CAs are arranged in a chain:

1. The root CA is at the top. Its certificate is signed by its own key. A computer trusts a root only because someone told it to.
2. An intermediate CA has a certificate signed by the root. It does the everyday signing, so the root key can stay out of use.
3. A leaf certificate belongs to one machine or person and is signed by an intermediate. It doesn’t sign other certificates.

To check a leaf, a program follows the signatures upward: the intermediate signed the leaf, the root signed the intermediate, and the root is trusted. If any step fails, the leaf is refused.

The chain: each certificate is signed by the one above it, and a check follows the signatures from the leaf, through the intermediate, up to the root.Swipe sideways to see the whole diagram →

Each controller in the course keeps its PKI in a folder: one root, its own intermediate, and two leaf certificates. It uses the server certificate when it’s the side that waits for a connection, and the client certificate when it’s the side that starts one. The course runs three controllers that work together as one cluster. When a new controller joins it, its setup uses the root certificate and the root key to issue the new controller’s own intermediate.

Why the root key stays locked away

Whoever holds the root’s private key can sign a certificate that every machine in the network trusts. The root can’t be replaced either, because every certificate chains up to the root certificate. The controller also needs the root key later, to renew the intermediate certificates. That is why OpenZiti’s backup guide says to back up the root.

In the course, the root key stays on the first controller, because new controllers need it to join. The Module 11 backup bundle includes it (pki/root/keys/root.key), so you keep that bundle where only your team can open it.

Production means the real network people depend on, not a lab. There, OpenZiti’s backup guide suggests a different layout: keep the root on a separate, protected host (a computer) and let the intermediates do the signing. The Module 11 lab adds that a production root lives offline.

Expiry and renewal

Every certificate has an end date. After it, programs refuse the certificate, even if nothing else has changed. Renewal means getting a fresh certificate before the old one ends.

• Routers try to extend their own certificates about a week before they expire, with no action from you. A router that stays offline past its expiry has to be enrolled again: set up from the start with a new one-time token so it can get a new certificate.
• Controller leaf certificates were valid for one year on the course’s controllers. The installer turns on a timer that issues new ones every month.
• The root and the intermediate last ten years and never renew on their own.
• Certificates from an outside CA that you register with OpenZiti have to be renewed by that CA’s owner, not by OpenZiti.

That’s why Module 11 ends with a certificate calendar: you read every controller certificate’s end date, then put the root and intermediate dates in your team’s calendar.

SAN: the names a certificate is valid for

A Subject Alternative Name (SAN) is a field that lists the names a certificate is valid for. These are DNS names (the names people type, which DNS turns into addresses), IP addresses (the numbers that identify a machine on a network) and web-style addresses called URIs, among others, and one certificate can list several.

A program that connects to a machine compares the name or address it used with that list. If there’s no match, it refuses the connection. In Module 4, a router in Meridian’s own data centre must list the private address it advertises (tells other machines to use). If that address is missing, the router fails when it starts.

Mutual TLS

TLS (Transport Layer Security) is the standard way two programs set up an encrypted connection. In ordinary TLS, as on most websites, only the server shows a certificate. In mutual TLS (mTLS), both sides present a certificate, and each checks the other’s chain. OpenZiti’s certificate management page says the controller, routers and clients use X.509 client and server certificates, and that routers and the controller always prove who they are with certificates.

Mutual TLS: both sides show a certificate, and each checks the other's chain.Swipe sideways to see the whole diagram →

Trust domain and SPIFFE ID

A trust domain is the name shared by everything one root CA vouches for. In Module 3 it’s meridian.ziti.

A SPIFFE ID is a standard name for a piece of software inside a trust domain, such as spiffe://meridian.ziti/controller/ctrl1. It’s stored in the certificate’s SAN as a URI. The controllers in a cluster use these IDs to recognise each other, so if one doesn’t match its controller’s name, the cluster won’t form.

Commands you’ll use in the course

OpenSSL is a widely used program for working with certificates, and it comes installed on Ubuntu. In its commands, -in names the certificate file, and -noout prints only what you asked for, not the whole encoded certificate.

The commands that start with sudo, and the systemctl one, run in a terminal on an Ubuntu controller or router that you reach over SSH, not in PowerShell on your workstation. sudo runs a command as the administrator, which these need because the certificate files are protected. The ziti edge commands run from your workstation.

Command	What it does
sudo openssl x509 -in <cert-file> -noout -enddate	Prints the date the certificate expires. The Module 11 calendar uses it.
sudo openssl x509 -in <cert-file> -noout -ext subjectAltName	Prints the certificate’s SAN list, with its addresses and its SPIFFE ID.
sudo openssl x509 -in <cert-file> -noout -text	Prints the whole certificate as readable text, including its validity dates.
openssl s_client -connect <router-address>:3022 -alpn ziti-link	Connects to a router’s port 3022 the way another router would, and shows the certificate the router presents. A port is the number that tells a machine which program a connection is for.
sudo ziti pki create client --pki-root <pki-folder> --ca-name intermediate --client-name <name> --client-file <file>	Makes a new client certificate and key, signed by the controller’s intermediate CA. The flags give the PKI folder, the signing CA, the name written in the certificate, and the file name.
systemctl list-timers ziti-controller-cert-renewal.timer	Shows when the controller’s automatic renewal last ran and when it runs next.
sudo tar -C /var/lib/ziti-controller -czf <bundle>.tgz pki	Packs the controller’s whole PKI folder, root key included, into one compressed file for the backup.
ziti edge create ca <name> <ca-cert.pem>	Registers an outside CA’s public certificate with OpenZiti. This is an optional exercise in Module 5.
ziti edge verify ca <name> --cert <verification.pem>	Proves you control that outside CA. OpenZiti gives you a code; you make a test certificate named with that code, sign it with the CA, and upload it with this command.