certs

package
v0.2.0 Latest Latest
Warning

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

Go to latest
Published: Aug 12, 2026 License: AGPL-3.0 Imports: 19 Imported by: 0

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

Constants

This section is empty.

Variables

View Source
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

func CheckIdentityConsistency(certsDir string, dbExisted bool) error

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

func GenerateServerCert(sans []string, notBefore time.Time) (certPEM, keyPEM []byte, err error)

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

func LoadOrCreateCA(dir string, log *slog.Logger) (*CA, bool, error)

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) CertPEM

func (c *CA) CertPEM() []byte

CertPEM returns the CA certificate, PEM-encoded, for the client to pin.

func (*CA) Fingerprint

func (c *CA) Fingerprint() string

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 GenerateServerCert's convention.

func (*CA) IssueServerCert

func (c *CA) IssueServerCert(sans []string, now time.Time) (certPEM, keyPEM []byte, err error)

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.

func (*CA) Pool

func (c *CA) Pool() *x509.CertPool

Pool returns an x509.CertPool containing only this CA, suitable for verifying either a device's client certificate or the agent's own server leaf.

Jump to

Keyboard shortcuts

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