374 lines
17 KiB
Markdown
374 lines
17 KiB
Markdown
# mTLS as Authentication
|
||
|
||
**Status:** implemented. Phases 1–3 of the original proposal, plus dialer-side
|
||
server identity pinning from phase 4, are in the tree and covered by
|
||
`test/mtls-chain-test.sh`. The remaining phase-4 items are listed under
|
||
[Not Implemented](#not-implemented).
|
||
|
||
**Scope:** turn transport-level mutual TLS into an authentication and
|
||
authorization mechanism.
|
||
|
||
## Problem
|
||
|
||
LogWisp already did mutual TLS at the transport layer. A listener with
|
||
`client_auth = true` refused any peer that could not present a certificate
|
||
chaining to `client_ca_file`, and `internal/tlsx` extracted the peer's Common
|
||
Name into session metadata as `tls_peer_cn`.
|
||
|
||
Nothing read it back. The result was a CA-wide membership check with no notion
|
||
of *which* peer connected:
|
||
|
||
1. **No per-identity authorization.** Every certificate the CA issued was
|
||
equivalent. There was no way to say "only `edge-01` and `edge-02` may write
|
||
to this ingest port", so one CA could not serve several trust domains, and
|
||
withdrawing one peer meant rotating the CA bundle for all of them.
|
||
2. **Node labels were unauthenticated.** With `trust_node = true` (the default)
|
||
a peer declares its own `node` label in the chain hello or the
|
||
`X-Logwisp-Node` header. Any certificate holder could claim any label,
|
||
including another host's, and every downstream consumer would attribute
|
||
those entries accordingly. The only defence, `trust_node = false`, replaced
|
||
the label with a remote address — unforgeable, but useless for identifying a
|
||
host behind NAT or a load balancer.
|
||
3. **The `http` sink had no authentication at all**, even with TLS on. Its
|
||
stream and status endpoints were readable by anyone who could reach the port.
|
||
|
||
Password, token, and SCRAM authentication were removed during the plugin/flow
|
||
restructure and the move to standard-library networking. Certificates are the
|
||
one credential the transport already carries, which made mTLS the cheapest path
|
||
back to authenticated peers.
|
||
|
||
## Goals
|
||
|
||
- Authorize peers by certificate identity, per listener. ✅
|
||
- Bind the chain `node` label to the authenticated identity, so origin
|
||
attribution is trustworthy. ✅
|
||
- Gate the `http` sink's endpoints on client certificates. ✅
|
||
- Make identity visible in sessions, statistics, and logs. ✅
|
||
- Change nothing for existing configurations that omit the new block. ✅
|
||
|
||
## Non-Goals
|
||
|
||
- Reviving password, token, or SCRAM authentication. The reserved hooks
|
||
(`chain.Hello.Auth`, the `Authorization` header comment in the `http_chain`
|
||
sink, the "Future: password auth block" comments in the network options
|
||
structs) stay reserved.
|
||
- IP allow/deny lists and per-peer rate limits. Related, but a separate feature
|
||
with its own config surface.
|
||
- OCSP. See [Revocation](#revocation) for what is done instead.
|
||
- Authorization *within* a stream — the unit of decision is a connection (TCP)
|
||
or a request (HTTP), never an individual entry.
|
||
|
||
## Design
|
||
|
||
### Identity
|
||
|
||
The authenticated identity is a single string derived from the peer's verified
|
||
leaf certificate. Because `tls.RequireAndVerifyClientCert` has already validated
|
||
the chain, signature, and validity window by the time we look, extraction is
|
||
pure field selection — `tlsx.PeerIdentity`.
|
||
|
||
| `identity` mode | Source | Notes |
|
||
|-----------------|--------|-------|
|
||
| `cn` (default) | `Subject.CommonName` | Matches the existing `tls_peer_cn` metadata |
|
||
| `san_dns` | first `DNSNames` entry | Preferred for host identities |
|
||
| `san_uri` | first `URIs` entry | SPIFFE-style IDs |
|
||
| `san_email` | first `EmailAddresses` entry | Operator identities |
|
||
|
||
An empty identity is a rejection, not an empty match: a certificate with no
|
||
usable identity field cannot satisfy any policy.
|
||
|
||
Identities are not secrets, so ordinary string comparison is used; there is no
|
||
timing side channel worth defending here.
|
||
|
||
### Configuration
|
||
|
||
An `auth` table sits beside `tls` in every network plugin's `config`. Keeping it
|
||
separate from `tls` matters: TLS answers "is this channel private and does the
|
||
peer chain to a CA", auth answers "may *this* peer do *this*", and a later
|
||
non-certificate method can reuse the block.
|
||
|
||
```toml
|
||
[pipelines.plugin_sources.config.auth]
|
||
type = "mtls" # none (default) | mtls
|
||
identity = "cn" # cn | san_dns | san_uri | san_email
|
||
allow = ["edge-01", "edge-02"] # exact identities
|
||
allow_patterns = ["^edge-\\d{2}$"] # RE2, anchored by the author
|
||
node_binding = "force" # none | assert | force
|
||
```
|
||
|
||
| Option | Type | Default | Meaning |
|
||
|--------|------|---------|---------|
|
||
| `type` | string | `none` | `none` preserves pre-auth behaviour exactly; `mtls` enables the policy |
|
||
| `identity` | string | `cn` | Which certificate field is the identity |
|
||
| `allow` | []string | `[]` | Exact identity matches |
|
||
| `allow_patterns` | []string | `[]` | RE2 patterns matched against the identity |
|
||
| `node_binding` | string | `force` when `type = "mtls"` | Chain sources only; see below |
|
||
|
||
Empty `allow` **and** empty `allow_patterns` under `type = "mtls"` means "any
|
||
identity the CA vouches for" — that is, the pre-auth behaviour, but with the
|
||
identity now recorded and node binding available. It is a deliberate, documented
|
||
default rather than a silent deny-all, and the plugin logs a WARN at startup
|
||
saying so.
|
||
|
||
`node_binding` applies only to the chain sources, where a `node` label is
|
||
declared. Setting it on any other plugin is a configuration error.
|
||
|
||
| Value | Connection label | Per-entry `node` field |
|
||
|-------|------------------|------------------------|
|
||
| `none` | `trust_node` governs, as before | `trust_node` governs |
|
||
| `assert` | Must equal the identity; a mismatch or an omission is rejected | `trust_node` governs |
|
||
| `force` | The declared label is ignored and the identity is used | Overwritten with the identity |
|
||
|
||
The split between `assert` and `force` is what makes both worth having:
|
||
|
||
- **`force`** is for an ingest boundary that does not trust its peer. Every
|
||
entry is relabeled, so a compromised edge cannot smuggle a foreign origin
|
||
through the per-entry `node` field either. It is the default under
|
||
`type = "mtls"` because it is the only setting where a misconfigured or
|
||
hostile edge cannot mislabel its entries.
|
||
- **`assert`** is for a relay-to-relay hop. The relay must prove *its own*
|
||
identity — a mismatch is loud rather than silently corrected — but the entries
|
||
it forwards keep the origin labels stamped at the first hop, so multi-hop
|
||
attribution survives.
|
||
|
||
`node_binding` overrides `trust_node`; when binding is active the constructor
|
||
logs that `trust_node` is being ignored.
|
||
|
||
Dialer-side plugins (`tcp_chain` and `http_chain` sinks) accept the same block
|
||
to pin the *server's* identity beyond hostname verification. There
|
||
`node_binding` does not apply, and `tls.insecure_skip_verify` is rejected:
|
||
identity read from an unverified chain is a claim, not a fact.
|
||
|
||
### Validation
|
||
|
||
At plugin construction, before anything binds:
|
||
|
||
- `type = "mtls"` on a listener requires `tls.enabled = true` and
|
||
`tls.client_auth = true`; on a dialer it requires `tls.enabled = true` and
|
||
forbids `tls.insecure_skip_verify`. Silently accepting an auth policy the
|
||
transport cannot enforce is the failure mode worth designing out.
|
||
- `identity` must be one of the four modes.
|
||
- Every entry in `allow_patterns` must compile.
|
||
- `node_binding` must be one of the three values, and must be absent or `none`
|
||
outside the chain sources.
|
||
|
||
Errors follow existing style: `auth: type "mtls" requires tls.client_auth`.
|
||
|
||
### The `internal/authz` package
|
||
|
||
```go
|
||
package authz
|
||
|
||
// Policy is the compiled form of config.AuthOptions.
|
||
type Policy struct { /* role, identity mode, exact set, patterns, binding, counters */ }
|
||
|
||
// Role selects the validation and behavior appropriate to the call site.
|
||
const ( RoleListener Role = iota; RoleChainListener; RoleDialer )
|
||
|
||
// New compiles a policy. Returns (nil, nil) when auth is disabled, matching
|
||
// the tlsx.Server / tlsx.Client convention. tlsOpts is the sibling `tls`
|
||
// block, so an unenforceable policy fails here rather than at run time.
|
||
func New(o *config.AuthOptions, tlsOpts *config.TLSOptions, role Role) (*Policy, error)
|
||
|
||
// Identity is the outcome of a successful authorization.
|
||
type Identity struct {
|
||
Name string // the selected certificate field
|
||
Method string // "mtls"
|
||
}
|
||
|
||
// Apply stamps an identity onto session metadata.
|
||
func (id Identity) Apply(meta map[string]any)
|
||
|
||
// Authorize extracts and checks the peer identity from a completed handshake.
|
||
func (p *Policy) Authorize(cs *tls.ConnectionState) (Identity, error)
|
||
|
||
// VerifyConnection is assignable to tls.Config.VerifyConnection on a dialer.
|
||
func (p *Policy) VerifyConnection(cs tls.ConnectionState) error
|
||
|
||
// ResolveNode applies node_binding to the label a peer declared.
|
||
func (p *Policy) ResolveNode(declared, fallback string, trustNode bool, id Identity) (string, error)
|
||
|
||
// TrustsEntryNode reports whether per-entry node labels survive the policy.
|
||
func (p *Policy) TrustsEntryNode(trustNode bool) bool
|
||
|
||
// Stats reports counters for the sink/source stats map.
|
||
func (p *Policy) Stats() map[string]any
|
||
```
|
||
|
||
This mirrors `internal/tlsx`: one small package that is the single seam between
|
||
declarative config and a cross-cutting concern. `New` returns `(nil, nil)` for
|
||
the disabled case and **every method tolerates a nil receiver**, so a call site
|
||
reads identically whether or not auth is configured — no nil checks, no branch
|
||
on config:
|
||
|
||
```go
|
||
id, err := s.auth.Authorize(tlsState) // nil policy: (zero Identity, nil)
|
||
if err != nil { /* reject */ }
|
||
```
|
||
|
||
### Enforcement Points
|
||
|
||
**`tcp_chain` source** (`internal/source/tcpchain/tcpchain.go`, `handleConn`)
|
||
|
||
Handshake → **authorize** → read hello → `ResolveNode` → create session. The
|
||
authorization sits between the handshake and the hello read, so an unauthorized
|
||
peer never gets a preamble parsed on its behalf. `chain.DecodeEntry` is then
|
||
called with `auth.TrustsEntryNode(trust_node)` rather than `trust_node` itself.
|
||
|
||
**`http_chain` source** (`internal/source/httpchain/httpchain.go`, `handleIngest`)
|
||
|
||
Per request, from `r.TLS`, before the body is read — an unauthorized sender does
|
||
not get to stream `max_body_bytes` into the process. Rejection is `403`,
|
||
distinct from the `400` used for protocol errors, so a sender can tell "you are
|
||
not allowed" from "your batch was malformed". `ResolveNode` then governs the
|
||
`X-Logwisp-Node` header exactly as it governs the TCP hello. The session cache
|
||
key includes the identity, so two peers sharing a remote address never share a
|
||
session.
|
||
|
||
**`tcp` sink** (`internal/sink/tcp/tcp.go`, `handleConn`)
|
||
|
||
After the explicit handshake, before the session is created and the client is
|
||
registered — so an unauthorized peer never appears in the client map and never
|
||
receives a broadcast.
|
||
|
||
**`http` sink** (`internal/sink/http/http.go`, `authMiddleware`)
|
||
|
||
A middleware around the mux covers both the stream and the status endpoint with
|
||
one wrapper and keeps the handlers themselves unaware of authorization. The
|
||
authorized identity is passed down through the request context for session
|
||
metadata. Rejections are `403` with no body detail — the status endpoint leaks
|
||
host, port, and throughput counters, so a rejection should not leak policy shape
|
||
on top of that.
|
||
|
||
**`tcp_chain` / `http_chain` sinks** (dialers)
|
||
|
||
The policy is installed as `tls.Config.VerifyConnection`, which runs after the
|
||
standard chain and hostname checks. A server whose identity the policy rejects
|
||
fails the handshake itself rather than the first write, and the chain sink's
|
||
existing backoff loop handles it as any other connect failure.
|
||
|
||
### Capabilities
|
||
|
||
`core.CapAuth` now means "this plugin authorizes peers" — it is derived from the
|
||
policy, not from `tlsConfig.ClientAuth`. Transport-level mTLS without a policy
|
||
still reports `CapTLS`, the `mtls=true` field on the startup log line, and the
|
||
`tls` statistic.
|
||
|
||
`Pipeline.initSourceCapabilities` and `initSinkCapabilities` treat this as a
|
||
cross-cutting check: a plugin advertising `CapAuth` without `CapTLS` is a
|
||
contradiction and fails pipeline construction rather than starting.
|
||
|
||
### Observability
|
||
|
||
Every authorization decision is visible, because a silent deny is
|
||
indistinguishable from a network fault at 3am.
|
||
|
||
- **Session metadata** gains `auth_method` and `auth_identity` alongside the
|
||
existing `tls` and `tls_peer_cn`.
|
||
- **Statistics** gain `auth`, `auth_identity` (the mode), `auth_unrestricted`,
|
||
`auth_allowed`, `auth_rejected`, and — on chain sources — `node_binding`, in
|
||
the `details` map of every affected source and sink. They surface in the
|
||
status reporter and in the `http` sink's status endpoint.
|
||
- **Logs** record a WARN per rejection with the remote address and the reason.
|
||
The startup line carries a rendered policy summary
|
||
(`auth="mtls identity=cn allow=[1 exact, 0 pattern(s)] node_binding=force"`),
|
||
a WARN when the allow list is empty, and an INFO when node binding overrides
|
||
`trust_node`.
|
||
|
||
### Revocation
|
||
|
||
Certificate revocation is handled by the allow-list rather than by CRL or OCSP:
|
||
|
||
1. Remove the identity from `allow` / `allow_patterns`.
|
||
2. `kill -HUP`.
|
||
|
||
The reload path rebuilds every pipeline, so the policy takes effect on the next
|
||
connection and existing connections are dropped by the rebuild itself. This is
|
||
one moving part instead of three, it needs no network calls on the handshake
|
||
path, and it is exact — no window between revocation and the next CRL
|
||
publication.
|
||
|
||
## Compatibility
|
||
|
||
No configuration breaks. Omitting the `auth` block, or setting `type = "none"`,
|
||
reproduces the previous behaviour exactly: `Policy` is nil, every call site
|
||
short-circuits, and `trust_node` continues to govern node labels.
|
||
|
||
The one behavioural note for adopters: turning on `type = "mtls"` defaults
|
||
`node_binding` to `force`, so entries from a peer whose certificate identity
|
||
differs from its configured `node` label will be relabelled. That is the point
|
||
of the feature, but it moves data between labels in a dashboard, so plan for it.
|
||
Use `node_binding = "assert"` on relay-to-relay hops where upstream origin
|
||
labels must survive.
|
||
|
||
## Verification
|
||
|
||
`test/mtls-chain-test.sh` builds a full PKI with `openssl` and exercises both
|
||
target topologies end to end:
|
||
|
||
```
|
||
./test/mtls-chain-test.sh --auto
|
||
```
|
||
|
||
Scenario 1 — chained instances, client authenticating with mTLS:
|
||
|
||
- an authorized edge (`edge-01`) delivers entries through both the `tcp_chain`
|
||
and `http_chain` ingest ports into a file sink
|
||
- `node_binding = "force"` overrides the label the sender configured
|
||
- an identity outside the allow list (`edge-99`) is refused, even while claiming
|
||
to be `edge-01`
|
||
- a peer presenting no certificate fails the handshake
|
||
- a dialer that pins a server identity the relay does not hold refuses to
|
||
connect, even though the server certificate chains to the trusted CA
|
||
|
||
Scenario 2 — a viewer client reading a streaming sink over mTLS:
|
||
|
||
- an authorized viewer streams from the `tcp` sink and from the `http` sink's
|
||
SSE endpoint, and reads `/status`
|
||
- a CA-valid but unauthorized viewer gets nothing from the `tcp` sink and `403`
|
||
from both `http` sink endpoints
|
||
- a client with no certificate fails the handshake
|
||
- the status endpoint reports the policy and its rejection count
|
||
|
||
`test/chain-test.sh` and `test/chain-aggregate-test.sh` continue to pass
|
||
unchanged, which is the regression check for the auth-disabled path.
|
||
|
||
## Not Implemented
|
||
|
||
The remaining phase-4 items, in rough order of value:
|
||
|
||
1. **CRL file support** alongside `client_ca_file`, re-read on reload, for
|
||
operators with existing CRL infrastructure. The allow-list covers the same
|
||
ground with fewer moving parts, so this is only worth doing for a fleet whose
|
||
revocation already flows through a CRL.
|
||
2. **Certificate expiry warnings** at startup and on reload — a leaf expiring
|
||
inside 30 days logged at WARN. Nothing warns today; expiry shows up as a
|
||
handshake failure.
|
||
3. **Per-identity rate limits.** The natural follow-on now that identity exists,
|
||
and the natural home for the per-IP limiting that was also removed. Kept out
|
||
of scope here so this feature stayed reviewable.
|
||
4. **Per-client identity in the `http` sink's status output.** The endpoint
|
||
reports the policy and counters, but not which identities are currently
|
||
connected; session metadata has the data.
|
||
5. **A list of `identity` modes** (try `san_uri`, fall back to `cn`) for
|
||
heterogeneous PKI. A single mode is simpler and covers a uniform CA.
|
||
|
||
## Decisions Taken
|
||
|
||
Four questions were left open by the proposal. What was chosen, and why:
|
||
|
||
1. **An empty allow-list allows rather than denies.** Deny-by-default is the
|
||
safer instinct, but `type = "mtls"` with no list is a legitimate
|
||
configuration — "any peer this CA issued, but bind the node labels" — and
|
||
node binding alone is worth enabling without enumerating every node.
|
||
Erroring on it would force operators to list their whole fleet to get
|
||
trustworthy attribution. The compromise is a WARN at startup naming the
|
||
condition and the fix.
|
||
2. **`identity` takes a single mode.** Simpler, and a uniform CA is the common
|
||
case. Listed above as a possible extension.
|
||
3. **Per-identity rate limits are out of scope**, as proposed.
|
||
4. **`assert` rejects rather than warns and corrects.** A certificate/config
|
||
mismatch under `assert` is an outage, which is the point: `force` is the
|
||
forgiving option and it is the default, so an operator reaches for `assert`
|
||
precisely when they want the mismatch to be loud.
|