To make this change effective you need to:
Publish and rebuild your app - to replace the old local storage database with the new ciphered database.
Uninstall the previous version of your app - to remove the old local storage for security reasons. The old local storage can no longer be accessed by the application.
Install the new version - only this version references the new ciphered database.
Important
Using this plugin disables Android's Auto Backup for your apps. Auto Backup for Apps automatically backs up user data from different apps. If the app is then installed on a new device, Android tries to restore the ciphered local database that was backed up and the device tries to decrypt it with a new key. This causes the app to crash, thus disabling Auto Backup protects your app from crashing.
This plugin uses a set of open-source components, whose license requires a visible reference in your application. For your convenience, you can find the license in the 'License' block under the Public flow of the CipheredLocalStoragePlugin module.
Enable Self Healing
Resets the local database to recover the app when the device is unable to decipher the local database. By default, this is disabled. To enable it, set the EnableSQLCipherSelfHealing preference to true in the Extensibility Configurations.
(Recommended) Using the universal extensibility configurations schema:
---
{
"appConfigurations": {
"cordova": {
"preferences": {
"EnableSQLCipherSelfHealing": true
}
Using the Cordova-based extensibiility configurations schema (for MABS versions lower than 12):
"preferences":{
"global": [{
"name": "EnableSQLCipherSelfHealing",
"value": true
}]
Notes:
Removing the plugin
Removing the plugin is a destructive operation. After you remove the cipher plugin the app cannot work and you lose all data in the Database. We recommend uninstalling the app, and then installing a new version that uses the Database without encryption
What do I need to configure the plugin?
The plugin requires no configuration. The plugin generates a securely randomized key which is used to cipher the database. This key is stored on the device in a secure way, by using the KeyChain (iOS) or the KeyStore (Android).
Can I turn off ciphering for development environments?
You can turn off ciphering for a particular environment. To do this open the CipheredLocalStoragePlugin module and clear the value for its "Extensibility Configurations" property.
Here's a video on how to do it:
https://screencast.com/t/bfftC1BdxZv2
Publish this version of the component in your environment. After you publish all the native apps local storage databases will not be ciphered.
Be careful not to stage this modified version of the "Ciphered Local Storage Plugin" application to other environments, unless you do want to turn off ciphering in such environments.
What happens under the hood when I use this plugin?
This plugin replaces the platform's default local storage database engine (SQLite) with a ciphered one (SQLCipher). The plugin generates a securely randomized key which is used to cipher the database. This key is stored on the device in a secure way, by using the KeyChain (iOS) or the KeyStore (Android).
What happens if you update an existing app to use this plugin?
Once the native app is updated on the device it will try to open the existing database, but it will fail with an error since it is expecting a ciphered database.
The plugin won't delete the existing database. To work around this, your end-user will have to uninstall the app and install it again to start with a new blank ciphered database.
What's the cipher algorithm the plugin uses?The plugin uses SQLCipher Community Edition, which offers 256-bit AES encryption. For more information check the SQLCipher site.
What happens if users update an existing app to remove this plugin?
Once the native app that doesn't contain the plugin is updated on the device, the app tries to open the existing database. This attempt fails with an error because the app expects a non-ciphered database.
The plugin doesn't delete the existing database. Your users need to uninstall the app and install it again. This creates a new blank database.
Do I need to have any special concerns when reading or writing data?
No need to do anything different, you can use local storage entities, entity actions, and aggregates as with the default local storage. What this plugin guarantee is that the data will be ciphered automatically when it is stored in the database and deciphered when it is read.
Are there any restrictions on using it (can I do the same operations)?
There are no restrictions.
Does this affect the data inspection in the browser using "Test In Browser"?
This plugin affects only the local storage database of a native build running on a device. "Test In Browser" keeps working as before.
Is there a way to debug apps? data on the device?
You will be unable to access the database with an external tool because you can't access the securely generated key for it. As a workaround, you can add extra screens with aggregates to your application to enable debugging in your mobile device, or, alternatively, use the browser's "Test In Browser".
Why in Android devices users will need to set a PIN?
This is due to the way Android KeyStore works since it requires a PIN in the device to keep information in the store safe.
I plan to use this plugin in a commercial application. Do I need to buy an SQLCipher license?
No, as long as you display the SQLCipher Community Edition license on the screen of your application. For your convenience, you can find the license in the 'License' block under the Public flow of the CipheredLocalStoragePlugin module.
Find the complete SQLCipher Community Edition terms below:
https://www.zetetic.net/sqlcipher/open-source/
Can I use other plugins for the same effect (ciphering local storage)?
Yes, but let us know what are your needs so we can help you.