capacitor-secure-storage

This plugin for Capacitor 6+ 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: Upgrading from 5.x

The minimum Android API level was increased from 22 to 23 (Android 6).

BREAKING CHANGES: Upgrading from 2.x

To be consistent with JavaScript’s Storage and @capacitor/preferences, the plugin now returns null instead of throwing an exception when getting a non-existent item.

Also, the plugin no longer encrypts data on the web, since this plugin is designed for native storage, and including blowfish was unnecessary bloat.

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 app.

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.