capacitor-secure-storage  

This plugin for Capacitor 8 provides secure key/value storage on iOS and Android. It was originally designed to be a companion to @aparajita/capacitor-biometric-auth in order to securely store login credentials, but can be used to store any JSON data types.

🛑 BREAKING CHANGES:

See the Capacitor 8 support page for information on changes to the minimum supported development tools and platforms.

Installation

pnpm add @aparajita/capacitor-secure-storage # npm install, yarn add

Not using pnpm? You owe it to yourself to give it a try. It’s faster, better with monorepos, and uses way, way less disk space than the alternatives.

Usage

The API is thoroughly documented here. For a complete example of how to use this plugin in practice, see the demo section.

iOS

On iOS, data is stored in the encrypted system keychain and is specific to your app. Please note that currently iOS will not delete an app’s keychain data when the app is deleted. But since only an app with the same app id — which is guaranteed by Apple to be unique across all apps — can access that data, this is not a security issue.

iCloud Keychain sync

You may synchronize data with iCloud Keychain. Synchronization can be controlled globally and per operation. This allows you to share secure data (such as login credentials) for the same app across multiple devices.

👉 The user must enable iCloud Keychain on a device in order for data to sync.

To turn sync on or off globally, call setSynchronize(). You can override the global setting per operation by passing a boolean in the sync option.

Note that iOS considers the local keychain and iCloud keychain as two separate keychains. Which keychain is affected by an operation depends on the global and per operation sync setting. This means, for example, that a value can be stored and retrieved with the same key in both keychains.

👉 When the resolved sync setting is true, calls to keys() return the keys for both the iCloud and local keychains. Thus there may be duplicates.

Android

On Android, data is encrypted using AES in GCM mode with a secret key generated by the Android KeyStore, then stored in SharedPreferences, which is specific to your app. If the app is deleted, its data is deleted as well.

Web

On the web, data is stored unencrypted in localStorage, so that you can see the data you are storing. This is for debugging purposes only; you should not use this plugin on the web in production.

Demo

The Ionic/Vue demo app demonstrates all of the features of this plugin. There are two variants of the demo, one which uses CocoaPods (demo-pods) and one which uses Swift Package Manager (demo-spm). Of course, CocoaPods and Swift Package Manager only apply to iOS. In both demos, the Android version is identical.

Installation

pnpm is required to run the demo.

# Clone the github repo and install dependencies
git clone https://github.com/aparajita/capacitor-secure-storage.git
cd capacitor-secure-storage
pnpm install -r

Running

Before running either of the demos, you must build the plugin first, as the demos reference a local build of the plugin.

pnpm build

From the root directory, you can run the demos using:

iOS:

pnpm demo.pods.ios
pnpm demo.spm.ios

Android:

pnpm demo.pods.android
pnpm demo.spm.android

Web:

pnpm demo.pods.browser
pnpm demo.spm.browser

You can also run commands from within the demo directory:

cd demo-pods # or cd demo-spm
pnpm ios
pnpm android
pnpm dev

Usage

Sync to iCloud Keychain (iOS only)

On iOS, an “iCloud sync” checkbox appears. Checking/unchecking this turns on/off iCloud sync globally.

In addition, a “Sync” checkbox appears to the right of the “Key” field which controls iCloud sync. By default, it is in an indeterminate state, which means the global sync setting is used. Tapping the “Sync” checkbox cycles between indeterminate => checked => unchecked. If the “Sync” checkbox is checked or unchecked, that overrides the global sync checkbox.

When the resolved sync setting is on, any operations (other than setting the prefix) affect the iCloud keychain instead of the local keychain.

Set the prefix

To change the key prefix, edit the "Prefix" field and press "Set".

Save a value

To save a key/value item to storage, enter the key in the "Key" field and a JSON-parseable value in the "Data" field. As you type in the "Data" field, if it is a valid value, the data type is displayed below the field.

You may store any valid JSON value: string, number, boolean, array, object, or null. In addition, if the "Data" field looks like an ISO 8601 datetime (begins with YYYY-MM-DD), it is parsed as such, and if successfully parsed the type will be shown as "date". Note that the time and milliseconds are optional. So, for example, these are all parsed as a valid date:

2020-08-27
2020-08-27T13:27:07
2020-08-27T13:27:07.413Z

Get a value

To get a value from storage, enter the key and press "Get".

Remove an item

To remove an item from storage, enter the key and press "Remove".

Clear all items

To remove all items with the current prefix from storage, press "Clear".

View all keys

To view all of the keys with the current prefix in storage, press "Keys". Note that if the resolved sync setting is true on iOS, keys from both the iCloud keychain and the local keychain will be displayed.