Getting Started with Kapsel – Part 5 — EncryptedStorage
EncryptedStorage
The EncryptedStorage plugin provides an asynchronous API to store key value pairs securely. The API is based on the the web storage interface but is asynchronous in nature.
For additional details see the JavaScript file in a project that includes this plugin at
project_name\www\plugins\com.sap.mp.cordova.plugins.encryptedstorage\www\encryptedstorage.js
or the JS Documentation at Kapsel EncryptedStorage API Reference.
The following steps will demonstrate this plugin.
- Create the project.
cordova -d create C:\Kapsel_Projects\StorageDemo com.mycompany.storage StorageDemo "{\"plugin_search_path\":\"C:/SAP/MobileSDK3/KapselSDK/plugins/\"}" cd StorageDemo cordova -d platform add android cordova -d create ~/Documents/Kapsel_Projects/StorageDemo com.mycompany.storage StorageDemo "{\"plugin_search_path\":\"/Users/i826567/SAP/MobileSDK3/KapselSDK/plugins/\"}" cd ~/Documents/Kapsel_Projects/StorageDemo cordova -d platform add ios
- Add the enycryptedstorage plugin.
cordova -d plugin add com.sap.mp.cordova.plugins.encryptedstorage
- Replace www\index.html with index.htmland run
cordova -d prepare
Notice that the API is asynchronous. This can make it a bit more challenging to work with. The article Asynchronous JS: Callbacks, Listeners, Control Flow Libs and Promise provides some suggestions on how to work with asynchronous methods.
- Use the Android IDE or Xcode to deploy and run the project.
- If the Logging plugin is added and the log level set to debug, the messages logged by the EncryptedStorage plugin can be viewed. The log tag it uses is SMP_ENCRYPTED_STORAGE.
- Note that as of SP03, the data vault of the Logon plugin is required by the EncryptedStorage plugin. The Logon plugin can be initialized using a new method in SP03 called sap.Logon.initPasscodeManager. This is to be used instead of sap.Logon.init if the application is not registering against an SAP Mobile Platform or Gateway server and Logon plugin’s data vault is required.
In SP03 the encryption keys are stored in the Logon Plugin’s data vault and the constructor
new sap.EncryptedStorage(store_name)
no longer takes a password as a parameter. The data contained in a store created with versions prior to SP03 is not migrated to SP03.
Note that as of SMP 3.0 SP02, if the Logon plugin’s data vault is deleted, the EncyptedStorage plugin will also delete all storage as well. This can occur when the user clicks the Forgot Application Passcode button on the unlock screen of the Logon plugin, if the user enters too many incorrect passcodes or if the method sap.Logon.core.deleteRegistration is called.
Note on Android, not more than 1 MB can be stored for a single key/value pair prior to SP03.
- The following are some technical details of where the data is stored on Android.
Key value pairs are stored in a SQLLite Database.
The database is created using local storage which can only be accessed by the application that created it. The file is stored under /data/data/packageName and can be seen and accessed when using an emulator but not a device.As of SP03 the values and the keys stored in this SQLLite database are encrypted. See EncryptedStorage Plugin for additional technical details on the encryption used to store the data.
Updated for SMP 3.0 SP03
Hi, When I am trying getItem method offline, I am getting the following error.
EncryptionHelper$DataEncryptionException: Datavault not accessable.
Kindly help me in fixing it up.
Thanks,
Balajee B
What OS version are you trying this on? Did you make any additional changes to the provided index.html? Do you have any additional instructions on how to reproduce the problem? Are you using the SP03 Kapsel plugins with Cordova 3.4.0-0.1.3?
I fixed the issue 🙂 It was because of logon plugin issue..
Thanks,
Balajee
Do we have any specific android version like after which the encrypted storage plugin works? Because, In android 19 and above it works fine but in android 16, it is not working..
Thanks,
Balajee
Kapsel plugins support android 4.0+ and IOS 6.0+.
Thanks Midhun 🙂 but when I try Kapsel in 4.1.2, it is not working but the same works in 4.2.2.
Can you provide a few more details of how to reproduce the problem you are seeing? I was able to run the sample described in this document in a 4.1.2 Android emulator.
This deals with the android version of this plugin. Is this functionality also (going to be) available for iOS?
It is supported in IOS(6.0+) too.
Midhun VP
I tried this on android but I found some problems, first off the application showed an error that sap.Logon.initPasscodeManager is undefined (uncaught Type error: Object#<Object> has no method 'initPasscodeManager ') while I added the logon plugin in the project. I pressed OK on the error shown and found that all function were working perfectly except for Delete Storage function (uncaught TypeError: Object[object Object] has no method 'deleteStore'). I tried also to use sap.Logon.init everything was working except the Delete Storage. How did everything worked without sap.initPasscodeManager? and why the deleteStorage function is not working? I also tried to remove all logon function and everything worked.How this happened while it is mentioned that Logon plugin is required by EncryptedStorage to store the encryption keys the Logon Plugin's data vault, isn't this weird? by the way I'm using SMP 3.0
Perhaps the issue is with the version of the SMP 3.0 SDK that you are using. The samples in the guide are meant to be used with the 3.0 SP03 release.
The new features section attempts to explain some of the relevant changes in the SDK and server releases from a Kapsel perspective. See the SDK SP02 and SDK SP03 sections for further details on the delete and initPasscodeManager methods in Getting Started with Kapsel - Appendix G -- New Features
There are also instructions mentioning how to download the SP03 release in Getting Started with Kapsel - Part 1
Finally, the upgrading section mentions how to look at the plugin.xml file from a Kapsel plugin to determine the version number. Getting Started with Kapsel - Appendix E -- Upgrading
Hope that helps,
Dan van Leeuwen
thank you... I updated to SMP3.0 SP03 and everything worked correctly.
Updated for SMP SDK 3.0 SP04
Updated for SMP SDK 3.0 SP05
Updated for SMP SP06 SDK and SP05 Server.
Hi Daniel,
I am getting Null reference exception while calling any method of EncryptedStorage. I am developing for Windows 8.1. I am using SMP SDK 3.0 SP07.
Error: Invalid pointer System.NullReferenceException: Object reference not set to an instance of an object.
Regards,
Nikhil Agarwala
I have forwarded this question on to one of my colleagues who works with Windows development.
I just gave the sample a quick try on Android and did not encounter a problem.
Regards,
Dan van Leeuwen
Hi Daniel,
Any updates on the above issue?
Regards,
Nikhil Agarwala
Yesterday was a public holiday in Canada.
One other thing to try would to try it again using the just released SP08 PL01 SDK.
Were there any errors when creating the project or adding the plugins?
Regards,
Dan van Leeuwen
Hi Daniel,
No there was no error while creating the project or during adding the plugin.
Regards,
Nikhil Agarwala
Hi Nikhil,
how do you use the UltraLite library (needed for EncryptedStorage lib)?
I could reproduce the NullReferenceException with only using UltraLite.winmd which is only a wrapper above dll (I called setItem method from JS). Adding UltraLite.dll to the sample's build folder fixed the error.
Best regards,
Peter
Nikhil,
1) Did you create the store before calling any other method?
2) I used 3.8 build and could not reproduce this issue.
Are you using the index.html that is included on this page? If not, please share your index.html.
Thanks,
Ashwin.
Thanks for the informative article. I have the plugin working, my only question is can you store data types other than string values? I need to be able to store arrays that include all data types. How would this be accomplished? Thank you!
Perhaps converting the array to a JSON string would help?
var stringToStore = JSON.stringify(myArray);
var myArray = stringToStore(JSON.parse(stringToStore));
Regards,
Dan van Leeuwen
That's a cool idea. I'll give that a try, I think it will work for me. Thanks!
Hi,
I am able to successfully test the sample application. But for my application I am registering to SMP using HTTPS POST method with no passcode screen. How can use the EncryptedStorage plugin?
I am using SP08. The error that I am getting for setItem method is:
The text associated with this error code could not be found.
SAP.Logon.LogonCore+LogonException: Exception of type 'SAP.Logon.LogonCore+LogonException' was thrown.
at SAP.EncryptedStorage.StorageDb.<setItem>d__0.MoveNext()
--- End of stack trace from previous location where exception was thrown ---
at System.Runtime.CompilerServices.TaskAwaiter.ThrowForNonSuccess(Task task)
at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)
at SAP.EncryptedStorage.StorageDbAsync.<>c__DisplayClass1.<<setItem>b__0>d__3.Mov
Thanks,
Chirag.
Thanks Daniel,
I have a question, what if I want to use pouchdb instead of SQLLite ?
Regards
Diego
I don't believe the encrypted storage plugin lets you plugin another database, but I don't see any reason you could not use another solution such as pouchdb instead of the encrypted storage plugin from the SDK.
What is the data size limit of SAP Encrypted Storage in iOS and Android in Megabytes (MB)?
Also, what is the size limit for Individual Key value pair in iOS and Android in megabytes (MB) in latest SMP SDK SP 14?
The current version of this document is available at
https://blogs.sap.com/2016/12/28/getting-started-with-kapsel-part-5-encrypted-storagesp13/
I don't believe there is a fixed max size.  When dealing with a mobile device that may have limited memory, you may wish to try to limit the amount of items you load into memory.
Regards,
Dan van Leeuwen