certs

package
v0.5.0 Latest Latest
Warning

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

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

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

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 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 IssueServerCert'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