Namespace: EncryptedStorage

sap. 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);

decryptFileWithStorePassword(path, outputPath, successCallback, errorCallback)

This function decrypts the file at the given path and writes a new decrypted file.
Parameters:
Name Type Description
path String The path of the input file for which to decrypt. For ios, it can be file URL (starting with "file"//") or file full path (starting with "/").
outputPath String The file path or file URL of the decrypted output file. If the parameter is set to null or empty string, then the output file is saved in the same folder as input file with the last file extention removed from the input filename. If the output file already exists, it will be deleted first before creating the output file. path and outputPath parameters cannot have the same value.
successCallback sap.EncryptedStorage~decryptFileSuccessCallback If successful, the successCallback is invoked with the path to the decrypted file (starting with "/") 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.decryptFileWithStorePassword("encryptedFilePath", null, successCallback, errorCallback);

encryptFileWithStorePassword(path, outputPath, successCallback, errorCallback)

This function encrypts the file at the given path and writes a new encrypted file.
Parameters:
Name Type Description
path String The path of the input file for which to encrypt. For ios, it can be file URL (starting with "file"//") or file full path (starting with "/").
outputPath String The file path or file URL of the encrypted output file. If the parameter is set to null or empty string, then the output file is saved in the same folder as input file with ".encr" appended to the input filename. If the output file already exists, it will be deleted first before creating the output file. path and outputPath parameters cannot set to the same value.
successCallback sap.EncryptedStorage~encryptFileSuccessCallback If successful, the successCallback is invoked with the path to the encrypted file path (starting with "/") 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.encryptFileWithStorePassword("decryptedFilePath", null, 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.