flutter_secure_storage

Note: usage of encryptedSharedPreference

When using the encryptedSharedPreferences parameter on Android, make sure to pass the option to the constructor instead of the function like so:

  AndroidOptions _getAndroidOptions() => const AndroidOptions(
                        encryptedSharedPreferences: true,
                      );
                final storage = FlutterSecureStorage(aOptions: _getAndroidOptions());
                

This will prevent errors due to mixed usage of encryptedSharedPreferences. For more info, see this issue.

Info

A Flutter plugin to store data in secure storage:

• Keychain is used for iOS
• AES encryption is used for Android. AES secret key is encrypted with RSA and RSA key is stored in KeyStore
• With V5.0.0 we can use EncryptedSharedPreferences on Android by enabling it in the Android Options like so:

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

For more information see the example app.

• libsecret is used for Linux.

Note KeyStore was introduced in Android 4.3 (API level 18). The plugin wouldn't work for earlier versions.

Getting Started

import 'package:flutter_secure_storage/flutter_secure_storage.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);
                
                

This allows us to be able to fetch secure values while the app is backgrounded, by specifying first_unlock or first_unlock_this_device. The default if not specified is unlocked. An example:

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

Configure Android version

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

android {
                    ...
                
                    defaultConfig {
                        ...
                        minSdkVersion 18
                        ...
                    }
                
                }
                

Note By default Android backups data on Google Drive. It can cause exception java.security.InvalidKeyException:Failed to unwrap key. You need to

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

Configure Web Version

Flutter Secure Storage uses an experimental implementation using WebCrypto. Use at your own risk at this time. Feedback welcome to improve it. The intent is that the browser is creating the private key, and as a result, the encrypted strings in local_storage 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 Forward Secrecy enabled and the proper headers applied to your responses or you could be subject to a javascript hijack.

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/

Configure Linux Version

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 it as a dependency after packaging your app). If you 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
                

Configure Windows Version

Note The current implementation does not support readAll and deleteAll and is subject to change.

Configure MacOS Version

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

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

Integration Tests

Run the following command from example directory

flutter drive --target=test_driver/app.dart
                

9.2.4

• [Android] Fix errors when building for release by upgrading Tink to 1.9.0.
• [iOS] Fix delete and deleteAll when synchronizable is set.
• [iOS] Update migration when value is saved while key already exists with different accessibility option.

9.2.3

• [iOS] Fix for issue #711: The specified item already exists in the keychain.
• [Linux] Fix json.dump with indentations.
• [Web] Update web dependency support to support <2.0.0 instead of <1.0.0.
• [Web] Add wrapKey and wrapKeyIv parameters to webOptions. See readme for more information.
• [macOS] Added useDataProtectionKeyChain parameter.

9.2.2

[iOS, macOS] Fixed an issue which caused the readAll and deleteAll to not work properly.

9.2.1

• Fix async race condition bug in storage operations.
• [macOS] Return nil on macOS if key is not found

9.2.0

New Features:

• [iOS, macOS] Reintroduced isProtectedDataAvailable.
• Listener functionality via FlutterSecureStorage().registerListener()

Bugs Fixed:

• [iOS] Return nil on iOS read if key is not found
• [macOS] Also set kSecUseDataProtectionKeychain on read for macos.

9.1.1

Reverts new feature because of breaking changes.

• [iOS, macOS] Added isProtectedDataAvailable, A boolean value that indicates whether content protection is active.

9.1.0

New Features:

• [iOS, macOS] Added isProtectedDataAvailable, A boolean value that indicates whether content protection is active.

Improvements:

• [iOS, macOS] Use accessibility option for all operations
• [iOS, macOS] Added privacy manifest
• [iOS] Fixes error when no item exists
• [Linux] Fixed search with schemas fails in cold keyrings
• [Linux] Fixed erase called on null
• [Android] Fixed native Android stacktraces in PlatformExceptions
• [Android] Fixed exception when reading data after boot

9.0.0

Breaking changes:

• [Windows] Migrated to FFI with win32 package.

8.1.0

• [Android] Upgraded to Gradle 8.
• [Android] Fixed resetOnError not working.
• [Windows] Changed PathNotFoundException to FileSystemException to be backwards compatible with Flutter SDK 2.12.0.
• [Windows] Applied lint suggestions.
• [Linux] Remove and replace libjsoncpp1 dependency.
• [Linux, macOS, Windows, Web] Update Dart SDK Constraint to support <4.0.0 instead of <3.0.0.

8.0.0

Breaking changes:

• [macOS] The minimum macOS version supported is now 10.14.

Other changes:

• [Android] Fixed an issue when Encrypted Shared Preferences failed, the fallback would not handle the data correctly.
• [Windows] Write encrypted data to files instead of the windows credential system.
• [Linux] Fixed an issue with memory management.

7.0.2

[macOS] Fix issue with plugin name.

7.0.1

[Android] Reverted double initialization of the SharedPreferences because this will break mixed usage of secureSharedPreference on Android.

7.0.0

Breaking changes:

• [macOS] The minimum macOS version supported is now 10.13.

Other changes:

• [Android] Fixed double initialization of the SharedPreferences which caused containsKey and other functions to not work properly.
• [macOS] Upgraded codebase to swift which fixed containsKey always returning true.

6.1.0

