Exploring Gnome Keyring

As a first step, I’ll show how to "explore" Gnome Keyring. A good start is ensure that the Gnome keyring Daemon is available using the is_available method. To search through existing keyrings we can use the list_keyring_names_sync method. If you test this from a Python Console you will notice an recurrent warning "g_set_application_name not set", an example:

>>> import gnomekeyring as gk
>>> gk.list_keyring_names_sync()

** (process:1737): WARNING **: g_set_application_name not set.
['login', 'MyKeyring', 'session']
>>>

This happens because the daemon requests information about which application is trying to access the Gnome Keyring info and as a Python Console we don’t have any application name. To solve this, we can import the gobject library and use the method set_application_name. Below, there is a simple keyring listing example:

>>> import gnomekeyring as gk
>>> import glib
>>> glib.set_application_name('gk-test')
>>> gk.is_available()
True
>>> gk.list_keyring_names_sync()
['login', 'MyKeyring', 'session']
>>>

Here you can see that the keyring named "MyKeyring", created in the last post is there. To explore our stored password we can use the list_item_ids_sync method, which returns a long type that identifies the stored items. The method item_get_info_sync will return an KeyringItemInfo instance that holds the basic informations defined in the last post. When calling this information, you may see a dialog asking if your application should access this item information.

Dialog requesting permission to access the password for magnun@Neptune:22

This happens because this sensitive information is being requested by an application that is not its creator. The KeyringItemInfo attributes can be accessed by methods get_secret and get_display_name. Below is an example:

>>>
>>> def list_keyring_items(keyring_name):
...     item_keys = gk.list_item_ids_sync(keyring_name)
...     print 'Existing item Keys:',item_keys
...     for key in item_keys:
...         item_info = gk.item_get_info_sync(keyring_name, key)
...         print "* Item number",key
...         print "tName:", item_info.get_display_name()
...         print "tPassword:", item_info.get_secret()
...
>>> list_keyring_items('MyKeyring')
Existing item Keys: [1L]
* Item number 1
    Name: magnun@Neptune:22
    Password: mypasswd
>>>

Considering that we will develop an application which will store lot’s of keyring items, it’s interesting to have one exclusive keyring for our application. Using this hook, I’ll show how to remove existing keyrings and it’s items. Remember, never remove the "login" and "session" keyrings, they’re used by the operational system.

Removing Keyrings

After understanding how Gnome Keyring works, removing a keyring and it’s items become an easy task. You can simply remove a single keyring item with the method item_delete_sync or use the delete_sync method to remove the keyring along with it’s items.

>>> gk.list_keyring_names_sync()
['MyKeyring', 'login', 'session']
>>> gk.list_item_ids_sync('MyKeyring')
[1L, 2L]
>>> gk.item_delete_sync('MyKeyring', 2L)
>>>
>>> gk.list_item_ids_sync('MyKeyring')
[1L]
>>> gk.delete_sync('MyKeyring')
>>> gk.list_keyring_names_sync()
['login', 'session']
>>>

Creating a Keyring and its Items

The keyring creation process is simple and resembles the graphical process. Just need to inform the name and it’s password:

>>> gk.list_keyring_names_sync()
['login', 'session']
>>> gk.create_sync('GKApp', 'gkpass')
>>> gk.list_keyring_names_sync()
['GKApp', 'login', 'session']
>>>

The creation of the keyring item is a little different, there is a new field called attributes. Lets see below an example:

>>> atts = {'username':'magnun',
...         'server':'Neptune',
...         'service':'SSH',
...         'port':'22',
...        }
>>> gk.item_create_sync('GKApp', gk.ITEM_GENERIC_SECRET,
...    'magnun@Neptune:22', atts, 'mypasswd', True)
1L
>>> item_keys = gk.list_item_ids_sync('GKApp')
>>> item_info = gk.item_get_info_sync('GKApp', item_keys[0])
>>> item_info.get_display_name()
'magnun@Neptune:22'
>>> item_info.get_secret()
'mypasswd'
>>>

The keyring Item creation process is slightly different. When we used Seahorse there was only 3 fields (keyring, description and password) and previously we selected the item type. Using the API there was six fields:

• Keyring - Define which keyring this item will belong. In this example it’s GKApp;
• Item Type - Describes the item that is being added. Can be ITEM_GENERIC_SECRET, ITEM_NETWORK_PASSWORD and ITEM_NOTE;
• Description - Also referred as display name. It’s the name used as key, this need to be unique inside the same keyring;
• Attributes - A dictionary representing custom attributes defined by the user. Those can be anything or nothing, the functionality of this field will be shown in the future;
• Password - Also referred as secret. This can be anything that needs to be stored secretly;
• Update if Exists - If True existing item (same description and attributes) will be updated.

Thats it, as simple as this! Now, looking through Seahorse we can see some differences from the item we created in the last post. Here are some screenshots.

Seahorse Keyring Item Properties Dialog showing the item’s details

Seahorse Keyring Item Dialog showing the item’s "owner application"

As we can see, now the attributes are filled with informations and the application name is set to gk-test, set with glib.set_application_name. Next post I’ll show a little more about how to properly use the keyrings, a little about security and show some scritps examples.