diff options
| -rw-r--r-- | docs/MESHBAY_DESIGN.md | 14 | ||||
| -rw-r--r-- | docs/USERGUIDE.md | 11 |
2 files changed, 20 insertions, 5 deletions
diff --git a/docs/MESHBAY_DESIGN.md b/docs/MESHBAY_DESIGN.md index a43e35d..e721cb2 100644 --- a/docs/MESHBAY_DESIGN.md +++ b/docs/MESHBAY_DESIGN.md @@ -160,7 +160,7 @@ document uses: | File content is unreadable | ✅ | ❌ **T3** (browser) · ✅ native | ❌ by design — the operator hosts the files | ❌ members share the group key | ✅ | | The file index is unreadable | ✅ | ❌ T3 · ✅ native | ❌ | ❌ | ✅ | | Chat content is unreadable | ✅ | ❌ T3 · ✅ native | ❌ — the operator is a member | ❌ | ✅ | -| Chat is unreadable **off a stolen disk** | ✅ | ✅ | ✅ without the keystore passphrase | ✅ | ✅ | +| Chat is unreadable **from a copy of the node's storage that lacks its unlock key** — not from a whole disk by default (§4.5) | ✅ | ✅ | — the operator holds the unlock key | ✅ | ✅ | | Content cannot be modified | ✅ | ✅ | ❌ by design | ✅ | ✅ | | The node cannot be impersonated | ✅ | ✅ | — | ✅ | ✅ | | Client code integrity | ❌ **T3, accepted** (browser) · ✅ ships in the package (native) | ❌ T3 · ⚠️ native: **detectable, not prevented** | ✅ | ✅ | ✅ | @@ -919,9 +919,15 @@ where it stands on its own instead of pointing at a file to compare against. > requirement rather than from a module somebody left behind. **What chat encryption protects against, in the words the user-facing docs should -use:** someone who obtains the node's storage **without the keystore passphrase** — -a hosting provider imaging the machine, a leaked backup, a seizure where the -passphrase is not surrendered. It does **not** protect chat from the operator or +use:** someone who obtains the node's stored chat **without the key that unlocks +its keystore** — a backup of the data directory, a copy of the chat database. **By +default that key is not elsewhere:** setup writes `unlock.key` into the same +configuration directory as `keystore.enc`, so the whole disk, an image of the +machine or a backup of the home directory carries both, and opens. Against those +the protection is the disk's own encryption — BitLocker or Windows device +encryption, LUKS — or an unlock key kept off that disk (`[keystore] unlock_file` +on other storage, or `MESHBAY_UNLOCK_KEY` supplied from outside it; `node.env` +is in the same directory and is not outside it). It does **not** protect chat from the operator or any current member (they hold the group key, and the chat key is delivered under it); from anyone holding any one device of any member; from a former member, for messages sent before the epoch changed; from the hub as regards *metadata*; or diff --git a/docs/USERGUIDE.md b/docs/USERGUIDE.md index eb9452e..e92f6bc 100644 --- a/docs/USERGUIDE.md +++ b/docs/USERGUIDE.md @@ -893,13 +893,22 @@ the confirmation on destructive commands. `man meshbay-node` has the full page. | `~/.config/meshbay/node.toml` | configuration — hand-edited, commented, preserved | | `~/.config/meshbay/node.env` | environment: keystore unlock, third-party tokens | | `~/.config/meshbay/keystore.enc` | the node's own keys. **Back this up.** | -| `~/.config/meshbay/unlock.key` | what opens the keystore. Mode 0600. | +| `~/.config/meshbay/unlock.key` | what opens the keystore. Mode 0600. Whoever has both files opens the keystore, and with it the group chat this node stores | | `~/.local/share/meshbay/` | roster, indexes, chat, caches, thumbnails | | `/opt/meshbay-common/venv/` | the shared Python environment | Losing the keystore means a new node identity: every group has to be re-linked and every member re-admitted. It is small — back it up somewhere safe. +The chat this node stores is encrypted under the keystore, and the keystore is +opened by `unlock.key`, which sits beside it. A stolen disk, an image of the +machine or a backup of your home directory therefore holds everything needed to +read it. What protects those is the disk's own encryption — BitLocker or device +encryption on Windows, LUKS on Linux — or keeping the unlock key on other +storage: point `[keystore] unlock_file` in `node.toml` at it and remove +`unlock.key`. (`node.env` is in the same directory, so moving the key there +changes nothing.) The node then cannot start without that storage. + ### Ports | | | |