Documentation

SSL certificate concepts

What each file in the certies store does, how the pieces fit together, and how a server uses them to authenticate clients.

The chain of trust

Every certificate in this system is either a CA certificate or signed by the CA. The CA signature is what makes a client certificate trustworthy: a server that holds the CA certificate can verify that a client certificate was issued by the same authority.

CA certificate (self-signed)
  |-- client certificate (alice/laptop)
  |-- client certificate (alice/phone)
  `-- client certificate (bob/desktop)

Files

ca/ca.key — CA private key

The CA private key signs every client certificate issued by the store. It is the most sensitive file: anyone who obtains it can issue certificates that your server will trust. It is stored with mode 0600 and should never leave the machine running certies.

ca/ca.crt — CA certificate

The CA certificate contains the CA public key and identity. This file is not secret and needs to be deployed to every server that will authenticate clients. It is what the server uses to verify that a presented client certificate was signed by your CA.

The CA certificate has a long validity period and must be replaced along with all client certificates if it expires or is compromised.

clients/<client>/<device>/<device>.key — client private key

The client private key stays on the client device. During the TLS handshake, it proves that the client holds the private key corresponding to the public key in its certificate. If a key password was set at issuance, the file is encrypted with AES-256-CBC.

clients/<client>/<device>/<device>.crt — client certificate

The client certificate is signed by the CA and contains the client public key, identity, validity window, serial number, usage extensions, and the CA signature over those fields.

During a TLS handshake, the client presents this certificate to the server. The server checks the CA signature, verifies the serial is not in the CRL, and checks that the certificate has not expired.

clients/<client>/<device>/<device>.p12 — PKCS#12 bundle

The PKCS#12 bundle packages the client private key, client certificate, and CA certificate chain into one encrypted file. This is the file commonly imported into operating systems, browsers, VPN clients, and other software that supports client certificates.

crl/crl.pem — Certificate Revocation List

The CRL is a signed list of certificate serial numbers revoked before their expiry date. Servers that check the CRL reject any client certificate whose serial appears in it, even if the certificate itself is still within its validity window.

The CRL has its own validity window and must be regenerated or redeployed before it expires. certies regenerates it automatically whenever a certificate is revoked.

How client authentication works

  1. The server is configured with ca.crt as its trusted CA and crl.pem as its revocation list.
  2. The client is provisioned with its .p12 bundle, or with separate .key and .crt files.
  3. The client presents its certificate during the TLS handshake.
  4. The server verifies the CA signature, expiry date, revocation status, and client-auth usage.
  5. The client proves ownership of the corresponding private key by signing handshake data.

If all checks pass, the server knows the client was explicitly issued a certificate by this CA and has not been revoked.

Revoking access

Deleting a certificate file does not revoke it. The client may still hold a copy, and the server has no way to know the file was deleted. To cut off access, run:

certies revoke <client> <device>

This adds the certificate serial to the revocation database and regenerates crl.pem. Deploy the updated CRL to the server so it rejects the revoked certificate on the next connection attempt.