@aparajita/capacitor-secure-storage
Version:
Capacitor 8+ plugin that provides secure storage for the iOS and Android
141 lines (84 loc) • 5.96 kB
Markdown
# capacitor-secure-storage [](https://badge.fury.io/js/@aparajita%2Fcapacitor-secure-storage)
This plugin for [Capacitor 8](https://capacitorjs.com) provides secure key/value storage on iOS and Android. It was originally designed to be a companion to [@aparajita/capacitor-biometric-auth](https://github.com/aparajita/capacitor-biometric-auth/#readme) 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](https://capacitorjs.com/docs/main/reference/support-policy) for information on changes to the minimum supported development tools and platforms.
## Installation
```sh
pnpm add @aparajita/capacitor-secure-storage # npm install, yarn add
```
Not using [pnpm](https://pnpm.io)? 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](src/definitions.ts). For a complete example of how to use this plugin in practice, see the [demo section](#demo).
### 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](https://pnpm.io) is required to run the demo.
```shell
# 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.
```shell
pnpm build
```
From the root directory, you can run the demos using:
iOS:
```shell
pnpm demo.pods.ios
pnpm demo.spm.ios
```
Android:
```shell
pnpm demo.pods.android
pnpm demo.spm.android
```
Web:
```shell
pnpm demo.pods.browser
pnpm demo.spm.browser
```
You can also run commands from within the demo directory:
```shell
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.