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.

SecretStorage code is hosted on GitHub.

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(*args, **kwargs)[source]

Returns a new connection to the session bus, instance of jeepney.DBusConnection instance. This connection can then be passed to various SecretStorage functions, such as get_default_collection().

Changed in version 3.0: Before the port to Jeepney, this function returned an instance of dbus.SessionBus class.

Examples of using SecretStorage

Creating a new item in the default collection:

>>> import secretstorage
>>> bus = secretstorage.dbus_init()
>>> collection = secretstorage.get_default_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.get_label()
'My first item'
>>> item.get_attributes()
{'another attribute': 'another value', 'application': 'myapp'}
>>> item.get_secret()

Locking and unlocking collections


You will need to install PyGObject (aka PyGI) bindings to make the code below working. The only exception is when you want to use exec_prompt_qt(), in that case you will need to install PyQt5.

The PyGObject bindings can not be installed from PyPI, but most distributions have them packaged (for example, you can use the python3-gi package on Debian).

The easiest way is using the synchronous API provided by SecretStorage. This means that if prompting the user for a password is needed, then unlock() call will block until the password is entered.

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

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