Module keyring::secret_service

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 to default)
• service (required & taken from entry creation call)
• username (required & taken from entry creation call)
• application (optional & always set to rust-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

• SsCredential
  The representation of an item in the secret-service.
• SsCredentialBuilder
  The builder for secret-service credentials

Functions

• create_collection
  Create a secret service collection labeled with the given name.
• decode_error
  Map underlying secret-service errors to crate errors with appropriate annotation.
• default_credential_builder
  Returns an instance of the secret-service credential builder.
• delete_item
  Given an existing item, delete it.
• get_collection
  Find the secret service collection whose label is the given name.
• get_item_password
  Given an existing item, retrieve and decode its password.
• matching_target_items
  Given a slice of items, filter out the ones that have an explicit target attribute that doesn’t match the given target.
• set_item_password
  Given an existing item, set its password.