Module secret_service Copy item path

§secret-service credential store

Items in the secret-service are identified by an arbitrary collection of attributes. This implementation controls the following attributes:

• target (optional & taken from entry creation call, defaults to default)
• service (required & taken from entry creation call)
• username (required & taken from entry creation call’s user parameter)

In addition, when creating a new credential, this implementation assigns two additional attributes:

• application (set to rust-keyring-client)
• label (set to a string with the user, service, target, and keyring version at time of creation)

Client code is allowed to retrieve and to set all attributes except the three that are controlled by this implementation. (N.B. The label string is not actually an attribute; it’s a required element in every item and is used by GUI tools as the name for the item. But this implementation treats the label as if it were any other non-controlled attribute, with the caveat that it will reject any attempt to set the label to an empty string.)

Existing items are always searched for at the service level, which means all collections are searched. The search attributes used are target (set from the entry target), service (set from the entry service), and username (set from the entry user). Because earlier versions of this crate did not set the target attribute on credentials that were stored in the default collection, a fallback search is done for items in the default collection with no target attribute if the original search for all three attributes returns no matches.

New items are created in the default collection, unless a target other than default is specified for the entry, in which case the item will be created in a collection (created if necessary) that is labeled with the specified target.

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, as well as earlier versions of this crate, that may already have created items that match the entry, and thus reduces the chance of ambiguity in later searches.

§Tokio runtime caution

If you are using the async-secret-service with this crate, and specifying tokio as your runtime, be careful: if you make keyring calls on the main thread, you will likely deadlock (see
this issue on GitHub for details). You need to spawn a separate thread on which you make your keyring calls to avoid this.

§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 starts the Gnome keyring unlocked with a known password; 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.