tls

Documentation

Overview

Package tls is the chassis's bundled TLS/ACME layer: an embedded ACME client (certmagic) that obtains and renews certificates for delegated zones, solving the ACME DNS-01 challenge IN-PROCESS against the chassis's own authoritative DNS head. Because the ACME client and the nameserver share one process, the challenge is published with a direct function call — no RFC2136, no external DNS provider, no plugin. The same challenge substrate (the dns head's ChallengeStore) also accepts challenges written over RFC2136 by an external ACME client; this package is the bundled, self-contained writer.

Two seams keep it deployable at any scale, each with a local default in core and a shared backend registered by a downstream overlay (mirroring chassis/auth/registry/dialect.go):

• cert/account storage (certmagic.Storage) — file by default, see storage.go
• the challenge substrate (ChallengePublisher) — the in-memory dns head store by default; a shared store lets any node answer the challenge.

Index

• func RegisterStorage(scheme string, f func(dsn string) (certmagic.Storage, error))
• func WildcardDomains(origins []string) []string
• type ChallengePublisher
• type Manager
  • func NewManager(opts Options) (*Manager, error)
  • func (m *Manager) Manage(ctx context.Context, domains []string) error
  • func (m *Manager) TLSConfig() *tls.Config
• type Options

Functions

func RegisterStorage

func RegisterStorage(scheme string, f func(dsn string) (certmagic.Storage, error))

RegisterStorage registers a certmagic.Storage factory for a DSN scheme. Called from a downstream overlay; core registers nothing.

func WildcardDomains

func WildcardDomains(origins []string) []string

WildcardDomains expands canonical origins (e.g. "ops.example.com") into the cert subject set we manage per delegated zone: the apex plus a wildcard covering every per-stack host. One cert per zone instead of one per host.

Types

type ChallengePublisher

type ChallengePublisher interface {
	Present(fqdn, value string)
	CleanUp(fqdn, value string)
}

ChallengePublisher is the minimal write surface the DNS-01 solver needs: publish and remove an `_acme-challenge` TXT value at an owner FQDN. Satisfied structurally by the dns head's ChallengeStore (Present/CleanUp), so this package never imports the dns personality.

type Manager

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

Manager owns a certmagic Config wired to issue/renew certs for delegated zones via in-process DNS-01. Build it once; call Manage as the set of delegated zones changes, and hand TLSConfig to the HTTPS listener.

func NewManager

func NewManager(opts Options) (*Manager, error)

NewManager builds the cert manager. It does not contact the CA or issue anything until Manage is called.

func (*Manager) Manage

func (m *Manager) Manage(ctx context.Context, domains []string) error

Manage (re)declares the exact set of domains to keep certificates for, obtaining missing ones in the background and renewing as needed. Safe to call repeatedly as delegated zones are added/removed.

func (*Manager) TLSConfig

func (m *Manager) TLSConfig() *tls.Config

TLSConfig returns a *tls.Config whose GetCertificate serves the managed certificates by SNI. The HTTPS listener on the web head uses this.

type Options

type Options struct {
	// Publisher is where DNS-01 challenges are written — the dns head's
	// ChallengeStore. REQUIRED for issuance to work.
	Publisher ChallengePublisher

	// Email is the ACME account contact (recommended by CAs).
	Email string

	// CA is the ACME directory URL. Empty ⇒ certmagic's default
	// (Let's Encrypt production). Point at LE staging or a local
	// Pebble/step-ca directory for testing.
	CA string

	// CARootFile is a PEM bundle to trust as the ACME CA's root, for a CA
	// whose root isn't in the system pool (Pebble/step-ca). Empty ⇒ system
	// roots — the right default for Let's Encrypt.
	CARootFile string

	// StorageDSN selects the cert/account store; empty ⇒ file at StoragePath.
	// A recognised scheme uses an overlay-registered backend (see storage.go).
	StorageDSN  string
	StoragePath string

	// Resolvers are the DNS servers certmagic uses for zone discovery and
	// DNS-01 propagation checks. Empty ⇒ query the zone's authoritative
	// servers directly (correct in production, where our head is the
	// authority). Point at our own head (e.g. 127.0.0.1:5354) for an
	// offline/localhost solve.
	Resolvers []string

	// PropagationDelay waits before the first propagation check. For a
	// single-node in-process solve the record is visible immediately, so 0
	// is fine; a small delay helps a shared store settle.
	PropagationDelay time.Duration

	Logger *zap.Logger
}

Options configures the bundled cert manager.