tls

tls

Package tls builds the TLS configuration a server serves with, and rereads the files behind it on an interval so that a rotated certificate is served without a restart. A Manager implements app.Component, so the app.App lifecycle starts and stops it alongside everything else.

Consumers do not import crypto/tls. Paths are strings, and the client authentication mode, the protocol versions and the cipher suites are string enums.

Quick start

manager, err := tls.NewWithConfig(&tls.Config{
    Name:     "api",
    Enabled:  true,
    CertFile: "/secrets/tls/tls.crt",
    KeyFile:  "/secrets/tls/tls.key",
    Logger:   a.Logger(),
})
if err != nil {
    return err
}

srv := httpserver.NewWithConfig(&httpserver.Config{
    Addr:       ":8443",
    Handler:    mux,
    TLSManager: manager,
})

a.Register(manager)
a.Register(srv)

The server does not own the manager. Register both, and register the manager first: components shut down in reverse registration order, so the server stops serving before the manager stops rereading.

One manager can be handed to several servers, which then serve the same material:

srv := httpserver.NewWithConfig(&httpserver.Config{
    Addr:            ":8443",
    Handler:         mux,
    TLSManager:      manager,
    ProbeTLSManager: manager,
})

Serving plaintext

The zero Config serves plaintext, and so does any config with Enabled: false. Manager.TLSConfig returns nil for such a manager, which is what leaves a listener unencrypted. A consumer can therefore wire TLS unconditionally and leave the decision to one configuration value.

Enabled is never inferred from the presence of certificate material. A configuration that names files without being enabled serves plaintext, and says so in a log line.

Configuration

manager, err := tls.NewWithConfig(&tls.Config{
    Name:           "api",                          // names this configuration in logs, errors and metrics (default: "tls")
    Enabled:        true,                           // default: false, which serves plaintext
    CertFile:       "/secrets/tls/tls.crt",         // PEM serving certificate
    KeyFile:        "/secrets/tls/tls.key",         // PEM private key for that certificate
    ClientCAFiles:  []string{"/secrets/ca/ca.crt"}, // authorities client certificates are verified against
    ClientAuth:     tls.ClientAuthOptional,         // default: resolved from ClientCAFiles; see below
    MinVersion:     tls.VersionTLS12,               // default: tls1.2
    MaxVersion:     tls.VersionTLS13,               // default: no maximum
    CipherSuites:   []tls.CipherSuite{"TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256"}, // default: left to crypto/tls
    ReloadInterval: time.Minute,                    // default: 1m
    Logger:         a.Logger(),                     // default: nothing is logged
    Registerer:     a.Metrics().Registerer(),       // default: no metrics
})

CipherSuites applies to TLS 1.2 only. TLS 1.3 cipher suites are not configurable in crypto/tls, so naming one here does not select it. Suites that crypto/tls reports as insecure are refused rather than served.

Verifying client certificates

ClientAuth decides what the server asks of a client, and what it does with the answer. The values are nginx's ssl_verify_client vocabulary, matched case-insensitively after trimming.

optional_no_ca requests a certificate and admits whatever arrives without checking it against anything. optional and on verify the chain against ClientCAFiles.

manager, err := tls.NewWithConfig(&tls.Config{
    Name:          "api",
    Enabled:       true,
    CertFile:      "/secrets/tls/tls.crt",
    KeyFile:       "/secrets/tls/tls.key",
    ClientCAFiles: []string{"/secrets/ca/ca.crt"},
    ClientAuth:    tls.ClientAuthOn,
})

An unset mode resolves from the authorities

Leaving ClientAuth unset resolves it from whether ClientCAFiles names an authority:

• No authority resolves to off.
• An authority resolves to optional, and says so at info level.

It resolves to optional rather than on so that adding an authority cannot by itself start rejecting clients. Mounting a CA and enforcing mutual TLS are then two separate changes, in that order, and the second is deliberate.

What is refused and what is only reported

A verifying mode with no authority to verify against is refused with ErrMissingClientCA, and so is one whose files yield no certificate between them. An empty pool is not the same as a permissive one: crypto/tls falls back to the host's trust store, which would admit a client certificate issued by any public authority.

Everything short of that is reported and skipped, so one bad entry does not stop a service starting:

• A ClientCAFiles entry that is blank, a file that cannot be read, and a PEM block that is not a certificate or does not parse are each logged and ignored.
• Authorities configured alongside off or optional_no_ca are logged as ignored, because neither mode reads them.

A file may hold a bundle, and every certificate in every file is trusted.

Reloading material

Registering the manager with the app.App starts the rereads. Every ReloadInterval, which defaults to one minute, the configured files are read again and what they hold replaces what the manager is serving. A manager serving plaintext starts nothing, and one that has already been started returns ErrAlreadyStarted rather than running a second loop.

A reread that cannot read the key pair changes nothing. The material already in use stays in place and the server goes on serving what it last read, so a secret caught half written does not interrupt service. The failure is logged at error level: construction refuses material it cannot read, so a service whose rereads are failing is one restart away from not starting at all, even while it serves clients normally.

The certificate authorities follow the rule given above instead. An unreadable file or an unusable entry is logged and skipped, and only a set that yields no certificate between them fails the reread, so a reread that succeeds commits whatever pool the readable files produced.

Shutdown ends the rereads and waits for a reread in flight to finish, or for its context to expire.

What a reload reaches

A rotated serving certificate is picked up without a restart. The certificate is chosen as each handshake arrives, rather than fixed into the configuration the server holds, so a connection that is already open keeps the certificate it handshook with and the next connection gets the new one. Nothing is closed to make the change take effect.

The client certificate authorities do not yet follow it. They are the ones loaded when Manager.TLSConfig was called, so changing trust roots currently takes a restart.

Metrics

Setting Registerer publishes two families, each labelled with Config.Name. A manager serving plaintext reads no material and publishes nothing.

manager, err := tls.NewWithConfig(&tls.Config{
    Name:       "api",
    Enabled:    true,
    CertFile:   "/secrets/tls/tls.crt",
    KeyFile:    "/secrets/tls/tls.key",
    Registerer: a.Metrics().Registerer(),
})

Scraped from a server wired that way:

# HELP gitlab_labkit_tls_certificate_expiry_timestamp_seconds Unix time at which the serving certificate stops being valid.
# TYPE gitlab_labkit_tls_certificate_expiry_timestamp_seconds gauge
gitlab_labkit_tls_certificate_expiry_timestamp_seconds{name="api"} 1.821738922e+09
# HELP gitlab_labkit_tls_reloads_total Total number of rereads of the configured TLS material, by outcome.
# TYPE gitlab_labkit_tls_reloads_total counter
gitlab_labkit_tls_reloads_total{name="api",outcome="failure"} 0
gitlab_labkit_tls_reloads_total{name="api",outcome="success"} 3

The expiry is an absolute timestamp rather than a remaining duration, read off the certificate at collection time.

Metric names are fixed, so one alert can cover every service. Config.Name is what tells one configuration's series from another's, which is why each configuration registered against the same registerer needs a distinct name; two that collide fail construction rather than reporting into one series.