tls

package
v0.2.33 Latest Latest
Warning

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

Go to latest
Published: Oct 1, 2026 License: MPL-2.0 Imports: 19 Imported by: 0

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

Constants

This section is empty.

Variables

View Source
var DevSelfSignedHosts = []string{
	"localhost", "127.0.0.1", "::1",
	"*.localhost", "*.local", "*.local.thanks.computer",
}

DevSelfSignedHosts are the names a dev certificate covers (`txco dev` IMAP, a `;self-signed` TCP listener): every dev-local hostname pattern the chassis auto-verifies on bind (see tenants.IsDevLocalHostname) plus loopback. A mail client shows the certificate once and the developer trusts it; that is the whole point — desktop clients refuse to even attempt LOGIN over a plaintext port.

Functions

func LoadOrMintSelfSigned added in v0.2.31

func LoadOrMintSelfSigned(certPath, keyPath string, hosts []string) (*tls.Config, bool, error)

LoadOrMintSelfSigned reuses the certificate at certPath/keyPath when it is still valid for 30 days and covers exactly these hosts; otherwise it mints a new one and writes both files (key 0600). A stable file is what lets a developer trust the certificate ONCE in the OS keychain instead of clicking through a warning on every chassis restart.

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 SelfSignedTLS added in v0.2.31

func SelfSignedTLS(hosts []string) (*tls.Config, error)

SelfSignedTLS builds a self-signed ECDSA certificate for the given hosts (DNS names, wildcards, or IPs) valid for a year, and a TLS config serving it. Development only — the bundled cert manager or cert files are the real paths (§25.3). See LoadOrMintSelfSigned for the on-disk variant a developer can trust once in the OS keychain.

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.

Jump to

Keyboard shortcuts

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