JSDoc: Namespace: EncryptedStorage

The EncryptedStorage class is used as a secure local store. The EncryptedStorage API is based on the W3C web storage API, but it is asynchronous.

As of version 3.0.3, the datavault managed by the Logon plugin is used to store the encryption keys. This means that no password needs to be provided to the EncrytedStorage plugin. The dependency on Logon's datavault means that Logon must be in an unlocked state for the EncryptedStorage functions to succeed.

If the datavault managed by the Logon plugin gets deleted (eg: the user forgets their passcode), then all encrypted stores will also be deleted.

Applications using EncryptedStorage plugin of version 3.0.2 need to be updated to remove the password parameter which only exists on 3.0.2 EncryptedStorage's constructor. Otherwise a javascript exception will be thrown. In addition, the data in encrypted storage needs to be recreated, as backward compatibility is not supported between encrypted storage versions 3.0.2 and 3.0.3.

Adding and Removing the EncryptedStorage Plugin
The EncryptedStorage plugin is added and removed using the Cordova CLI.

To add the EncryptedStorage plugin to your project, use the following command:
cordova plugin add kapsel-plugin-encryptedstorage

To remove the EncryptedStorage plugin from your project, use the following command:
cordova plugin rm kapsel-plugin-encryptedstorage

Members

(constant) COMPLEX_STRING_MAXIMUM_LENGTH

This constant is the length of the largest string that is guaranteed to be successfully stored on Android for plugin version 3.0.2 and earlier (as of version 3.0.3 this size restriction no longer applies). The limit depends on how many bytes the string takes up when encoded with UTF-8 (under which encoding characters can take up to 4 bytes). This is the maximum length of a string for which every character takes all 4 bytes. Note that this size restriction is present only on Android and not iOS.

(constant) ERROR_BAD_PASSWORD

This error code indicates that the operation failed due to an incorrect password. The password is set by the constructor of EncryptedStorage for version 3.0.2 and earlier. As of 3.0.3, the password is no longer provided, and this error should not occur.

(constant) ERROR_DATAVAULT_ACCESS_ERROR

This error indicates that the data vault access error.

(constant) ERROR_DATAVAULT_LOCKED

This error indicates that the datavault managed by the Logon plugin is locked. the Logon plugin must be in an unlocked state to use the EncryptedStorage plugin.

(constant) ERROR_DB_ERROR

This error indicates that the SQLite database error.

(constant) ERROR_GREATER_THAN_MAXIMUM_SIZE

This error indicates that the string was too large to store. Only applies for plugin version 3.0.2 and earlier on Android. For iOS and for plugin version 3.0.3 and later on Android, no hard limit is imposed, but be aware of device memory constraints.

(constant) ERROR_INVALID_PARAMETER

This error code indicates an invalid parameter was provided. (eg: a string given where a number was required).

(constant) ERROR_UNKNOWN

This error code indicates an unknown error occurred.

(constant) SIMPLE_STRING_MAXIMUM_LENGTH

This constant is the length of the largest string that can successfully be stored on Android for plugin version 3.0.2 and earlier (as of version 3.0.3 this size restriction no longer applies). Only if all the characters in the string are encoded in 1 byte in UTF-8 can a string actually be this big. Since characters in UTF-8 can take up to 4 bytes, if you do not know the contents of a string, the maximum length that is guaranteed to be successful is EncryptedStorage.COMPLEX_STRING_MAXIMUM_LENGTH, which is EncryptedStorage.SIMPLE_STRING_MAXIMUM_LENGTH/4. Note that this size restriction is present only on Android and not iOS.

Methods

(static) deleteStore(successCallback, errorCallback)

Due to changes in the implementation of EncryptedStorage, calling this function is exactly equivalent to calling EncryptedStorage.clear.

Parameters:

Name	Type	Description
`successCallback`	sap.EncryptedStorage~successCallback	If successful, the successCallback is invoked with no parameters.
`errorCallback`	sap.EncryptedStorage~errorCallback	If there is an error, the errorCallback is invoked with an ErrorInfo object as the parameter.

Example

