Documentation
¶
Overview ¶
Package certs owns the agent's TLS material on disk: generating a server certificate on first start, reusing it afterwards, and reporting when the configured addresses have drifted away from what it covers.
Phase 1 is self-signed. Phase 2 replaces generation with CA issuance; the shape returned here is identical, so tlsconf and httpapi need no change.
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 GenerateServerCert(sans []string, notBefore time.Time) (certPEM, keyPEM []byte, err 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 GenerateServerCert ¶
GenerateServerCert produces a self-signed EC P-256 leaf covering sans.
sans are split into DNS names and IP addresses automatically. notBefore is a parameter so tests can pin the validity window.
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 an Android 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 GenerateServerCert'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.