Secure preferences¶
PlayxSecurePrefs stores small secrets (tokens, keys, credentials) encrypted at rest. It has the same typed API as the other preference stores, but every operation is asynchronous, and you choose where the data lives.
- Quick start
- Choosing a backend
- Settings reference
- The
autobackend - Encrypted preferences
- Hiding key names
- Web
- Switching an existing app
- Errors and failures
- Security notes
Quick start¶
PlayxCore.bootCore creates it with the default settings:
await PlayxCore.bootCore();
await PlayxSecurePrefs.setString('access_token', 'abc123');
final token = await PlayxSecurePrefs.getString('access_token');
final missing = await PlayxSecurePrefs.maybeGetString('nope'); // null
await PlayxSecurePrefs.remove('access_token');
await PlayxSecurePrefs.clear();
Typed values and structured data work like the other stores:
await PlayxSecurePrefs.setInt('attempts', 3);
await PlayxSecurePrefs.setBool('biometrics', true);
await PlayxSecurePrefs.setDouble('balance', 12.5);
await PlayxSecurePrefs.setMap('session', {'id': 7, 'role': 'admin'});
await PlayxSecurePrefs.setObject('user', user, toJson: (u) => u.toJson());
| Type | Read (null if missing) |
Read with fallback | Write |
|---|---|---|---|
String |
maybeGetString |
getString ('') |
setString |
int |
maybeGetInt |
getInt (-1) |
setInt |
double |
maybeGetDouble |
getDouble (-1) |
setDouble |
bool |
maybeGetBool |
getBool (false) |
setBool |
| Map / List / Object | maybeGetMap, maybeGetList, maybeGetObject |
getMap, getList, getObject |
setMap, setList, setObject |
Numbers and bools are stored as strings and parsed back; a value that can't be parsed reads as null (so getBool returns its fallback). See Preferences for maps, lists and objects.
Other members:
| Member | Purpose |
|---|---|
PlayxSecurePrefs.storageType |
The backend actually in use, e.g. after an auto fallback. |
PlayxSecurePrefs.isInitialized |
Whether create has been called. |
PlayxSecurePrefs.securePrefs |
The underlying FlutterSecureStorage instance (always created). |
PlayxSecurePrefs.create(securePrefsSettings:) |
Create it yourself instead of through bootCore. |
PlayxSecurePrefs.dispose() |
Release it (mostly for tests). |
PlayxSecurePrefs.migrateFromFlutterSecureStorage() |
Move data from flutter_secure_storage. See below. |
Choosing a backend¶
Select it with PlayxSecurePrefsSettings.storageType. The API stays the same whichever you pick.
PlayxSecureStorageType |
Stores values in | Notes |
|---|---|---|
flutterSecureStorage (default) |
flutter_secure_storage: Keystore-backed storage on Android, Keychain on iOS and macOS, DPAPI on Windows, libsecret on Linux |
The default of previous versions. No startup health check. |
simpleSecureStorage |
simple_secure_storage: the same native stores through a different, actively maintained plugin |
Initialization errors are thrown (unless throwOnError: false). |
encryptedPrefs |
SharedPreferencesAsync, each value encrypted with AES-256-GCM |
The key lives in a secure store, with a fallback. Works anywhere preferences work. |
auto |
The first healthy backend of autoOrder |
Recommended when you want the app to keep working on devices where a plugin fails. |
memory |
A map in memory | Nothing survives a restart. For tests, or as a last resort. |
await PlayxCore.bootCore(
securePrefsSettings: const PlayxSecurePrefsSettings(
storageType: PlayxSecureStorageType.auto,
),
);
Which should I pick?
- Existing app, no problems with
flutter_secure_storage: keep the default. - Seeing plugin errors or crashes on some devices: use
autowithsimple_secure_storagefirst. Data in the old store can be moved withmigrateFromFlutterSecureStorage. - Web: nothing to choose; every type except
memoryuses WebCrypto. - Tests:
memory.
Settings reference¶
PlayxSecurePrefsSettings¶
| Option | Default | Meaning |
|---|---|---|
storageType |
flutterSecureStorage |
The backend. |
autoOrder |
[simpleSecureStorage, flutterSecureStorage, encryptedPrefs] |
Order auto tries backends in. Only these three types are allowed; memory is always the last resort. The first entry is the preferred backend. |
throwOnError |
true |
When false, errors are logged instead of thrown: reads return null, writes are ignored, and memory is used if the backend can't be created. |
encryptKeys |
false |
Hide key names. See below. |
flutterSecureStorageOptions |
defaults | Platform options for flutter_secure_storage. |
simpleSecureStorageOptions |
defaults | Options for simple_secure_storage. |
encryptedPrefsOptions |
defaults | Options for encryptedPrefs. |
clearOnReinstall |
true |
Clear the store on the first start after a reinstall (the iOS and macOS Keychain survives uninstalling). |
createSecurePrefs |
true |
Whether bootCore creates it. |
PlayxFlutterSecureStorageOptions¶
Groups the native flutter_secure_storage options: iosOptions, androidOptions, linuxOptions, windowsOptions, macOsOptions. Defaults use KeychainAccessibility.first_unlock on iOS.
const PlayxSecurePrefsSettings(
flutterSecureStorageOptions: PlayxFlutterSecureStorageOptions(
iosOptions: IOSOptions(accessibility: KeychainAccessibility.unlocked),
),
);
PlayxSimpleSecureStorageOptions¶
| Option | Default | Meaning |
|---|---|---|
appName |
null |
Your app name, used by the plugin on some platforms. |
namespace |
null |
Your app namespace, e.g. com.example.app. |
prefix |
'sss_' |
Prepended to every key to avoid conflicts. |
darwinAccessibility |
afterFirstUnlock |
Keychain accessibility on iOS and macOS. |
PlayxEncryptedPrefsOptions¶
| Option | Default | Meaning |
|---|---|---|
keyPrefix |
'playx_secure_' |
Prefix of every key stored in preferences. It isolates secure values from your other preferences, so clear() only removes keys with this prefix. Must not be empty. |
keyStores |
[simpleSecureStorage, flutterSecureStorage] |
Where the encryption key is kept, in order of preference. Only these two are allowed. |
The auto backend¶
auto picks a backend at every start:
- For each type in
autoOrder, it creates the backend and runs a health check: write a random value, read it back, delete it. - The first backend that passes is used. Failures are logged, not thrown.
- If none passes, it uses
memory, so the app still starts (nothing is persisted that session).
// Prefer simple_secure_storage, fall back to encrypted preferences.
const PlayxSecurePrefsSettings(
storageType: PlayxSecureStorageType.auto,
autoOrder: [
PlayxSecureStorageType.simpleSecureStorage,
PlayxSecureStorageType.encryptedPrefs,
],
);
Data follows the preferred backend¶
If a fallback was used in one session, auto keeps a small journal (in preferences) of what happened, so the data can be moved to the preferred backend on a later start where it works again:
- values written during the fallback are moved back;
- values removed during the fallback stay removed;
- a
clear()during the fallback (for example a logout) is applied to the preferred backend too; - an older fallback value never overwrites a newer one.
The journal contains key names and backend names, never values. With encryptKeys: true it is encrypted as well.
Native crashes can't be caught. Only Dart exceptions trigger a fallback. If a plugin crashes the app natively on some devices, put it last in
autoOrderor remove it.
Encrypted preferences¶
encryptedPrefs encrypts each value with AES-256-GCM (with a random nonce per value, and authentication, so tampering is detected) and saves it in SharedPreferencesAsync. Two keys are involved:
- The primary key: random bytes generated on the device, kept in the first healthy store of
keyStores(on web, a non-extractable WebCrypto key). A marker in preferences remembers which store holds it. - The fallback key: random bytes kept in plain preferences, used when the primary key can't be loaded. It only obfuscates the data: anyone with the preferences file can decrypt it.
Each stored value records which key encrypted it, so values written with the fallback key stay readable once the primary key is back.
Protecting the primary key¶
The key is never discarded while values encrypted with it may still be readable:
| Situation | What happens |
|---|---|
| The key store is unavailable this session | The fallback key is used; the stored key is left untouched. |
| The key store works but the key reads back missing or invalid | The fallback key is used; the stored key is not replaced. |
| It stays missing for 3 starts in a row (for example the Android Keystore was reset) | The key is considered lost: values encrypted with it are removed (they can't be decrypted anymore) and a new key is created. |
| The key is missing and there is no data that needs it | A new key is created right away. |
A key store is removed from keyStores later |
An existing key is still read from where it was created; keyStores only decides where new keys go. |
Hiding key names (encryptKeys)¶
Encrypting values doesn't hide key names such as access_token: some stores keep them readable in files. Enable encryptKeys to store each value under a keyed hash (HMAC-SHA256) of its name instead:
| Storage | Names with encryptKeys: true |
|---|---|
encryptedPrefs (every platform, so all of web) |
Hidden; only keyPrefix stays visible |
flutterSecureStorage on Android |
Hidden (otherwise plain text in a private preferences file) |
simpleSecureStorage on Android |
Already encrypted by the plugin |
| iOS and macOS Keychain | Kept by the OS, out of app files |
| Windows and Linux credential stores | Not hidden |
How it works:
- The hash key is kept in secure storage (the keystore, or a non-extractable WebCrypto key on web), so names can't be guessed from the files alone.
- The real name is stored inside the encrypted value, so
readAll, migrations and recovery keep working. - It can be turned on or off at any time: stored values are converted on the next start. For
flutter_secure_storagethe conversion happens lazily on first use, so startup does no extra work. - If the primary key is unavailable for a session, names are hashed with the fallback key; each entry carries a timestamp, so the newest value wins once the primary key is back, and removals made meanwhile are applied.
- Values you write directly to
PlayxSecurePrefs.securePrefsbypass playx and keep plain names. playx still reads them as a fallback.
Web¶
On web every storage type except memory uses encryptedPrefs with a non-extractable WebCrypto key stored in IndexedDB:
- Nothing secret ships with your app: there is no password, salt or key to configure.
- Scripts can use the key while the page runs, but the browser never lets them read or export its bytes. Stored data can't be decrypted on another machine or offline.
- Values saved by 1.x (which used
flutter_secure_storageon web) are migrated automatically on the first start.
What it doesn't protect against: code running in your page (for example XSS) and full access to the user's browser profile. For auth tokens on web, prefer HttpOnly cookies set by your server.
Switching an existing app from flutter_secure_storage¶
Values saved with the default backend stay in flutter_secure_storage. After changing storageType, copy them over:
await PlayxCore.bootCore(
securePrefsSettings: const PlayxSecurePrefsSettings(
storageType: PlayxSecureStorageType.auto,
),
);
// Safe to call on every start: once the source is empty it does nothing.
final moved = await PlayxSecurePrefs.migrateFromFlutterSecureStorage();
| Parameter | Default | Meaning |
|---|---|---|
from |
PlayxSecurePrefs.securePrefs |
The FlutterSecureStorage holding the data. Pass your own instance if it was created with custom options. |
deleteFromSource |
true |
Delete migrated values from flutter_secure_storage afterwards. |
- Keys that already exist in the new backend are kept, because they are newer.
- It returns the number of values copied, and
0when the current backend isflutterSecureStorageitself. - It understands entries whose names were hidden by
encryptKeys, and skips playx's own internal keys. - It reads
flutter_secure_storage, so it runs into any native crash that plugin has on a device. If that is why you are switching, consider doing the migration once, behind your own guard.
Errors and failures¶
By default errors are thrown to your code. Set throwOnError: false for the lenient behavior:
throwOnError: true (default) |
throwOnError: false |
|
|---|---|---|
| Read fails | throws | logs, returns null / the fallback |
| Write, remove or clear fails | throws | logs, does nothing |
| Backend can't be created | create throws |
logs, uses memory |
Value can't be decrypted (encryptedPrefs) |
returns null (always) |
returns null |
auto and encryptedPrefs never throw because a storage is unavailable: they end up on memory. Failures are written to the PLAYX CORE logger (see Logging).
Security notes¶
- What is protected. Values at rest on the device. Other apps and casual file access can't read them.
- What isn't. A rooted or compromised device, a debugger attached to your running app, and values while they are in memory.
- The fallback key is obfuscation, not secrecy. Treat sessions that use it as lower assurance, and prefer a backend that passes its health check.
- Don't store what you can avoid storing. Refresh tokens and short-lived credentials are good fits; long-lived secrets shared by all users belong on your server.
See also: Preferences, Secure env (for secrets that ship with the app), Testing.