From 87440d5a23f0fd894d949295a7c1ff85043550fc Mon Sep 17 00:00:00 2001
From: salmonik <salmonik@tuta.io>
Date: Wed, 28 Oct 2026 22:55:51 +0100
Subject: v0.4.0: add first-time TLS setup and server help

---
 docs/SERVER_SETUP.md | 100 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 100 insertions(+)
 create mode 100644 docs/SERVER_SETUP.md

(limited to 'docs/SERVER_SETUP.md')

diff --git a/docs/SERVER_SETUP.md b/docs/SERVER_SETUP.md
new file mode 100644
index 0000000..e2f3177
--- /dev/null
+++ b/docs/SERVER_SETUP.md
@@ -0,0 +1,100 @@
+# Server setup
+
+The server speaks TLS and needs a PKCS#12 identity (`identity.p12`) plus the
+PEM key/certificate used to build it. The files are read from the current
+working directory.
+
+## Quick start
+
+From the project root:
+
+```sh
+cargo run --bin server -- --init
+cargo run --bin server
+```
+
+`--init` creates a self-signed development identity and exits. The next
+command starts the server on `127.0.0.1:11525`.
+
+If `identity.p12` is missing at startup, the server now prints these same
+instructions instead of only the raw OS error.
+
+## What `--init` creates
+
+| File | Purpose |
+| --- | --- |
+| `identity.p12` | PKCS#12 identity loaded by `native-tls`. Empty password. Uses PBE-SHA1-3DES and a SHA-1 MAC so the Windows SChannel backend can load it. |
+| `key.pem` | RSA private key used to build the identity. Not read at runtime. |
+| `cert.pem` | Public certificate, useful for inspection. |
+
+On Unix, `identity.p12` and `key.pem` are set to mode `0600`. All three are
+ignored by git (`*.p12`, `*.pem`, `*.key`).
+
+## Manual setup
+
+If `openssl` is not installed or you want to control the certificate:
+
+```sh
+openssl req -x509 -newkey rsa:2048 \
+  -keyout key.pem -out cert.pem \
+  -days 3650 -nodes -subj "/CN=localhost"
+
+openssl pkcs12 -export -out identity.p12 \
+  -inkey key.pem -in cert.pem -passout pass:
+```
+
+The password must be empty because the server calls
+`Identity::from_pkcs12(&data, "")`.
+
+## Running
+
+```sh
+# default: 127.0.0.1:11525
+cargo run --bin server
+
+# listen on all interfaces
+cargo run --bin server -- -i 0.0.0.0 -p 11525
+
+# show options
+cargo run --bin server -- --help
+```
+
+Then start the client in another terminal:
+
+```sh
+cargo run --bin client
+```
+
+On first contact the client prints the SPKI fingerprint and pins it. If you
+regenerate the server identity, the client will reject the new key; run
+`forget-host` in the client if the change is intentional.
+
+## Windows
+
+`--init` shells out to `openssl`, so OpenSSL must be installed and on `PATH`
+(Git for Windows, WSL, or a standalone OpenSSL build). The generated files work
+the same way. `--init` uses SChannel-friendly PKCS#12 algorithms; if you build
+the identity by hand on Windows, use:
+
+```sh
+openssl pkcs12 -export -out identity.p12 -inkey key.pem -in cert.pem \
+  -passout pass: -keypbe PBE-SHA1-3DES -certpbe PBE-SHA1-3DES -macalg sha1
+```
+
+## Security notes
+
+- This is a self-signed development identity with an empty PKCS#12 password.
+  Treat `key.pem` and `identity.p12` as secrets and do not commit them.
+- The trust model is TOFU: clients pin the SPKI fingerprint on first contact.
+  A changed key is a loud error, not an automatic re-trust.
+- For a public deployment, use a CA-issued certificate and protect the
+  PKCS#12 with a password; the current server code expects an empty password.
+
+## Troubleshooting
+
+| Symptom | Fix |
+| --- | --- |
+| `Failed to initialize TLS: Could not read TLS identity` | Run `cargo run --bin server -- --init`. |
+| `Address already in use` | Stop the other server or pass `-p <port>`. |
+| Client says `HOST KEY CHANGED` | The server certificate changed. If intentional, run `forget-host` in the client. |
+| `openssl` not found | Install OpenSSL or use the manual commands on a machine that has it. |
-- 
cgit v1.2.3