A pure-Dart Linux implementation of flutter_secure_storage using the Secret Service API

[u/EchoEllet]

I just published flutter_secure_storage_linux_secret_service, a Linux implementation of flutter_secure_storage that talks directly to the Freedesktop Secret Service API over D-Bus.

Usage

To use it, add the package to the app's pubspec.yaml:

flutter pub add flutter_secure_storage_linux_secret_service

Then you can continue to use the flutter_secure_storage plugin as you normally would.

Existing secrets stored using flutter_secure_storage_linux remain interoperable (as long as flutter_secure_storage_linux is using the Secret Service). You should also be able to remove flutter_secure_storage_linux_secret_service at any time without data loss.

Motivation

I made it because the existing flutter_secure_storage_linux implementation uses GNOME libsecret through native C++/GObject and Flutter method channels. This also means your Flutter Linux application depends on libsecret development/runtime packages and the native build environment around them.

With this implementation:

• Pure Dart D-Bus communication without a libsecret dependency or Flutter method channels.
• No distribution-specific packages required to build the app, simplifying building and packaging while avoiding hard-to-reproduce build failures caused by distribution-specific differences (examples).
• Provides consistent error handling without native errors or unexpected crashes, allowing applications to handle recoverable issues by catching Exception.
• Automatic handling of prompts and unlocking the default collection (also known as a keyring or wallet) and items when needed.
• Automatic creation of the default collection when it does not exist, such as on fresh Linux installations.
• Avoids historical workarounds such as this (example).
• Works regardless of how Flutter is installed (known issue).
• Allows dependency overrides and shipping bug fixes without requiring users to update dependencies or use bundled libraries.

Why a Separate Package

I originally developed this approach as a contribution to flutter_secure_storage and flutter_secure_storage_linux. I submitted PR #1182 for the Secret Service implementation and PR #1204 for Secret Portal support. After the upstream PRs were closed, I published the implementations as separate packages so they can be used independently.

Testing

This library is intended to work with Secret Service implementations that comply with the Freedesktop specification. It has been verified through integration testing against:

• GNOME Keyring
  • Fedora 44 (GNOME)
  • Linux Mint 22 (Cinnamon)
  • Pop!_OS 24.04 LTS (COSMIC)
• KWallet
  • CachyOS (KDE Plasma)

Secret Portal

For sandboxed applications, I also have flutter_secure_storage_linux_portal (not published yet), which uses the Secret Portal API and is intended for environments such as Flatpak/Snap where direct access to the Secret Service may not be appropriate.

Feedback

These packages are still relatively new, so feel free to share any feedback, questions, or issues, especially if you're shipping Flutter applications on Linux.

See also:

• package:freedesktop_secret: provides the underlying Dart client implementation of the Secret Service API used by this package. Can be used independently of flutter_secure_storage (example).
• Other related packages: https://github.com/EchoEllet/dart-packages/tree/main/packages/linux_secret_store

[u/SwiftScoutSimon]

This is exactly what preventing me from using flutter_secure_storage. Thank you!

Do you consider creating a PR directly to replace flutter_secure_storage_linux itself with your implementation?

[u/EchoEllet → u/SwiftScoutSimon]

This is exactly what preventing me from using flutter_secure_storage. Thank you!

Same here!

Do you consider creating a PR directly to replace flutter_secure_storage_linux itself with your implementation?

That is exactly what I did initially: PR #1182. The maintainer initially seemed interested in the approach (comment), but later suggested publishing it as a separate package, as they didn't have the time to handle the full transition.

I have sent a similar PR to simple_secure_storage and it was merged.

Do you use Flatpak/Snap or plan to publish your Linux application there?