Skip to content
Titanium SDK

appcelerator.encrypteddatabase

An encrypted version of the Ti.Database namespace

API reference

Compiled from

Modules.EncryptedDatabase

pseudoAndroidiPhoneiPadsince 1.0.0

Extends Titanium.Database

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 require to access this module from JavaScript:

    var encryptedDatabase = require('appcelerator.encrypteddatabase');

    The encryptedDatabase variable is a reference to the Module object.

Example applications

  • Example applications are located in the example folder of the module:

    • ToDo Alloy demonstrates how to use this module with Alloy.
    • JSON1-Extension demonstrates how to use the SQLite JSON1 extension

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();
}

Properties 7

HMAC_SHA1

Numbersince Android 3.3.0, iPhone 2.1.0, iPad 2.1.0read-only

Assigned to hmacAlgorithm to hash with SHA1.

hmacAlgorithm

Numbersince Android 3.3.0, iPhone 2.1.0, iPad 2.1.0

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.

Default: Modules.EncryptedDatabase.HMAC_SHA512

hmacKdfIterations

Numbersince Android 3.3.0, iPhone 2.1.0, iPad 2.1.0

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.

Default: 256000

pageSize

NumberAndroidsince 5.0.0

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

password

Stringsince 1.0.0

The password used to encrypt sensitive data.

Methods 2

cipherUpgrade

iPhoneiPadsince 1.3.1

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.

Parameters
ParametersTypeDescription
nameString

database name

Returns CipherUpgradeResult

isCipherUpgradeRequired

iPhoneiPadsince 1.3.1

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.

Parameters
ParametersTypeDescription
nameString

database name

Returns Boolean