flutter_secure_storage_linux_secret_service

A Linux implementation of the flutter_secure_storage plugin using the standard Secret Service API through a pure Dart D-Bus client. It provides an alternative to the native libsecret-based flutter_secure_storage_linux implementation without requiring libsecret system packages to build or run the application.

See also package:freedesktop_secret, which provides the underlying Dart client implementation of the Secret Service API used by this package.

Features

  • Pure Dart implementation using D-Bus directly.
    • Does not require additional system packages to build or run the application (e.g., libsecret-1-0 or libsecret-1-dev on Ubuntu).
    • Provides consistent error handling, allowing applications to handle recoverable issues by catching Exception.
  • Uses the standard Secret Service API, which is the primary API used by GNOME libsecret, making it possible to retain compatibility with secrets stored by flutter_secure_storage_linux.
  • Handles prompts, unlocking the default collection (also known as a keyring or wallet) and items when needed.
  • Automatically creates the default collection when it does not exist (e.g., on fresh Linux installations).

Requirements

These requirements are typically already satisfied by default on most Linux desktop environments.

  • A Linux operating system with D-Bus support.
  • A running Secret Service implementation (e.g., GNOME Keyring, KDE Wallet or another implementation of the org.freedesktop.secrets D-Bus service).

Usage

Add the package as a dependency in the app's pubspec.yaml:

flutter pub add flutter_secure_storage_linux_secret_service

Tip

Adding this package automatically registers this implementation and overrides flutter_secure_storage_linux (the endorsed implementation of flutter_secure_storage). No explicit imports are required.

Legacy data migration

Older versions of flutter_secure_storage_linux had a historical bug that caused the xdg:schema attribute to be populated incorrectly.

flutter_secure_storage_linux was updated in 4.0.0-beta.1 to fix this issue and migrate data affected by it. See the relevant PR for details.

This implementation also automatically migrates the old data when appropriate.

The old secrets are not automatically deleted by default to avoid destructive changes, consistent with the behavior of flutter_secure_storage_linux, which leaves legacy items in place during migration (the relevant code).

To opt in to deleting the old data:

import 'package:flutter_secure_storage_linux_secret_service/flutter_secure_storage_linux_secret_service.dart';
import 'package:flutter_secure_storage_platform_interface/flutter_secure_storage_platform_interface.dart';
// ยทยทยท

final secureStorageImplementation = FlutterSecureStoragePlatform.instance;
if (secureStorageImplementation is FlutterSecureStorageLinuxSecretService) {
  secureStorageImplementation.deleteLegacyData = true;
}

To opt out of migrating the old data:

// Opting out of migration for newer apps avoids an additional lookup.
secureStorageImplementation.migrateLegacyData = false;

Historical Background

This implementation was originally developed as a complete rewrite of flutter_secure_storage_linux in #1182. The PR was not merged, and the implementation was subsequently extracted into this separate package.

Libraries

flutter_secure_storage_linux_secret_service