flutter_secure_storage_x 12.1.2

flutter_secure_storage_x provides API to store data in secure storage. Keychain is used in iOS, KeyStore based solution is used in Android.

flutter_secure_storage_x

This package is a fork of the popular flutter_secure_storage package.

Philosophy

flutter_secure_storage_x is designed with a focus on long-term stability and maintainability for the most common use cases.

Rather than offering an exhaustive feature set, we aim to provide a minimal, transparent layer that respects and utilizes the native security primitives provided by the OS (such as Android KeyStore, Jetpack DataStore, and Apple Keychain).

Note on Specialized Requirements

Specialized features, such as biometric authentication, require holistic design—from checking prerequisites and handling failure recovery to balancing user experience (UX) with strict security requirements.

For these specialized use cases or applications requiring extreme security levels, we recommend that developers implement their own native code. This ensures the implementation is fully optimized and tailored to the specific needs of the application, rather than relying on generalized library options.

For more detailed information and usage examples, please refer to the example app.

Roadmap & History

Android

The following table outlines the evolution of storage and encryption on Android, and the recommended migration path.

Version	Storage Backend	Encryption	Migration Status
v10	SharedPreferences (Default) DataStore (Opt-in)	Custom Implementation & EncryptedSharedPreferences	Migration Bridge. Essential for v9 users. Ensures data accessibility before EncryptedSharedPreferences removal in v11.
v11	SharedPreferences (Default) DataStore (Opt-in)	Custom Implementation (RSA/AES)	Stabilization. Removed unstable EncryptedSharedPreferences.
v12	SharedPreferences (Default) DataStore (Opt-in)	Android KeyStore (OS Standard)	MANDATORY MIGRATION BRIDGE. IMPORTANT: This is the LAST version that supports migrating data from Custom Implementation. Users MUST upgrade to v12 and launch the app to migrate data to KeyStore format.
v13 (Target)	DataStore (Default) SharedPreferences (Legacy)	Android KeyStore ONLY	BREAKING CHANGE. Support for Custom Implementation logic is REMOVED. Any data not already migrated to KeyStore (via v12) will be LOST/UNREADABLE. Default backend switches to DataStore.
v14 (Planned)	DataStore ONLY	Android KeyStore	Finalization. SharedPreferences support is completely removed.

Important

Android Migration Warning (v12 -> v13)

In v13, the decryption logic for "Custom Implementation (RSA/AES)" used in v11 and earlier will be completely removed. v13 can only read data encrypted with "Android KeyStore".

Therefore, if you update directly from v11 to v13 without going through v12, all existing encrypted data will become unreadable and lost.

Developers must follow these steps:

1. Update the app to v12 and release it.
2. Ensure users launch the v12 app to complete the internal data migration to KeyStore (migration happens automatically on first launch in v12).
3. After a sufficient migration period, update to v13 (DataStore default).

Recommended Configuration: In v13, DataStore becomes the default storage backend. We recommend explicitly enabling AndroidOptions(dataStore: true) in v12 (instead of encryptedSharedPreferences: true). This allows you to complete both data migration and backend modernization in the v12 phase, making the transition to v13 smoother.

Summary

• v10 & v11: Focus on stability and preparing for DataStore.
• v12 (Current): Unifies encryption to the standard Android KeyStore. All legacy custom implementations (RSA/AES) are removed to improve security and maintainability.
• v13 (Planned): DataStore becomes the default backend.
• v14 (Planned): DataStore becomes the only supported backend. SharedPreferences support is removed.

Note: Direct upgrades from v12 or earlier to v14 will not be supported. Users must upgrade to v13 first to migrate their data.

Windows & Linux

Planned for v15+. The current priority is to resolve stability issues on Android (v12-v14). Major updates for Windows and Linux will be addressed in v15 or later.

• Windows: Issue #88
• Linux: Issue #87

Platform Implementation

Please note that this table represents the functions implemented in this repository and it is possible that changes haven't yet been released on pub.dev

	read	write	delete	containsKey	readAll	deleteAll	isCupertinoProtectedDataAvailable	onCupertinoProtectedDataAvailabilityChanged
Android	✅	✅	✅	✅	✅	✅
iOS	✅	✅	✅	✅	✅	✅	✅	✅
Windows	✅	✅	✅	✅	✅	✅
Linux	✅	✅	✅	✅	✅	✅
macOS	✅	✅	✅	✅	✅	✅	✅	✅ (on macOS 12 and newer)
Web	✅	✅	✅	✅	✅	✅

Getting Started

If not already present, call WidgetsFlutterBinding.ensureInitialized() in your main() function before interacting with the MethodChannel. See this issue for more information: https://github.com/mogol/flutter_secure_storage/issues/336

import 'package:flutter_secure_storage_x/flutter_secure_storage_x.dart';

