The recent release of SQLCipher 4 introduces many new performance
and security enhancements for applications that use SQLCipher for
secure local data storage. However, the introduction of new default
algorithms, increased KDF iterations and a larger page size means that
SQLCipher 4 will not open older databases by default.
This document provides guidance on the upgrade options available to
applications that have previously integrated SQLCipher versions 1
through 3.
Option 1: Database File Migration
SQLCipher provides a very convenient way to perform an “in place”
migration of a SQLCipher database using PRAGMA cipher_migrate.
This does all the work of updating the database file format with a
single SQL statement. After migration the database will use all of the
latest default settings so an application can immediately benefit from
improved performance and security.
PRAGMA cipher_migrate be run a single time immediately after the key
is provided (i.e. via sqlite3_key() or PRAGMA key in order to
upgrade the database. This would normally occur on the first run after
the application is upgraded to perform a one-time conversation.
After the migration is complete the application will no longer need to
call the command again on subsequent opens.
PRAGMA key = '<key material>';
PRAGMA cipher_migrate;
The PRAGMA will return a single row with the value 0 after
successful completion of the migration process. A non-zero column
value will be returned in the event of a migration failure. On success
the migrated database will remain open and use the same filename.
Important: The cipher_migrate PRAGMA is potentially expensive because it needs to attempt to open the database for each version to
determine the appropriate settings. Therefore an application should
NOT call the PRAGMA every time a database is opened. Instead, an
application should use the recommended process in the cipher_migrate
API documentation.
Note: SQLCipher for Android Java users: when opening a database connection to run PRAGMA cipher_migrate, you must include the
SQLITE_OPEN_CREATE flag as the migration process will temporarily
attach a new database during the migration process.
Option 2: Backwards Compatibility
The second option is to use the new SQLCipher 4 library, but use all
of the SQLCipher 3 (or earlier) settings. This requires an
application to execute PRAGMA statements immediately after keying the
database that will match the settings originally used to create the
database.
Starting with SQLCipher 4.0.1, you can use the new
cipher_compatibility feature. Passing values 1, 2, or 3 to the
PRAGMA will cause SQLCipher to operate with default settings
consistent with the respective major version number for the current
connection. For example, the following will cause SQLCipher to treat
the current database as a SQLCipher 3.x database:
PRAGMA cipher_compatibility = 3;
It is also possible to use the similar cipher_default compatibility
PRAGMA to set the value for the lifetime of a process before key
operations are invoked.
