@klassicd/capacitor-secure-storage v1.0.12
capacitor-secure-storage
This plugin for Capacitor 2 provides secure key/value storage on the web, iOS, and Android, with an API closely matching that of the Capacitor Storage plugin. If you are using the Storage plugin, this plugin is (more or less) a secure drop-in replacement.
👉 NOTE: This plugin has been tested with Capacitor 3.
Installation
pnpm install @aparajita/capacitor-secure-storage # 'pnpm add' also works
npm install @aparajita/capacitor-secure-storage
yarn add @aparajita/capacitor-secure-storage
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 and below. For a complete example of how to use this plugin in practice, see the demo app.
Web
On the web, data is stored in localStorage
by default. You may change that to sessionStorage
by setting the storageType
property.
Data is encrypted on the web using Blowfish encryption with no IV. Before modifying storage, you must call setEncryptionKey
to set the “password” used to encrypt/decrypt the data.
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.
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.
API
Methods keys() setEncryptionKey(...) set(...) get(...) remove(...) clear()
keys()
keys() => Promise<string[]>
Return a list of all keys with the current storage prefix. The returned keys do not have the prefix.
Returns: Promise<string[]>
setEncryptionKey(...)
setEncryptionKey(key: string) => void
web only
Set the secret key used to encrypt/decrypt data on the web, using blowfish/ECB encryption without an IV.
If you are not using this plugin on the web (including testing), then you do not need to call this method.
If you are using this plugin on the web, this method MUST be called before set() or get().
If key is null or empty, StorageError(code: encryptionKeyNotSet) is thrown.
Param | Type |
---|---|
key | string |
set(...)
set(key: string, data: DataType, convertDate?: boolean | undefined) => Promise<void>
Store data under a given key in the store. If data is not a string, it is converted to stringified JSON first. If data is a Date and convertDate is true (the default), it is converted to an ISO 8601 string and stored as such. Note that dates within an object or an array are converted to ISO strings by JSON.stringify, but will not be converted back to dates by get().
On the web, if setEncryptionKey() has not been called successfully, StorageError(code: encryptionKeyNotSet) is thrown.
Param | Type |
---|---|
key | string |
data | | string| number| boolean| Object| any[]| Date| null |
convertDate | boolean |
get(...)
get(key: string, convertDate?: boolean | undefined) => Promise<DataType>
Retrieve data for a given key from the store. If the retrieved data is in the form of an ISO 8601 date string and convertDate is true (the default), it is converted to a Date.
If no item with the given key can be found, StorageError(code: notFound) is thrown.
On the web, if setEncryptionKey() has not been called successfully, StorageError(code: encryptionKeyNotSet) is thrown.
Param | Type |
---|---|
key | string |
convertDate | boolean |
Returns: Promise<DataType>
remove(...)
remove(key: string) => Promise<boolean>
Remove the data for a given key from the store.
Param | Type |
---|---|
key | string |
Returns: Promise<boolean>
clear()
clear() => Promise<void>
Remove all items from the store with the current key prefix.
Enums
StorageType
Members |
---|
sessionStorage |
localStorage |