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.

Who can read the root key¶

The root key is a 0600 file owned by the user who provisioned it, and that is the whole of its protection. Anything running as that user can read it: another program, a shell script, a compromised dependency in a build you run. localca does not put it in a keychain or behind a passphrase — why it is a file explains that choice.

The consequence to hold on to is that a local development CA moves the security boundary to "who can run code as me on this machine". If that boundary is already broken, the CA key is not the biggest problem — but it is a problem, and the answer is Uninstall and re-provision rather than anything cleverer.

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.

A leaf is never issued with a NotAfter beyond its root's: a certificate that outlives the CA that signs it produces a confusing chain-validation error in clients. As the root approaches the end of its ~10-year life, localca clamps each minted leaf to the root's expiry and logs a WARN ("root CA expiring soon … re-run Install") so an operator knows to renew the root before it lapses.

Durable writes¶

The root key and cert — and each cached leaf — are written atomically: localca writes to a temp file in the data dir, sets the file mode (0600 for keys), then renames it over the target. Because a rename is atomic on a single filesystem, a crash or power-loss mid-write can never leave a truncated key at the target. A reader always sees either the complete previous material or the complete new material — so an interrupted Install can't brick the local CA by half-writing its root key.

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.

The full list of what localca will not do — including the platforms where trust installation does not work at all — is in limitations.