localca

package module
v0.3.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 13, 2026 License: MIT Imports: 32 Imported by: 0

README

localca

A framework-free, mkcert-style local development CA for Go: generate a per-machine root, install it into the OS and browser trust stores, and mint browser-trusted HTTPS certs with no manual setup

Go Reference Pipeline Coverage phpboyscout Go toolkit

Part of the phpboyscout Go toolkit — small, framework-free Go modules for the phpboyscout tool family. Docs: localca.go.phpboyscout.uk


gitlab.com/phpboyscout/go/localca lets a Go tool serve browser-trusted HTTPS on localhost and LAN IPs with no certificate fuss. On first run it generates a per-machine ECDSA root CA, installs it into the host's system and NSS (Firefox/ Chromium) trust stores, and mints short-lived leaf certificates, surfaced as a go/tls.Pair so any transport serves the trusted cert unchanged.

It is Layer 1 of a two-layer TLS strategy for the phpboyscout tool family: a per-machine local CA that works offline forever. The public ACME path (Layer 2) is a separate concern; this module stays the offline / CI / air-gapped fallback.

Design

  • Framework-free. Works from a typed Config, an injected afero.Fs for storage, and an optional *slog.Logger. No config framework, no TUI, no OpenTelemetry, no go-tool-base. A depfootprint_test.go guard enforces it.
  • One-liner first run. EnsureServed ensures the root exists and is trusted, then returns a servable go/tls.Pair. Idempotent: an already-trusted root re-prompts nothing and a still-valid leaf is reused.
  • Cross-OS trust, as a library. The trust-store install uses smallstep/truststore (mkcert's logic), behind an injectable TrustStore seam so the crypto core is fully testable without a real store.

Security

The root's private key never leaves the machine and is stored 0600. A shared or shipped CA key would be a universal MITM key against every user, so one is never generated or bundled; every install mints its own root. Installing a system-trusted root requires an OS elevation prompt (the consent gate), and it is reversible via Authority.Uninstall.

Key and cert material is written atomically (temp file + rename), so a crash mid-write can't truncate the root key and brick the CA. Leaves are never issued past the root's expiry. Near the root's end of life each leaf is clamped to it and a WARN is logged so you renew the root in time; once the root has expired, minting a leaf fails with an error naming the root's NotAfter.

Install

go get gitlab.com/phpboyscout/go/localca

Quick start

package main

import (
	"context"
	"net/http"

	"gitlab.com/phpboyscout/go/localca"
)

func main() {
	cfg := localca.Config{DataDir: "/home/me/.myapp", AppName: "myapp"}

	// First run installs the local root (one OS prompt); later runs are silent.
	pair, err := localca.EnsureServed(context.Background(), cfg, []string{"localhost", "127.0.0.1"})
	if err != nil {
		panic(err)
	}

	tlsCfg, err := pair.ServerConfig() // go/tls hardened config with the leaf loaded
	if err != nil {
		panic(err)
	}

	srv := &http.Server{Addr: ":8443", TLSConfig: tlsCfg}
	_ = srv.ListenAndServeTLS("", "")
}

Key concepts

  • Authority: a per-machine CA. Install / Uninstall the root into trust stores, Installed to report where it's trusted, Leaf to mint a server cert.
  • Private: a second kind of CA, from NewPrivate, that is never installed. A service runs one for mutual TLS: it serves the service's TLS, signs machines' CSRs as client-only certificates (SignClient), and exposes its root as a Root with a pool and fingerprint. Only a Private signs CSRs.
  • EnsureServed: the first-run one-liner, ensure + install + mint + persist, returning a go/tls.Pair.
  • Config: typed and module-owned, with DataDir, AppName, Organization, and overridable RootTTL (~10y) / LeafTTL (90d), plus a Private CA's ClientTTL (30d) / MaxClientTTL (90d).
  • TrustStore: the cross-OS install seam (default: smallstep/truststore); inject a fake in tests.

Documentation

localca.go.phpboyscout.uk has a tutorial, how-to guides, a reference tier covering every config field, file, platform and error, and the trust/security model. Start with limitations if you need to know what it will not do.

API signatures: pkg.go.dev.

License

See LICENSE.

Documentation

Overview

Package localca is a framework-free, mkcert-style local development certificate authority for Go tools. On first run it generates a per-machine ECDSA root CA, installs it into the host's system and NSS (Firefox/Chromium) trust stores, and mints short-lived leaf certificates for local hosts (localhost, 127.0.0.1, ::1, and LAN IPs) so a tool can serve browser-trusted HTTPS with zero manual setup.

The leaf is surfaced as a gitlab.com/phpboyscout/go/tls.Pair, so any transport that already consumes the shared TLS plumbing serves the trusted certificate unchanged. EnsureServed is the one-liner: ensure the root exists and is trusted, then return a ready-to-serve Pair.

The package is framework-free: it works from a typed Config, an injected github.com/spf13/afero.Fs for storage, and an optional *log/slog.Logger. The cross-OS trust-store install sits behind the TrustStore seam so the pure-crypto core is fully testable without touching a real trust store.

This is Layer 1 of a two-layer TLS strategy for the phpboyscout tool family: a per-machine local CA that works offline forever. The public ACME path (Layer 2) is a separate, downstream concern; this module remains the offline/CI/air-gapped fallback even once Layer 2 exists.

Security

The root's private key never leaves the machine and is stored 0600. A shared or shipped CA key is a universal MITM key against every user and is never generated or bundled — every install mints its own root. Installing a system-trusted root requires OS elevation; that prompt is the consent gate, and the install is reversible via Authority.Uninstall.

Index

Examples

Constants

This section is empty.

Variables

View Source
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)",
)

