[−][src]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

extern crate secret_service;
use secret_service::SecretService;
use secret_service::EncryptionType;


// 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();

//create new item
collection.create_item(
    "test_label", // label
    vec![("test", "test_value")], // 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();

EncryptionType::Dh requires the gmp feature to be enabled in Cargo.toml, which is the default. This requires libgmp to be available.

When the gmp feature is disabled by disabling the default features in Cargo.toml, EncryptionType::Plain will be the only one available.

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 SsError. dbus and rust-crypto crate errors are converted into SsErrors.

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.

Structs

Collection
Item
SecretService

Secret Service Struct.

Enums

EncryptionType
SsError

Type Definitions

Result

Result type often returned from methods that have SsError. Fns in this library return ::Result when using this alias.