// Create storage
final storage = FlutterSecureStorage();

// Read value
String? value = await storage.read(key: key);

// Read all values
Map<String, String> allValues = await storage.readAll();

// Delete value
await storage.delete(key: key);

// Delete all
await storage.deleteAll();

// Write value
await storage.write(key: key, value: value);

Important Considerations

Background Access

By default, this package configures both iOS Keychain and Android KeyStore to only allow data access when the device is unlocked. This is a security feature to protect sensitive data.

This means that if your app is launched in the background (e.g., by a push notification or background fetch) while the device is locked, any attempts to access the secure storage will fail.

If your application requires background access to the storage, you must configure this explicitly. This allows fetching secure values while the app is backgrounded by specifying first_unlock or first_unlock_this_device. The default, if not specified, is unlocked.

iOS: Use the iOptions parameter with an appropriate KeychainAccessibility value, such as KeychainAccessibility.first_unlock_this_device.

An example using KeychainAccessibility.first_unlock:

final options = IOSOptions(
  accessibility: KeychainAccessibility.first_unlock,
);
await storage.write(
  key: key,
  value: value,
  iOptions: options,
);

Android: The default Android settings generally allow background access as long as the device has been unlocked once since booting. No special configuration is typically needed for this use case.

Platform-specific configuration

Android

In [project]/android/app/build.gradle set minSdkVersion to >= 23.

android {
    ...

    defaultConfig {
        ...
        minSdkVersion 23
        ...
    }

}

Note: By default, Android backs up data on Google Drive. This can cause an exception: java.security.InvalidKeyException: Failed to unwrap key. You need to:

• disable autobackup, details
• exclude sharedprefs FlutterSecureStorage used by the plugin, details

DataStore support has been available since v10.0.0. When using DataStore, set the options as follows.

AndroidOptions _getAndroidOptions() => const AndroidOptions(
  dataStore: true,
);

Web

The web implementation uses WebCrypto and should be considered experimental. It only works on secure contexts (HTTPS or localhost). Feedback is welcome to help improve it.

The intent is for the browser to create the private key, and as a result, the encrypted strings in localStorage are not portable to other browsers or other machines and will only work on the same domain.

It is VERY important that you have HTTP Strict Transport Security enabled and the proper headers applied to your responses, or you could be subject to a JavaScript hijacking attack.

Please see:

• https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security
• https://www.netsparker.com/blog/web-security/http-security-headers/

WASM support

Supported from v2.0.0.

application-specific key option

On the web, all keys are stored in localStorage. This package offers an option to wrap these stored keys with an application-specific key to make analysis more difficult.

final _storage = const FlutterSecureStorageX(
  webOptions: WebOptions(
    wrapKey: '${your_application_specific_key}',
    wrapKeyIv: '${your_application_specific_iv}',
  ),
);

This option encrypts the key stored in localStorage with WebCrypto wrapKey. It is decrypted with WebCrypto unwrapKey when used. Generating and managing application-specific keys requires careful attention from developers. See (https://github.com/mogol/flutter_secure_storage/issues/726) for more information.

Linux

You need libsecret-1-dev and libjsoncpp-dev on your machine to build the project, and libsecret-1-0 and libjsoncpp1 to run the application (add them as dependencies after packaging your app). If you are using Snapcraft to build the project, use the following:

parts:
  uet-lms:
    source: .
    plugin: flutter
    flutter-target: lib/main.dart
    build-packages:
      - libsecret-1-dev
      - libjsoncpp-dev
    stage-packages:
      - libsecret-1-0
      - libjsoncpp-dev

In addition to libsecret, you also need a keyring service. For this, you can use either gnome-keyring (for GNOME users), ksecretsservice (for KDE users), or other lightweight providers like secret-service.

macOS

You also need to add the Keychain Sharing capability to your macOS runner. To achieve this, please add the following in both macos/Runner/DebugProfile.entitlements and macos/Runner/Release.entitlements (you need to change both files).

<key>keychain-access-groups</key>
<array/>

If your application is configured to use App Groups, you will need to add the name of the App Group to the keychain-access-groups argument above. Failure to do so will result in values appearing to be written successfully but never actually being written at all. For example, if your app has an App Group named "aoeu", then the value above would instead read:

<key>keychain-access-groups</key>
<array>
	<string>$(AppIdentifierPrefix)aoeu</string>
</array>

If you are configuring this value through Xcode, then the string you set in the Keychain Sharing section would simply read "aoeu", with Xcode appending the $(AppIdentifierPrefix) when it saves the configuration.

Windows

You need the C++ ATL libraries installed along with the rest of the Visual Studio Build Tools. Download them from here and ensure the C++ ATL component under 'Optional' is also installed.

Integration Tests

Run the following command from flutter_secure_storage_x/example directory:

flutter test integration_test

This command runs tests on the currently active device.