Crate secret_service [−] [src]
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();
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 SsError
s.
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 |