client

Documentation

Index

• Constants
• func CertExpiry(dir string) (time.Time, error)
• func ChallengeRenew(ctx context.Context, cfg RenewConfig, fingerprint string) (*imprint.EnrollmentResponse, error)
• func Enroll(ctx context.Context, cfg EnrollConfig) (*imprint.EnrollmentResponse, error)
• func IsEnrolled(dir string) bool
• func IsExpired(dir string) (bool, error)
• func LoadCert(dir string) (*x509.Certificate, error)
• func LoadTLS(dir string) (*tls.Config, error)
• func NeedsRenewal(dir string, threshold time.Duration) (bool, error)
• func ReloadableTLS(dir string) (*tls.Config, error)
• func Renew(ctx context.Context, cfg RenewConfig) (*imprint.EnrollmentResponse, error)
• func RenewOrReenroll(ctx context.Context, renewCfg RenewConfig, enrollCfg EnrollConfig, ...) (string, error)
• func SaveEnrollment(dir string, keyPEM, certPEM, caCertPEM []byte, serverID, fingerprint string) error
• type AutoRenewer
  • func NewAutoRenewer(cfg AutoRenewerConfig) *AutoRenewer
  • func (ar *AutoRenewer) Start(ctx context.Context)
• type AutoRenewerConfig
• type EnrollConfig
• type EnrollmentMeta
  • func LoadMeta(dir string) (*EnrollmentMeta, error)
• type RenewConfig

Constants

const DefaultRenewalThreshold = 30 * 24 * time.Hour

DefaultRenewalThreshold is the default duration before certificate expiry at which NeedsRenewal returns true (30 days).

Functions

func CertExpiry

func CertExpiry(dir string) (time.Time, error)

CertExpiry returns the NotAfter time of the client certificate.

func ChallengeRenew

func ChallengeRenew(ctx context.Context, cfg RenewConfig, fingerprint string) (*imprint.EnrollmentResponse, error)

ChallengeRenew performs Tier 2 challenge-based renewal for expired certificates. The client proves identity by signing a digest with the old private key. The fingerprint parameter should be the device's current hardware fingerprint.

func Enroll

func Enroll(ctx context.Context, cfg EnrollConfig) (*imprint.EnrollmentResponse, error)

Enroll performs the enrollment handshake with the service. It generates an ECDSA keypair, creates a CSR, POSTs to the enrollment endpoint, and persists the returned certificate + CA cert to StoreDir.

func IsEnrolled

func IsEnrolled(dir string) bool

IsEnrolled returns true if enrollment files exist in the directory.

func IsExpired

func IsExpired(dir string) (bool, error)

IsExpired returns true if the client certificate's NotAfter is in the past.

func LoadCert

func LoadCert(dir string) (*x509.Certificate, error)

LoadCert parses the client certificate from the store directory.

func LoadTLS

func LoadTLS(dir string) (*tls.Config, error)

LoadTLS reads the enrollment credentials from dir and returns a *tls.Config configured for mTLS. The certificate is loaded once at call time. Use this for short-lived processes. For long-running services with AutoRenewer, use ReloadableTLS instead.

func NeedsRenewal

func NeedsRenewal(dir string, threshold time.Duration) (bool, error)

NeedsRenewal returns true if the certificate is valid but will expire within the given threshold duration.

func ReloadableTLS

func ReloadableTLS(dir string) (*tls.Config, error)

ReloadableTLS returns a *tls.Config that reloads the client certificate from disk on every new TLS connection. This allows renewed certificates to be picked up automatically without restarting the process. Use this with AutoRenewer for long-running services.

Note: the CA certificate (RootCAs) is loaded once at call time and is not reloaded on subsequent connections. This is acceptable because CA certificates have a long validity period (20 years by default). If CA rotation support is needed in the future, the caller should recreate the TLS config.

func Renew

func Renew(ctx context.Context, cfg RenewConfig) (*imprint.EnrollmentResponse, error)

Renew performs Tier 1 mTLS certificate renewal. The client must have a valid (not-yet-expired) certificate. A new keypair and CSR are generated, and the request is authenticated via the existing mTLS credentials.

func RenewOrReenroll

func RenewOrReenroll(ctx context.Context, renewCfg RenewConfig, enrollCfg EnrollConfig, threshold time.Duration) (string, error)

RenewOrReenroll implements the three-tier renewal fallback:

1. If no cert on disk: re-enroll (Tier 3)
2. If cert valid but nearing expiry: mTLS renew (Tier 1)
3. If cert expired within challenge window: challenge renew (Tier 2)
4. If cert expired beyond window or Tier 2 fails: re-enroll (Tier 3)

Returns the action taken: "renewed", "challenge_renewed", "reenrolled", or "none".

func SaveEnrollment

func SaveEnrollment(dir string, keyPEM, certPEM, caCertPEM []byte, serverID, fingerprint string) error

SaveEnrollment writes the client key, signed certificate, CA certificate, and enrollment metadata to the given directory. Files are written atomically (write to .tmp, then rename) to prevent corruption on crash.

Types

type AutoRenewer

type AutoRenewer struct {
	// contains filtered or unexported fields
}

AutoRenewer periodically checks certificate expiry and renews as needed.

func NewAutoRenewer

func NewAutoRenewer(cfg AutoRenewerConfig) *AutoRenewer

NewAutoRenewer creates a new AutoRenewer with the given configuration.

func (*AutoRenewer) Start

func (ar *AutoRenewer) Start(ctx context.Context)

Start begins the auto-renewal loop. It blocks until the context is cancelled.

type AutoRenewerConfig

type AutoRenewerConfig struct {
	RenewConfig   RenewConfig
	EnrollConfig  EnrollConfig
	CheckInterval time.Duration       // how often to check; default: 24h
	Threshold     time.Duration       // renew when cert expires within this; default: 30 days
	OnRenew       func(action string) // called on successful renewal with the action taken
	OnError       func(error)         // called on renewal failure
}

AutoRenewerConfig configures the background certificate auto-renewer.

type EnrollConfig

type EnrollConfig struct {
	ServiceURL  string // base URL of the enrollment service (e.g. "https://updates.example.com")
	BuildSecret string // compiled-in build secret
	Fingerprint string // hardware fingerprint ("sha256:...")
	Hostname    string
	OS          string       // defaults to runtime.GOOS if empty
	Arch        string       // defaults to runtime.GOARCH if empty
	StoreDir    string       // directory to persist enrollment state
	HTTPClient  *http.Client // optional; defaults to a client with 30s timeout
}

EnrollConfig configures a client enrollment request.

type EnrollmentMeta

type EnrollmentMeta struct {
	ServerID    string `json:"server_id"`
	Fingerprint string `json:"fingerprint"`
}

EnrollmentMeta is persisted alongside the certificates.

func LoadMeta

func LoadMeta(dir string) (*EnrollmentMeta, error)

LoadMeta reads the enrollment metadata from disk.

type RenewConfig

type RenewConfig struct {
	ServiceURL      string        // base URL of the service
	StoreDir        string        // directory containing enrollment state
	ChallengeWindow time.Duration // max age of expired cert for Tier 2; 0 = 30 days
	HTTPClient      *http.Client  // optional; defaults to a client with 30s timeout
}

RenewConfig configures certificate renewal requests.