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.

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

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) ERROR_BAD_PASSWORD

This error code indicates a wrong password was provided

(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_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.

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_BAD_PASSWORD, 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.