# 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), KWallet (since version 5.97) and KeePassXC.

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() → DBusConnection

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

  Warning

  The D-Bus socket will not be closed automatically. You can close it manually using the `DBusConnection.close()` method, or you can use the `contextlib.closing` context manager:

      from contextlib import closing
      with closing(dbus_init()) as conn:
          collection = secretstorage.get_default_collection(conn)
          items = collection.search_items({'application': 'myapp'})

  However, you will not be able to call any methods on the objects created within the context after you leave it.

  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.

If you need to quickly check whether the Secret Service daemon is available (either running or activatable via D-Bus) without trying to call any its methods, you can use the following function:

secretstorage.check_service_availability(connection: DBusConnection) → bool

  Returns True if the Secret Service daemon is either running or available for activation via D-Bus, False otherwise.

  New in version 3.2.

## 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
  - `Collection`
  - `create_collection()`
  - `get_all_collections()`
  - `get_any_collection()`
  - `get_collection_by_alias()`
  - `get_default_collection()`
  - `search_items()`
- The `secretstorage.item` module
  - `Item`
- Additional utility functions
  - `exec_prompt()`
  - `format_secret()`
  - `unlock_objects()`
- Possible exceptions
  - `ItemNotFoundException`
  - `LockedException`
  - `PromptDismissedException`
  - `SecretServiceNotAvailableException`
  - `SecretStorageException`
- SecretStorage changelog
  - SecretStorage 3.3.3, 2022-08-13
  - SecretStorage 3.3.2, 2022-04-19
  - SecretStorage 3.3.1, 2021-02-09
  - SecretStorage 3.3.0, 2020-11-24
  - SecretStorage 3.2.0, 2020-11-07
  - SecretStorage 3.1.2, 2020-01-08
  - 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

## Indices and tables

- Index

- Search Page