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
() → jeepney.io.blocking.DBusConnection[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 asget_default_collection()
.Changed in version 3.0: Before the port to Jeepney, this function returned an instance of
dbus.SessionBus
class.Changed in version 3.1: This function no longer accepts any arguments.
Examples of using SecretStorage¶
Creating a new item in the default collection:
>>> import secretstorage
>>> connection = secretstorage.dbus_init()
>>> collection = secretstorage.get_default_collection(connection)
>>> 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()
b'pa$$word'
Locking and unlocking collections¶
The current version of SecretStorage provides only the synchronous API for
locking and unlocking.
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()
True
>>> collection.unlock()
>>> collection.is_locked()
False
If you want to use the asynchronous API, please file a bug and describe your use case.
Contents¶
- The
secretstorage.collection
module - The
secretstorage.item
module - Additional utility functions
- Possible exceptions
- SecretStorage changelog
- SecretStorage 3.1.1, 2019-01-24
- SecretStorage 3.1.0, 2018-09-02
- SecretStorage 3.0.1, 2018-04-24
- SecretStorage 3.0.0, 2018-04-23
- SecretStorage 2.3.1, 2016-08-27
- SecretStorage 2.3.0, 2016-08-17
- SecretStorage 2.2.1, 2016-06-27
- SecretStorage 2.2.0, 2016-06-18
- SecretStorage 2.1.4, 2016-01-10
- SecretStorage 2.1.3, 2015-12-20
- SecretStorage 2.1.2, 2015-06-30
- SecretStorage 2.1.1, 2014-07-12
- SecretStorage 2.1, 2014-05-28
- SecretStorage 2.0, 2014-01-27
- SecretStorage 1.1, 2013-11-15
- SecretStorage 1.0, 2013-05-08
- SecretStorage 0.9, 2013-03-05
- SecretStorage 0.8, 2013-01-05
- SecretStorage 0.2, 2012-06-22
- SecretStorage 0.1, 2012-06-02