mtls

package
v0.5.1 Latest Latest
Warning

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

Go to latest
Published: Sep 25, 2026 License: MIT Imports: 15 Imported by: 0

Documentation

Overview

Package mtls provides a small per-daemon self-signed certificate authority used to secure the broker / git-gateway / dockerproxy TCP listeners (docs/plans/phase6-container-backend.md §決定5). It is intentionally minimal — issue short-lived leaf certificates off a CA persisted on disk, nothing more (no ACME, no external PKI), using only crypto/tls + crypto/x509 per project convention.

CA generation/persistence and per-listener SERVER certs are wired into internal/server.Server. Per-JOB CLIENT certs are not materialized or distributed to any real job by this package's production callers — IssueClientCert exists so the mTLS handshake can be exercised end-to-end in tests.

Index

Constants

View Source
const (
	// CAFileName and KeyFileName are the on-disk names LoadOrCreate reads
	// and writes under its dir argument. The production caller
	// (internal/server.Server) points dir at ~/.local/share/boid/tls.
	CAFileName  = "ca.crt"
	KeyFileName = "ca.key"
)

Variables

This section is empty.

Functions

func EncodeCertPEM

func EncodeCertPEM(cert tls.Certificate) (certPEM, keyPEM []byte, err error)

EncodeCertPEM PEM-encodes a leaf certificate issued by IssueServerCert / IssueClientCert into the (certPEM, keyPEM) pair most file-based TLS consumers expect — docker's DOCKER_CERT_PATH convention (cert.pem + key.pem + ca.pem, see CA.CertPEM for the third file) among them. tls.Certificate itself is Go-internal (raw DER bytes plus a crypto.PrivateKey interface value) rather than a file format, so this is the one conversion step every such consumer needs.

Types

type CA

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

CA is a loaded or freshly generated self-signed internal certificate authority.

func LoadOrCreate

func LoadOrCreate(dir string) (*CA, error)

LoadOrCreate loads ca.crt/ca.key from dir, or generates and persists a new self-signed CA there if either file is missing. dir is created (0700) if needed.

Publish uses atomicfile.PublishIfAbsent for each file independently instead of a plain os.WriteFile, so two daemon instances racing to boot against the same fresh, empty volume never observe a half-written ca.crt/ca.key that fails to parse.

Known residual risk: PublishIfAbsent's one-winner guarantee is per FILE, not per (cert,key) PAIR — a race where one caller wins the ca.crt publish while a different caller wins the ca.key publish would produce a cryptographically mismatched pair. This is not guarded against here (see parseCA); the hazard window is "two daemon instances racing at boot against the same volume", not a supported topology for this daemon.

func (*CA) CertPEM

func (ca *CA) CertPEM() []byte

CertPEM returns this CA's own certificate, PEM-encoded — the "ca.pem" file docker's DOCKER_CERT_PATH convention expects alongside a leaf cert/key pair (see EncodeCertPEM for the leaf half).

func (*CA) CertPool

func (ca *CA) CertPool() *x509.CertPool

CertPool returns an x509.CertPool containing just this CA's certificate — suitable for tls.Config.ClientCAs (verify client certs against this CA) or RootCAs (verify a server cert issued by this CA).

func (*CA) ClientTLSConfig

func (ca *CA) ClientTLSConfig(serverName string, cert tls.Certificate) *tls.Config

ClientTLSConfig builds a tls.Config for connecting to a listener secured by ServerTLSConfig: trusts this CA as the server's root and presents cert (from IssueClientCert) as the client's identity. serverName must match a DNS/IP SAN on the listener's server cert (or be set to skip verification in tests, which callers should avoid in production code).

func (*CA) IssueClientCert

func (ca *CA) IssueClientCert(cn string) (tls.Certificate, error)

IssueClientCert issues a leaf client-authentication certificate identified by cn, valid for the default leafValidity (30 days). No production caller uses this — it exists so tests can exercise a real mTLS handshake against a ServerTLSConfig listener. A real per-job client cert must use IssueShortLivedClientCert instead (see its own doc comment for why 30 days is too long for that use case).

func (*CA) IssueServerCert

func (ca *CA) IssueServerCert(hosts ...string) (tls.Certificate, error)

IssueServerCert issues a leaf certificate for a TCP listener, valid for the given DNS names / IP addresses (hosts). The first host becomes the certificate's CommonName; hosts may be empty (a nameless cert still works for tests that skip hostname verification via ServerName). Never persisted — issue fresh on every listener bind.

func (*CA) IssueShortLivedClientCert

func (ca *CA) IssueShortLivedClientCert(cn string, validity time.Duration) (tls.Certificate, error)

IssueShortLivedClientCert issues a client-authentication leaf certificate identified by cn, like IssueClientCert, but with a caller-supplied validity window instead of the default 30-day leafValidity.

This is what a per-job dockerproxy client cert must use, not IssueClientCert: a per-job cert's trust boundary is meant to track the job it was issued for, but a copy of the cert made onto a sibling before the job exits would otherwise stay valid — and usable against the dockerproxy listener — long after the job and the daemon's own record of it are gone. A short (typically 1h) validity bounds that exposure window.

func (*CA) ServerOnlyTLSConfig

func (ca *CA) ServerOnlyTLSConfig(hosts ...string) (*tls.Config, error)

ServerOnlyTLSConfig builds a tls.Config for a TCP listener that authenticates only the SERVER side (a standard, non-mutual TLS config) — unlike ServerTLSConfig, it does not require or verify a client certificate.

This is for a listener (the git gateway) whose per-connection authorization is already fully handled at the application layer by an existing per-job bearer token, with no per-job client cert ever wired for it — requiring one anyway (ServerTLSConfig's unconditional tls.RequireAndVerifyClientCert) would make the listener unusable by any real client.

func (*CA) ServerTLSConfig

func (ca *CA) ServerTLSConfig(hosts ...string) (*tls.Config, error)

ServerTLSConfig builds a tls.Config for a TCP listener: presents a fresh server cert for hosts and requires (and verifies) a client certificate signed by this CA — mutual TLS. Any connection without a CA-signed client cert is rejected at the handshake; the server does not inspect *which* identity the client cert names.

Jump to

Keyboard shortcuts

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