SecretStorage

SecretStorage is a Python module for securely storing passwords and other secrets. It interfaces with the D-Bus Secret Service API, making it compatible with implementations like GNOME Keyring, ksecretd (KWallet), KeePassXC, and OO7.

Core abstractions include:

• secretstorage.Item: Represents an individual secret, consisting of a label, a secret value, and associated attributes.
• secretstorage.Collection: A container where Item objects are stored.

The module supports standard Secret Service operations such as creating/deleting items and collections, editing items, and locking/unlocking collections.

To run the test suite, you must have a Secret Service daemon (like GNOME Keyring) installed and running.

Important: If a default collection exists, it must be unlocked. If no default collection exists, the test suite can use the session collection provided by the daemon.

To run tests in a standard environment:

python3 -m unittest discover -s tests

To run tests in an isolated or headless environment (using a D-Bus session):

dbus-run-session -- python3 -m unittest discover -s tests

To build SecretStorage, ensure you have Python ≥ 3.10 and the following dependencies installed:

• Jeepney
• python-cryptography

Use the standard Python build module to compile the package.

python3 -m build

Before using SecretStorage, you must initialize a D-Bus connection. This is a prerequisite for interacting with the Secret Service daemon (e.g., GNOME Keyring, KeePassXC).

Use secretstorage.dbus_init() to create the connection. You can also use secretstorage.check_service_availability() to verify if a Secret Service daemon is running or activatable via D-Bus without attempting to call specific methods.

import secretstorage

# Initialize the connection
connection = secretstorage.dbus_init()

# Optionally check if the service is available
if secretstorage.check_service_availability(connection):
    print("Secret Service is available")

SecretStorage provides a synchronous API for managing the lock state of a collection.

Note: The unlock() method is blocking. If the Secret Service requires user interaction (e.g., a graphical password prompt), the call will block until the user provides the credentials.

Use lock() to secure the collection, unlock() to make it accessible, and is_locked() to check the current state.

# Assuming 'collection' is an initialized secretstorage.collection.Collection
collection.lock()
print(collection.is_locked())  # True

collection.unlock()
print(collection.is_locked())  # False

To store a secret, obtain a collection (such as the default collection) and use collection.create_item(). You must provide a label, a dictionary of attributes for searching, and the secret itself as bytes.

Once created, you can retrieve the label, attributes, and the secret data using get_label(), get_attributes(), and get_secret() respectively.

import secretstorage

connection = secretstorage.dbus_init()
collection = secretstorage.get_default_collection(connection)

# Create a new item
attributes = {'application': 'myapp', 'another attribute': 'another value'}
item = collection.create_item('My first item', attributes, b'pa$$word')

# Retrieve data
label = item.get_label()           # 'My first item'
attrs = item.get_attributes()      # {'application': 'myapp', ...}
secret = item.get_secret()        # b'pa$$word'

The secretstorage.util module provides helper functions for common tasks when working with secrets, such as formatting secret data, executing prompts, and unlocking multiple objects simultaneously.

Available functions:

• format_secret: Formats a secret for display or storage.
• exec_prompt: Executes a prompt (likely for user input or authentication).
• unlock_objects: A batch operation to unlock multiple secret objects.