# Password Authentication (Argon2id-SCRAM) **Status:** planned. Ships in two batches: 1. **Done:** `lixenwraith/auth` gained SCRAM channel binding, and the mTLS layer was hardened (see [mTLS Hardening](#mtls-hardening)). 2. **Next:** the SCRAM integration described here, pinned to the tagged `auth` release that carries channel binding. **Scope:** optional username/password authentication on every network plugin, next to the existing certificate method, without weakening what mTLS gives. ## Goals - Password authentication for chain links (`tcp_chain`, `http_chain`: sources verify, sinks present) and for viewers of the `tcp` and `http` sinks. - No password or password-equivalent on the wire, no KDF work on listeners, and no credential relay through a TLS-terminating MITM. - Default stays `auth.type = "none"`; existing configurations are unaffected. - Config in TOML, credential management and viewer clients in a `logwisp auth` CLI. ## Non-Goals - Standard SASL SCRAM-SHA-256 interoperability. The `auth` exchange is logwisp-to-logwisp (or logwisp CLI) only. - Browser `EventSource` viewers under SCRAM: they cannot set `Authorization` or run Argon2. mTLS remains the browser path. - Multiple backends behind a non-sticky L7 balancer: handshake state and the token key live in one process. ## Mechanism `lixenwraith/auth` Argon2id-SCRAM. The listener stores a verifier per user: `StoredKey = SHA-256(HMAC(K, "Client Key"))`, `ServerKey = HMAC(K, "Server Key")`, `K = Argon2id(password, salt)`. The Argon2id digest itself is never stored: it is the salted password, from which both keys derive. Verifying a proof is HMAC only; Argon2 runs on the dialer or CLI (64 MiB, t=3, the `auth` defaults). **Channel binding.** Both peers pass `auth.WithChannelBinding(SHA-256(server leaf DER))` at the proof step. The server hashes its configured certificate; the client hashes the certificate it saw. A relay presenting any other certificate, even one the CA trusts, makes the server reject the proof, so it never obtains a link or a token. A mismatch is indistinguishable from a wrong password by design; the client also sends its hash as a diagnostic field so the listener can log "TLS interception or terminating proxy" and count it. TLS must terminate at logwisp. **HTTP pinning.** HTTP auth takes two requests and every later request may use a new pooled connection, so binding the exchange is not enough. After step 1 the dialer pins the bound hash on its `VerifyConnection`: step 2 and every ingest request must present the same leaf. A mismatch clears token and pin and re-authenticates, which also covers certificate rotation. A token handed to curl by the CLI is unpinned. ## Configuration ```toml # listener (tcp_chain/http_chain source, tcp/http sink) [pipelines.plugin_sources.config.auth] type = "scram" credentials_file = "/etc/logwisp/users.toml" token_lifetime_ms = 900000 # http sink and http_chain source only node_binding = "force" # chain sources; binds to the username # dialer (tcp_chain/http_chain sink) [pipelines.plugin_sinks.config.auth] type = "scram" username = "edge-01" password_file = "/etc/logwisp/edge-01.pass" ``` Validation at construction: - `scram` requires TLS; a dialer also forbids `insecure_skip_verify`. - Listeners require `credentials_file` and reject `allow`/`allow_patterns`: the credentials file is the allow list. Use one file per listener when listeners admit different users. - Dialers require `username` + `password_file`, and reject `credentials_file`, `allow*` and `identity` (server pinning stays an mTLS feature). - `identity` on a listener requires `tls.client_auth` and **binds the certificate to the user**: the certificate's identity field must equal the SCRAM username, so a peer needs its own certificate and its own password (PostgreSQL's `clientcert=verify-full`). Without it the factors are independent: any CA-issued certificate plus any valid password (`clientcert=verify-ca`). - `token_lifetime_ms` only on HTTP listeners; default 15 minutes. - `/auth` is reserved; no configured path may equal it. **Credentials file** (TOML, written by the CLI, mode 0600): ```toml decoy_key = "" [[users]] username = "edge-01" salt = "" argon_time = 3 argon_memory = 65536 argon_threads = 4 stored_key = "" server_key = "" ``` `decoy_key` keeps unknown-user challenges stable across restarts and edits, so probing usernames reveals nothing. It is created by the first `add-user` and preserved by every rewrite. An empty user set, a duplicate user, a missing `decoy_key` or mixed KDF profiles are configuration errors. The file is read at construction; the SCRAM server starts in the plugin's `Start` and stops in `Stop`, so a rejected reload leaks nothing. ## Wire Protocol `chain.Hello` gains `scram` (raw JSON, decoded by `authz`); the protocol version stays 1 because the field is additive. Every message after the hello is one `authStep`: `error`, `challenge`, `proof` (+ `binding`), `final` (+ `token`, `expires_in` on HTTP). Pre-auth lines are capped at 4 KiB. **TCP** (`tcp_chain`, `tcp` sink): hello carrying the client-first message, challenge, proof, final — all under one deadline (`hello_timeout_ms` on the `tcp_chain` source, 10 s on the `tcp` sink and every dialer, with the dialer's context able to cut it short). The final is written only after every admission check (certificate binding, node binding); the stream then continues on the same buffered reader. A source without SCRAM answers a hello carrying credentials with `error: authentication not enabled`; only an old binary stays silent, and the dialer's deadline covers that. **HTTP** (`http_chain` source, `http` sink): `POST /auth`, outside the auth middleware, with its own 10 s read/write deadline and a 4 KiB body limit. | Step | Request body | Success | Failure | |------|--------------|---------|---------| | 1 | hello | `200` challenge | `429` throttled, `503` handshake table full, `400` malformed | | 2 | proof | `200` final, token, expires_in | `401 {"error":"authentication failed"}` | Protected endpoints take `Authorization: Bearer `: missing or invalid is `401` with `WWW-Authenticate: Bearer realm="logwisp"`, a certificate-binding miss is `403`. Tokens are HS256 JWTs from `auth.NewJWT` with a random per-instance key, so every reload revokes them. An SSE stream is checked at connect and outlives its token; a reload ends it. **Dialer outcomes** (`http_chain` sink): every `/auth` failure is transient (the batch is held under backoff); `404`/`405` from `/auth` logs "no auth endpoint: older logwisp or auth.type is not scram"; an ingest `401` clears the token and is retried; `403` drops the batch; a pin mismatch clears token and pin. Rejections are logged at WARN once per change of state and counted in `auth_failures` / `last_auth_error`. ## Throttling Per remote IP (the socket address, never a forwarded header), on handshake starts: a token bucket (burst 10, 1/s) refunded on success, and at most 4 unfinished exchanges. The table is bounded and fails closed when full. Abandoned TCP exchanges release their slot in the `auth` handshake table immediately. Counters: `auth_allowed` and `auth_rejected` once per exchange outcome; `auth_throttled`, `auth_busy` and `auth_binding_mismatch` separately. ## The `authz` Seam Listeners never call `Authorize` directly any more; one entry point per transport decides, and `Authorize` itself refuses under `scram` so a missed call site fails closed. - `Admit(conn, cs, wantHello, timeout)` returns an admission (identity, hello, reader) whose `Accept` or `Reject` writes the final message. - `AuthorizeRequest(r)` covers mTLS certificates and bearer tokens; `ServeAuth(w, r)` serves `/auth`. - Dialers: `Greet(ctx, conn, node)` writes the hello (plain or SCRAM); `Authenticate`, `SetAuthorization`, `ClearToken` and `VerifyConnection` serve HTTP. - `Start`/`Close` bracket the SCRAM server and are nil-safe like everything else. ## CLI ``` logwisp auth add-user -credentials F -user U [-password-file P] [-generate] logwisp auth remove-user -credentials F -user U logwisp auth token -url https://host:port -user U -password-file P [TLS flags] logwisp auth stream -addr host:port -user U -password-file P [TLS flags] ``` - `add-user` takes the password from `-password-file` when it exists; a new user without one gets a generated 130-bit password, written to that file (0600) or printed once. Rotating an existing user needs the file or `-generate`, so a mistyped path cannot replace a password. The file's KDF profile and decoy key are reused, the result is validated with the daemon's own loader, and the rewrite (temp file in the same directory, rename) keeps the existing mode and owner. - `remove-user` refuses to remove the last user. - Both print that changes apply on `SIGHUP`: `auto_reload` does not watch the credentials file. - `token` prints a bearer token for curl (`-H @<(...)` keeps it out of argv); `stream` authenticates to a `tcp` sink and copies the stream to stdout. - TLS flags: `-ca-file`, `-server-name`, `-cert-file`, `-key-file`. There is no insecure flag. ## Rollout and Rotation - Turning SCRAM on is per listener and cuts off unconfigured dialers. To migrate without a gap, upgrade binaries, add a second SCRAM listener, move dialers, then remove the old listener. - Password rotation: `add-user -generate`, `SIGHUP` the listener, deploy the new password file, `SIGHUP` the dialer. The dialer retries under backoff in between. - Revocation: `remove-user`, `SIGHUP`. All tokens die with the reload. ## Verification Go tests, one per rule: binding (match, mismatch, one-sided, length) in `auth`; in `authz` the validation table, credential loading, decoy stability across edits, TCP exchange over `net.Pipe` (success, wrong password equals unknown user, binding mismatch, missing hello, silent peer within the deadline, abandoned exchange frees its slot, final and first entry in one write, assert mismatch gets an error rather than a final), HTTP exchange on a TLS test server (token accepted, garbage and foreign tokens `401`, forged final yields no token, a different certificate after step 1 refused before the body is sent), the limiter bound; `http_chain` sink re-authentication and outcome table; CLI add/remove/rotate, mode preservation, last-user refusal, password trimming. `test/scram-chain-test.sh --auto` (ports 15821-15825): a relay with SCRAM on all four listener types plus one `client_auth` + SCRAM port; authorized edges over both chain transports; node labels forced to usernames; wrong password, unknown user and no-auth edges deliver nothing; a `tcp` sink viewer through `logwisp auth stream` held past the exchange deadline; a raw TLS client without a hello gets nothing; the `http` sink through `logwisp auth token` and curl; missing and bad tokens get `401`; `remove-user` + `SIGHUP` revokes token and login; throttling last. The existing scripts keep passing. ## mTLS Hardening Shipped with this plan, independent of SCRAM: - The `http_chain` sink no longer follows redirects. Go's client resends the body on a 307/308, including from `https` to plaintext `http`. - Its response drain is bounded (64 KiB). - The `tcp` sink tracks connections from accept, so `Stop` and reloads no longer wait out the 10 s handshake timeout of a silent peer. - Unknown keys in any plugin's config, at any depth, fail construction: a typo such as `[...tls] enabeld = true` used to switch protection off silently. - Startup and every reload warn about certificates that expired, are not yet valid, or expire within 30 days; about `insecure_skip_verify`; about `allow_patterns` that are not anchored at both ends of every alternative; and, once per path, about key files every local user can read. - An `http` sink with an auth policy no longer sends `Access-Control-Allow-Origin: *`.