ErrElevationUnavailable is returned when installing into the system trust store needs administrator privileges but none can be obtained interactively: the process is not root and there is no terminal (or no sudo) to prompt with. A consumer catches this to fall back — e.g. keryx drops to an untrusted self-signed cert (spec 0027 §5.4) — rather than hanging on a prompt that can never be answered.

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

ErrRequestRefused marks every refusal of a SignClient request: a name, CSR or lifetime the caller or the requesting machine got wrong, as distinct from a failure of the CA itself.

Functions

func EnsureServed

func EnsureServed(ctx context.Context, cfg Config, hosts []string, opts ...Option) (gotls.Pair, error)

EnsureServed is the first-run one-liner: ensure the root exists and is trusted in every supported store, mint (or reuse a cached) leaf for hosts, persist it, and return a go/tls.Pair ready for any transport's ServerConfig. Idempotent: a second call with a still-installed root and a still-valid cached leaf re-prompts nothing and re-mints nothing.

Example

ExampleEnsureServed shows the first-run one-liner: provision a per-machine local CA (installing it into the trust store on first run) and serve browser-trusted HTTPS. It compiles as documentation; it is not executed (it would mutate the host trust store).

package main

import (
	"context"
	"log"
	"net/http"

	"gitlab.com/phpboyscout/go/localca"
)

func main() {
	cfg := localca.Config{DataDir: "/home/me/.myapp", AppName: "myapp"}

	pair, err := localca.EnsureServed(context.Background(), cfg, []string{"localhost", "127.0.0.1"})
	if err != nil {
		log.Fatal(err)
	}

	tlsCfg, err := pair.ServerConfig()
	if err != nil {
		log.Fatal(err)
	}

	srv := &http.Server{Addr: ":8443", TLSConfig: tlsCfg}
	log.Fatal(srv.ListenAndServeTLS("", ""))
}

Types

type Authority

