Home

Welcome to the secret-service wiki!

To understand how to use this library, it's recommended to read (the short) Secret Service API Draft 0.2 first.

Obtain a session

To store and receive secrets on a Linux keychain daemon like KDE kwallet or GNOME keyring, you need to establish a session first. This can be plain or encrypted:

var service = new Service();
var response = service.openSession(EncryptedSession.Algorithm.PLAIN, new Variant<>(""));
Variant<?> output = response.value().a;
var session = response.value().b;

The output will be of type String and be empty, and the session can be then used to store and receive secrets.

var session = new EncryptedSession();
session.setupEncryptedSession();
var encryptedSession = session.getSession();

The encryptedSession can be then used to store and receive secrets, that are encrypted and decrypted on the transfer via DBus.

Check DBus responses

The DBus Secret Service API is designed to access collections and secrets, that are stored in collections. However, DBus can return an error for a request, in case the collection or item is locked. There are other errors too.

To handle request, this library returns an object for a request, that contains the possible DBus response and the possible DBus error. The returned object can be examined, whether the request was successful and the returned DBus response can be processed further:

var service = new Service();
var props = Collection.createProperties("myCollection");
var request = service.createCollection(props, "");
if (request.isSuccess()) {
    var collectionDBusPath = request.value().a;
    ...
}

Convenience methods

There are some methods to make developers life easier:

Service#isAvailable()

Service#hasDefaultCollection()

Service#ensureUnlocked(DBusPath item)

EncryptedSession#setupEncryptedSession()

Collection#createProperties(String label)

Item#createProperties(String label)

Util#promptAndGetResultAsDBusPath(DBusPath path)

Util#promptAndGetResultAsArrayList(DBusPath path)

Further information

All other information can be found in the included JavaDoc and the JUnit test cases.