TLS and CA trust

Every middleware instance serves HTTPS with a certificate issued, and renewed automatically, by the Kiwi Vault PKI from a single root CA. Workers and clients trust that CA directly rather than the system certificate store.

Pinning the CA#

Set middleware_ca_url to the middleware's plain-HTTP CA endpoint (for example http://mw:8080/ca/cert). On first use the SDK:

1. Fetches the PEM over plain HTTP. It can contain a chain, so every -----BEGIN CERTIFICATE----- block is accepted.
2. Caches it (trust on first use) under ~/.kiwi/ca/<host>_<port>.pem. The CLI keeps its own cache under %LOCALAPPDATA%\kiwi\ca\ on Windows.
3. Uses it as the only trusted root for HTTPS to middleware_url, with full validation and subject alternative name checks.

If a later fetch fails but a healthy cache exists, the cache is used. A stale cache after the middleware's CA has been rotated must be deleted by the operator.

Strict certificate validation#

The Vault PKI issues RFC 5280-conformant certificates with subject and authority key identifiers on every certificate in the chain, so strict validators accept the chain unmodified. This matters for Python 3.13 and later, whose default context is strict. A middleware built against an older Vault PKI that serves certificates without an authority key identifier fails Python 3.13 and openssl -x509_strict; use a middleware build that includes the fix.

Development shortcuts#

ignore_ssl=true skips verification entirely. Use it only on a developer machine, never in production.

Load balancers#

For TLS-sensitive clients, use a layer-4 (TCP) pass-through listener so the TLS session ends at a middleware instance and the Vault certificate chain is preserved end to end. Serve the CA endpoint over plain HTTP separately.