Trust & security model¶

localca deliberately makes one strong trade-off: it installs a certificate authority you control into your machine's trust stores. This page explains what that means, why it's safe when done this way, and where the boundaries are.

The problem it solves¶

A browser will not trust a certificate unless it chains to a CA already in its trust store. For a public website you get that from a public CA (Let's Encrypt et al.). For localhost and LAN IPs there is no public CA that will issue to you — and operating a publicly-trusted CA is out of reach for a small org. The mkcert insight: run a local CA, trusted only on your machine, and mint whatever local certs you need offline.

Per-machine root, never a shared key¶

Every install generates its own root key pair, stored under the data dir with the key file at 0600. localca never ships or generates a shared root.

This is the single most important rule. A CA root key that is bundled into a distributed binary — or otherwise shared between machines — is a universal man-in-the-middle key: anyone who extracts it can forge a trusted certificate for any site and intercept traffic for every user who trusts that root. So the root:

is generated locally, per machine;
never leaves the machine;
has a blast radius of exactly one machine;
has nothing central to revoke.

That is the mkcert trade-off, stated plainly: convenience and offline operation in exchange for a trust anchor that lives on your laptop and must be protected like any other private key.

Installing a root into the system trust store requires OS elevation — the macOS Keychain prompt, Windows UAC, or sudo on Linux. localca treats that prompt as the consent gate: it never installs a system-trusted root silently. The NSS (Firefox) path is user-level and needs no elevation, only certutil.

Every install is reversible: Authority.Uninstall removes the root from the trust stores, and Purge additionally deletes the stored key.

The system store is the anchor; NSS is best-effort¶

localca considers the root "trusted enough" to serve when the system store trusts it — that store is read by Chrome, Safari, Edge, and Go's own HTTP client. The NSS store (Firefox, some Chromium builds) is installed alongside when certutil is available, but it never gates provisioning: many hosts (headless servers, CI) have no certutil, and requiring it would break them. Firefox trust is therefore a bonus, not a prerequisite.

Short-lived, scoped leaves¶

Server certificates are minted short-lived (90 days by default) and scoped to exactly the hostnames/IPs you ask for — no long-lived wildcards. A leaf is re-minted when it nears expiry or when your host list changes.

What it is not¶

Not a public CA. The root is trusted only where you install it. It cannot and must not be used to issue certificates other people rely on.
Not detection of out-of-band changes. System-store membership is tracked in a marker file reflecting localca's own installs. If you remove the root through other means, re-run the install — the same idempotent, mkcert-style behaviour.
Not the whole story. This is Layer 1 of a two-layer strategy. A future public-ACME path (Layer 2) can issue publicly-trusted certs for real hostnames resolving to local IPs, with nothing installed — but it needs standing infrastructure, so the local CA remains the permanent offline / CI / air-gapped fallback.