SecretStorage

SecretStorage provides a Python API for storing and retrieving secrets, such as passwords, tokens, and other sensitive data, through the D-Bus Secret Service specification. It talks to whatever keyring daemon is running on the user’s Linux desktop, including GNOME Keyring, KWallet’s ksecretd, KeePassXC, and oo7, giving applications a single interface for secure secret storage regardless of desktop environment.

Under the hood it uses Jeepney for low-level D-Bus communication and the cryptography package to implement the Diffie-Hellman key exchange and AES-CBC encryption that the Secret Service protocol uses to protect secrets in transit. The library exposes Collection and Item classes for creating, searching, locking, and unlocking secrets, and is best known as the Secret Service backend used by the widely-adopted keyring package.

What You Get

• Collection and Item classes - object-oriented wrappers around Secret Service D-Bus collections and items for creating, editing, and deleting secrets
• Encrypted transport - built-in Diffie-Hellman key exchange and AES-CBC encryption via the cryptography package so secrets aren’t sent over D-Bus in plaintext
• Locking and unlocking support - blocking APIs to unlock a collection or item, including handling the interactive unlock prompt with an optional timeout
• Full type hints - a py.typed marker and a mypy —strict-clean codebase for editor autocompletion and static analysis

Common Use Cases

• Storing OAuth tokens or API credentials for a desktop Linux application
• Implementing a password-manager-agnostic backend for the keyring Python package
• Building CLI tools that need to cache credentials securely between runs
• Integrating desktop apps with GNOME Keyring, KWallet, or KeePassXC without vendoring D-Bus code

Under The Hood

Architecture The package is organized into small, single-responsibility modules: __init__.py exposes the public API surface (dbus_init, check_service_availability) plus re-exports from the other modules; collection.py holds the Collection class and module-level factory functions (get_default_collection, get_any_collection, create_collection, search_items); item.py holds the Item class for secret CRUD; util.py provides DBusAddressWrapper (wrapping Jeepney’s DBusAddress) plus session/prompt/unlock helpers; dhcrypto.py implements the Diffie-Hellman key-exchange math in a standalone Session class; and defines.py/exceptions.py hold D-Bus constants and a small typed exception hierarchy. Data flows in one direction: callers obtain a DBusConnection via dbus_init(), pass it into Collection/Item constructors, which each build a DBusAddressWrapper per D-Bus object path and route every call through send_and_get_reply, centralizing D-Bus error-to-Python-exception translation in one place. There is no dependency-injection framework; construction is direct and explicit, and the one abstraction the whole library funnels through is DBusAddressWrapper.call/get_property.

Tech Stack Pure Python 3.10+, with only two runtime dependencies: jeepney>=0.6 (a pure-Python D-Bus library that avoids the C-extension dbus-python bindings) and cryptography>=2.0 (AES/DH primitives). Packaging uses setuptools>=77 with PEP 621 metadata in pyproject.toml, and the distribution ships a py.typed marker. There is no web/ORM/CLI framework involved, since this is a systems-integration library rather than an application framework; its deployment target is any Linux desktop session with a running D-Bus bus and a Secret Service provider. CI (.github/workflows/main.yml) runs a Python 3.10-3.14 test matrix that clones GNOME’s libsecret repository and runs its mock Secret Service servers under dbus-run-session, plus separate flake8 and mypy --strict jobs and a trusted-publisher PyPI release job on tags. Docs are built with Sphinx and hosted on Read the Docs.

Code Quality Tests live under tests/ and use the standard-library unittest framework, run against three real mock Secret Service D-Bus servers pulled from the upstream libsecret project (mock-service-normal, only-plain, and lock variants) rather than hand-rolled mocks, a notably rigorous integration-testing approach for a library of this size. Error handling is deliberate: DBusAddressWrapper.send_and_get_reply() explicitly catches DBusErrorResponse and re-raises one of a small typed exception hierarchy (ItemNotFoundException, SecretServiceNotAvailableException, LockedException, PromptDismissedException) instead of letting raw D-Bus errors leak to callers. Naming is consistent and PEP8-conforming, type hints are used throughout and enforced in CI via mypy --strict, and flake8 enforces style with an 88-character line limit. No dead code or unresolved TODOs were found in the core modules.

What Makes It Unique SecretStorage does not try to be novel: it is a faithful, thin client binding for an established freedesktop specification. Its distinguishing technical choice is implementing the Diffie-Hellman key-exchange and AES session encryption itself (dhcrypto.py) rather than delegating to the legacy dbus-python bindings, and building on Jeepney’s pure-Python, transport-agnostic D-Bus implementation instead of a C extension, which is why it can be installed without system D-Bus development headers. That combination is why it has become the de facto Secret Service backend used by the widely-adopted keyring package on Linux.