mtls

package
v0.3.0 Latest Latest
Warning

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

Go to latest
Published: Aug 13, 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 introduced by docs/plans/phase6-container-backend.md §PR4 (§決定5: "gateway / broker / dockerproxy はサービス名 (DNS) + TCP (mTLS) で 到達する"). It is intentionally minimal — issue short-lived leaf certificates off a CA persisted on disk, nothing more (no ACME, no external PKI). crypto/tls + crypto/x509 only, per project convention (CLAUDE.md: 外部ライブラリは最小限。標準ライブラリで実現できるものは追加しない).

Scope note (PR4): CA generation/persistence and per-listener SERVER certs are real and wired into internal/server.Server. Per-JOB CLIENT certs (§決定5's "per-job 短命 client cert") 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 today. Wiring an actual per-job identity (env delivery, container-local materialization, DOCKER_CERT_PATH, ...) is PR6 scope per the plan doc.

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 — the same data-dir convention
	// internal/dispatcher.LoadOrCreateKey's web_secret file uses.
	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, docs/plans/phase6-container-backend.md §PR6/§決定5's per-job client cert delivery. 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. Mirrors internal/dispatcher.LoadOrCreateKey's load-or-generate-and-persist shape for the web_secret file.

Publish uses atomicfile.PublishIfAbsent (docs/plans/volume-only-daemon.md §論点 d) for each file independently, instead of a plain os.WriteFile: two daemon instances racing to boot against the same fresh, empty named volume must never observe a half-written ca.crt/ca.key that fails to parse.

Known residual risk (documented, not solved by this function): 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 (each file individually well-formed PEM, parseable, but the key does not correspond to the cert's public key). This function does not lock across the two files to prevent that interleaving: doing so would mean inventing a new synchronization primitive (e.g. a lock file) beyond the write-temp+os.Link pattern this package is deliberately reusing as-is. The hazard window this guards is "two daemon instances racing at boot against the same volume" — not a supported topology for this daemon (one compose replica per data volume) — so it is accepted here rather than engineered around.

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 (docs/plans/phase6-container-backend.md §PR6, §決定5's per-job client cert delivery — 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). Production callers do not use this in PR4 — it exists so tests can exercise a real mTLS handshake against a ServerTLSConfig listener. PR6's real per-job client cert issuance uses 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 (§決定5, PR6's containerBackend.materializeDockerClientCert) must use, not IssueClientCert (Blocker 4, PR6 codex review): the pre-fix code issued per-job certs with the same 30-day validity as a long-lived per-listener server cert, but a per-job cert's whole trust boundary is meant to track the job it was issued for — a job's own materialization directory is deleted the moment the job exits (see containerSession.dockerTLSDir's own retention contract), yet a copy of the cert a job made onto a sibling before exiting would otherwise stay valid, and usable against the dockerproxy TCP listener, for up to 30 days after the job — and the daemon's own record of it — are gone. A short (typically 1h) validity bounds that exposure window to "revocation by expiry" on a timescale close to a job's own lifetime, pending PR7's full fix (binding the cert's CN/SAN to a job_id dockerproxy itself verifies per request — see mtls.CA's own package doc comment).

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 server config) — unlike ServerTLSConfig, it does not require or verify a client certificate.

This is for a listener whose per-connection authorization is already fully handled at the application layer by an existing per-job bearer token (docs/plans/phase6-container-backend.md §決定5: 「per-job の... token は既存 broker/gitgateway の per-job capability token パターンを流用」 — the git gateway's own Registry-issued, URL-path-embedded per-job token is exactly that). A client certificate would add no per-job authorization this token doesn't already provide, and — unlike dockerproxy, whose own §決定5 write-up explicitly designs a per-job short-lived client cert with broker-style env delivery — no PR ever actually built or wired per-job client cert issuance/delivery for the git gateway; this package's own doc comment already flags that gap ("Per-JOB CLIENT certs ... are NOT materialized or distributed to any real job by this package's production callers"). Requiring one anyway (ServerTLSConfig's unconditional tls.RequireAndVerifyClientCert) makes the listener unusable by any real client — PR9's real-docker e2e-container CI job hit exactly this: every sandbox-internal clone attempt failed the TLS handshake with "tls: client didn't provide a certificate" server-side (and a matching client-side "server certificate verification failed" once the client was separately given something to trust the server with).

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. This is the "skeleton" mTLS server auth PR4 delivers: any connection without a CA-signed client cert is rejected at the handshake, but the server does not yet inspect *which* identity the client cert names (per-job scoping is PR6 — §決定5's "per-job client cert" note).

Jump to

Keyboard shortcuts

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