- commit
- c61955c59dcf8643ac0f33cba1f4a61d7a093a0f
- parent
- 48688bbed73d28c7cf89fd428e456c08ba872371
- Author
- Tobias Bengfort <tobias.bengfort@posteo.de>
- Date
- 2026-05-24 21:22
update README
Diffstat
| M | README.md | 124 | ++++++++++++++++++++++++++++++++++++++++++++----------------- |
1 files changed, 89 insertions, 35 deletions
diff --git a/README.md b/README.md
@@ -1,54 +1,58 @@ 1 1 # xi keyring 2 23 -1 a simple and extensible alternative for gnome-keyring.-1 3 A simple and extensible alternative to gnome-keyring that implements -1 4 the -1 5 [`org.freedesktop.Secret`](https://specifications.freedesktop.org/secret-service/) -1 6 DBus interface and the [XDG Desktop Portal Secrets -1 7 backend](https://flatpak.github.io/xdg-desktop-portal/docs/doc-org.freedesktop.impl.portal.Secret.html) -1 8 as well as a simple JSON socket interface. 4 95 -1 gnome-keyring is tightly integrated into the linux desktop. There are many-1 10 ## Design -1 11 -1 12 ### Focus on Experimentation -1 13 -1 14 gnome-keyring is tightly integrated into the Linux desktop. There are many 6 15 other password managers with interesting features. Just to name a few: 7 16 [KeePassXC](https://github.com/keepassxreboot/keepassxc), 8 17 [Bitwarden](https://bitwarden.com), [pass](https://www.passwordstore.org/), and9 -1 [Himitsu](https://sr.ht/~sircmpwn/himitsu/). Unfortunately, none of them really10 -1 implement the `org.freedesktop.Secrets` dbus specification, so they cannot11 -1 completely replace gnome-keyring. On the other hand, gnome-keyring itself has12 -1 accumulated a sizable legacy, which makes it very hard to extend.13 -114 -1 So this project tries to fill the gap:-1 18 [Himitsu](https://sr.ht/~sircmpwn/himitsu/). However, they do not all implement -1 19 the `org.freedesktop.Secret` interface, so they cannot be used as drop-in -1 20 replacements. On the other hand, gnome-keyring is so big and complex that it is -1 21 hard to experiment with new features. 15 2216 -1 - Work as a drop-in replacement for gnome-keyring for most common use cases17 -1 - Keep the code simple and extensible18 -1 - Experiment with new features-1 23 The main focus of this project is to provide a simple code base that makes it -1 24 easy to experiment with new features. While the result is usable, the focus is -1 25 on experimentation rather than providing a complete product. 19 2620 -1 ## Threat model-1 27 ### Limit access to secrets 21 2822 -1 *As the main focus for now is experimentation, there is no fixed threat model23 -1 yet. There are some ideas though.*24 -125 -1 With gnome-keyring, secrets in an unlocked collection can be read by a26 -1 malicious application that is running on the user's desktop. This does startle27 -1 some users, but the developers have repeatedly explained that [there is just no28 -1 point in trying to protect against malicious un-sandboxed-1 29 With gnome-keyring, secrets in an unlocked collection can be read by any -1 30 application that has access to the session bus. This does startle some users, -1 31 but the developers have repeatedly explained that [there is just no point in -1 32 trying to protect against malicious un-sandboxed 29 33 applications](https://gitlab.gnome.org/GNOME/gnome-keyring/-/issues/5#note_1876550). 30 3431 -1 While I am very critical of security theater myself, I feel like there is room32 -1 for nuance here. These are some of the **ideas** I want to experiment with:-1 35 While I understand the sentiment, I feel like there is room for nuance here. -1 36 These are some of the mechanisms xi-keyring uses to limit access to secrets: 33 3734 -1 - Prompt the user when an application tries to access a password to provide some degree of observability35 -1 - Prevent malicious applications from taking memory dumps by using [`PR_SET_DUMPABLE`](https://www.man7.org/linux/man-pages/man2/prctl.2.html)36 -1 - Use a yubikey to store the encryption secret off-device37 -1 - Allow to configure access rules (always allow, always deny, prompt) per application38 -1 - Encrypt the meta data39 -1 - Keep the keyring locked as much as possible without impacting user comfort too much. For example, don't unlock automatically on login.40 -1 - Use separate namespaces for different applications, so one application can not access the secrets stored by another.-1 38 - Prompt the user when an application tries to access a password to provide -1 39 some degree of observability. -1 40 - Prevent malicious applications from taking memory dumps by using -1 41 [`PR_SET_DUMPABLE`](https://www.man7.org/linux/man-pages/man2/prctl.2.html) -1 42 - Keep the keyring locked as much as possible without impacting user comfort -1 43 too much. For example, don't unlock automatically on login. -1 44 - Allow to use different namespaces for different applications (see below for -1 45 details) 41 4642 -1 **I am not claiming that this is or ever will be more secure than43 -1 gnome-keyring.** The gnome-keyring developers are much more experienced with44 -1 this stuff than I am. For example, they have put a lot of effort into45 -1 preventing secrets from being swapped to disk. That is not something I am even46 -1 considering (partially because I rely on full disk encryption).-1 47 Of course, a malicious application that is completely unrestricted can still -1 48 work around these measures, e.g. by starting a modified keyring implementation. -1 49 However, the amount of sandboxing necessary with these restrictions already in -1 50 place is greatly reduced. 47 5148 -1 ## Deviations from the dbus specification-1 52 ### Compatibility with DBus interface 49 53 50 54 While this project aims to be a drop-in replacement for gnome-keyring, some51 -1 features of the `org.freedesktop.Secrets` specification have been simplified:-1 55 features of the `org.freedesktop.Secrets` interface have been simplified: 52 56 53 57 - There is only a single collection (called "it") 54 58 - Trying to create or delete a collection fails @@ -60,3 +64,53 @@ features of the `org.freedesktop.Secrets` specification have been simplified: 60 64 - Prompts are transparent for the caller. No prompt is ever returned 61 65 - Labels are generated automatically and cannot be changed 62 66 - `Created`/`Modified` is always 0 -1 67 -1 68 ### Compatibility with XDG Desktop Portal -1 69 -1 70 It took me a while to understand the Secret Desktop Portal. When it finally -1 71 clicked I wrote a [blog -1 72 post](https://blog.ce9e.org/posts/2024-07-27-password-plan/) about it. -1 73 -1 74 The main idea is that the backend only stores a single key for each -1 75 applications, and the application uses that key to encrypt its own secrets. -1 76 -1 77 Applications that are sandboxed with flatpak can reliably be identified by this -1 78 mechanism. However, application running on the host can identify an arbitrary -1 79 app ID using the [Registry -1 80 portal](https://flatpak.github.io/xdg-desktop-portal/docs/doc-org.freedesktop.host.portal.Registry.html). -1 81 -1 82 ### Simple socket interface -1 83 -1 84 One major downside of DBus is that all services share a single socket. This -1 85 means that a mount namespace has either access to all service, no services at -1 86 all, or it has to use -1 87 [xdg-dbus-proxy](https://github.com/flatpak/xdg-dbus-proxy). -1 88 -1 89 From this perspective, using one socket per service is a much better approach. -1 90 That is the basic idea of -1 91 [xi-desktop-portals](https://github.com/xi/xi-desktop-portals). For the -1 92 keyring, a socket is available at `$XDG_RUNTIME_DIR/xi.portal.Secret`. -1 93 -1 94 A client is included in `scripts/socket_client.py`. It has an interface similar -1 95 to the [keyring CLI](https://github.com/jaraco/keyring). -1 96 -1 97 ### Namespacing -1 98 -1 99 xi-keyring loads the keys from a file in the client's mount namespace. This -1 100 makes it easy to give each application its own set of secrets. Simply mount a -1 101 different folder into `$XDG_DATA_HOME/xikeyring/`. *The mount namespace is the -1 102 secret namespace.* -1 103 -1 104 However, you need to be careful when using proxies: -1 105 -1 106 - With flatpak, `xdg-dbus-proxy` is the immediate client, and it has full -1 107 access to `$XDG_DATA_HOME`. -1 108 - With portal APIs, `xdg-desktop-portal` is the immediate client, and it has -1 109 full access to `$XDG_DATA_HOME`. -1 110 -1 111 When using flatpak, I recommend using the portal APIs and their namespacing -1 112 based in app IDs. -1 113 -1 114 With other sandboxing mechanisms, I recommend using the socket interface -1 115 because it allows to nest different sandboxes inside of each other and does not -1 116 require a separate proxy process.