Skip to content

0033: Linux: the freedesktop Secret Service for the OS keychain tier, logind for locking, zenity or kdialog for approvals

  • Status: accepted
  • Date: 2026-10-03

Context

ADR 0009 says that on Linux desktops without biometrics, tier 2 falls back to a passphrase plus the system keyring. Linux has no single credential API or biometric gate: desktops expose a keyring through the freedesktop Secret Service D-Bus API (gnome-keyring, KWallet's provider, KeePassXC), session state through systemd-logind, and no standard approval dialog. Group 8 of add-agent-daemon built this layer in pure Go over godbus.

Decision

  • The os-keychain tier and the machine key are Secret Service items on the session bus. Each identity's 32-byte wrapping key is the secret of a new item whose reference is random (at least 128 bits) and never replaces an existing item, because identity names repeat across profiles. Items carry application=vaultfold, identity=<name> (informational) and item=<reference>; lookup is by application and reference only, and more than one match is refused as ambiguous. The machine key's item carries machine-key=<canonical Data directory>, so two profiles never share one.
  • Transport hygiene. Sessions use the dh-ietf1024-sha256-aes128-cbc-pkcs7 algorithm first; plain only when the service answers that DH is not supported and the bus says the owner of org.freedesktop.secrets runs as our uid; a DH public value out of range fails the operation with no plain retry. The default dial never auto-launches a bus. The client keeps one long-lived bus connection and opens and closes one Secret Service session per operation, holding nothing between unlocks; operations are serialized process-wide, because gnome-keyring 42.1 was seen to abort when a new connection arrived right after another disconnected.
  • Unlock prompts are the keyring's own. A locked collection or item is unlocked through the service's prompt; a dismissed prompt is a cancellation, and its completion is accepted only from the bus name that owned the service when the operation started. vaultfold never asks for the keyring password itself.
  • The machine key never prompts. A locked store is an error, not a prompt. An existing data/machine.key is migrated (stored, read back, compared, then renamed aside, zeroed and removed), and a marker file <Data>/machine.key.secret-service records that the key lives in the store. Without a usable Secret Service the machine key stays in data/machine.key, but never once the marker exists: then a missing item is an error, so a second key is never minted beside the first.
  • Lock triggers from logind: the session's Lock signal and LockedHint lock, IdleHint (with IdleSinceHint) gives system idle, and PrepareForSleep gives sleep. Signals are matched on the owner of org.freedesktop.login1 and the session's path; a spoofed signal could only cause a lock, so this is hygiene, not a boundary. A lost bus connection makes the trigger unavailable, which locks every vault.
  • Approvals with zenity or kdialog, found without PATH. The daemon may have been auto-started by the very agent whose request needs approval, so its PATH and environment are not trusted to pick the dialog: tools are looked up only in /usr/bin, /bin and /usr/local/bin, must be regular, root-owned files in root-owned directories that are not group- or world-writable, and run with PATH=/usr/bin:/bin and an allowlisted environment (display, session bus, locale and desktop variables). kdialog is preferred on KDE, zenity elsewhere, and a display (DISPLAY or WAYLAND_DISPLAY) is required. An allow needs a positive answer: zenity runs with --default-cancel, kdialog with a menu whose default entry is Deny, and any other outcome is "unavailable", never an allow. Field text is cut to 256 characters and every non-graphic character is replaced, so a field cannot forge a line. Passphrases are never read through a dialog.
  • Where no Secret Service is usable (servers, minimal window managers, WSL, SSH sessions without a session bus) the passphrase tier is the default: key new makes a passphrase identity and says why, and doctor reports it. An existing os-keychain identity is never silently downgraded.

Consequences

  • Linux-only code runs only in make check-in-docker, whose image has dbus and gnome-keyring; a gated interop test there drives a real gnome-keyring-daemon and cross-checks the machine key with secret-tool. A pass on real GNOME and KDE desktops (keyring prompts and dialogs) has not been done.
  • zenity 3.44 or later is assumed (older versions may expand backslash escapes); doctor reports an older one, and a dialog tool that exists but is a symlink or not root-owned (alternatives, Nix), which the daemon then does not use.
  • A read-only Data directory makes the machine key fail when the marker must be written.
  • The Secret Service has no biometric gate: an unlocked keyring hands an item to any process of the user that asks, so the daemon is still the gate for agent sessions and approvals. The threat model records the same-user limits.

Alternatives considered

  • libsecret through cgo. Rejected: cgo stays darwin-only (ADR 0031); the D-Bus API is small enough to speak directly.
  • The kernel keyring (keyctl). Rejected: not persistent across reboots, and no desktop unlock integration.
  • Finding dialog tools on PATH. Rejected: the requesting caller can control the daemon's PATH.
  • Our own dialog (GTK or a terminal UI). Rejected: a new GUI dependency, and the desktop app will be the richer approval endpoint.