pki

Documentation

Overview

Package pki generates and loads the private certificate authority used to secure agent<->server gRPC connections (see docs/adr/0005-remote-agent-transport-and-registration.md). This is deliberately not a public CA (Let's Encrypt etc.) — that's a separate, out-of-scope concern reserved for the web dashboard. Boxy mints its own CA so agent<->server traffic gets real TLS encryption and full mutual authentication without depending on any external certificate authority.

This package is public (moved from internal/pki, see issue #138): it is stdlib-only with zero dependencies on the rest of boxy, so it's a clean seam for reuse outside this module. Its API is not yet stable — boxy is prerelease and this package may still change shape without notice.

Index

• func IssueAgentCert(ca *CA, agentID string) (certPEM, keyPEM []byte, serial string, err error)
• type CA
  • func EnsureCA(dir string) (*CA, error)
• type ServerCert
  • func IssueServerCert(ca *CA, dir string, sans []string) (*ServerCert, error)

Functions

func IssueAgentCert

func IssueAgentCert(ca *CA, agentID string) (certPEM, keyPEM []byte, serial string, err error)

IssueAgentCert mints a fresh client certificate for a newly registered agent, signed by ca. Unlike EnsureCA/IssueServerCert, this is never written to disk server-side: the private key is generated ephemerally, returned once (over the already-authenticated registration stream) for the agent to persist on its own host, and the server retains only the serial number (for future revocation, see pkg/store's RevokedAgentIdentity) — never the agent's private key.

Types

type CA

type CA struct {
	Cert    *x509.Certificate
	Key     *ecdsa.PrivateKey
	CertPEM []byte
}

CA is boxy's private certificate authority: a self-signed root used to sign the server's leaf certificate and every agent's client certificate.

func EnsureCA

func EnsureCA(dir string) (*CA, error)

EnsureCA loads dir/ca.crt and dir/ca.key if both are present, or generates a new self-signed CA and writes them if not. Safe to call on every `boxy serve` startup.

type ServerCert

type ServerCert struct {
	CertPEM []byte
	KeyPEM  []byte
}

ServerCert is the gRPC listener's leaf certificate, signed by the CA.

func IssueServerCert

func IssueServerCert(ca *CA, dir string, sans []string) (*ServerCert, error)

IssueServerCert loads dir/server.crt and dir/server.key if both are present and their SANs already match sans (compared as an order-independent set of DNS names/IPs), or (re)issues a new leaf certificate — signed by ca, valid for sans — and writes/overwrites both files otherwise. This means changing the configured SANs (e.g. via a new --grpc-cert-san / server.grpc_cert_sans entry) takes effect automatically on the next call — no manual deletion required. dir/server.crt and dir/server.key are entirely boxy-managed (see docs/adr/0005-remote-agent-transport-and-registration.md); if the existing cert can't be parsed, IssueServerCert fails rather than silently overwriting it — delete both files by hand and call again to recover.