How to use gnome-keyring

by havoc

I was recently trying to use gnome-keyring and ended up having to ask
Alex what was going on. Here is a short explanation so anyone else
googling the subject might find it.

The keyring repository maps attribute sets (like {,foo=bar}) to
secrets. A secret is just a string that gets encrypted, typically it
would contain your password or username/login. The
(attribute-set,secret) pair is called an “item.”

There’s a ton of stuff in gnome-keyring.h. What you want to use is
create_item_sync() to create your secret, and find_items() to retrieve
it. The “network password” API is just a convenience layer that
keeps you from making up your own attribute names.

If you’re using the Python bindings, you have a problem; one of the
two functions you want to use, find_items(), just crashes.
The example
that comes with gnome-python-desktop jumps through some weird
hoops with gconf to work around this; it stores the id of the item in
gconf, instead of using find_items(). This example also calls the id
“auth_token” as if it were special or secret, but the id is just a
handle to the item. This example is totally wrong in a
confusing way, is what it comes down to.

The last thing to know is that there are multiple keyrings, but
you only care about two. A NULL keyring means to use the default
persistent one, and the string “session” means to use an in-memory
keyring that will be dropped on logout. find_items() searches
all keyrings, and that’s why find_items() has no keyring

I filed a
bug on the python bindings
since they aren’t really usable without
find_items() but it looks like these bindings are unmaintained (the
bug got assigned to “Nobody’s working on this”).

(This post was originally found at

My Twitter account is @havocp.
Interested in becoming a better software developer? Sign up for my email list and I'll let you know when I write something new.