Errors and log output¶

The sentinel errors you should handle¶

ErrElevationUnavailable¶

var ErrElevationUnavailable = errors.New(
    "localca: administrator privileges are required to install into the system trust " +
        "store, but no elevation is available (not root, and no interactive terminal to prompt)",
)

Returned when a system-store install needs administrator privileges that cannot be obtained: the process is not root, and either sudo is missing from PATH or standard input is not an interactive terminal.

It is the one error a consuming tool is expected to branch on, because it is not a fault. It is the environment telling you to take a different path. Match it with errors.Is; it survives the wrapping that Install applies:

if _, err := authority.Install(ctx); errors.Is(err, localca.ErrElevationUnavailable) {
    // Fall back: NSS only, an untrusted self-signed certificate, or tell the
    // user to run the install once from a terminal.
}

ErrRequestRefused¶

var ErrRequestRefused = errors.NewSentinel("localca.request_refused", "localca: request refused")

Every refusal from Private.SignClient wraps it: a client name, a CSR or a lifetime that the caller or the requesting machine got wrong. Its message says which, for example localca: request refused: the CSR's subject must be exactly CN="relay-1", got "CN=relay-2". Branch on it to tell a bad request (answer the machine with a refusal) from a failure of the CA itself (report it):

cert, err := ca.SignClient(ctx, csr, localca.ClientRequest{Name: machine})
if errors.Is(err, localca.ErrRequestRefused) {
    // The request was wrong; tell the machine. Nothing was signed or written.
}

Everything else localca returns is a fault to report, not a condition to branch on.

Every error localca produces itself¶

All are created with gitlab.com/phpboyscout/go/errors, so they carry a stack trace and unwrap normally. Errors from the standard library or the trust-store backend are wrapped with a short context prefix and passed through.

A leaf that fails to parse is not an error: it is treated as an empty cache and re-minted.

Wrapped errors and their prefixes¶

These prefixes tell you which step failed. The wrapped cause carries the detail.

installing root into trust store appears twice in a failed install: once from the trust-store backend and once from Authority.Install wrapping it. That is cosmetic; errors.Is and the underlying cause are unaffected.

What localca logs, and when¶

localca logs through an injected *slog.Logger. The default is a discard handler, so nothing is logged unless you pass WithLogger. That includes the expiry warning below, which is the only advance notice you get that your local CA is running out.

There are exactly two lines.

INFO: a root is about to be installed¶

installing a local development CA into the trust store so this tool can serve HTTPS
locally; reverse with Uninstall

Attribute: common_name, the root's Common Name.

Emitted by Install (including the Install that EnsureServed performs) only on the call that mints the root, immediately before the trust-store install and therefore immediately before any password prompt. It exists so a user who is suddenly asked for a password can see why. If you attach no logger, the prompt appears with no explanation.

Loading an existing root does not log it, so this line appears once in the life of a data directory.

WARN: the root CA is expiring¶

root CA expiring soon; leaf lifetime clamped to the root's. Renew it with
Uninstall(Purge()) and provision again

Attributes: common_name, and root_not_after, the root's expiry timestamp.

Emitted whenever a leaf has to be shortened because the requested LeafTTL would have run past the root's expiry. In practice that means the root has less than one leaf lifetime left: by default, less than 90 days. It repeats on every mint from then on, until the root expires; after that minting fails with the root CA expired at error instead.

The fix is to renew the root: Uninstall with Purge(), delete the cached leaf files, then provision again. See what Purge leaves behind.

A Private CA logs the same line, with the same attributes, whenever one of its server leaves or client certificates is shortened. For a client certificate the window is its lifetime: ClientTTL, 30 days by default, or the lifetime the request asked for. Its advice replaces Uninstall(Purge()):

root CA expiring soon; leaf lifetime clamped to the root's. Renew it with a fresh
root: stop the service, delete privateCA.pem and privateCA-key.pem, and enrol every
machine again

What is deliberately not logged¶

• The private key, and any part of it.
• The certificate contents. Only the Common Name and the root's expiry appear in log attributes.
• The trust-store commands and their output. sudo, certutil and security write their own messages to the terminal directly; localca does not capture or re-emit them, which is why a failing install can print output that does not appear in your structured logs.