Module keyring::secret_service
source · Expand description
§secret-service credential store
Items in the secret-service are identified by an arbitrary collection of attributes, and each has “label” for use in graphical editors. This implementation uses the following attributes:
target
(optional & taken from entry creation call, defaults todefault
)service
(required & taken from entry creation call)username
(required & taken from entry creation call)application
(optional & always set torust-keyring
)
Existing items are always searched for at the service level, which means all collections are searched. Only the required attributes are used in searches, so 3rd party clients (such as v1 of this crate) that use matching service and user fields will have their items found by our searches. (Items we write with the same service and user attributes but different target attributes will also come back in searches, but they are filtered out of the results automatically.)
New items are always created with all four attributes, and if they have a non-default target then they are created in a collection whose label matches the target (creating it if necessary).
Setting the password on an entry will always update the password on an existing item in preference to creating a new item. This provides better compatibility with 3rd party clients that may already have created items that match the entry, and reduces the chance of ambiguity in later searches.
§Async runtime required
While this crate uses the secret-service via its blocking API,
the secret-service crate is built on zbus which always talks to the dbus via async calls.
Thus, using the secret-service implies using an async runtime under the covers.
If you are already using an async runtime,
you can use keyring features to make sure that secret-service
uses a compatible runtime. But be careful: if you make keyring calls
on the main thread in this situation, you will likely crash because
you will block the main thread (see
this issue on GitHub
for details). You will need to spawn a separate thread on which
you make your keyring calls so the main thread doesn’t block.
§Headless usage
If you must use the secret-service on a headless linux box,
be aware that there are known issues with getting
dbus and secret-service and the gnome keyring
to work properly in headless environments.
For a quick workaround, look at how this project’s
CI workflow
uses the
linux-test.sh script;
a similar solution is also documented in the
Python Keyring docs
(search for “Using Keyring on headless Linux systems”).
The following bash
function may be helpful:
function unlock-keyring ()
{
read -rsp "Password: " pass
echo -n "$pass" | gnome-keyring-daemon --unlock
unset pass
}
For an excellent treatment of all the headless dbus issues, see this answer on ServerFault.
§Usage - not! - on Windows Subsystem for Linux
As noted in this issue on GitHub, there is no “default” collection defined under WSL. So this keystore doesn’t work “out of the box” on WSL. See the issue for more details and possible workarounds.
Structs§
- The representation of an item in the secret-service.
- The builder for secret-service credentials
Functions§
- Create a secret service collection labeled with the given name.
- Map underlying secret-service errors to crate errors with appropriate annotation.
- Returns an instance of the secret-service credential builder.
- Given an existing item, delete it.
- Find the secret service collection whose label is the given name.
- Given an existing item, retrieve and decode its password.
- Given a slice of items, filter out the ones that have an explicit target attribute that doesn’t match the given target.
- Given an existing item, set its password.