type Authority interface {
	// Installed reports where the root is currently trusted.
	Installed(ctx context.Context) (TrustState, error)

	// Install mints the root if absent and installs it into the given trust stores
	// (all supported when none are given). Installing into the system store triggers
	// the OS elevation prompt.
	Install(ctx context.Context, stores ...Store) (TrustState, error)

	// Uninstall removes the root from trust stores; with Purge it also deletes the
	// stored key and cert.
	Uninstall(ctx context.Context, opts ...UninstallOption) error

	// Leaf returns a short-lived server certificate valid for hosts, signed by the
	// root. It does not install the root; it errors if no root exists yet (use
	// EnsureServed for the mint-and-install path).
	Leaf(ctx context.Context, hosts ...string) (*cryptotls.Certificate, error)
}

Authority is a per-machine local CA that can install itself into the host's trust stores and issue leaf certificates for local hosts.

func New

func New(cfg Config, opts ...Option) (Authority, error)

New constructs an Authority from typed config and injected dependencies. DataDir is required.

type ClientCert added in v0.3.0

type ClientCert struct {
	DER         []byte
	PEM         []byte
	Fingerprint [sha256.Size]byte // SHA-256 of the DER, what a caller pins
	NotAfter    time.Time
	Clamped     bool // NotAfter was cut to the root's expiry
}

ClientCert is a signed client certificate.

type ClientRequest added in v0.3.0

type ClientRequest struct {
	// Name must equal the CSR's CommonName, and is the certificate's only
	// subject attribute: 1 to 64 bytes of UTF-8, no control characters.
	Name string

	// TTL is the lifetime. Zero uses Config.ClientTTL; outside one hour to
	// Config.MaxClientTTL is refused.
	TTL time.Duration
}

ClientRequest is what the caller has decided about a client certificate.

type Config

type Config struct {
	// DataDir is where the root key/cert and cached leaves live. Required. The key
	// files are written 0600. Must be a stable per-machine location.
	DataDir string

	// AppName seeds the root CommonName ("<AppName> local CA (<user>@<host>)") so an
	// installed root is self-evidently a per-machine dev identity. Defaults to "local".
	AppName string

	// Organization seeds the root subject Organization. Defaults to AppName.
	Organization string

	// RootTTL is the root CA validity. Zero uses defaultRootTTL (~10 years).
	RootTTL time.Duration

	// LeafTTL is the issued leaf validity. Zero uses defaultLeafTTL (90 days).
	LeafTTL time.Duration

	// ClientTTL is a Private CA's client certificate lifetime when a request
	// names none. Zero uses 30 days. An Authority ignores it.
	ClientTTL time.Duration

	// MaxClientTTL is the longest client certificate lifetime a request to a
	// Private CA may ask for; a longer one is refused. Zero uses 90 days. An
	// Authority ignores it.
	MaxClientTTL time.Duration
}

Config is the typed configuration for an Authority. It is owned by this module and carries no framework coupling: a GTB consumer decodes its own config section into this struct in its adapter; a standalone consumer fills it directly.

type Option

type Option func(*options)

Option injects the runtime environment. All options are optional and nil-safe.

func WithClock

func WithClock(now func() time.Time) Option

WithClock overrides the time source for deterministic tests.

func WithFS

func WithFS(fs afero.Fs) Option

WithFS overrides the filesystem used for key/cert storage (default: OS fs). First-run provisioning is serialised across processes only on the OS fs.

func WithLogger

func WithLogger(l *slog.Logger) Option

WithLogger attaches a structured logger. Nil is ignored (logging stays silent).

func WithTrustStore

func WithTrustStore(ts TrustStore) Option

WithTrustStore swaps the cross-OS trust-store backend — the seam that keeps the crypto core testable without touching a real store.

type Private added in v0.3.0

type Private interface {
	// Root returns the CA's root, minting it on first use.
	Root(ctx context.Context) (Root, error)

	// Leaf returns a short-lived server certificate valid for hosts, signed by
	// the root. It is not cached; call it again to renew.
	Leaf(ctx context.Context, hosts ...string) (*cryptotls.Certificate, error)

	// SignClient signs a client certificate for the key in csrDER. The CSR must
	// prove possession of its key and name exactly req.Name; it contributes
	// nothing else. Every refusal is ErrRequestRefused.
	SignClient(ctx context.Context, csrDER []byte, req ClientRequest) (ClientCert, error)
}

