Certs

kabactl always serves its API over HTTPS. It generates everything it needs on first run, so there is nothing to set up for a single machine. This page explains what gets created and how to replace it.

The API certificate

On first start, and whenever the files are missing, kabactl generates a self-signed certificate and private key:

File	Contents
<storage>/certs/kaba.cert	PEM certificate
<storage>/certs/kaba.key	PEM private key

The paths are recorded in config.toml as cert_path and key_path.

Field	Value
Subject	CN=kaba local, O=kabalabs
Subject alternative names	localhost, kaba.local, 127.0.0.1, ::1
Type	Self-signed, marked as a CA
Key usage	certificate signing, digital signature, key encipherment

Because the names are all local, the generated certificate is only valid for connections to the same machine. Devices in a cluster do not use it to reach each other; they talk over the mesh, which has its own keys.

Regeneration

config.toml carries a cert_format_version. When it is lower than the version the binary expects, or when either file is missing, both are regenerated at start and the version is updated. There is no scheduled rotation in kabactl 0.87. To rotate by hand, stop the server, delete both files and start it again.

Permissions

kabactl doctor warns when the key is readable by group or others:

chmod 600 ~/.config/kaba/certs/kaba.key

How the client trusts it

The client does not disable certificate checks to reach its own engine. At start it waits for certs/kaba.cert to appear, then builds certs/trust-bundle.pem from:

1. the local kaba.cert, and
2. any certificates you place in certs/trusted/.

Requests from the client to the engine are verified against that bundle. To let the client talk to an engine that presents a different certificate, drop the certificate into certs/trusted/ and restart the client.

For any other tool, either trust the certificate explicitly or skip verification for a quick local check:

curl --cacert ~/.config/kaba/certs/kaba.cert https://localhost:28832/health
curl -k https://localhost:28832/health

Using your own certificate

Point cert_path and key_path at a PEM certificate and key, or overwrite the two generated files, then restart. The certificate must be valid for whatever host name your clients use.

On Kubernetes the Helm chart can mount a certificate from cert-manager or from an existing Secret into the same paths. See kubernetes.

Caution

If you replace the files but leave cert_format_version lower than the binary expects, they will be regenerated. A config written by kabactl already has the current version, so this only matters for hand-written configs: set cert_format_version = 1.

Other keys kabactl creates

File or value	Purpose
<storage>/node.key	This node’s mesh identity. The node ID that peers see is derived from it. Deleting it makes the node look like a brand-new device.
<storage>/outbound_keys.toml	Credentials this node uses when it calls each peer.
<storage>/node-account.toml	Written when a node joins a cluster.
jwt_secret in config.toml	Signs session tokens and off-box proxy credentials.
Per-account encryption key	Derived from the account password; protects memories and saved logins. See security.

Back up node.key and config.toml if you want a reinstalled node to keep its identity.

Site certificate errors in the browser

Certificates of the websites you visit are a separate matter, handled by the client. When a site’s certificate fails, Kaba shows an error page where you can go back or, for sites you trust, accept the certificate for the session or permanently. Accepted exceptions can be revoked.

[todo: add screenshot of the certificate error page and of parts certificate details, go back, accept for session, accept permanently.]