Modules.EncryptedDatabase
Provides transparent, secure 256-bit AES encryption of SQLite database files.
This module exposes the same API as Titanium.Database, but it encrypts all content (even the schema) using a password you specify.
You can download the module at appcelerator.encrypteddatabase
Getting Started
- View the Using Titanium Modules document for instructions on getting started with using this module in your application.
Accessing the Module
Use
requireto access this module from JavaScript:var encryptedDatabase = require('appcelerator.encrypteddatabase');The
encryptedDatabasevariable is a reference to the Module object.
Example applications
Example applications are located in the
examplefolder of the module:ToDo Alloydemonstrates how to use this module with Alloy.JSON1-Extensiondemonstrates how to use the SQLite JSON1 extension
Extends: Titanium.Database · Since: 1.0.0 · Platforms: android, iphone, ipad
Properties #
hmacAlgorithm#
Type: Number
The hashing algorithm the encrypted database will use.
This property must be assigned before calling the open() method for it to be applied to the database.
When opening an existing database that was using a different KDF value than what's currently assigned,
then it will be automatically migrated. How long the migration takes depends on the size of the database.
hmacKdfIterations#
Type: Number
Number of iterations that the KDF (Key Derivation Function) will use for hashing.
Integer where the higher the value, the more secure the generated key will be at the cost of performance.
The minimum value allowed is 4000.
Older versions of this module defaulted to 64000, which made database operations faster
(but less secure) compared to the newest module versions. If you want to restore the older version's
performance, then use this property to change it back to 64000 iterations.
This property must be assigned before calling the open() method for it to be applied to the database.
When opening an existing database that was using a different KDF value than what's currently assigned,
then it will be automatically migrated. How long the migration takes depends on the size of the database.
pageSize#
Type: Number
Setting the PRAGMA cipher_page_size value
Setting the PRAGMA cipher_page_size value. For more info look at
https://www.zetetic.net/sqlcipher/sqlcipher-api/#cipher_page_size
Methods #
cipherUpgrade #
Upgrades sqlcipher used in database.
This method can be used to upgrade the sqlcipher used in the database, when
upgrading from an existing app that uses this module from version 1.0.0 to 1.3.1.
Make sure the password is set before using this method.
Alternatively, using database.open() would also update the sqlcipher if the module
detects that it's using an older version. This method is optional to give developers
more flexibility when doing version upgrade on apps.
| Name | Type | Summary | Optional |
|---|---|---|---|
name | String | database name | No |
Returns: CipherUpgradeResult
isCipherUpgradeRequired #
Checks and returns if sqlcipher is required to be updated
This is a check to see if the database is using an older version of sqlcipher.
Use this to check before opening the database, so that you could prompt or inform
the user that it might take a while for database.open() to execute completely, since
calling database.open() does the updating internally, and it might take a while depending
on how big the database is. Returns true if required, otherwise false.
| Name | Type | Summary | Optional |
|---|---|---|---|
name | String | database name | No |
Returns: Boolean
Examples #
Open an encrypted database
var DB = require('appcelerator.encrypteddatabase');
var instance = null;
var dataTofetch = null;
var win = Ti.UI.createWindow({
backgroundColor: 'white'
});
win.addEventListener('open', function () {
init();
setup();
insert();
fetch();
closeDB();
});
var indicator = Ti.UI.createActivityIndicator({
color: 'green',
message: 'Upgrading database ...',
style: Ti.UI.ActivityIndicatorStyle.DARK,
top: 100,
height: Ti.UI.SIZE,
width: Ti.UI.SIZE
});
function init() {
// iOS: check if cipher upgrade is required
if (Ti.Platform.osname === 'iphone' || Ti.Platform.osname === 'ipad') {
if (DB.isCipherUpgradeRequired) {
// check if cipher upgrade required.
if (DB.isCipherUpgradeRequired('test.db')) {
Ti.API.info('upgrade of database required');
indicator.show();
DB.password = 'secret';
Ti.API.info('Opening DB ...');
instance = DB.open('test.db');
indicator.hide();
Ti.API.info('database upgrade complete');
return;
}
}
}
DB.password = 'secret';
Ti.API.info('Opening DB ...');
instance = DB.open('test.db');
}
function setup() {
instance.execute('CREATE TABLE IF NOT EXISTS testtable(id integer PRIMARY KEY);');
instance.execute('INSERT OR IGNORE INTO testtable(id) VALUES (1);');
}
function insert() {
var dataToInsertHandle = instance.execute('SELECT id FROM testtable ORDER BY id DESC LIMIT 1;');
var dataToInsert = null;
if(dataToInsertHandle.isValidRow()) {
dataToInsert = (dataToInsertHandle.fieldByName('id') + 1);
dataTofetch = dataToInsert;
}
instance.execute('INSERT OR IGNORE INTO testtable(id) VALUES (' + dataToInsert + ');');
}
function fetch() {
var rowValue = null;
var rowHandle = instance.execute('SELECT * FROM testtable WHERE id=' + dataTofetch + ';');
if (rowHandle.isValidRow()) {
rowValue = rowHandle.fieldByName('id');
}
alert('Fetched Data: ' + rowValue);
}
function closeDB() {
instance.close();
}
win.add(indicator);
win.open();Use the JSON1-extension to encode/decode JSON-based content
var DB = require('appcelerator.encrypteddatabase');
var win = Ti.UI.createWindow({ backgroundColor: 'white' });
var btn = Ti.UI.createButton({ title: 'Trigger' });
btn.addEventListener('click', accessDatabase);
win.add(btn);
win.open();
function accessDatabase() {
DB.password = 'secret';
Ti.API.info('Opening DB ...');
var instance = DB.open('test.db');
instance.execute('CREATE TABLE IF NOT EXISTS user(name string, phone string);');
instance.execute('INSERT into user (name, phone) VALUES("oz", json(\'{"cell":"+491765", "home":"+498973"}\'));');
var dataToInsertHandle = instance.execute('select user.phone from user where user.name==\'oz\'');
var result = dataToInsertHandle.isValidRow() ? dataToInsertHandle.fieldByName('phone') : null;
alert('Fetched data: ' + result);
Ti.API.info('Closing DB ...');
instance.close();
}