Private is a CA that is never installed in a trust store. It serves its owner's TLS and signs the client certificates of machines the owner enrols, for mutual TLS (spec 0003). Only a Private signs CSRs.

func NewPrivate added in v0.3.0

func NewPrivate(cfg Config, opts ...Option) (Private, error)

NewPrivate constructs a Private CA over cfg.DataDir, minting its root on first use. It refuses a DataDir that holds an Authority's root, and a ClientTTL above MaxClientTTL. WithTrustStore has no effect on it.

Example

ExampleNewPrivate shows a service running a private CA for mutual TLS: serving its own TLS from the CA, requiring client certificates from it, and signing a machine's CSR. It compiles as documentation; it is not executed.

package main

import (
	"context"
	"crypto/tls"
	"errors"
	"log"

	"gitlab.com/phpboyscout/go/localca"
)

func main() {
	ctx := context.Background()

	ca, err := localca.NewPrivate(localca.Config{DataDir: "/var/lib/collector/ca", AppName: "collector"})
	if err != nil {
		log.Fatal(err)
	}

	root, err := ca.Root(ctx)
	if err != nil {
		log.Fatal(err)
	}

	leaf, err := ca.Leaf(ctx, "collector.internal", "10.0.0.5")
	if err != nil {
		log.Fatal(err)
	}

	tlsCfg := &tls.Config{
		Certificates: []tls.Certificate{*leaf},
		ClientCAs:    root.Pool(),
		ClientAuth:   tls.RequireAndVerifyClientCert,
		MinVersion:   tls.VersionTLS13,
	}

	// csrDER arrives from a machine the service has already decided may enrol.
	var csrDER []byte

	cert, err := ca.SignClient(ctx, csrDER, localca.ClientRequest{Name: "relay-1"})
	if errors.Is(err, localca.ErrRequestRefused) {
		log.Printf("refused: %v", err)

		return
	}

	// Send the machine cert.PEM and root.PEM, and record cert.Fingerprint.
	_ = cert
	_ = tlsCfg
}

type Root added in v0.3.0

type Root struct {
	Cert        *x509.Certificate
	PEM         []byte
	Fingerprint [sha256.Size]byte // SHA-256 of the DER
}

Root is a Private CA's root certificate, in the forms a server and its clients need.

func (Root) Pool added in v0.3.0

func (r Root) Pool() *x509.CertPool

Pool returns a pool holding only this root, for tls.Config ClientCAs or RootCAs.

type Store

type Store int

Store identifies a trust store the root can be installed into.

const (
	// StoreSystem is the OS system trust store (macOS Keychain, Linux
	// ca-certificates, Windows CryptoAPI). Installing here needs OS elevation.
	StoreSystem Store = iota
	// StoreNSS is the shared NSS database used by Firefox and Chromium. Install is
	// user-level but needs the platform certutil.
	StoreNSS
)

type TrustState

type TrustState struct {
	System bool
	NSS    bool
}

TrustState reports where the root is currently trusted.

type TrustStore

type TrustStore interface {
	// Install adds the root to the given stores (all supported when none are given)
	// and returns the resulting state.
	Install(root *x509.Certificate, stores ...Store) (TrustState, error)
	// Uninstall removes the root from the given stores (all when none are given).
	Uninstall(root *x509.Certificate, stores ...Store) error
	// State reports where the root is currently trusted.
	State(root *x509.Certificate) (TrustState, error)
}

TrustStore is the cross-OS trust-store backend seam. The default implementation wraps github.com/smallstep/truststore (mkcert's logic); tests inject a fake so the crypto core needs no real store. Implementations act on the root's public certificate only — a trust store never holds the private key.

type UninstallOption

type UninstallOption func(*uninstallOpts)

UninstallOption tunes Authority.Uninstall.

func Purge

func Purge() UninstallOption

Purge deletes the stored root key/cert after removing it from trust stores.

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL