# Security This page covers LogWisp's transport security: what it protects, how to configure it, and — equally important — what it does not yet do. ## Current State **Implemented:** - TLS 1.2 / 1.3 on all network sources and sinks. - Server certificate verification by dialers, by a CA or by the pin of the server's key (`pin_sha256`). - Certificates without files: listeners make theirs at startup, self-signed or from an issuer CA, and `lw tls` makes a CA and certificates: see [Certificates made at startup](#certificates-made-at-startup). - Mutual TLS (client certificate required and verified), at the transport layer. - Peer identity recorded per session. - Authorization from certificate identity (allow-lists, node binding): see [The Auth Block](#the-auth-block). - Password (Argon2id-SCRAM) authentication, bound to the TLS channel: see [Password Authentication](#password-authentication-scram). - Authentication on the `http` sink's stream and status endpoints: client certificate or bearer token. - Browser logins behind a site's TLS-terminating proxy: see [Browsers behind a TLS-terminating proxy](#browsers-behind-a-tls-terminating-proxy). - Server pinning by dialers: certificate identity (`mtls`), bound certificate (`scram`). - Address rules and per-client connection and request limits on every listener, applied before TLS to the client a PROXY header (v1 or v2) from a listed L4 proxy names, and per request to the client an L7 proxy forwards: see [The ACL Block](#the-acl-block). - Startup warnings for expiring certificates and risky settings: see [Startup Warnings](#startup-warnings). - Unknown configuration keys rejected: a typo in `tls`, `auth`, `acl` or a table path fails startup. - Configuration input hardened (lixenwraith/config v0.2.2 and lixenwraith/toml v0.1.3, reviewed with adversarial tests and fuzzing like `auth`): - a document creates at most 65536 tables, so a small file cannot exhaust memory, and unescaped control characters are refused in strings and comments; - a string in the file is one list entry, so a filter pattern holding a comma is not split into patterns that match nothing; - the file is opened without blocking, so a FIFO swapped in for it cannot hang the watcher or a `SIGHUP` reload; - a permission change on the file is reported once and does not stop auto-reload; - parse and conversion errors name the key, never the value, so a secret placed in the wrong key does not reach the log. **Not implemented:** - Certificate revocation lists (CRL) or OCSP: revoke by editing the allow-list or credentials file. - Per-identity limits: the per-client limits count addresses, not the identities `auth` proves. - Per-client stream caps: under HTTP/2 `max_connections_per_client` bounds a client's connections, not the streams each carries; the request rate only slows how fast it opens them. Two credentials are supported. Certificates (`mtls`) are the one the transport already carries: the `tls` block establishes that a peer chains to your CA, and the `auth` block decides which of those peers may do what. Passwords (`scram`) need no client PKI: the listener holds verifiers, never passwords, and every login is bound to the listener's certificate. ## The TLS Block One option shape serves both roles, so the configuration reads the same wherever it appears. Which keys matter depends on whether the plugin listens or dials. ```toml [pipelines.plugin_sources.config.tls] # or plugin_sinks.config.tls enabled = false cert_file = "" key_file = "" client_auth = false client_ca_file = "" ca_file = "" server_name = "" insecure_skip_verify = false pin_sha256 = "" self_signed = false issuer_cert_file = "" issuer_key_file = "" hosts = [] min_version = "1.3" ``` Options by role, each with its default: - Both roles - `enabled` (`false`): master switch; when false the whole block is ignored. - `cert_file`: local certificate; a listener needs it, `self_signed` or the issuer files, a dialer may present it as its client identity. - `key_file`: private key for `cert_file`; set the two together. - `min_version` (`"1.3"`): `"1.2"` or `"1.3"`. - Listeners - `self_signed` (`false`): make a self-signed certificate at startup. - `issuer_cert_file`, `issuer_key_file`: make one at startup, signed by this CA (`lw tls ca`). - `hosts` (`[]`): names and addresses a made certificate carries, beyond the listener's `host`, `os.Hostname()`, `localhost`, `127.0.0.1` and `::1`. - `client_auth` (`false`): require and verify a client certificate (mTLS). - `client_ca_file`: CA bundle that verifies client certificates; **required** when `client_auth` is true. - Dialers - `ca_file` (system store): CA bundle that verifies the server certificate. - `server_name` (the configured `host`): SNI and certificate name to verify against. - `insecure_skip_verify` (`false`): disable server verification. - `pin_sha256`: `sha256//BASE64` of the server's public key, curl's `--pinnedpubkey` form, `;` between several; it replaces the CA and name checks. Listeners are the `tcp` and `http` sinks and the `tcp_chain` and `http_chain` sources; dialers are the `tcp_chain` and `http_chain` sinks. > `min_version` takes `"1.2"` or `"1.3"`. The older `"TLS1.2"` spelling from > pre-restructure releases is rejected. There is no `max_version` and no > `cipher_suites` option; TLS 1.3 suites are not configurable in Go, and the > 1.2 defaults are the standard library's. ### Validation Misconfiguration fails at plugin construction, before the pipeline starts: - a listener with `enabled = true` and none of `cert_file`/`key_file`, `self_signed`, `issuer_cert_file`/`issuer_key_file`, or more than one; an issuer that is no CA (`lw tls ca` makes one) - `pin_sha256` with `ca_file` or `insecure_skip_verify`, or not of the `sha256//BASE64` form; a listener key on a dialer, or `pin_sha256` on a listener - `client_auth = true` with no `client_ca_file` - a dialer with only one of `cert_file` / `key_file` - a certificate or key that will not load, or a CA file containing no certificates - a `min_version` that is neither `"1.2"` nor `"1.3"` - a key the plugin does not know, at any depth: `unknown key "tls.enabeld"`. A misspelled option must not silently leave a protection switched off ## The Auth Block TLS answers "is this channel private, and does the peer chain to a CA". Auth answers "may *this* peer do *this*". They are separate blocks because they are separate questions. ```toml [pipelines.plugin_sources.config.auth] # or plugin_sinks.config.auth type = "none" # none | mtls | scram identity = "cn" # cn | san_dns | san_uri | san_email allow = [] # mtls allow_patterns = [] # mtls node_binding = "force" # chain sources only credentials_file = "" # scram listeners token_lifetime_ms = 0 # scram, HTTP listeners; 10 s to 24 h, 0 = 15 minutes username = "" # scram dialers password_file = "" # scram dialers trusted_proxies = [] # scram http sink behind a TLS-terminating proxy ``` Options by where they apply, each with its default: - Every plugin - `type` (`none`): `none` ignores the block; `mtls` authorizes by certificate identity, `scram` by password. - Chain sources - `node_binding` (`force`): `none`, `assert` or `force`. - `mtls`, and `scram` listeners - `identity`: the certificate field carrying the identity; `cn` under `mtls`, unset under `scram`, where it binds the client certificate to the user. - `mtls` - `allow` (`[]`): exact identities to admit. - `allow_patterns` (`[]`): RE2 patterns matched against the identity; anchor them yourself. - `scram` listeners - `credentials_file`: verifiers written by [`lw auth add-user`](cli.md#lw-auth). - `token_lifetime_ms` (15 minutes): bearer token lifetime, 10 s to 24 h; the `http` sink and `http_chain` source only. - `trusted_proxies` (`[]`): addresses or CIDRs of the reverse proxies that end the browsers' TLS; the `http` sink only, see [Browsers behind a TLS-terminating proxy](#browsers-behind-a-tls-terminating-proxy). - `scram` dialers - `username`: user to log in as. - `password_file`: file holding the password; one trailing line break is trimmed. **Roles by plugin**, and what the block decides: - Listeners - `tcp_chain` and `http_chain` sources: which senders may ingest, and what node label their entries carry. - `tcp` and `http` sinks: which clients may read the stream (and, on `http`, the status endpoint). - Dialers: the `tcp_chain` and `http_chain` sinks. - `mtls`: which server identity to accept, beyond hostname verification. - `scram`: which user to log in as. ### Identity Under `mtls` the identity is one string pulled from the peer's verified leaf certificate; under `scram` it is the username. The handshake has already checked the chain, signature, and validity window, so this is pure field selection. Modes, each with the field it reads and its typical use: - `cn` (default): `Subject.CommonName`; matches the existing `tls_peer_cn` metadata. - `san_dns`: the first DNS SAN; host identities. - `san_uri`: the first URI SAN; SPIFFE-style IDs. - `san_email`: the first email SAN; operator identities. A certificate with no usable value in the chosen field is rejected. An empty identity is a refusal, not an empty match. ### The allow list `allow` is an exact-match set; `allow_patterns` holds RE2 patterns. An identity passes if it appears in either. Under `scram` the credentials file is the allow list, and both keys are refused. Leaving **both** empty under `type = "mtls"` admits any identity the CA vouches for. That is deliberate — it is how you enable node binding without enumerating a whole fleet — but it is announced rather than silent: ``` WARN msg="Auth policy admits any identity the configured CA vouches for" component=tcp_chain_source instance_id=in_tcp hint="set auth.allow or auth.allow_patterns to authorize named peers" ``` Anchor your patterns. `allow_patterns = ["edge-\\d{2}"]` matches `evil-edge-01-impostor`; `["^edge-\\d{2}$"]` does not. An unanchored pattern is reported at startup. ### Node binding `node_binding` applies only to the chain sources. `assert` and `force` take the connection label over from `trust_node`; only `force` also overrides the per-entry labels. - `none`: `trust_node` governs both the connection label and the per-entry `node` field. - `assert` - Connection label: must equal the identity; a mismatch or an omission is rejected. - Per-entry `node` field: `trust_node` governs. - `force` - Connection label: ignored; the identity is used. - Per-entry `node` field: overwritten with the identity. Use **`force`** on an ingest boundary you do not trust. Every entry is relabelled, so a compromised edge cannot smuggle a foreign origin through the per-entry `node` field either. It is the default whenever `type` is `mtls` or `scram`. Use **`assert`** on a relay-to-relay hop. The relay must prove its own identity — a mismatch fails loudly instead of being silently corrected — but the entries it forwards keep the origin labels stamped at the first hop, so multi-hop attribution survives. When binding is active the source says so at startup: ``` INFO msg="Node labels bound to peer identity; trust_node is ignored" component=tcp_chain_source node_binding=force trust_node=true ``` ### Dialer-side pinning Under `mtls`, the block on a chain sink pins the *server's* identity. Hostname verification already proves the server holds a certificate valid for the address you dialed; pinning additionally requires that certificate to name an identity you listed. ```toml [pipelines.plugin_sinks.config.auth] type = "mtls" allow = ["relay.internal"] ``` The check runs as part of the handshake, so a server the policy rejects never receives an entry — the sink's normal backoff loop handles it like any other connect failure. Under `scram` the dialer binds its login to the certificate it was shown instead; see [Channel binding](#channel-binding). ### Validation Misconfiguration fails at plugin construction, before the pipeline starts: - `type` `mtls` or `scram` without `tls.enabled` (proxy mode aside), or on a dialer with `tls.insecure_skip_verify`: an identity read from an unverified chain is a claim, and an unverified server could relay a login - `type = "mtls"` on a listener without `tls.client_auth` - a block naming peers or credentials (`allow`, `allow_patterns`, `credentials_file`, `token_lifetime_ms`, `username`, `password_file`, `trusted_proxies`) whose `type` is `none` or unset: auth was intended and the type forgotten - a key of the other method: `allow` or `allow_patterns` under `scram`, a `scram` key under `mtls` - a `scram` listener without a loadable `credentials_file` (see [Credentials file](#credentials-file)), with `username` or `password_file`, with a `token_lifetime_ms` outside 10 s to 24 h or on a TCP listener, or with `identity` but no `tls.client_auth` - a `scram` dialer without `username` and `password_file`, with `credentials_file`, `token_lifetime_ms`, `trusted_proxies` or `identity` (server pinning is `mtls` only), or with a password file that is empty or over 1024 bytes - `trusted_proxies` on anything but the `http` sink, with `identity`, or with an entry that is neither an address nor a CIDR; `login_page` or `viewer_page` without `trusted_proxies`, `viewer_page` without `login_page` - an `identity` that is not one of the four modes - an `allow_patterns` entry that does not compile - a `node_binding` that is not one of the three values, or one set on a plugin that has no node concept - an HTTP path (`stream_path`, `status_path`, `ingest_path`) equal to `/auth`, which is reserved for logins Errors read like `auth: type "mtls" requires tls.client_auth`. ## The ACL Block `acl`, beside `tls` and `auth` on the four listeners (`tcp` and `http` sinks, `tcp_chain` and `http_chain` sources), refuses peers by address as the socket is accepted: before the TLS handshake or a byte of the protocol, so a refused peer costs no handshake and never reaches `auth`. ```toml [pipelines.plugin_sources.config.acl] allow = ["192.0.2.0/24", "198.51.100.7"] # addresses or CIDRs; empty: all deny = ["192.0.2.66"] # refused, listed in allow or not proxy_protocol = "required" # off (default), optional, required proxy_from = ["10.0.0.5"] # L4 proxies sending PROXY headers max_connections_per_client = 4 # at once; 0 (default): no cap requests_per_second_per_client = 10 # HTTP listeners; 0 (default): none ``` - `deny` wins; then a non-empty `allow` admits only its entries, an empty one every address `deny` does not list. - Entries are of the listener's [family](networking.md#address-family): IPv4 on an IPv4 listener, IPv6 on an IPv6 one, either behind a hostname (only the family it binds ever matches). Behind `proxy_from` or the `http` sink's `trusted_proxies` they take either, as the proxy may name a client of either. An entry of the other family, an IPv4-mapped address, one with a zone, or anything but an address or CIDR fails construction. A link-local peer matches without its zone. - A refused connection is closed at once and counted in `acl_denied`, or `acl_limited` past a [limit](#per-client-limits) (plugin stats, the `http` sink's status). A WARN names the client, the reason and the counts, at most once a minute per listener; the refusals in between are only counted. - The rules see the client: the socket peer, or the client a PROXY header names. Behind the `http` sink's `trusted_proxies` they judge the L7 proxy as the peer, then each request's forwarded client (`403` when refused, counted in `acl_denied`): allow both. - The `serve` and `aggregator` presets take `allow` and `deny` list keys. - Dialers have no `acl`: on a `tcp_chain` or `http_chain` sink it is an unknown key. ### Per-client limits - `max_connections_per_client` caps the connections a client holds at once, on every listener; past it a connection is closed like a refused one. - HTTP keep-alive connections count, idle ones too, and a browser opens up to six; under HTTP/2 one connection carries a client's many requests. - Behind `trusted_proxies` every connection is the proxy's, so the key fails construction: cap clients at the proxy. - `requests_per_second_per_client`, on the `http` sink and the `http_chain` source, admits a second's worth of requests at once (at least one), refilled at that rate; past it a request gets `429`, with `Retry-After` the seconds until its next (1 at a rate of 1 or more). - Every request counts but the SCRAM exchange (`POST /auth`), which [throttling](#throttling) limits: stream, status, ingest and the viewer's files, about six for a viewer's first load. - A client is the address the rules see, an IPv6 one by its /64 and a link-local one per link, so the hosts of one /64 (a SLAAC LAN) share a budget; behind `trusted_proxies` the request rate counts the forwarded client. - Each limit tracks up to 65,536 clients, a client until its budget is whole again, and refuses new ones when full, failing closed. SCRAM throttling keeps its budgets the same way. ### PROXY protocol Behind an L4 proxy that passes TLS through (nginx `stream`, HAProxy `mode tcp`) every peer comes from the proxy's address. With `proxy_protocol` the proxy names the client in a PROXY header, v1 (text) or v2 (binary), sent before the TLS ClientHello; LogWisp still ends TLS, so channel binding and client certificates are unchanged. - `proxy_protocol` and `proxy_from` come together; `proxy_from` holds the proxies' addresses or CIDRs, of the listener's family. A peer with a zone (link-local IPv6) is never a proxy. - A peer in `proxy_from`: - sends its header within `tlsx.HandshakeTimeout` (10 s); a malformed, oversized (v1 over 107 bytes, a v2 block over 2048) or late one is refused; - under `required` is refused without a header; under `optional` it keeps its socket address, after up to 10 s if it sends nothing at first. A client the proxy forwards without a header then passes as the proxy, so `optional` (which warns at startup) suits only a rollout; set `required` once every route from `proxy_from` sends the header; - keeps its socket address for `LOCAL` (v2) and `UNKNOWN` (v1), the proxies' health checks, and for v2 families other than TCP over IPv4 and IPv6. TLVs are skipped. - Headers are read off the accept loop: a slow proxy holds only its own connection. - A peer not in `proxy_from` connects as itself; one that sends a header is refused at its first read, as any peer can write one. - The connection then reports the client (an IPv4-mapped one as IPv4) to the rules, SCRAM [throttling](#throttling), sessions and logs. Session metadata keeps the proxy as `peer_addr`, and a refusal's WARN names it. - `acl_proxy_headers` counts the headers read. - The `http` sink's proxy mode is the L7 counterpart: `trusted_proxies` trusts `X-Forwarded-For` from a proxy that ends TLS, `proxy_from` a PROXY header from one that passes it through. ## Startup Warnings Some settings work but are usually mistakes. Each plugin reports them at WARN when it is constructed, so startup and every reload repeat them: - a certificate in `cert_file`, `ca_file`, `client_ca_file` or `issuer_cert_file` that has expired, is not yet valid, or expires within 30 days - a self-signed listener, with the `pin_sha256` its dialers need - `insecure_skip_verify` on a dialer - an `allow_patterns` entry not anchored at both ends of every alternative (`^a|b$` admits `a…` and `…b`) - a `key_file`, `issuer_key_file`, `credentials_file` or `password_file` every local user can read (once per path per process) - an `acl` entry with host bits set (`10.0.0.1/8`), naming the network it matches; an `acl.allow` entry of a whole family (`0.0.0.0/0`, `::/0`); a wildcard listener whose `acl` has `deny` but no `allow`; an `acl.proxy_from` entry reaching beyond private, loopback and link-local addresses; `acl.proxy_protocol = "optional"` ## Certificates made at startup A listener needs no certificate files. With `self_signed = true`, or with `issuer_cert_file` and `issuer_key_file`, it makes an ECDSA P-256 key once per process and, at startup and every reload, a certificate for it valid 397 days (never past the issuer), for `hosts`, its `host` (unless a wildcard), `os.Hostname()`, `localhost`, `127.0.0.1` and `::1`. - **Self-signed.** No CA can vouch for it, so dialers pin its key: `pin_sha256`, which the listener logs at WARN on every start. A reload keeps the key and so the pin; a restart changes both, and every dialer must be given the new pin. Suits one aggregator and a few edges, a test, or a stream read by `curl --pinnedpubkey`. - **Issuer.** `lw tls ca` makes a CA once; the listener signs its own certificate with it, and dialers verify it with `ca_file = ca.crt`, by name, across restarts. The CA key then lives on the listener's host: give each listener group its own CA, or issue certificates elsewhere with `lw tls cert` and use `cert_file`. - **Pins.** A pin is the SHA-256 of the server's public key, not of its certificate, so it survives reissue. `pin_sha256` accepts several, `;` between them, for a rotation. It replaces chain, name and validity checks: whoever holds the key is the server. `scram` dialers still bind every login to that certificate. ```bash lw tls ca --dir /etc/logwisp/pki # ca.crt, ca.key (0600) lw tls cert --ca-dir /etc/logwisp/pki --name agg.example.org --server lw tls cert --ca-dir /etc/logwisp/pki --name edge-01 --client ``` ## Enabling mTLS ### 1. Generate a CA and certificates `lw tls` makes them ([above](#certificates-made-at-startup)); with `openssl`, `cfssl`, `step-cli` or an existing PKI: ```bash # CA openssl req -x509 -newkey rsa:4096 -nodes -days 3650 \ -keyout ca.key -out ca.crt -subj "/CN=LogWisp CA" # Relay (server) certificate — SAN must match how clients address it openssl req -newkey rsa:2048 -nodes -keyout relay.key -out relay.csr \ -subj "/CN=relay.internal" openssl x509 -req -in relay.csr -CA ca.crt -CAkey ca.key -CAcreateserial \ -out relay.crt -days 825 \ -extfile <(printf "subjectAltName=DNS:relay.internal\nextendedKeyUsage=serverAuth") # Edge (client) certificate — CN identifies the node openssl req -newkey rsa:2048 -nodes -keyout edge-01.key -out edge-01.csr \ -subj "/CN=edge-01" openssl x509 -req -in edge-01.csr -CA ca.crt -CAkey ca.key -CAcreateserial \ -out edge-01.crt -days 825 \ -extfile <(printf "extendedKeyUsage=clientAuth") ``` The server certificate's SAN must cover the address clients dial. Dialers seed `ServerName` from the configured `host`, so an IP literal in `host` requires an IP SAN, and a DNS name requires a DNS SAN. Override with `server_name` when the dialed address and the certificate name legitimately differ. ### 2. Configure the listener ```toml [pipelines.plugin_sources.config.tls] enabled = true cert_file = "/etc/logwisp/tls/relay.crt" key_file = "/etc/logwisp/tls/relay.key" client_auth = true client_ca_file = "/etc/logwisp/tls/ca.crt" min_version = "1.3" [pipelines.plugin_sources.config.auth] type = "mtls" allow = ["edge-01", "edge-02"] node_binding = "force" ``` Without the `auth` block the listener accepts every certificate the CA issued. With it, only `edge-01` and `edge-02` may ingest, and their entries are labelled from their certificates rather than from whatever they declare. ### 3. Configure the dialer ```toml [pipelines.plugin_sinks.config.tls] enabled = true ca_file = "/etc/logwisp/tls/ca.crt" cert_file = "/etc/logwisp/tls/edge-01.crt" key_file = "/etc/logwisp/tls/edge-01.key" min_version = "1.3" [pipelines.plugin_sinks.config.auth] type = "mtls" allow = ["relay.internal"] ``` ### 4. Verify Startup logs report the transport flags and the compiled policy: ``` INFO msg="TCP chain source initialized" ... tls=true mtls=true auth="mtls identity=cn allow=[2 exact, 0 pattern(s)] node_binding=force" INFO msg="TCP chain sink initialized" ... tls=true mtls=true auth="mtls identity=cn allow=[1 exact, 0 pattern(s)] node_binding=none" ``` A client that presents no certificate is refused during the handshake (`tls: client didn't provide a certificate`, counted in `tls_handshake_errors`). A client whose certificate is valid but whose identity is not authorized gets past the handshake and is refused by the policy: ``` WARN msg="Connection rejected by auth policy" component=tcp_chain_source remote_addr= error="auth: refused: identity \"edge-99\" is not allowed" ``` Policy rejections are counted in the plugin's `auth_rejected` statistic; the `http` sink's status endpoint reports its own. Accepted peers are recorded in session metadata as `auth_method` and `auth_identity`. `test/mtls-chain-test.sh` builds a throwaway PKI and exercises the whole surface end to end — run it with `--auto` to see each guarantee asserted. ## Password Authentication (SCRAM) `type = "scram"` authenticates peers by username and password with Argon2id-SCRAM from `lixenwraith/auth`. It needs TLS but no client certificates, works on all six network plugins, and is LogWisp's own protocol, not standard SASL: viewers use the [`lw auth`](cli.md#lw-auth) CLI or, behind a TLS-terminating proxy, the shipped browser client. ```toml # Listener: tcp_chain/http_chain source, tcp/http sink [pipelines.plugin_sources.config.tls] enabled = true cert_file = "/etc/logwisp/tls/relay.crt" key_file = "/etc/logwisp/tls/relay.key" [pipelines.plugin_sources.config.auth] type = "scram" credentials_file = "/etc/logwisp/users.toml" # Dialer: tcp_chain/http_chain sink [pipelines.plugin_sinks.config.tls] enabled = true ca_file = "/etc/logwisp/tls/ca.crt" [pipelines.plugin_sinks.config.auth] type = "scram" username = "edge-01" password_file = "/etc/logwisp/edge-01.pass" ``` Startup reports `auth="scram users=2 certificate=independent node_binding=force"` on such a chain source, and `auth="scram user=edge-01"` on the dialer. ### Mechanism For each user the listener keeps a salt, the Argon2id cost, and two keys derived from `K = Argon2id(password, salt)`: `StoredKey = SHA-256(HMAC(K, "Client Key"))` and `ServerKey = HMAC(K, "Server Key")`. Neither logs anyone in, but each password guess against them costs one Argon2id, so keep the file private. Checking a login is HMAC work only; Argon2id (3 passes, 64 MiB, 4 threads) runs on the dialer or the CLI. The proof is mutual: the dialer accepts the server's final message only when it is signed with this user's `ServerKey`, and it refuses a challenge asking for less Argon2 work than those defaults, so a rogue server cannot request a cheaply crackable proof. An unknown user gets a stable decoy challenge and fails exactly like a wrong password: `authentication failed`. ### Channel binding Both sides bind the proof to the SHA-256 of the listener's leaf certificate: the listener hashes the certificate it serves, the dialer the one it was shown. A TLS-terminating proxy or interceptor shows another certificate — CA-valid or not — so the proof fails and the relay never obtains a link or a token. The dialer is told `authentication failed` either way; the listener compares the hash the dialer reports, logs `the client saw another server certificate: TLS interception or a terminating proxy`, and counts `auth_binding_mismatch`. An HTTP login takes two requests, and every later request may open a new pooled connection. After the challenge the dialer pins the certificate it was bound to: the proof and every ingest request must meet the same certificate, or the TLS handshake fails before anything is sent. The `http_chain` sink then drops token and pin and logs in again, which also covers a rotated server certificate. A token printed by `lw auth token` is not pinned. ### Certificates and users `tls.client_auth` is optional under `scram`, and on its own independent of the password: a peer needs *some* certificate the CA issued and *some* valid password, like PostgreSQL's `clientcert=verify-ca`. Setting `identity` (which requires `tls.client_auth`) binds the two: the certificate's identity field must equal the username, so every peer needs its own certificate *and* its own password, like `clientcert=verify-full`. A mismatch fails the login; an HTTP request whose certificate does not match its token's user gets `403`. Startup shows the mode as `certificate=independent` or `certificate=cn=username`. ### Tokens The `http` sink and `http_chain` source answer a login at `POST /auth` with a bearer token: an HS256 JWT valid for `token_lifetime_ms` (default 15 minutes) and signed with a key drawn when the plugin is built, so **every reload revokes every token** (a rejected reload keeps the running service and its tokens). A missing, invalid or expired token gets `401` with `WWW-Authenticate: Bearer realm="logwisp"`. An SSE stream is checked when it connects and then outlives its token; a reload ends it. TCP has no tokens: each connection runs its own exchange. ### Throttling Logins are throttled per client (an IPv6 client per /64): the socket peer, the client a [PROXY header](#proxy-protocol) names, or on an `http` sink in proxy mode the forwarded client; forwarded headers are read only from `trusted_proxies`. Each exchange takes a token from a bucket of 10 that refills at one per second, and a successful login gives it back, so only failed or abandoned attempts drain it. At most 4 exchanges per address may be unfinished: an HTTP challenge never answered holds its slot for up to 30 s, a TCP connection that ends mid-exchange frees it at once. A refused start answers `too many attempts` (HTTP `429`) and counts `auth_throttled`; the table holds 65,536 addresses and refuses new ones when full. Separately, at most 4,096 exchanges may be in flight per listener; beyond that, or while the plugin stops, a login gets `busy` (HTTP `503`) and counts `auth_busy`. Peers behind one NAT, or one passthrough proxy that sends no PROXY header, share a bucket: there, one client can exhaust every other client's logins. ### Credentials file ```toml # logwisp SCRAM verifiers, written by `lw auth add-user`. Keep it private. decoy_key = "" [[users]] argon_memory = 65536 argon_threads = 4 argon_time = 3 salt = "" server_key = "" stored_key = "" username = "edge-01" ``` Write it with [`lw auth add-user`](cli.md#lw-auth) rather than by hand. The whole file is validated when the plugin is built: a `decoy_key` of at least 32 bytes, at least one user, unique names, no unknown keys, and one Argon2 profile and salt length for every user, since mixed profiles would tell a prober which users exist. `decoy_key` keeps unknown-user challenges stable across restarts and edits; the CLI creates it once and preserves it. A single probe cannot tell a real user from an unknown one, but a prober polling a name sees its salt change when the user is added, rotated or removed. The file is read only when the plugin is built and `auto_reload` does not watch it: send `SIGHUP` after every change. Use one file per listener when listeners admit different users. ### Rollout, rotation and revocation - **Rollout.** Turning `scram` on cuts off every dialer of that listener that has no credentials. Upgrade every binary first, then add a second listener with `scram` on another port, move the dialers to it, and remove the old one. - **Password rotation.** `lw auth add-user --generate` with the user's `--password-file` replaces verifier and password together. `SIGHUP` the listener, deploy the password file, `SIGHUP` the dialer. Logins fail in between and the dialer retries under backoff, holding its current entry or batch while its input queue fills. To avoid the gap, add a second user, move the dialer to it, then remove the first; under `node_binding = "force"` the node label follows the username. - **Revocation.** `lw auth remove-user`, then `SIGHUP`. The reload drops every connection and revokes every token; other dialers log in again on their own. ### Limits - TLS must terminate at LogWisp, except on an `http` sink in proxy mode. Behind any other terminating proxy or load balancer every login fails by design; pass TLS through instead (TCP or SNI routing), with a [PROXY header](#proxy-protocol) so each client keeps its own throttling budget. - One process per HTTP address. Handshake state and the token key live in one instance, so behind a balancer the proof or the token can reach an instance that never saw the login. - Browsers log in only to an `http` sink in proxy mode, below; elsewhere use `mtls` for browsers. - `nc` and `openssl s_client` cannot read a `scram` `tcp` sink; use `lw auth stream`. `test/scram-chain-test.sh --auto` exercises these guarantees end to end. ### Browsers behind a TLS-terminating proxy A site that serves the log stream inside its own pages ends TLS at its reverse proxy and need not give LogWisp a private key. `trusted_proxies` puts the `http` sink in proxy mode, where browsers log in with the client LogWisp ships; the password reaches neither the proxy nor LogWisp. ```toml [pipelines.plugin_sinks.config] host = "127.0.0.1" port = 8081 login_page = true # GET /auth/login viewer_page = true # GET /auth/view, needs login_page [pipelines.plugin_sinks.config.auth] type = "scram" credentials_file = "/etc/logwisp/users.toml" trusted_proxies = ["127.0.0.1"] # addresses or CIDRs ``` ```nginx location /logs/ { proxy_pass http://127.0.0.1:8081/; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } ``` - **Trust.** Every other peer gets `403` on every path. `X-Forwarded-Proto` must be `https` on every hop, so a site accidentally served in plaintext fails closed. The client is the rightmost `X-Forwarded-For` hop that is not a proxy; throttling, sessions and logs use it. List only the proxies: a client inside a listed range is trusted to name its own hops. - **Unbound logins.** The browser cannot see a certificate LogWisp could bind to, so proofs are unbound and a party on the hop between proxy and LogWisp could relay a login. Keep that hop on loopback or a trusted network, or enable `tls` on the sink; a plaintext hop to a proxy off this host is warned about at startup. `identity` cannot be combined with proxy mode. - **Sessions.** The login page asks for a cookie: `logwisp_session`, `HttpOnly`, `Secure`, `SameSite=Strict`, `Max-Age` the token lifetime, and no `Path`, so it scopes itself to the mount (`/logs` above). Stream and status accept it or a bearer token, so `new EventSource("/logs/stream")` works on any page of the site, beside the site's own Basic auth too, and `lw auth token --unbound` keeps working. `POST /auth` with `{"logout": true}` clears the cookie and revokes the token until it expires. `/auth` takes only `application/json`, which a cross-origin page cannot send without a preflight. - **Private windows.** Private or incognito windows keep cookies in memory, apart from normal windows: they sign in on their own, and the session ends at the token lifetime or when the last private window closes. - **Cookies disabled.** The viewer runs in token mode when the browser keeps no cookie for the site. - It notices from `navigator.cookieEnabled`, from a throwaway cookie with the session's attributes that does not come back (Chromium blocking every cookie still reports `cookieEnabled`), or from a `401` right after a cookie login, and shows its own sign-in form. - The token lives in a page variable only, never in storage or the URL. It lasts as long as the page and at most the token lifetime: a reload, another tab, or a reconnect after expiry asks again; sign out revokes it. - The login page says that cookies are unavailable and links to the viewer. A page not served over HTTPS keeps no `Secure` cookie either: both pages name HTTPS instead and offer no sign-in. - **Integrating `scram.js`.** A site with its own CSP can copy `scram.js` from `internal/sink/http/web/` into its bundle: one dependency-free ES module, where `base` is the mount URL ending in `/`. It needs a secure context for WebCrypto and takes about 2 s of Argon2 per login on a desktop. - Cookie mode, the default: `login(base, username, password, {onProgress})`, then `EventSource` and `fetch` as for any same-origin resource; `logout(base)`. - Token mode: `login(..., {session: "token"})` resolves to `{username, expiresIn, token}`. Keep the token in memory; `stream(url, {token, signal, onEvent})` reads the event stream through `fetch` with the bearer, status takes `Authorization: Bearer`, and `logout(base, {token})` revokes it. The bearer replaces the Basic credentials a browser would send, so token mode cannot pass a proxy that asks for its own Basic auth. - `cookiesUsable()` tells which applies: false when the session cookie would not stick. `loginUnavailable()`, asked first, names why neither can run (no secure context), or is empty. - **Pages.** Under `/auth/` the sink serves `scram.js` and `style.css` always, and with `login_page` / `viewer_page` the login page and a minimal live viewer with their scripts; `GET /` leads to the viewer, else the login page. All are served under `default-src 'none'; script-src 'self'; connect-src 'self'; style-src 'self'; form-action 'self'; frame-ancestors 'none'; base-uri 'none'`. `test/scram-proxy-test.sh --auto` logs in from headless Chromium through such a proxy, with cookies and with every cookie blocked. ### Behind nginx or another proxy A proxy in front of LogWisp works at one of two layers: - **L7, ending TLS** (nginx `http` block, HAProxy `mode http`): the `http` sink in [proxy mode](#browsers-behind-a-tls-terminating-proxy). - `trusted_proxies` lists the proxy's address. - The proxy sends `X-Forwarded-Proto: https` and `X-Forwarded-For`. It may overwrite `X-Forwarded-For` with the real client: the rightmost hop that is not a proxy is the client either way. - **L4, passing TLS through to LogWisp's own TLS** (nginx `stream` with `ssl_preread`, HAProxy `mode tcp`), with a [PROXY header](#proxy-protocol): whatever needs TLS to end at LogWisp. - Chain links (`tcp_chain`, `http_chain`). - `lw auth stream` viewers of a `tcp` sink. - An `http` sink that keeps its own TLS, and with it SCRAM channel binding or client certificates. A common shape serves both from port 443: ``` :443 nginx stream: ssl_preread routes by SNI, proxy_protocol on logs.example.org -> 127.0.0.1:8443 nginx http relay.example.org -> a LogWisp TLS listener, which reads the header (below) 127.0.0.1:8443 nginx http: listens with proxy_protocol, ends TLS /logs/ -> 127.0.0.1:8081 LogWisp http sink, proxy mode ``` **The `http` sink behind the `http` block** works in proxy mode as is: `trusted_proxies` is the `http` block's address, usually `127.0.0.1`, and the block names the client from the PROXY header. ```nginx server { listen 127.0.0.1:8443 ssl proxy_protocol; server_name logs.example.org; # ssl_certificate, ssl_certificate_key: the site's own location /logs/ { proxy_pass http://127.0.0.1:8081/; proxy_set_header X-Real-IP $proxy_protocol_addr; proxy_set_header X-Forwarded-For $proxy_protocol_addr; proxy_set_header X-Forwarded-Proto https; } } ``` `$proxy_add_x_forwarded_for` does not fit this shape: it appends the stream server's address, not the client's. LogWisp would name that address as every client or, when it is trusted (both on `127.0.0.1`), the hop to its left: one the client wrote, so the client picks its own throttling address. LogWisp ignores `X-Real-IP`. **LogWisp's own TLS listeners read the header** when their `acl` sets `proxy_protocol` and lists the stream server in `proxy_from`; one stream `server` with `proxy_protocol on` then routes every name: ```nginx stream { map $ssl_preread_server_name $route { relay.example.org 127.0.0.1:9001; # tcp_chain source tail.example.org 127.0.0.1:9002; # tcp sink, for lw auth stream default 127.0.0.1:8443; # the http block, logs.example.org } server { listen 443; ssl_preread on; proxy_protocol on; proxy_pass $route; } } ``` ```toml [pipelines.plugin_sources.config.acl] # tcp_chain source; tcp sink alike proxy_protocol = "required" proxy_from = ["127.0.0.1"] # the stream server ``` - HAProxy: `send-proxy` or `send-proxy-v2` on the LogWisp backends. - A listener without `proxy_protocol` behind such a route fails every connection: the header lands in front of its TLS handshake. - Dialers must send the name: a `host` that is one, or `tls.server_name` (`--server-name` for `lw auth`); an IP literal sends no SNI. - `test/acl-test.sh --auto` runs each listener kind behind a stub proxy sending a v1 or v2 header, and the `tcp` sink behind nginx when installed. **Passthrough without PROXY** brings every peer from the proxy's address: - All peers share one SCRAM [throttling](#throttling) budget: 10 failed or abandoned logins, then one per second, and 4 unfinished at once. One client that keeps failing logins makes every other client's logins answer `too many attempts` until it stops. - Established `tcp_chain` links and open streams keep flowing; a reconnect waits for the budget. An `http_chain` sink whose early renewal is put off (`too many attempts` or `busy`) keeps sending on its token to the server it pinned, retrying every few seconds, and holds its batches only once that token has expired; any other refusal ends the token at once. - Logs and sessions name the proxy, and `acl` rules see only the proxy: allow it, not the clients. ## What Each Layer Enforces **`tls` with `client_auth = true`** — a membership check. The peer holds a certificate chaining to `client_ca_file`, within its validity window, and holds the matching private key. Every CA-issued certificate is equivalent at this layer. **`auth` with `type = "mtls"`** — an identity check, per listener: only the identities you list may connect, so one CA can serve several trust domains and a single peer can be withdrawn without touching the others. **`auth` with `type = "scram"`** — a password check, per listener: only the users in its credentials file may connect, the login cannot be relayed through another certificate (proxy mode, where TLS ends at the site's proxy, aside), and with `identity` each user is tied to its own certificate. Under either method the chain `node` label can be bound to the identity, so a compromised edge cannot attribute its entries to another host, and the `http` sink's stream and status endpoints stop being open to anyone who can reach the port. **`acl`** — an address check, per listener, before TLS: it narrows who can reach the other layers and how much each address may take, never proves who a peer is. **Revocation** is the allow-list or the credentials file, not a CRL. Remove the identity or user and send `SIGHUP`: the reload rebuilds every pipeline, so the change takes effect on the next connection and existing ones are dropped by the rebuild. No network call on the handshake path, and no window between revocation and the next CRL publication. See [mtls-auth-plan.md](mtls-auth-plan.md#not-implemented) for what CRL support would add. ## Surfaces Without Access Control An `auth` block (`mtls` or `scram`) closes each of these. Without one, bind them to a trusted interface, front them with an authenticating proxy, or narrow them to known networks with `acl.allow`. What each exposes when `auth.type = "none"`: - `http` sink `stream_path`: the full log stream, with `Access-Control-Allow-Origin: *`, so any browser origin can read it (the header is omitted once an auth policy is set). - `http` sink `status_path`: host, port, TLS flag, uptime, client counts, throughput counters. - `http` sink `GET /` (`303` to `/auth/view`) and the viewer's files: static pages that read the two endpoints above under the CSP and expose nothing beyond them. Under `mtls` they are served before the allow list, while the stream and status stay gated. - `tcp` sink: the full log stream to any client that connects. - `tcp_chain` and `http_chain` sources: ingest from any peer that can connect (with `client_auth`, any the CA vouches for), under any node label it claims. `max_connections` bounds concurrency on all but the `http_chain` source; the `acl` block's [per-client limits](#per-client-limits) bound each caller's share. Both methods require TLS on the listener, except an `http` sink in proxy mode, where TLS ends at the trusted proxy; `mtls` also requires `client_auth`. ## Operational Guidance **Certificates and secrets** - Use a dedicated CA for LogWisp so its trust decisions stay independent. - Keep leaf lifetimes short (90–825 days) and automate renewal. - Key, credentials and password files should be `0600` and owned by the service account; a world-readable one is reported at startup. `lw auth` creates them `0600` and keeps the mode of an existing file. - Rotation requires a reload (`SIGHUP`), because certificates and credentials are loaded once at plugin construction; there is no on-disk watch for them. - Startup and every reload warn 30 days before a certificate lapses. Still automate renewal; the warning only reaches someone reading the log. - Keep the identity field you authorize on stable across rotations. Reissuing a leaf with a different CN silently drops the peer out of the allow list. **Deployment** - Prefer `min_version = "1.3"`. Drop to `"1.2"` only for a peer that genuinely cannot do 1.3. - Never enable `insecure_skip_verify` outside a lab; it disables server verification entirely and makes the connection trivially interceptable. It is reported at startup. - Bind listeners to specific interfaces rather than `0.0.0.0` where you can. - On any ingest port reachable from a network you do not fully control, set an `auth` block: `mtls` with an explicit `allow` list, or `scram`. `trust_node = false` is the fallback when neither is an option; it is unforgeable but labels entries by remote address, which is useless behind NAT or a load balancer. - Run LogWisp as an unprivileged user with write access only to its own log and configuration directories. **Log content** Logs routinely contain secrets that were never meant to leave the host. Filters are the available tool: ```toml [[pipelines.flow.filters]] type = "exclude" patterns = ["password", "api[_-]?key", "authorization", "bearer ", "secret"] ``` Choose a sanitizer policy that matches the sink — `json` for JSON output, `txt` for files and consoles — so control characters in log data cannot break framing or inject terminal escapes downstream. See [Formatters](formatters.md). The `raw` format passes control characters through. A console sink writing to a terminal escapes them itself (`escape = "auto"`), so a log line cannot move the cursor, retitle the window, write the clipboard (OSC 52) or reorder text with bidi controls; pipes and files get the bytes unchanged. See [Sinks](sinks.md#console).