tls

tls

Package tls builds the TLS configuration a server serves with, and rereads the files behind it on an interval so that rotated material 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 configured with no authority at all is refused with ErrMissingClientCA. 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.

Every configured file must be usable. One that cannot be read fails with the underlying filesystem error, so a secret that has not been mounted is recognisable with errors.Is against fs.ErrNotExist; one holding no certificate, or a certificate that does not parse, fails with ErrInvalidPEM. A pool built from whichever files happened to read would narrow what the server trusts without saying so.

Two things are reported rather than refused, because neither changes what is trusted: a blank ClientCAFiles entry, and authorities configured alongside off or optional_no_ca, which never read them.

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

Application protocols

The application protocols offered during the handshake, as ALPN, belong to the server rather than to the material: a manager cannot know what the server it is given to speaks. httpserver names them for its listeners with WithNextProtos, so a consumer serving through it has nothing to do here. A server that names none negotiates none, which leaves an HTTP client on HTTP/1.1.

The configuration Manager.TLSConfig returns replaces itself as each handshake arrives, so a field set on it afterwards is not the one the handshake reads. An Option carries anything that has to reach the handshake.

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 authorities follow the same rule. Any configured file that cannot be read, or that holds something unusable, fails the reread, so the pool a server is verifying against is never narrowed by a bundle that was briefly unreadable.

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

What a reload reaches

A reread is picked up without a restart. Both the serving certificate and the client certificate authorities are chosen as each handshake arrives, rather than fixed into the configuration the server holds, so a connection that is already open keeps what it handshook with and the next connection gets what was last read. Nothing is closed to make the change take effect.

A client whose authority the server has stopped trusting is refused even when it resumes a cached session.

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.