# flutter_secure_storage_linux 3.0.3

Linux implementation of flutter_secure_storage




## Installing
```
export PUB_HOSTED_URL=https://pub.mirror.p-hatan.com
flutter pub add 'flutter_secure_storage_linux:3.0.3'
```
Published: 2026-09-11T11:45:49.372900Z
Expected archive SHA-256: caa75bd78f017422912e3a904933113b2428eb79f981ac37acd2dd2a700458ea

Available in cache; verification: upstream_checksum
## Direct dependencies
- flutter: map[sdk:flutter]
- flutter_secure_storage_platform_interface: ^2.0.1

## Package README (untrusted upstream documentation)
# flutter_secure_storage_linux

This is the platform-specific implementation of `flutter_secure_storage` for Linux.

## Features

- Secure storage using `libsecret` library.
- Compatible with various Linux keyring services like GNOME Keyring and KDE KWallet.

## Installation

Install [libsecret](https://github.com/GNOME/libsecret) — both the development package (to build) and the runtime package (to run). The runtime package (`libsecret-1-0`) is typically pre-installed on most Linux desktops.

<details>
<summary>apt / dnf / pacman</summary>

Ubuntu / Debian-based (Linux Mint, Pop!_OS, …):

```shell
sudo apt install libsecret-1-0 libsecret-1-dev
```

Fedora / RHEL / CentOS:

```shell
sudo dnf install libsecret libsecret-devel
```

Arch-based (single package contains both):

```shell
sudo pacman -S libsecret
```

</details>

<details>
<summary>Flatpak / Flathub</summary>

libsecret is included in Freedesktop runtime 25.08+ (also GNOME runtime 49, KDE runtime 6.10 and 5.15-25.08), so no extra manifest entry is needed:

```yaml
runtime: org.freedesktop.Platform
runtime-version: '25.08' # must be 25.08 or newer
```

For older runtimes, use [Flathub Shared Modules](https://docs.flathub.org/docs/for-app-authors/shared-modules) (`shared-modules/libsecret/libsecret.json`), though this is no longer recommended.

</details>

<details>
<summary>Snapcraft</summary>

```yaml
parts:
  your-app:
    plugin: flutter
    flutter-target: lib/main.dart
    build-packages:
      - libsecret-1-dev
    stage-packages:
      - libsecret-1-0
```

</details>

> **Note:** `libjsoncpp-dev` is no longer required. The plugin uses a bundled header-only JSON library.

## Configuration

Apart from libsecret, a running keyring service is required at runtime. This is typically already provided by the desktop environment:

- **GNOME / Ubuntu:** [`gnome-keyring`](https://wiki.gnome.org/Projects/GnomeKeyring) — usually active by default in a GNOME session.
- **KDE:** [`kwallet`](https://wiki.archlinux.org/title/KDE_Wallet) — enabled via KDE Wallet Manager.
- **Other / lightweight:** [`secret-service`](https://github.com/yousefvand/secret-service)
- **Headless / CI:** start `gnome-keyring-daemon` with an unlocked keyring:
  ```bash
  eval $(dbus-launch --sh-syntax)
  echo "" | gnome-keyring-daemon --unlock --daemonize --components=secrets
  ```

## Known issues

### Flutter installed via snap on Ubuntu 22.04+

Building with the Flutter snap may produce linker errors like:

```
undefined reference to `g_task_set_static_name'
undefined reference to `g_once_init_enter_pointer'
```

This is caused by a version mismatch between the GLib bundled in the Flutter snap and the system `libsecret`, which is compiled against a newer GLib. The plugin shared library links fine, but executables (including native test binaries) may fail to link.

**Workaround:** install Flutter via the [official tar archive](https://docs.flutter.dev/get-started/install/linux) instead of snap, so the toolchain uses the system linker and libraries consistently.

## Running the tests

### Native tests (C++ / GoogleTest)

The native tests exercise the `SecretStorage` layer directly against a real keyring. Build the example app first to compile the test binary, then run via CTest:

```bash
# 1. Start a keyring daemon (skip if already running in a desktop session)
eval $(dbus-launch --sh-syntax)
echo "" | gnome-keyring-daemon --unlock --daemonize --components=secrets

# 2. Build (compiles the test binary alongside the app)
cd flutter_secure_storage/example
flutter build linux --debug

# 3. Run
cd build/linux/x64/debug/plugins/flutter_secure_storage_linux
ctest --output-on-failure
```

### Integration tests

```bash
cd flutter_secure_storage/example
xvfb-run flutter test integration_test/linux_test.dart -d linux
```

## Usage

Refer to the main [flutter_secure_storage README](../README.md) for common usage instructions.

## License

This project is licensed under the BSD 3 License. See the [LICENSE](../LICENSE) file for details.

## Changelog
# Changelog

## [3.0.3](https://github.com/juliansteenbakker/flutter_secure_storage/compare/flutter_secure_storage_linux-v3.0.2...flutter_secure_storage_linux-v3.0.3) (2026-09-11)


### Bug Fixes

* **linux:** skip D-Bus keyring warmup when sandboxed ([#1223](https://github.com/juliansteenbakker/flutter_secure_storage/issues/1223)) ([1e625c9](https://github.com/juliansteenbakker/flutter_secure_storage/commit/1e625c9718b0d301039c3456bf97bbbfbc020ea3))

## [3.0.2](https://github.com/juliansteenbakker/flutter_secure_storage/compare/flutter_secure_storage_linux-v3.0.1...flutter_secure_storage_linux-v3.0.2) (2026-08-06)


### Bug Fixes

* handle missing default keyring on linux ([b39c7c1](https://github.com/juliansteenbakker/flutter_secure_storage/commit/b39c7c1db6c1fe651367031c9d0033d590784de0))
* **linux:** fail closed on orphaned keyring data ([2e720ff](https://github.com/juliansteenbakker/flutter_secure_storage/commit/2e720ff7e6b956a5d1197a5077bb8be39a5d5632))
* **linux:** return structured libsecret error codes ([4691b83](https://github.com/juliansteenbakker/flutter_secure_storage/commit/4691b838519ae91383618120d82fd97a60a35493))

## 3.0.1
- Fixed `deleteKeyring` storing the string `"null"` instead of an empty JSON object `{}`.
- Fixed non-UTF-8 error messages from libsecret causing a `FormatException` on the Dart side; messages are now sanitised before being sent through the method channel.
- Fixed locked or unavailable keyring now surfacing as a catchable `PlatformException` with code `KeyringLocked`.
- Fixed JSON parse errors and other C++ exceptions now surfacing as a `PlatformException` with code `StorageError` instead of sending malformed bytes through the channel.
- Updated README with installation instructions for apt, dnf, pacman, Flatpak, and Snapcraft.

## 3.0.0
- Fixed whitespace deprecation warning.
- Reverted json.dump with indentations due to problems. If still needed, pin version to 2.x

## 2.0.1
Adds application ID to cmake file

## 2.0.0
- This plugin requires a minimum dart sdk of 3.3.0 or higher and a minimum flutter version of 3.19.0.
- Updated documentation

## 1.2.3
- Adds application ID to cmake file

## 1.2.2
- Fix json.dump with indentations 

## 1.2.1
- Fixed search with schemas fails in cold keyrings
- Fixed erase called on null

## 1.2.0
- Remove and replace libjsoncpp1 dependency
- Update Dart SDK Constraint to support <4.0.0 instead of <3.0.0.

## 1.1.3
Fixed a memory management issue

## 1.1.2
Updated flutter_secure_storage_platform_interface to latest version.

## 1.1.1
Fixed an issue where no error was being reported if there was something wrong accessing the secret service.

## 1.1.0
Add containsKey function.

## 1.0.0
- Initial Linux implementation
- Removed unused Flutter test and effective_dart dependency