@atroo/capacitor-secure-storage-plugin

Securely store secrets such as usernames, passwords, tokens, certificates or other sensitive information (strings) on iOS & Android

Compatibility

Since v5 we follow the versioning of Capacitor, which means v5 of this plugin can be used with Capacitor 5, while v6 can be used with Capacitor 6.

Install

npm install @atroo/capacitor-secure-storage-plugin
npx cap sync

Features

Android

This plugin uses EncryptedSharedPreferences to store sensitive information securely on any Android device. It will automigrate data from older versions after update.

iOS

When using set() you can specify a different accessibility modifier of the keychain to control, when access to a key should be allowed. Providing a different accessibility modifier on consecutive calls of set() for the same key, will remove the old key and create it new under the hood to prevent keychain errors.

Notes

Android

AutoBackup

To stay secure you need to handle the Auto Backup rules in Android. Please refer to this document.

Java 21

The plugin requires Java 21 to run. You can set it using the following options:

• changing the IDE settings.
• changing the JAVA_HOME environment variable.
• changing org.gradle.java.home in gradle.properties.

upgrading gralde

go to android run ./gradlew --version and check the Android Gradle Plugin version in android/build.gradle.

Edit gradle/wrapper/gradle-wrapper.properties: distributionUrl=https\://services.gradle.org/distributions/gradle-8.7-all.zip

Then update the wrapper:

./gradlew wrapper --gradle-version 8.7

API

• setStorageAdapter(...)
• getStorageAdapter()
• get(...)
• getAccessibility(...)
• set(...)
• remove(...)
• clear()
• keys()
• getPlatform()
• Interfaces
• Type Aliases
• Enums

The SecureStoragePlugin plugin interface

setStorageAdapter(...)

setStorageAdapter(options: { web: { adapter: WebStorageAdapter; }; }) => Promise<{ value: boolean; }>

gets the value for the given key

| Param | Type | Description | | ------------- | --------------------------------------------------------------------------------------- | -------------------- | | options | { web: { adapter: WebStorageAdapter; }; } | key to get value for |

Returns: Promise<{ value: boolean; }>

getStorageAdapter()

getStorageAdapter() => Promise<{ adapter: WebStorageAdapter; }>

gets the current storage adapter or null

Returns: Promise<{ adapter: WebStorageAdapter; }>

get(...)

get(options: { key: string; }) => Promise<{ value: string; }>

gets the value for the given key

| Param | Type | Description | | ------------- | ----------------------------- | -------------------- | | options | { key: string; } | key to get value for |

Returns: Promise<{ value: string; }>

getAccessibility(...)

getAccessibility(options: { key: string; }) => Promise<{ value: string | undefined; }>

gets the accessibility for the given key

| Param | Type | Description | | ------------- | ----------------------------- | ---------------------------- | | options | { key: string; } | key to get accessibility for |

Returns: Promise<{ value: string; }>

set(...)

set(options: SetDataOptions) => Promise<{ value: boolean; }>

sets the value for the given key

| Param | Type | Description | | ------------- | --------------------------------------------------------- | -------------------- | | options | SetDataOptions | key and value to set |

Returns: Promise<{ value: boolean; }>

remove(...)

remove(options: { key: string; }) => Promise<{ value: boolean; }>

removes the value for the given key

| Param | Type | Description | | ------------- | ----------------------------- | ----------------------- | | options | { key: string; } | key to remove value for |

Returns: Promise<{ value: boolean; }>

clear()

clear() => Promise<{ value: boolean; }>

clears all values

Returns: Promise<{ value: boolean; }>

keys()

keys() => Promise<{ value: string[]; }>

gets all keys

Returns: Promise<{ value: string[]; }>

getPlatform()

getPlatform() => Promise<{ value: string; }>

gets the platform

Returns: Promise<{ value: string; }>

Interfaces

SetDataOptions

allows to define how properties can be accessed on iOS

| Prop | Type | | ------------------- | ------------------------------------------------------- | | key | string | | value | string | | accessibility | Accessibility |

Type Aliases

Accessibility

allows to define how properties can be accessed on iOS

'afterFirstUnlock' | 'afterFirstUnlockThisDeviceOnly' | 'whenUnlocked' | 'whenUnlockedThisDeviceOnly' | 'always' | 'alwaysThisDeviceOnly' | 'whenPasscodeSetThisDeviceOnly'

Enums

WebStorageAdapter

| Members | Value | | -------------------- | ----------------------------- | | LocalStorage | 'LocalStorage' | | SessionStorage | 'SessionStorage' | | SessionCookie | 'SessionCookie' |