tlsutil

Documentation

Overview

Package tlsutil provides the two certificate paths the server supports: ephemeral self-signed dev certificates that Chromium accepts for WebTransport, and file-backed certificates (e.g. mounted from a cert-manager Secret) that reload transparently when renewed.

Index

• Constants
• func CertHashHex(cert *x509.Certificate) string
• func GenerateDevCert(hosts []string, validity time.Duration) (tls.Certificate, error)
• func LoadOrGenerate(certPath, keyPath string, hosts []string, validity time.Duration) (tls.Certificate, bool, error)
• func SPKIFingerprint(cert *x509.Certificate) string
• func WriteCertPair(certPath, keyPath string, cert tls.Certificate) error
• type Reloader
  • func NewReloader(certPath, keyPath string, log *slog.Logger) (*Reloader, error)
  • func (r *Reloader) GetCertificate(*tls.ClientHelloInfo) (*tls.Certificate, error)

Constants

const MaxDevCertValidity = 14 * 24 * time.Hour

MaxDevCertValidity is Chromium's hard upper limit on the validity period of certificates used with serverCertificateHashes; longer-lived certs are rejected for QUIC regardless of trust flags.

Functions

func CertHashHex

func CertHashHex(cert *x509.Certificate) string

CertHashHex returns hex(SHA-256(certificate DER)), the copy-paste form of the hash the JS WebTransport constructor takes in serverCertificateHashes.

func GenerateDevCert

func GenerateDevCert(hosts []string, validity time.Duration) (tls.Certificate, error)

GenerateDevCert creates a self-signed ECDSA P-256 certificate for the given hosts (DNS names or IP addresses). Chromium requires ECDSA and a validity period of at most 14 days for WebTransport; validity is capped accordingly. The returned certificate has Leaf populated.

func LoadOrGenerate

func LoadOrGenerate(certPath, keyPath string, hosts []string, validity time.Duration) (tls.Certificate, bool, error)

LoadOrGenerate returns the certificate at certPath/keyPath, generating and writing a fresh dev certificate for hosts when NEITHER file exists, or when the pair on disk is an EXPIRED certificate this package issued. generated reports whether it wrote one. If exactly one of the two paths exists it returns an error without writing anything: half-generating over a stray file is how a developer loses a key they meant to keep.

This is what makes a local dev certificate survive a restart (R38, docs/41 D3) — the hash a browser was given stays valid instead of being invalidated by every `-dev-cert` start.

Expiry is the other half of that bargain, and it is not cosmetic: dev certs live at most 14 days, and nothing downstream notices a dead one. The healthcheck dials without -cert-hash so it skips verification, config-gen renders the expired leaf's hash quite happily, and the only thing that fails is the browser — opaquely, which is the failure class this milestone exists to remove. Regeneration is gated on the certificate being *ours*: an expired certificate we did not issue belongs to whoever put it there.

func SPKIFingerprint

func SPKIFingerprint(cert *x509.Certificate) string

SPKIFingerprint returns base64(SHA-256(SubjectPublicKeyInfo)), the value Chromium expects in --ignore-certificate-errors-spki-list.

func WriteCertPair

func WriteCertPair(certPath, keyPath string, cert tls.Certificate) error

WriteCertPair writes cert (0644) and key (0600) as PEM to the given paths: a CERTIFICATE block and an EC PRIVATE KEY block, the encoding gawk-devcert has always produced. Parent directories must already exist. The modes are applied explicitly rather than left to the umask, so a key written under a permissive umask is still owner-only.

Types

type Reloader

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

Reloader serves a certificate from files and picks up renewals (e.g. cert-manager rewriting a mounted Secret) without a restart. It checks the cert file's mtime at most once per statInterval, from the TLS handshake path, so no background goroutine or fsnotify is needed.

func NewReloader

func NewReloader(certPath, keyPath string, log *slog.Logger) (*Reloader, error)

NewReloader loads the certificate pair immediately and fails fast if it is unreadable, so a misconfigured server never starts.

func (*Reloader) GetCertificate

func (r *Reloader) GetCertificate(*tls.ClientHelloInfo) (*tls.Certificate, error)

GetCertificate satisfies tls.Config.GetCertificate. It returns the cached pair, reloading it first when the cert file's mtime has changed. A failed reload keeps serving the previous certificate.