SecureStorage plugin for Apache Cordova

Introduction

This plugin is for use with Apache Cordova and allows your application to securely store secrets such as usernames, passwords, tokens, certificates or other sensitive information (strings) on iOS & Android phones and Windows devices.

Supported platforms

• Android
• iOS
• Windows (Windows 8.x/Store, Windows 10/UWP and Windows Phone 8.1+)

Contents

• Installation
• Plugin API
• LICENSE

Installation

Below are the methods for installing this plugin automatically using command line tools. For additional info, take a look at the Plugman Documentation, cordova plugin command and Cordova Plugin Specification.

Cordova

The plugin can be installed via the Cordova command line interface:

• Navigate to the root folder for your phonegap project.
• Run the command:

cordova plugin add cordova-plugin-secure-storage-persistent

or if you want to be running the development version,

cordova plugin add https://github.com/brendoncoin/cordova-plugin-secure-storage-persistent.git

Plugin API

Create a namespaced storage.

var ss = new cordova.plugins.SecureStorage(
    function () { console.log('Success')},
    function (error) { console.log('Error ' + error); },
    'my_app');

Set a key/value in the storage.

ss.set(
    function (key) { console.log('Set ' + key); },
    function (error) { console.log('Error ' + error); },
    'mykey', 'myvalue');

where key and value are both strings.

Get a key's value from the storage.

ss.get(
    function (value) { console.log('Success, got ' + value); },
    function (error) { console.log('Error ' + error); },
    'mykey');

Remove a key from the storage.

ss.remove(
    function (key) { console.log('Removed ' + key); },
    function (error) { console.log('Error, ' + error); },
    'mykey');

Get all keys from the storage.

ss.keys(
    function (keys) { console.log('Got keys ' + keys.join(', ')); },
    function (error) { console.log('Error, ' + error); });

Clear all keys from the storage.

ss.clear(
    function () { console.log('Cleared'); },
    function (error) { console.log('Error, ' + error); });

Platform details

iOS

On iOS secrets are stored directly in the KeyChain through the SAMKeychain library.

Configuration

On iOS it is possible to configure the accessibility of the keychain by setting the KeychainAccessibility preference in the config.xml to one of the following strings:

• AfterFirstUnlock
• AfterFirstUnlockThisDeviceOnly
• WhenUnlocked (default)
• WhenUnlockedThisDeviceOnly
• WhenPasscodeSetThisDeviceOnly (this option is available only on iOS8 and later)

For reference what these settings mean, see Keychain Item Accessibility Constants.

For example, include in your config.xml the following:

    <platform name="ios">
        <preference name="KeychainAccessibility" value="WhenUnlocked"/>
    </platform>

iOS 7 Support

iOS 7 is supported without WhenPasscodeSetThisDeviceOnly option.

How to test the plugin using iOS 7 simulator:

• Download and install Xcode 6 into a separate folder, e.g. /Application/Xcode 6/
• Run $ xcode-select --switch <path to Xcode6>/Contents/Developer
• Build Cordova app with the plugin and run it in iOS 7 simulator

Android

On Android there does not exist an equivalent of the iOS KeyChain. The SecureStorage API is implemented as follows:

• A random 256-bit AES key is generated.
• The AES key encrypts the value.
• The AES key is encrypted with a device-generated RSA (RSA/ECB/PKCS1Padding) from the Android KeyStore.
• The combination of the encrypted AES key and value are stored in SharedPreferences.

The inverse process is followed on get.

Native AES is used when available, otherwise encryption is provided by the sjcl library. API level 23 (Android 6.0 Lollipop) is required on Android.

Users don't need to have a secure screen-lock set.

The plugin does not require encryption on the device so that the stored values will persist when changing lock screen settings, even without any security on the lock screen at all.

Android keystore deletion on security setting change

Changing the lock screen type on Android may erase the keystore (issues 61989 and 210402). This is also described in the Android Security: The Forgetful Keystore blog post.

This plugin has relaxed encryption settings to obtain persistent storage on Android.

Windows

Windows implementation is based on PasswordVault object from the Windows.Security.Credentials namespace. The contents of the locker are specific to the app so different apps and services don't have access to credentials associated with other apps or services.

Limitations: you can only store up to ten credentials per app. If you try to store more than ten credentials, you will encounter an error. Read documentation for more details.

Browser

The browser platform is supported as a mock only. Key/values are stored unencrypted in localStorage.

FAQ

• I get the error cordova.plugins.SecureStoragePersistent is not a function, what gives?

  You can instantiate the plugin only after the deviceready event is fired. The plugin is not available before that. Also make sure you use the plugin after its success callback has fired.

• Do my users need to set a PIN code on their Android devices to use the plugin?

  No. Users are free to determine their own risk tolerance and take appropriate precautions, or not.

Testing

Setup

1. Create a cordova app.
2. Change the start page in config.xml with <content src="cdvtests/index.html" />
3. Add your platforms.
4. Add the cordova-plugin-test-framework plugin:

cordova plugin add http://git-wip-us.apache.org/repos/asf/cordova-plugin-test-framework.git

5. Finally add the secure storage plugin as well as the tests from its location

cordova plugin add PATH_TO_SECURE_STORAGE_PLUGIN
cordova plugin add PATH_TO_SECURE_STORAGE_PLUGIN/tests

Running the tests

Just run the app for all platforms. Remember, if you have changes to test you will need to remove the secure storage plugin and add it again for the changes to be seen by the app.

LICENSE

The MIT License

Copyright (c) 2015 Crypho AS.

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.