var successCallback = function() {
   alert("Store deleted!");
}
var errorCallback = function(error) {
   alert("An error occurred: " + JSON.stringify();
}
ks = new sap.EncryptedStorage("storename");
ks.deleteStore(successCallback, errorCallback);

clear(successCallback, errorCallback)

This function removes all items from the store. If there are no items in the store in the first place, that is still counted as a success.

Parameters:

Name	Type	Description
`successCallback`	sap.EncryptedStorage~successCallback	If successful, the successCallback is invoked with no parameters.
`errorCallback`	sap.EncryptedStorage~errorCallback	If there is an error, the errorCallback is invoked with an ErrorInfo object as the parameter.

Example

var store = new sap.EncryptedStorage("storeName");
var successCallback = function() {
   alert("Store cleared!");
}
var errorCallback = function(error) {
   alert("An error occurred: " + JSON.stringify();
}
store.clear(successCallback, errorCallback);

decryptFile(path, successCallback, errorCallback)

This function gets the decrypted file path corresponding to the given path.

Parameters:

Name	Type	Description
`path`	String	The path of the encrypted file for which to decrypt.
`successCallback`	sap.EncryptedStorage~decryptFileSuccessCallback	If successful, the successCallback is invoked with the path to the decrypted file as the parameter
`errorCallback`	sap.EncryptedStorage~errorCallback	If there is an error, the errorCallback is invoked with an ErrorInfo object as the parameter.

Example

var store = new sap.EncryptedStorage("storeName");
var successCallback = function(decryptedFilePath) {
   alert("Decrypted file path is " + decryptedFilePath);
}
var errorCallback = function(error) {
   alert("An error occurred: " + JSON.stringify(error));
}
store.decryptFile("encryptedFilePath", successCallback, errorCallback);

encryptFile(path, successCallback, errorCallback)

This function gets the encrypted file path corresponding to the given path.

Parameters:

Name	Type	Description
`path`	String	The path of the decrypted file for which to encrypt.
`successCallback`	sap.EncryptedStorage~encryptFileSuccessCallback	If successful, the successCallback is invoked with the path to the encrypted file as the parameter
`errorCallback`	sap.EncryptedStorage~errorCallback	If there is an error, the errorCallback is invoked with an ErrorInfo object as the parameter.

Example

var store = new sap.EncryptedStorage("storeName");
var successCallback = function(encryptedFilePath) {
   alert("Encrypted file path is " + encryptedFilePath);
}
var errorCallback = function(error) {
   alert("An error occurred: " + JSON.stringify(error));
}
store.encryptFile("decryptedFilePath", successCallback, errorCallback);

getItem(key, successCallback, errorCallback)

This function gets the value corresponding to the given key. If there is no item with the given key, then the success callback is invoked with null as the parameter.

Parameters:

Name	Type	Description
`key`	String	The key of the item for which to get the value. If null or undefined is passed, "null" is used.
`successCallback`	sap.EncryptedStorage~getItemSuccessCallback	If successful, the successCallback is invoked with the value as the parameter (or null if the key did not exist).
`errorCallback`	sap.EncryptedStorage~errorCallback	If there is an error, the errorCallback is invoked with an ErrorInfo object as the parameter.

Example

var store = new sap.EncryptedStorage("storeName");
var successCallback = function(value) {
   alert("Value is " + value);
}
var errorCallback = function(error) {
   alert("An error occurred: " + JSON.stringify(error));
}
store.getItem("theKey", successCallback, errorCallback);

key(index, successCallback, errorCallback)

This function gets the key corresponding to the given index.

Parameters:

Name	Type	Description
`index`	number	The index of the store for which to get the key. Valid indices are integers from zero (the first index), up to, but not including, the length of the store. If the index is out of bounds, then the success callback is invoked with null as the parameter.
`successCallback`	sap.EncryptedStorage~keySuccessCallback	If successful, the successCallback is invoked with the key as the parameter.
`errorCallback`	sap.EncryptedStorage~errorCallback	If there is an error, the errorCallback is invoked with an ErrorInfo object as the parameter.

Example

// This example shows how to get the key for the last item.
var store = new sap.EncryptedStorage("storeName");
var errorCallback = function( error ){
   alert("An error occurred: " + JSON.stringify(error));
}
var keySuccessCallback = function(key) {
   alert("Last key is " + key);
}
var lengthSuccessCallback = function(length) {
   store.key(length - 1, keySuccessCallback, errorCallback);
}
store.length(lengthSuccessCallback, errorCallback);

length(successCallback, errorCallback)

This function gets the length of the store. The length of a store is the number of key/value pairs that are in the store.

Parameters:

Name	Type	Description
`successCallback`	sap.EncryptedStorage~lengthSuccessCallback	If successful, the successCallback is invoked with the length of the store as the parameter.
`errorCallback`	sap.EncryptedStorage~errorCallback	If there is an error, the errorCallback is invoked with an ErrorInfo object as the parameter.

Example

var store = new sap.EncryptedStorage("storeName");
var successCallback = function(length) {
   alert("Length is " + length);
}
var errorCallback = function(error) {
   alert("An error occurred: " + JSON.stringify(error));
}
store.length(successCallback, errorCallback);

removeItem(key, successCallback, errorCallback)

This function removes the item corresponding to the given key. If there is no item with the given key in the first place, that is still counted as a success.

Parameters:

Name	Type	Description
`key`	String	The key of the item to remove. If null or undefined is passed, "null" is used.
`successCallback`	sap.EncryptedStorage~successCallback	If successful, the successCallback is invoked with no parameters.
`errorCallback`	sap.EncryptedStorage~errorCallback	If there is an error, the errorCallback is invoked with an ErrorInfo object as the parameter.

Example

var store = new sap.EncryptedStorage("storeName");
var successCallback = function() {
   alert("Value removed");
}
var errorCallback = function(error) {
   alert("An error occurred: " + JSON.stringify(error));
}
store.removeItem("somekey", successCallback, errorCallback);

setItem(key, value, successCallback, errorCallback)

This function sets an item with the given key and value. If no item exists with the given key, then a new item is created. If an item does exist with the the given key, then its value is overwritten with the given value.

Parameters:

Name	Type	Description
`key`	String	The key of the item to set. If null or undefined is passed, "null" is used.
`value`	String	The value of the item to set. If null or undefined is passed, "null" is used.
`successCallback`	sap.EncryptedStorage~successCallback	If successful, the successCallback is invoked with no parameters.
`errorCallback`	sap.EncryptedStorage~errorCallback	If there is an error, the errorCallback is invoked with an ErrorInfo object as the parameter.

Example

var store = new sap.EncryptedStorage("storeName");
var successCallback = function() {
   alert("Item has been set.");
}
var errorCallback = function(error) {
   alert("An error occurred: " + JSON.stringify(error));
}
store.setItem("somekey", "somevalue", successCallback, errorCallback);

Type Definitions

errorCallback(errorCode)

Callback function that is invoked in case of an error.

Parameters:

Name	Type	Description
`errorCode`	number	An error code indicating what went wrong. Will be one of sap.EncryptedStorage#ERROR_UNKNOWN, sap.EncryptedStorage#ERROR_INVALID_PARAMETER, sap.EncryptedStorage#ERROR_DATAVAULT_LOCKED, sap.EncryptedStorage#ERROR_DB_ERROR, or sap.EncryptedStorage#ERROR_DATAVAULT_ACCESS_ERROR.

Example

function errorCallback(errCode) {
   //Set the default error message. Used if an invalid code is passed to the
   //function (just in case) but also to cover the
   //sap.EncryptedStorage.ERROR_UNKNOWN case as well.
   var msg = "Unkown Error";
   switch (errCode) {
      case sap.EncryptedStorage.prototype.ERROR_INVALID_PARAMETER:
         msg = "Invalid parameter passed to method";
         break;
      case sap.EncryptedStorage.prototype.ERROR_DATAVAULT_LOCKED:
         msg = "Datavault locked";
         // If we want to we could call sap.Logon.unlock in this case.
         break;
   };
   //Write the error to the log
   console.error(msg);
   //Let the user know what happened
   navigator.notification.alert(msg, null, "EncryptedStorage Error", "OK");
};

getItemSuccessCallback(value)

Callback function that is invoked on a successful call to EncryptedStorage.getItem. If the returned value is null, that means the key passed to EncryptedStorage.getItem did not exist.

Parameters:

Name	Type	Description
`value`	String	The value of the item with the given key. Will be null if the key passed to EncryptedStorage.getItem did not exist.

keySuccessCallback(key)

Callback function that is invoked on a successful call to EncryptedStorage.key. If the key returned is null that means the index passed to EncryptedStorage.key was out of bounds.

Parameters:

Name	Type	Description
`key`	String	The key corresponding to the given index. Will be null if the index passed to EncryptedStorage.key was out of bounds.

lengthSuccessCallback(length)

Callback function that is invoked on a successful call to EncryptedStorage.length.

Parameters:

Name	Type	Description
`length`	number	The number of key/value pairs in the store.

successCallback()

Callback function that is invoked on a successful call to a function that does not need to return anything.