Exported API summary¶

Everything the package exports, what it returns and how it fails. Full godoc, with source links, is on pkg.go.dev.

The package name is tls, which collides with the standard library's. Import one of them under an alias — the package's own tests use cryptotls "crypto/tls".

DefaultConfig¶

func DefaultConfig() *crypto/tls.Config

A fresh hardened config: TLS 1.2 floor, six AEAD suites, X25519 then P-256. No certificate, no trust store, no ALPN. Cannot fail. Every other builder starts here.

Full field-by-field breakdown: What DefaultConfig sets.

Pair¶

type Pair struct {
    Enabled    bool
    Cert       string
    Key        string
    ClientCAs  []string
    ClientAuth string
}

The typed TLS settings block: paths and policy, not loaded material. Struct tags for mapstructure, yaml and json are documented in Configuration keys.

The zero value is inert — no TLS, no client-certificate policy.

Pair.Valid¶

func (p Pair) Valid() bool

Reports Enabled && Cert != "" && Key != "". A pure field check: it does not stat the paths, parse anything, or look at ClientCAs/ClientAuth. Valid() returning true does not mean the certificate loads.

This is the only place Enabled is read — see What enabled: false actually does.

Pair.Certificate¶

func (p Pair) Certificate() (crypto/tls.Certificate, error)

Loads Cert/Key through tls.LoadX509KeyPair. Errors are wrapped as loading TLS certificate: …. Reads the files on every call — there is no caching and no reload.

Use it directly to attach a client certificate for mTLS, which ClientConfig does not do for you:

cert, err := clientPair.Certificate()
cfg.Certificates = []cryptotls.Certificate{cert}

Pair.ServerConfig¶

func (p Pair) ServerConfig(nextProtos ...string) (*crypto/tls.Config, error)

DefaultConfig() plus ApplyTo — the hardened config with this pair's certificate loaded, its client-CA policy applied, and each of nextProtos advertised via ALPN. Pass "h2", "http/1.1" for an HTTP server, "h2" alone for a raw gRPC TLS listener, nothing for no ALPN.

Returns nil and an error if the certificate cannot be loaded or the client-CA policy is invalid. It does not check Enabled.

Pair.ApplyTo¶

func (p Pair) ApplyTo(cfg *crypto/tls.Config, nextProtos ...string) error

Merges the pair into a config you already own, instead of replacing it. Three things happen:

• the pair's certificate is appended to cfg.Certificates;
• each of nextProtos is appended to cfg.NextProtos unless already present;
• the pair's ClientCAs/ClientAuth are applied only if cfg.ClientAuth is NoClientCert and cfg.ClientCAs is nil.

Everything the caller set survives, including a weak MinVersion. ApplyTo adds a certificate; it does not harden — see ApplyTo does not harden the config you pass it.

Errors on a nil config (nil TLS config), on an unparseable certificate, and on an invalid ClientAuth — the last one even when the caller's policy is the one that wins, so a typo cannot pass silently.

Calling it twice with the same pair appends the certificate twice. It is not idempotent.

PairOverrides and ResolvePair¶

type PairOverrides struct {
    Enabled    bool
    Cert       bool
    Key        bool
    ClientCAs  bool
    ClientAuth bool
}

func ResolvePair(shared Pair, transport Pair, overrides PairOverrides) Pair

A pure per-field merge: each field comes from transport when its override boolean is set, and from shared otherwise. No I/O, no validation, no error return. See Sharing one certificate across several listeners.

CertPool¶

func CertPool(caFiles ...string) (*crypto/x509.CertPool, error)

Builds an x509.CertPool from PEM files. Errors if a file cannot be read (reading CA file "…": …) or contains no certificate (no certificates found in "…").

The pool starts empty: it does not include the system roots. With no arguments it returns a valid, empty pool — trusting nothing — rather than an error.

ClientConfig¶

func ClientConfig(caFiles ...string) (*crypto/tls.Config, error)

DefaultConfig() with RootCAs set from CertPool(caFiles...). With no arguments it leaves RootCAs nil, which means the system root store.

Passing CA files replaces system trust rather than adding to it. That is usually what you want for an internal service and wrong for a client that also calls public endpoints — see Private-CA trust replaces the system roots.

It sets no client certificate. For mutual TLS from the client side, attach one yourself with Pair.Certificate.

Client-auth constants¶

const (
    ClientAuthRequest       = "request"
    ClientAuthVerifyIfGiven = "verify-if-given"
    ClientAuthRequireVerify = "require-verify"
)

The accepted values of Pair.ClientAuth. Any other non-empty string is an error; an empty string means "no client-certificate auth" unless ClientCAs is set, in which case it means require-verify.