Reference¶

Exact, lookup-oriented detail: what every configuration field means, what it defaults to, what happens when it is wrong, what ends up on disk, which platforms work, and what each entry point does.

• Configuration and options — every Config field and every Option, with defaults and invalid-value behaviour.
• Data directory layout — the files localca writes, their permissions, and which call creates or deletes each one.
• Platform support — which trust stores work on which OS, what each install needs, and what happens where it does not work.
• Errors and log output — every error localca returns and every line it logs.

Function signatures and type definitions are on pkg.go.dev and are not repeated here. This tier documents behaviour — the things a signature does not tell you.

What each entry point does¶

localca has one package-level function and one interface with four methods.

EnsureServed(ctx, cfg, hosts, opts...)¶

The first-run one-liner. In order it:

1. rejects an empty hosts slice with localca: EnsureServed needs at least one host;
2. constructs an Authority (so an empty Config.DataDir fails here);
3. loads the stored root, or mints and persists a new one;
4. asks the trust-store backend for the current TrustState, and calls Install only if that lookup errored or the system store is not trusted — this is what stops a password prompt appearing on every run;
5. reuses the cached leaf if it covers every requested host and is more than seven days from expiry, otherwise mints and persists a new one;
6. returns a go/tls.Pair with Enabled: true and Cert/Key set to the leaf paths under DataDir.

The returned Pair is file-backed. Pair.ServerConfig() reads those two files when you call it, so the files must still exist when the server starts.

Authority.Install(ctx, stores...)¶

Mints the root if there is none, then installs it. With no stores argument it targets both StoreSystem and StoreNSS. Unlike EnsureServed it does not check the current state first — calling it always runs the install, and therefore always runs the elevation pre-flight when StoreSystem is in the list.

It returns the resulting TrustState. On the call that mints the root it logs one INFO line before prompting; see errors and log output.

Authority.Installed(ctx)¶

Returns where the root is currently trusted. It errors with localca: no root CA provisioned (call Install or EnsureServed first) when no root has been stored yet — it never mints one.

Authority.Leaf(ctx, hosts...)¶

Mints a fresh in-memory *crypto/tls.Certificate for hosts and returns it. It errors if no root exists. Three things it deliberately does not do: install the root, write anything to disk, or consult the cached leaf. Every call mints a new certificate with a new key. Use it when you want a certificate for something other than the cached serving pair; use EnsureServed for the serving path.

Authority.Uninstall(ctx, opts...)¶

Removes the root from all stores — the store list is not configurable on this call, so it runs the elevation pre-flight even if you only ever installed into NSS. If no root is stored a bare Uninstall(ctx) returns nil without touching anything. Pass Purge() to also delete the stored root certificate and key — that deletion is attempted whether or not a root was found, and files that are already absent are not an error.

TrustState¶

type TrustState struct {
    System bool
    NSS    bool
}

System reflects the marker file localca writes for its own installs, not a live query of the OS store — see data directory layout. NSS is queried live with certutil and is false whenever certutil or an NSS profile is missing.

localca treats the root as trusted enough to serve when System is true. NSS never gates anything; see why NSS is best-effort.

Store¶

const (
    StoreSystem Store = iota // OS trust store — needs elevation
    StoreNSS                 // Firefox/Chromium NSS databases — needs certutil
)

Passing no Store values to Install means both. There is no value for "none"; to install nowhere, do not call Install.