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

http://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;


// initialize secret service (dbus connection and encryption session)
let ss = SecretService::new(EncryptionType::Dh).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(
    vec![("test", "test_value")]
).unwrap();

let item = search_items.get(0).unwrap();

// 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. A new instance of SecretService will initialize the dbus connection and negotiate an encryption session.

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

or

SecretService::new(EncryptionType::Dh).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.

Errors

This library provides a custom Error. dbus and rust-crypto crate errors are converted into Errors.

Types of errors:

• dbus
• crypto
• parsing dbus output
• no result, if dbus gives back result but doesn’t contain expected parameter
• locked, if an object path is locked
• prompt dismissed, if action requires prompt but the prompt is dismissed

Crypto

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

In this library, the encryption negotiation and key exchange is carried out in the session module, and encryption/decryption is done in the ss_crypto module.