Crate dbus_secret_service

Expand description

§Dbus-Based access to the Secret Service

This library implements a rust wrapper that uses libdbus to access the Secret Service. Its use requires that a session DBus is available on the target machine.

§About the Secret Service

https://standards.freedesktop.org/secret-service/

The Secret Service provides a secure mechanism for persistent storage of data. Both the Gnome keyring and the KWallet implement the Secret Service API.

§Basic Usage

use dbus_secret_service::SecretService;
use dbus_secret_service::EncryptionType;
use std::collections::HashMap;

fn main() {
   // initialize secret service (dbus connection and encryption session)
   let ss = SecretService::connect(EncryptionType::Plain).unwrap();

   // get default collection
   let collection = ss.get_default_collection().unwrap();

   let mut properties = HashMap::new();
   properties.insert("test", "test_value");

   //create new item
   collection.create_item(
       "test_label", // label
       properties,
       b"test_secret", //secret
       false, // replace item with same attributes
       "text/plain" // secret content type
   ).unwrap();

   // search items by properties
   let search_items = ss.search_items(
       HashMap::from([("test", "test_value")])
   ).unwrap();

   // retrieve one item, first by checking the unlocked items
   let item = match search_items.unlocked.first() {
       Some(item) => item,
       None => {
           // if there aren't any, check the locked items and unlock the first one
           let locked_item = search_items
               .locked
               .first()
               .expect("Search didn't return any items!");
           locked_item.unlock().unwrap();
           locked_item
       }
   };

   // retrieve secret from item
   let secret = item.get_secret().unwrap();
   assert_eq!(secret, b"test_secret");

   // delete item (deletes the dbus object, not the struct instance)
   item.delete().unwrap()
}

§Overview of this library:

§Entry point

The entry point for this library is the SecretService struct. Creating an instance of this structure will initialize the dbus connection and create a session with the Secret Service.

SecretService::connect(EncryptionType::Plain).unwrap();

A session started with EncryptionType::Plain does not obscure the content of secrets in memory when sending them to and from the Secret Service. These secrets are encrypted by the Secret Service when put into its secure store.

If you have specified a crypto feature (crypto-rust or crypto-openssl), then you can use EncryptionType:Dh to force Diffie-Hellman shared key encryption of secrets in memory when they are being sent to and received from the Secret Service.

Once you have created a SecretService struct, you can use it to search for items, connect to the default collection of items, and to create new collections. The lifetimes of all the collection and item objects you retrieve from the service are tied to the service, so they cannot outlive the service instance. This restriction will be enforced by the Rust compiler.

§Collections and Items

The Secret Service API organizes secrets into collections, and holds each secret in an item.

Items consist of a label, attributes, and the secret. The most common way to find an item is a search by attributes.

While it’s possible to create new collections, most users will simply create items within the default collection.

§Actions overview

The most common supported actions are create, get, search, and delete for Collections and Items. For more specifics and exact method names, please see each structure’s documentation.

In addition, set and get actions are available for secrets contained in an Item.

§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.

Structs§

Collection: Represents a Secret Service collection of items.
Item: Represents a Secret Service item that has key/value attributes and a secret.
SearchItemsResult: Represents the results of doing a service-wide search.
SecretService: Encapsulates a session connected to the Secret Service.

Enums§

EncryptionType: The algorithms that can be used for encryption-in-transit.
Error: An error that could occur interacting with the secret service dbus interface.

Crate dbus_secret_serviceCopy item path