ADR: The library key can live in the OS keychain

Development These docs follow the development version and change with every merge.

Last updated View as Markdown

Context

One random 32-byte data-encryption key (DEK) seals every row of encrypted_secrets: store sign-ins, the operator token, plugin secrets, library links. It lives in $BOOKCLERK_FILES_DIR/master.key, either raw (BCK1) or wrapped with the auth password (BCK2). The database stores the key's SHA-256 fingerprint in library_identity, and a branch whose key doesn't match refuses to start. Shared branches hold the same key.

Most installs run BCK1, because nothing asks for a password on a desktop or a home server. A copy of the files directory (a backup, a synced folder, a stolen disk) then carries the key next to library.db, which is every store sign-in.

Every desktop operating system has a credential store tied to the user's login: Keychain Services on macOS, Credential Manager on Windows, and the Secret Service (GNOME Keyring, KWallet) on Linux desktops. A headless Linux server usually has none: there is no session D-Bus, and nothing unlocks a collection at boot.

The keychain protects the key against copies of the files directory. It does not protect it against code running as the same OS user, which can ask the keychain for the item as Bookclerk does.

Decision

1. Two key stores, chosen per install

The key is kept in one of two stores:

Store Where the key is master.key holds
file master.key The envelope: BCK1, or BCK2 under the auth password
keychain One OS keychain item A BCK3 pointer to the item

The keychain item holds the same BCK1 or BCK2 envelope the file would, so a password still wraps the key when one is set, and no new key format exists. Items live under the service app.bookclerk.master-key, with a random per-install UUID as the account name, so two installs for one OS user keep separate items.

[auth].key_store = "file" | "keychain" in config.toml chooses the store for new keys. Unset, the desktop window uses the keychain and bookclerkd and the CLI use the file. The desktop default falls back to the file, with a warning, when the keychain can't take the key; a configured store is required.

The bookclerk-keystore crate reads, writes and deletes items: through the keyring-core native stores on macOS and Windows, and on Linux by speaking the Secret Service API over zbus itself. It opens a plain session there, because the encrypted session needs AES-CBC and the store-free host scan forbids block ciphers in the hosts. The session bus is the user's own local socket, the same boundary the keychain protects. An existing item is updated where it is, a missing default collection is created, and a keychain prompt that gets no answer in five minutes fails the call. Its errors never carry item bytes.

2. master.key always says where the key is

On a keychain install master.key is a 52-byte BCK3 record: the header, the item's UUID and the key's SHA-256 fingerprint. It holds no key material. Loading follows whatever master.key says, whatever the setting:

  • BCK1 and BCK2 load from the file, as before.
  • BCK3 reads the item and checks that the key inside matches the fingerprint.

A missing item, a locked or unreachable keychain, or a fingerprint mismatch is an error that names the cause. Bookclerk never mints a key while master.key exists, so a pointer can't silently become a new, empty library.

Putting the location in the key's own record rather than only in the setting means a lost config.toml or a changed setting can't send a branch looking in the wrong place.

3. Existing keys move on purpose

bookclerk config master-key move keychain|file moves the key and records the choice as [auth].key_store. The key's bytes don't change, so sealed secrets stay readable. Moving to the keychain writes the item, reads it back, then replaces master.key with the pointer atomically. Moving to the file writes the envelope over the pointer, reloads it, then deletes the item.

The desktop window moves a key still in master.key into the keychain when it starts, unless [auth].key_store is set. bookclerkd never moves a key by itself: a server operator chooses that moment.

A shared branch joining a library writes the library's key into its own store, so shared branches of one library can keep the key in different stores. The fingerprint check is the same.

4. Recovery copies

A key in the keychain is no longer in a copy of the files directory. bookclerk config master-key export --out <file> writes a BCK2 recovery copy under a password read from stdin, and bookclerk config master-key import --from <file> restores it (or a copied master.key) on an install that has no key, into that install's store.

The desktop window offers to save a recovery copy when a library is started in it. Skipping it shows a warning, and Settings keeps a reminder until one is saved. The answer is recorded per key, beside master.key, so a restored or replaced key asks again.

5. Other per-install secrets stay sealed in the database

The desktop window's patron session and other per-install rows stay sealed in encrypted_secrets. With the key in the keychain they are protected by it already, and one item per install means one macOS access prompt.

6. A systemd-creds store for headless Linux

A third store, key_store = "systemd-creds", for servers with no Secret Service. Packaging can't seal the key: it doesn't exist when the package installs, and a shared-branch join replaces it at runtime. So:

  • Bookclerk seals it itself. On start, bookclerkd moves a key still in master.key into a credential sealed with systemd-creds --user (systemd 256 or later; TPM2 when present, the host key otherwise), written beside master.key as master-key-<id>.cred and read back before master.key becomes a BCK4 pointer. The tool runs with a cleared environment and the envelope goes over stdin, never argv.
  • Administrators can seal it themselves. bookclerk config master-key credential writes the envelope, unchanged, to a pipe for systemd-creds encrypt --name=bookclerk-master-key. The unit loads it with LoadCredentialEncrypted=, and a move into systemd-creds adopts that credential (same bytes) instead of sealing its own copy. This works on older systemd and with the system credential store.
  • Sealing always falls back. If sealing fails for any reason, the key stays in master.key (password-wrapped when a password is set) with a warning, even when key_store is set. An explicit config master-key move systemd-creds still fails instead, so the operator sees why.
  • Unsealing fails closed. A sealed key that no longer opens is an error, as for a missing keychain item; the fix is the recovery copy.

Consequences

  • A copied files directory no longer exposes sealed secrets on keychain installs.
  • Backups of a keychain install need a recovery copy (or the keychain's own backup). The backup docs say so.
  • Unsigned development builds on macOS see an "allow access" prompt after each rebuild, because Keychain Services ties access to the code signature. cargo dev runs bookclerkd, whose default is the file.
  • No new untrusted-input boundary: master.key and the keychain item are written by the branch itself, and import --from reads a file the operator chose, with the same trust as master.key (whoever can hand the CLI that file can already replace master.key). The pointer and envelope parsers still have strict header and length tests.
  • bookclerk-keystore joins the security surface.
  • Headless Linux servers can seal the key with systemd-creds (decision 6), or keep the password-wrapped file. A sealed key doesn't survive a new TPM or a reinstall, so the recovery copy matters as much there as on a desktop.
  • The keychain does not help against code running as the same OS user, and removing a shared branch still doesn't take the key back; re-keying the library is a separate decision.

Source: docs/adr/master-key-store.md at main · View as Markdown