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