Crate secret_service

Secret Service libary

This library implements a rust interface to the Secret Service API which is implemented in Linux.

About Secret Service API

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

Secret Service provides a secure place to store secrets. Gnome keyring and KWallet implement the Secret Service API.

Basic Usage

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

#[tokio::main(flavor = "current_thread")]
async fn main() {
   // initialize secret service (dbus connection and encryption session)
   let ss = SecretService::connect(EncryptionType::Dh).await.unwrap();

   // get default collection
   let collection = ss.get_default_collection().await.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
   ).await.unwrap();

   // search items by properties
   let search_items = ss.search_items(
       HashMap::from([("test", "test_value")])
   ).await.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().await.unwrap();
           locked_item
       }
   };

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

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

Overview of this library:

Entry point

The entry point for this library is the SecretService struct. A new instance of SecretService will initialize the dbus connection and negotiate an encryption session.

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

or

SecretService::connect(EncryptionType::Dh).await.unwrap();

Once the SecretService struct is initialized, it can be used to navigate to a collection. Items can also be directly searched for without getting a collection first.

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 struct’s documentation.

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

Crypto

Specifics in SecretService API Draft Proposal: https://standards.freedesktop.org/secret-service/

Async

This crate, following zbus, is async by default. If you want a synchronous interface that blocks, see the blocking module instead.

Modules

• blocking
  A blocking secret service API.

Structs

• Collection
• Item
• SearchItemsResult
  Used to indicate locked and unlocked items in the return value of SecretService::search_items and blocking::SecretService::search_items.
• SecretService
  Secret Service Struct.

Enums

• EncryptionType
• Error
  An error that could occur interacting with the secret service dbus interface.