• [iOS] (From 6.1.0-beta.1) Migrated from objective C to Swift. This also fixes issues with containsKey and possibly other issues.
• [Android] Upgrade security-crypto from 1.1.0-alpha03 to 1.1.0-alpha04
• [Android] Fix deprecation warnings.
• [All] Migrated from flutter_lints to lint and applied suggestions.

6.1.0-beta.1

• [iOS] Migrated from objective C to Swift. This also fixes issues with containsKey and possibly other issues.

6.0.0

• [Android] Upgrade to Android SDK 33.

5.1.2

This version reverts some breaking changes of update 5.1.0. These changes will become available in version 6.0.0

• [Android] Revert upgrade to Android SDK 33.

5.1.1

• Example app dependencies updated
• Updated homepage

5.1.0

• [Android] You can now select your own key prefix or database name.
• [Android] Upgraded to Android SDK 33.
• [Android] You can now select the keyCipherAlgorithm and storageCipherAlgorithm.
• [Linux] Fixed an issue where no error was being reported if there was something wrong accessing the secret service.
• [macOS] Fixed an memory-leak.
• [macOS] You can now select the same options as for iOS.

5.0.2

• [Android] Fixed bug where sharedPreference object was not yet initialized.

5.0.1

• [Android] Added java 8 requirement for gradle build.

5.0.0

First stable release of flutter_secure_storage for multi-platform! Please see all beta release notes for changes.

This first release also fixes several stability issues on Android regarding encrypted shared preferences.

[5.0.0-beta.5]

• [Linux, iOS & macOS] Add containsKey function.
• [Linux] Fix for use of undeclared identifier 'flutter_secure_storage_linux_plugin_register_with_registrar'

[5.0.0-beta.4]

• [Windows] Fixed application crashing when key doesn't exists.
• [Web] Added prefix to local storage key when deleting, fixing items that wouldn't delete.

[5.0.0-beta.3]

• [Android] Add possibility to reset data when an error occurs.
• [Windows] Add readAll, deleteAll and containsKey functions.
• [All] Refactor option defaults.

[5.0.0-beta.2]

• [Android] Improved EncryptedSharedPreferences by not loading unused Cipher.
• [Android] Removed deprecated classes
• [Web] Improved containsKey function

[5.0.0-beta.1]

Initial BETA support for macOS, web & Windows. Development is still ongoing so expect some functions to not work correctly! Please read the readme.md for information about every platform.

• Migrated to a federated project structure. #254. Thanks jhancock4d
• Added support for encrypted shared preferences on Android. #259

[4.2.1]

• Added kSecAttrSynchronizable support by setting IOSOptions.synchronizable #51
• Changed deprecated jcenter to mavenCentral #246

[4.2.0]

• Remove Strongbox for Android 225. Thanks JordyLangen.

[4.1.0]

• Add support for Linux 185. Thanks talhabalaj
• Improve first-time read speed on Android by not creating cipher when key is not present. Thanks PieterAelse
• Make it possible to customize iOS account name(kSecAttrService). Thanks klyver

[4.0.0]

• Introduce null-safety. Thanks Steve Alexander

[3.3.5]

• Fix thread safety issues in android code to close 161. Thanks koskimas

[3.3.4]

• Fix Android hanging UI on StorageCipher initialization #116 by morrica
• Fix crash only observed for v2 apps #124 by lidongze91
• Fix crash when generating keys in android with RTL locales #132 by iassal
• Fix returning the error as String rather than Exception #134 by wytesk133s
• Fix Android crash onDetachedFromEngine when init fails #144 by iassal
• Handle null value at write function #95 by ewertonrp
• Add support for containsKey #139 by iassal

[3.3.3]

• Fix compatibility with non-AndroidX project. AndroidX Migration is recommended.

[3.3.2]

• Migrate to Android v2 embedder.
• Adds support for specifying iOS Keychain Item Accessibility.

[3.3.1+2]

• Fix iOS build warning Issue 30

[3.3.1+1]

• Fix Android Manifest error Issue 77 and Issue 79. Thanks nate-eisner.

[3.3.1]

• Fix crash without iOSOptions.

[3.3.0]

• Added groupId for iOS keychain sharing. Thanks Maleandr.
• Fix Gradle version in gradle-wrapper.properties. Thanks blasten.
• Added minimum sdk requirement on AndroidManifest. Thanks lidongze91.

[3.2.1]

• Fix Android 9.0 Pie KeyStore exception.

[3.2.0]

• Breaking change. Migrate from the deprecated original Android Support Library to AndroidX. This shouldn't result in any functional changes, but it requires any Android apps using this plugin to also migrate if they're using the original support library. Thanks I-am-original.
• Enable StrongBox on Android devices that support it. Thanks bbedward.

[3.1.3]

• Fix Android 9.0 Pie KeyStore exception. Thanks hacker1024

[3.1.2]

• Added recreating secretKey if its decoding failed. Fix for unwrap key. Thanks hnvn.

[3.1.1]

• Suppress warning about unchecked operations when compiling for Android.

[3.1.0]

• Added readAll and deleteAll.

[3.0.0]

• Breaking change. Changed payloads encryption for Android from RSA to AES, AES secret key is encrypted with RSA.

[2.0.0]````

• Breaking change. Changed key alias to fix Android 4.4.2 issue. The plugin isn't able to get previous stored data.

[1.0.0]

• Bump version

[0.0.1]

• Initial release