tls

gitlab.com/phpboyscout/go/tls — small, hardened TLS plumbing for Go servers and clients. It gives you one opinionated, secure *crypto/tls.Config (TLS 1.2 floor, AEAD-only cipher suites, modern curve preferences), a typed Pair for the enabled/cert/key triple, ServerConfig/ClientConfig builders, and a CertPool helper for trusting private CAs.

It is the same TLS posture behind go-tool-base's HTTP, gRPC and gateway transports, extracted so any project can adopt it without pulling in the framework.

Design

• Framework-free. The only external dependency is cockroachdb/errors. No config framework, no TUI, no OpenTelemetry, no go-tool-base. A depfootprint_test.go guard enforces it.
• Typed values in, hardened config out. The package works entirely from typed Pair values — you own how those are sourced (flags, env, a config file). ResolvePair merges a shared pair against per-transport overrides so one certificate can serve many listeners.
• Secure by default. DefaultConfig fixes a TLS 1.2 minimum, six curated ECDHE-AEAD cipher suites, and X25519/P-256 curve preferences — the same config underpins both the server and client builders.

Install

go get gitlab.com/phpboyscout/go/tls

Quick start

package main

import (
	"net/http"

	"gitlab.com/phpboyscout/go/tls"
)

func main() {
	pair := tls.Pair{Enabled: true, Cert: "/etc/certs/server.pem", Key: "/etc/certs/server-key.pem"}

	cfg, err := pair.ServerConfig("h2", "http/1.1") // hardened defaults + ALPN
	if err != nil {
		panic(err)
	}

	srv := &http.Server{Addr: ":8443", TLSConfig: cfg}
	_ = srv.ListenAndServeTLS("", "") // certs already loaded into TLSConfig
}

Client side, trusting a private CA:

clientCfg, err := tls.ClientConfig("/etc/certs/ca.pem") // or no args to trust system roots

Key concepts

• DefaultConfig — the shared hardened *crypto/tls.Config (TLS 1.2 floor, AEAD cipher suites, modern curves). The foundation for both builders.
• Pair — the typed {Enabled, Cert, Key} triple. Valid reports whether TLS is on and both paths are set; Certificate loads the X509 key pair; ServerConfig returns the hardened config with the certificate loaded (optionally advertising ALPN protocols).
• ResolvePair — pure per-field merge of a shared Pair with a per-transport Pair, driven by a PairOverrides mask. Lets one cert serve multiple transports with targeted overrides, with no dependency on any config lookup interface.
• ClientConfig / CertPool — a hardened client config trusting either the system roots or an explicit set of PEM CA files.

Documentation

Full guides and the security threat model: tls.go.phpboyscout.uk. API reference: pkg.go.dev.

License

See LICENSE.