Community › Forge › Assets list › Ciphered Local Storage Plugin
ciphered-local-storage-plugin
Mobile icon

Ciphered Local Storage Plugin

Supported
Stable version 3.2.4 (Compatible with OutSystems 11)
Other versions available for 10
Uploaded
 on 15 Nov
 by 
OutSystems
4.8
 (4 ratings)
ciphered-local-storage-plugin

Ciphered Local Storage Plugin

Documentation
3.2.0

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 in 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 workaround 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, that offers a 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 in 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 concern 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 in 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”.


Where can I find the source code of the plugin so I can customize it?

You can find it here:

https://github.com/OutSystems/cordova-outsystems-secure-sqlite-bundle


I plan to use this plugin in a commercial application. Do I need to buy a SQLCipher license?

No, as long as you display the SQLCipher Community Edition license in a 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. 


3.1.4

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 in 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 workaround 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, that offers a 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 in 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 concern 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 in 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.


Where can I find the source code of the plugin so I can customize it?

You can find it here:

https://github.com/OutSystems/cordova-outsystems-secure-sqlite-bundle#v1.0.0


I plan to use this plugin in a commercial application. Do I need to buy a SQLCipher license?

No, as long as you display the SQLCipher Community Edition license in a 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.