Documentation
¶
Overview ¶
Package trust owns the Overcast local Certificate Authority: minting it, signing leaf server certificates from it (see ca.go), and installing the CA certificate into the operating system's trust store so browsers and HTTP clients accept Overcast's HTTPS without the usual self-signed-cert dance. `overcast trust install|uninstall|status` and `OVERCAST_TLS=auto` both hang off this package, and off the same key material.
The Store interface mirrors the shape of smallstep/truststore; the concrete backends shell out to each platform's own tooling (certutil, security, update-ca-certificates) so no extra dependency is needed.
Index ¶
- Constants
- Variables
- func DirFor(dataDir string) string
- func FetchRemoteCA(ctx context.Context, endpoint string) ([]byte, *x509.Certificate, error)
- func LoopbackEndpoint(endpoint string) (bool, error)
- func ParseCertificatePEM(pemBytes []byte) (*x509.Certificate, error)
- func RemoteDirFor(dataDir, endpoint string) string
- func SaveRemoteCA(dir string, certPEM []byte) error
- func ServerCertificate(dir string, sans []string) (tls.Certificate, *x509.CertPool, error)
- type CA
- type Store
Constants ¶
const ( // CACertFile is the CA certificate (public — safe to share and to // install into trust stores). CACertFile = "rootCA.pem" )
File names for the persisted key material. The rootCA* names deliberately match mkcert's, so users who have handled a local CA before recognise what they are looking at.
const CAPemPath = "/_overcast/ca.pem"
CAPemPath is the daemon endpoint serving the CA certificate (PEM, public half only). Registered in internal/router; fetched by FetchRemoteCA.
Variables ¶
var ErrUnsupported = errors.New("trust: no backend available on this platform")
ErrUnsupported is returned by New on platforms or build configurations that do not yet have a trust-store backend wired up.
Functions ¶
func FetchRemoteCA ¶
FetchRemoteCA fetches and validates the CA certificate of the daemon at endpoint (an origin such as "http://localhost:4566"). It returns the PEM exactly as served plus the parsed certificate.
A TLS-serving daemon (OVERCAST_TLS=auto — the very case this exists for) answers only https, while every doc and log line spells the endpoint http://; an http:// endpoint that fails is therefore retried once as https. TLS verification is skipped (see the file comment for why that is sound here); the payload validation below is the real gate.
func LoopbackEndpoint ¶
LoopbackEndpoint reports whether endpoint's host is a loopback name or address. Only literal loopback counts: a name that merely resolves to 127.0.0.1 (localhost.overcast.sh) is still a remote-controlled DNS answer, so it does not qualify for the silent path.
func ParseCertificatePEM ¶
func ParseCertificatePEM(pemBytes []byte) (*x509.Certificate, error)
ParseCertificatePEM parses the first CERTIFICATE block in pemBytes. Used by the /_overcast/ca.pem endpoint to refuse serving a corrupt file, and by the remote fetch to validate what a daemon handed back.
func RemoteDirFor ¶
RemoteDirFor returns the cache directory for a CA fetched from endpoint: <dataDir>/ca-remote/<host_port>. Deterministic, so uninstall/status find the same cache install used; scheme-agnostic, since http and https name the same daemon; and disjoint from DirFor's <dataDir>/ca, so a fetched CA can never be mistaken for (or overwrite) a locally-minted one.
func SaveRemoteCA ¶
SaveRemoteCA caches a fetched CA certificate under dir (see RemoteDirFor). Only the certificate is ever written — a remote CA has no key here.
func ServerCertificate ¶
ServerCertificate returns a TLS server certificate covering sans, signed by the CA in dir (created on first use), plus a pool containing that CA for clients that need to dial the resulting server.
The leaf is cached on disk next to the CA and reused across restarts; a new one is minted only when the cached leaf is missing, unreadable, no longer chains to the current CA, does not cover every requested SAN, or expires within leafRenewalMargin. Re-minting a leaf never touches the CA, so an installed trust-store entry stays valid.
Caching the leaf is best-effort, and deliberately so: dir may be a READ-ONLY mount. Sharing one CA with an ephemeral daemon means mounting the directory the host owns, and mounting it `:ro` is the correct way to do that — the container has no business rewriting the machine's trust anchor. A leaf is derived data worth about a millisecond of ECDSA, so failing to persist it costs a re-mint per restart, not a startup. Creating the CA itself stays fatal: that is the one thing here that is not reproducible.
Types ¶
type CA ¶
type CA struct {
// Cert is the CA certificate.
Cert *x509.Certificate
// CertPEM is the PEM encoding of Cert, ready to write into trust stores.
CertPEM []byte
// contains filtered or unexported fields
}
CA is a loaded local certificate authority.
func LoadOrCreateCA ¶
LoadOrCreateCA loads the CA from dir, creating (and persisting) a new one when none exists yet. Idempotent: repeat calls return the same CA.
type Store ¶
type Store interface {
// Install adds the CA certificate in the store's directory to the
// system trust store. The certificate must already exist — the CLI
// creates it via LoadOrCreateCA (local flow) or caches a fetched one
// via SaveRemoteCA (--endpoint flow). Installing an already-installed
// CA is a no-op.
Install(ctx context.Context) error
// Uninstall removes the local CA from the system trust store. The CA
// key material on disk is preserved so that a later Install can reuse
// it without invalidating previously-minted leaf certificates.
Uninstall(ctx context.Context) error
// Installed reports whether the local CA is currently present in the
// system trust store.
Installed(ctx context.Context) (bool, error)
}
Store manages a local Certificate Authority in the system trust store.
Implementations must be safe for concurrent use. All methods must be idempotent: installing an already-installed CA, or uninstalling one that was never installed, must succeed without error.
Source Files