root
9c459909c3
Why: the usual way to hand a secret to a container is to mount it as a file and name the path in the environment. Compose, swarm and Kubernetes all do it that way, and it keeps the key out of the process environment and off any disk the container can write. What: the master key is now looked for in KEEPORG_MASTER_KEY, then KEEPORG_MASTER_KEY_FILE, then the configured master_key_file. A secret file may hold base64, with or without padding or a trailing newline, or exactly 32 raw bytes, because secret stores produce both. Only the configured path is ever created, which is what keeps a plain package install working with no setup. The two environment variables name a key something else owns, so a missing one is reported and vault creation refused. Minting a replacement there would be worse than failing: it opens none of the existing vaults, and the mistake would otherwise surface one failed merge at a time. The compose example now provisions the key as a real secret rather than an environment variable, and the Dockerfile and README show the same. Neither names a version any more, so they stop drifting as the server is bumped. Proved: unit tests for every source and precedence, all four accepted encodings, and that a missing secret writes nothing anywhere. In real containers: a podman secret carrying base64 survives a stop and start with "1 vault keys available for merging" and merges a stale push afterwards; a secret holding 32 raw bytes creates a vault; and a secret that failed to mount is named in the startup log, with vault creation answering with the three places a key may come from.
88 lines
3.5 KiB
Markdown
88 lines
3.5 KiB
Markdown
# KeepOrg
|
|
|
|
A synchronization adapter for KeePass. Your databases stay ordinary `.kdbx`
|
|
files that KeePassXC, KeePass2 or KeePassDX opens directly; a server keeps
|
|
them in step between everyone who has access.
|
|
|
|
When two people save at once, the server can **merge** both edits: it opens
|
|
the two copies in memory, folds them together by KeePass's own rules and
|
|
stores the result. Nothing is lost, and no one has to reconcile two files by
|
|
hand.
|
|
|
|
Merging means decrypting, so a merge vault's password is kept on the server,
|
|
encrypted under a master key held outside the data directory. That makes the
|
|
server part of your trust boundary. Vaults on any other conflict strategy
|
|
keep their key off the server entirely, exactly as before.
|
|
|
|
- **Server** (`keeporgd`, Linux): hosts many KDBX databases, controls access
|
|
with a tree of user groups, accepts registrations by invite link or OIDC,
|
|
merges concurrent edits, and pushes updates to connected clients. Its web
|
|
page at `/web` is for creating a vault and setting its password.
|
|
- **Desktop client** (`keeporg`, Linux, macOS, Windows, BSD): mirrors every
|
|
assigned database into one directory as a real file, pushes each save and
|
|
applies what others push.
|
|
- **Android client**: the same, published to every file picker as a storage
|
|
provider.
|
|
|
|
No third-party dependencies, no cgo, no FUSE. The KDBX 4 codec, including
|
|
ChaCha20, BLAKE2b and Argon2, is part of the repository and is tested against
|
|
both the relevant RFCs and a real KeePassXC.
|
|
|
|
## Quick start
|
|
|
|
```sh
|
|
make check # gofmt, vet, tests
|
|
make all # keeporgd and keeporg for this host
|
|
|
|
# a server for trying it out, on 127.0.0.1:8765
|
|
KEEPORG_ADMIN_PASSWORD=dev-password-1 make run-server
|
|
|
|
# in another shell
|
|
build/linux-arm64/keeporg login -server http://127.0.0.1:8765 -user admin
|
|
build/linux-arm64/keeporg groups
|
|
build/linux-arm64/keeporg vault -create "Team Vault" -group <group-id>
|
|
build/linux-arm64/keeporg run
|
|
```
|
|
|
|
`Team Vault.kdbx` appears in `~/KeepOrg`; open it in KeePassXC with the vault
|
|
password you just set. Every save is pushed, and a save that races with a
|
|
colleague's is merged rather than refused.
|
|
|
|
Or open `http://127.0.0.1:8765/web` and create the vault from the browser.
|
|
|
|
## Packaging
|
|
|
|
```sh
|
|
make deb # Debian packages for the client and the server
|
|
make docker # server container image, scratch-based, about 9 MB
|
|
make dmg # macOS disk image with an /Applications symlink (on macOS)
|
|
make windows # Windows zip with a Task Scheduler job
|
|
make android # unsigned release APK (needs the Android SDK)
|
|
make help # every target
|
|
```
|
|
|
|
Running the server in a container:
|
|
|
|
```bash
|
|
head -c 32 /dev/urandom | base64 > master.key
|
|
podman secret create keeporg_master_key master.key
|
|
podman run -d -p 8765:8765 \
|
|
--secret keeporg_master_key \
|
|
-e KEEPORG_MASTER_KEY_FILE=/run/secrets/keeporg_master_key \
|
|
-e KEEPORG_ADMIN_PASSWORD=change-me \
|
|
-v keeporg-data:/var/lib/keeporg \
|
|
keeporgd:latest -addr :8765 -data /var/lib/keeporg -url https://keeporg.example.com
|
|
```
|
|
|
|
Keep that master key: it unwraps the vault keys, and without it the server
|
|
can no longer merge. `KEEPORG_MASTER_KEY` takes the base64 key directly if
|
|
your secret store injects variables instead of files. See
|
|
[packaging/docker/compose.yaml](packaging/docker/compose.yaml).
|
|
|
|
## Documentation
|
|
|
|
- [docs/HANDOVER.md](docs/HANDOVER.md) — architecture, the decisions behind
|
|
it, operations, and what is left to do.
|
|
- [docs/PROTOCOL.md](docs/PROTOCOL.md) — the HTTP API.
|
|
- [android/README.md](android/README.md) — the Android module.
|