Documentation
¶
Overview ¶
Package certs owns the agent's TLS material on disk: creating or loading a local CA on first start, issuing the server certificate and per-device client certificates from it, and reporting when the configured addresses have drifted away from what the server certificate covers.
Nothing in this package ever logs key material, PEM bytes, or a file's contents — only SANs, serials, and expiry.
Index ¶
- Variables
- func CheckIdentityConsistency(certsDir string, dbExisted bool) error
- func LoadOrCreateServerCert(dir string, sans []string, ca *CA, log *slog.Logger) (tls.Certificate, error)
- type CA
- func (c *CA) CertPEM() []byte
- func (c *CA) Fingerprint() string
- func (c *CA) IssueDeviceCert(csrDER []byte, commonName string, now time.Time) (certPEM []byte, serial string, notAfter time.Time, err error)
- func (c *CA) IssueServerCert(sans []string, now time.Time) (certPEM, keyPEM []byte, err error)
- func (c *CA) Pool() *x509.CertPool
Constants ¶
This section is empty.
Variables ¶
var ErrIdentityIncomplete = errors.New("agent identity is incomplete")
ErrIdentityIncomplete reports that the state directory holds some of the agent's identity but not all of it — the signature of a partial restore or a destroyed bind mount, not of a first install. See CheckIdentityConsistency.
Functions ¶
func CheckIdentityConsistency ¶
CheckIdentityConsistency implements D9's matrix over (state database present, certificate authority present):
- neither present: nil — a genuine first run.
- both present: nil — the normal running state.
- exactly one present: ErrIdentityIncomplete, naming which half is missing. This is the signature of a partial restore or a destroyed bind mount, not of a first install, and must never be treated as one: silently minting a fresh identity here would be indistinguishable from an attacker replacing the agent's identity outright.
certsDir is the directory holding ca.crt/ca.key (CheckIdentityConsistency does not touch server.crt/server.key, which are re-derived from the CA and carry no independent identity). dbExisted reports whether the state database file was already on disk before this start (state.Store's FirstRun, negated).
func LoadOrCreateServerCert ¶
func LoadOrCreateServerCert(dir string, sans []string, ca *CA, log *slog.Logger) (tls.Certificate, error)
LoadOrCreateServerCert returns the persisted server keypair, issuing one from ca if none is present.
When the stored certificate no longer covers every address in sans — typically because the VPS's address changed — it is re-issued from ca automatically (D10). Clients pin the CA, not this leaf, so re-issuance is invisible to them: no device has to re-pair.
Types ¶
type CA ¶
type CA struct {
// contains filtered or unexported fields
}
CA is the agent's certificate authority: a self-signed root that issues the server leaf and every paired device's client certificate. Its private key never leaves this process; nothing in this package logs it, its PEM encoding, or any other key material.
func LoadOrCreateCA ¶
LoadOrCreateCA returns the persisted certificate authority, generating and writing one if it is absent. created reports whether this call generated a new CA — the caller (main.go) logs the fingerprint at WARN exactly once, on that transition, so the operator can record it.
func (*CA) Fingerprint ¶
Fingerprint is the hex SHA-256 digest over the CA certificate's DER bytes. It is the pinning anchor a client records at pairing time and is published on GET /v1/status — publishing it is the point, and nothing else about the CA may join it.
func (*CA) IssueDeviceCert ¶
func (c *CA) IssueDeviceCert(csrDER []byte, commonName string, now time.Time) (certPEM []byte, serial string, notAfter time.Time, err error)
IssueDeviceCert signs a client leaf from a device-supplied PKCS#10 CSR.
The CSR's Subject is attacker-controlled and is ignored entirely — the leaf's CommonName always comes from commonName, the agent's own record of the device (its ID). A CSR asking to be CN=admin does not get it.
now is a parameter so tests can pin the validity window, matching IssueServerCert's convention.
func (*CA) IssueServerCert ¶
IssueServerCert produces a CA-signed EC P-256 server leaf covering sans, replacing the self-signed leaf Phase 1 generated. sans are split into DNS names and IP addresses automatically.
serverCertValidity — not caValidity — bounds this leaf: modern mobile TLS stacks reject certificates longer-lived than the CA/Browser Forum maximum, and clients pin the CA, not this leaf, so its short life is invisible to them.