Welcome to SecretStorage documentation!

This module provides a way for securely storing passwords and other secrets.

It uses D-Bus-based FreeDesktop.org Secret Service standard that is, for example, supported by GNOME Keyring (since version 2.30) and by KSecretsService.

It allows one to create new secret items, delete and search for passwords matching given attributes. It also supports graphical prompts when unlocking is needed.

Initializing D-Bus

See also

If you don’t know how D-Bus works, please read Introduction to D-Bus firstly.

Before using SecretStorage, you need to initialize D-Bus. This can be done using this function:

secretstorage.dbus_init(main_loop=True, use_qt_loop=False)[source]

Returns new SessionBus. If main_loop is True, registers a main loop (Qt main loop if use_qt_loop is True, otherwise GLib main loop).

Note

Qt uses GLib main loops on UNIX-like systems by default, so one will rarely need to set use_qt_loop to True.

Examples of using SecretStorage

Creating a new item in the default collection:

>>> import secretstorage
>>> bus = secretstorage.dbus_init()
>>> collection = secretstorage.Collection(bus)
>>> attributes = {'application': 'myapp', 'another attribute':
...     'another value'}
>>> item = collection.create_item('My first item', attributes,
...     b'pa$$word')

Getting item’s label, attributes and secret:

>>> item = collection.create_item('My first item', attributes, b'pa$$word')
>>> item.get_label()
'My first item'
>>> item.get_attributes()
{'another attribute': 'another value', 'application': 'myapp'}
>>> item.get_secret()
b'pa$$word'

Locking and unlocking collections:

>>> collection.lock()
>>> collection.is_locked()
True
>>> collection.unlock()
>>> collection.is_locked()
False

Asynchronously unlocking the collection (the GLib main loop is used here, Qt loop is also supported):

>>> from gi.repository import GLib
>>> loop = GLib.MainLoop()
>>> def callback(dismissed, unlocked):
...     print('dismissed:', dismissed)
...     print('unlocked:', unlocked)
...     loop.quit()
...
>>> collection.unlock(callback); loop.run()
dismissed: False
unlocked: [dbus.ObjectPath('/org/freedesktop/secrets/aliases/default')]

Indices and tables

Table Of Contents

Next topic

The secretstorage.collection module

This Page