Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Generating TLS Certificates

By default Zizq uses plain HTTP. HTTPS and Mutual TLS can be enabled by providing the applicable certificates and keys. If you have a server certificate from a public certificate authority (CA) such as DigiCert, or Let’s Encrypt this should just work. In many cases you may prefer generate and use your own CA in order to secure the Zizq API. The zizq CLI provides utilities to facilitate certificate generation, both for the server and for client use with mTLS. This is packaged up under zizq tls, which is structured in terms of subcommands.

See zizq tls --help for a full list of options.

What You Will Need

TLS is inherently bound to hostnames. You will need to know the hostname through which the Zizq API will be accessed in order to generate a valid certificate.

Client certificates are more straightforward and are named arbitrarily.

Once you have generated server certificates, there are three necessary files:

  1. The CA certificate (the authority that signs and verifies the certificates).
  2. The server certificate file.
  3. The private key for the server certificate.

If any of these are missing, TLS will not function correctly.

For generated client certificates you need the equivalent:

  1. The CA certificate.
  2. The client certificate file(s).
  3. The private key(s) for the client certificate(s).

The opposite side needs to know the CA in order to verify certificates. For example, clients need a copy of the CA used by the server in order to verify the server certificate, and the server needs a copy of the CA used by all clients in order to verify client certificates. These certificate authorities can, and often are, the same for both sides.

Using zizq tls init

The init subcommand is able to generate a CA, a server certificate and one or more client certificates in a single command. See zizq tls init --help.

Specify --out-dir to have the certificates written to a specific output directory. The default is {root-dir}/tls.

Multiple hostnames can be provided by providing --san more than once. Multiple client certificates can be generated by providing --client more than once. There is generally no need to generate a different certificate per client, however (clients that are all logically the same can share the same client certificate).

Certificate expiry can be specified by providing --days N. The defaul is 365 days.

All server and client certificates will share the same CA.

zizq tls init \
    --out-dir certs \
    --san localhost \
    --san zizq.internal \
    --client worker

Generating CA (Zizq CA):
  wrote: certs/ca-cert.pem
  wrote: certs/ca-key.pem
Generating server certificate (SANs: localhost, zizq.internal):
  wrote: certs/server-cert.pem
  wrote: certs/server-key.pem
Generating client certificate (worker):
  wrote: certs/client-worker-cert.pem
  wrote: certs/client-worker-key.pem

The common name for the certificate authority can be changed by providing --cn.

Once certificates have been generated, you will likely want to copy those somewhere stable.

Configuring the Server for TLS

The server can be configured to use TLS with the generated certificates by providing --tls-cert and --tls-key.

zizq serve --tls-cert certs/server-cert.pem --tls-key certs/server-key.pem

...
2026-04-07T04:53:43.404716Z  INFO zizq::commands::serve: primary API listening addr=127.0.0.1:7890 scheme=https
...

The CA will need to be provided to any clients that want to connect with the server in order, otherwise verification will fail. With curl this is done with the --cacert flag.

curl -i --cacert certs/ca-cert.pem  https://zizq.internal:7890/health

HTTP/2 200
content-type: application/json
content-length: 15
date: Tue, 07 Apr 2026 04:55:35 GMT

{"status":"ok"}

Configuring the Server for Mutual TLS

Note

Mutual TLS support requires a pro license.

In order for the server to use Mutual TLS, it needs to know the CA for the certificates clients will present. This is configured with the --tls-client-ca argument.

zizq serve \
    --license-key @license.jwt \
    --tls-cert certs/server-cert.pem \
    --tls-key certs/server-key.pem \
    --tls-client-ca certs/ca-cert.pem

Client then need to be configured to present their client certificates and use the matching key. In curl this is done with --cert and --key.

curl -i \
    --cacert certs/ca-cert.pem  \
    --cert certs/client-worker-cert.pem \
    --key certs/client-worker-key.pem \
    https://zizq.internal:7890/health

HTTP/2 200
content-type: application/json
content-length: 15
date: Tue, 07 Apr 2026 05:04:53 GMT

{"status":"ok"}

Generating Additional Certificates

Running zizq tls init more than once with the same --out-dir will not overwrite existing files by default. This can be done, for example, to generate an additional client certificate using the existing CA.

zizq tls init --out-dir certs --client new-worker

CA already exists, reusing:
  skip: certs/ca-cert.pem (already exists)
  skip: certs/ca-key.pem (already exists)
Generating server certificate (SANs: localhost):
  skip: certs/server-cert.pem (already exists)
  skip: certs/server-key.pem (already exists)
Generating client certificate (new-worker):
  wrote: certs/client-new-worker-cert.pem
  wrote: certs/client-new-worker-key.pem

Using zizq tls ca

If you want to generate a CA separately, use zizq tls ca. See zizq tls ca --help.

zizq tls ca --out-dir certs

Generating CA (Zizq CA):
  wrote: certs/ca-cert.pem
  wrote: certs/ca-key.pem

This CA can be explicitly provided to zizq tls server-cert or zizq tls client-cert.

Using zizq tls server-cert

To generate a new server certificate (e.g. to use a different hostname/SAN), use zizq tls server-cert. See zizq tls server-cert --help.

This commands requires --ca-cert and --ca-key and accepts one or more --san names.

zizq tls server-cert \
    --out-dir certs \
    --ca-cert certs/ca-cert.pem \
    --ca-key certs/ca-key.pem \
    --san localhost \
    --san zizq.new.internal

Generating server certificate (SANs: localhost, zizq.new.internal):
  wrote: certs/server-cert.pem
  wrote: certs/server-key.pem

Using zizq tls client-cert

To generate a new client certificate, use zizq tls client-cert. See zizq tls client-cert --help.

This command requires --ca-cert, --ca-key and the client name.

zizq tls client-cert \
    --out-dir certs \
    --ca-cert certs/ca-cert.pem \
    --ca-key certs/ca-key.pem \
    --name external-worker

Generating client certificate (external-worker):
  wrote: certs/client-external-worker-cert.pem
  wrote: certs/client-external-worker-key.pem