From ed1c15929d2eb2dbc6432986c26661bf1549964a Mon Sep 17 00:00:00 2001 From: Anders Betts Date: Thu, 17 Sep 2026 21:26:20 +0200 Subject: Add native TLS transport, TLS clients and lego cert sidecar - bokfd: optional TLS listener (OpenSSL), certificate reload on change - clients: tls:host:port targets with chain and host verification - compose: port 8788 and an INWX/lego renewal sidecar - Makefile: header dependency tracking (-MMD -MP) --- docs/PROTOCOL.md | 32 +++++++++++++++++++++----------- 1 file changed, 21 insertions(+), 11 deletions(-) (limited to 'docs/PROTOCOL.md') diff --git a/docs/PROTOCOL.md b/docs/PROTOCOL.md index 6dc8c7b..e9c4331 100644 --- a/docs/PROTOCOL.md +++ b/docs/PROTOCOL.md @@ -41,15 +41,20 @@ by the daemon (`backup.snapshot`), not by clients. first line of defense. - Intended for `bokftui`, `bokfctl` and agents running on the same host. -### 3.2 TCP (optional) - -- Disabled by default. When enabled it binds `127.0.0.1` unless explicitly - configured otherwise. -- TLS is **not implemented in v1**. The intended deployments are: - - loopback + SSH tunnel (`ssh -L`), or - - a private overlay network (Tailscale/WireGuard), or - - a reverse proxy that terminates TLS in front of `bokfd`. -- Every command on TCP requires authentication, including read commands. +### 3.2 TCP and TLS (optional) + +- Plain TCP is disabled by default. When enabled it binds `127.0.0.1` unless + explicitly configured otherwise. It is intended for loopback, an SSH + tunnel (`ssh -L`) or a private overlay network (Tailscale/WireGuard). +- A separate TLS listener (`tls`, e.g. `0.0.0.0:8788`) serves exactly the + same protocol over TLS 1.2+ using a PEM certificate chain and key + (`tls_cert`, `tls_key`). The daemon reloads the certificate when the files + change, so an ACME renewer can replace them without a restart. +- Clients select the transport with `BOKFD_SOCKET`/`--socket`: a Unix socket + path, `tcp:host:port` or `tls:host:port`. The TLS client verifies the + certificate chain and host name against the system trust store; + `BOKFD_TLS_CA` adds a PEM file for private CAs. +- Every TCP/TLS command requires authentication, including read commands. `meta` and `health` are the only unauthenticated commands. ### 3.3 Framing @@ -434,7 +439,9 @@ beyond the session and calls nothing but public commands. ## 10. Security notes - Bind nothing publicly by default. Loopback or Unix socket unless the operator - opts in. + opts in; use the TLS listener when clients connect from outside the LAN and + forward only that port. Each person or agent gets their own account or + token, never VPN access to the host network. - Passwords: Argon2id (vendored reference implementation). Tokens: 256-bit random, stored hashed, revocable, never logged. Sessions: memory only. - Audit and logs redact secrets: `session.open` records username and outcome, @@ -453,7 +460,10 @@ beyond the session and calls nothing but public commands. | Key | Default | Meaning | |---|---|---| | `socket` | `/run/bokfd/bokfd.sock` | Unix socket path | -| `tcp` | off | `host:port` to enable TCP | +| `tcp` | off | `host:port` to enable plain TCP | +| `tls` | off | `host:port` to enable the TLS listener | +| `tls_cert` | `/var/lib/bokfd/certs/fullchain.pem` | PEM certificate chain | +| `tls_key` | `/var/lib/bokfd/certs/privkey.pem` | PEM private key | | `db` | `/var/lib/bokfd/bokfd.db` | SQLite database | | `backup_dir` | `/var/lib/bokfd/backup` | destination for `backup.snapshot` | | `export_dir` | `/var/lib/bokfd/export` | SIE exports | -- cgit v1.3