Libsecret revealed

GNOME developer Stef Walter has started work on a new client library for interacting with the secret-storage subsystems that allow users to keep track of passwords, encryption keys, and other sensitive data. The new project is named libsecret, and will enable more applications to connect to the GNOME and KDE "secret services," as well as fix longstanding threading and notification problems.

GNOME and KDE each provide their own mechanisms for storing, editing, and retrieving saved secrets; GNOME uses the gnome-keyring-daemon, and KDE uses ksecretservice (evidently there is no formal project page, but a ksecretservice-devel mailing list exists). However, both systems conform to the same standard, the Freedesktop.org Secret Service API. The API defines a "secret item" as a sensitive string needing protection (such as a password or key) along with an array of attributes. It also provides a way to group secret items into collections, each of which can be locked (i.e. encrypted) or unlocked separately.

Typically a desktop environment creates a default collection for each user account, unlocking it at login time, and locking it again when the session ends. Everyday applications like email clients or WiFi network applets can communicate with the service over D-Bus to securely store and retrieve credentials. However, the API also enables specialty applications (such as the Seahorse encryption key manager) to do more, like implement an interface through which users can create and manage their own collections at will.

Building a better client library

Previous GNOME releases exposed gnome-keyring-daemon to applications via the libgnome-keyring library. Libsecret is designed to be a more modern replacement for libgnome-keyring — the secret service daemon itself will remain unchanged. Walter announced the libsecret project on the GNOME desktop-devel list on March 26, noting that the new project would improve on libgnome-keyring by being thread-safe, introspectable, and properly asynchronous. The code is hosted on GNOME's Git repository, while the documentation currently resides in Walter's personal web space.

In an email, Walter elaborated on the shortcomings in libgnome-keyring that warranted writing a replacement from scratch. At its core, he said, libgnome-keyring was built around its own binary protocol. Support for speaking the Secret Service API over D-Bus was added later, but ultimately the underlying code needed to go. Libsecret is designed from the ground up for Secret Service and D-Bus, not only implementing the full API, but doing away with the custom bits. As a result, Walter said, applications will in theory be able to use libsecret to communicate with any Secret Service implementation, including ksecretservice (although so far this has not been tested).

The older API, Walter said, did not include support for change notifications from gnome-keyring-daemon. As a result, applications needed to restart in order to see changes to collections and secret items.

Libgnome-keyring had several other technical limitations, not related to the API. First, it was not thread-safe. Since multiple client applications may need to access password storage (including some that may do so with multiple threads) simultaneously, this was a serious impediment. Second, libgnome-keyring could not use GObject introspection (introduced in GTK+ 3.0), which made developing for it in JavaScript or Python impossible. Walter has added JavaScript and Python examples to the libsecret documentation illustrating the creation of a secret schema and storing, retrieving, and deleting a password.

The API rollout

Walter's documentation breaks the libsecret API into two parts. The first is a simple password API, which he has declared stable. The second is a more general API for "power user" applications, which he plans to continue to develop over the course of the GNOME 3.6 development cycle. The plan is to have the complete API finalized in time for 3.6, and patches deployed to migrate existing core GNOME applications over to libsecret prior to the release.

The simple password API defines methods for storing a secret item in a collection, searching the collection for a secret item, retrieving the secret, and deleting the item from storage. There are both synchronous and asynchronous calls; GUI apps can access the asynchronous methods to avoid blocking while waiting for a response from the Secret Service, while non-GUI applications are expected to use the synchronous methods.

The exact makeup of a secret item is defined by a schema. Every item contains a "secret" plus an optional list of attributes that may vary depending on the type of secret. Secret Services store all attributes as string data (in key-value pairs), but the values may be marked as boolean or integer types so that applications can properly interpret them. By default, retrieving a secret item begins with the application initiating a search against a particular collection (either the default collection, or a specified alternative) for a secret matching some search term. Libsecret assumes that the typical search will include the schema name (e.g., "password" or "key") desired, as the different schemas generally represent disjoint use-cases for secret storage, but this can be turned off with a flag.

The simple password API does not explore using the library for encryption keys or other secret items, but the complete API supports these data types, and libsecret eventually will. The Secret Service API recommends that applications use human-readable text as the storage format for secrets, but this is also not a strict requirement. Applications can even use secret items to store compound data by encoding it in XML or another markup language.

The complete libsecret API also provides methods for an application to create, unlock, access, and lock collections, and to prompt the user for input (such as the password required to unlock a particular collection, or what to name a new collection). There will be support for a session collection that is automatically deleted at logout (which would be useful for storing temporary credentials like login passwords for mounting remote storage).

By itself, libsecret is neutral about the Secret Service used, which can have implications for the application developer. Libsecret, for example, does not guarantee that secret items are stored securely in the service, or that they are transferred to the client application in a secure manner. The Secret Service API allows a service and an application to negotiate an encryption algorithm for transferring secrets, but libsecret does not (yet) support this. However, as the Secret Service documentation points out, there may be other methods an application can use to minimize the risk of exposure, such as using mlock() to prevent memory pages from being written to swap.

Libsecret is still in its infancy, but the prospect of a modern password-and-key-storage mechanism is a refreshing one. Perhaps the most interesting new outcome would be more applications that can seamlessly support gnome-keyring-daemon and ksecretservice, but with the increasing presence of desktop applications written in JavaScript, an API accessible to that language is certainly valuable, too. Shortly after Walter posted the announcement about libsecret, he pushed out updates to the Seahorse, libcryptui, and gnome-keyring packages as well. Those updates were for GNOME 3.4 and thus were not changes for libsecret support, but that effort for those utilities should begin any day.