Repository files navigation

SQLCipher for Android provides a library replacement forandroid.database.sqlite on the Android platform for use onSQLCipher databases. This library is based on the upstreamAndroid Bindings project and aims to be a long-term replacement for the originalSQLCipher for Android library.

SQLCipher for Android supports Android API 21 and up onarmeabi-v7a,x86,x86_64, andarm64-v8a architectures.

We welcome contributions, to contribute to SQLCipher for Android, acontributor agreement needs to be submitted. All submissions should be based on themaster branch.

Add a local reference to the local library and dependency:

implementation files('libs/sqlcipher-android-undefined-release.aar')implementation'androidx.sqlite:sqlite:2.2.0'

or source a Community edition build from Maven Central:

implementation'net.zetetic:sqlcipher-android:undefined@aar'implementation'androidx.sqlite:sqlite:2.2.0'

importnet.zetetic.database.sqlcipher.SQLiteDatabase;System.loadLibrary("sqlcipher");SQLiteDatabasedatabase =SQLiteDatabase.openOrCreateDatabase(databaseFile,password,null,null,null);

To perform operations on the database instance immediately before or after the keying operation is performed, provide aSQLiteDatabaseHook instance when creating your database connection:

SQLiteDatabaseHookhook =newSQLiteDatabaseHook() {publicvoidpreKey(SQLiteConnectionconnection) { }publicvoidpostKey(SQLiteConnectionconnection) { }    };

There are two main options for using SQLCipher for Android within an Application:

1. Using the SQLCipher for Android classes
2. Using SQLCipher for Android in conjunction with the Android Room API

In both cases, prior to using any portion of the SQLCipher for Android library, the native SQLCipher core library must be loaded into the running application process. The SQLCipher core library is bundled within the AAR of SQLCipher for Android, however, the developer must load this library explicitly. An example below:

System.loadLibrary("sqlcipher");

SQLCipher for Android provides two classes for opening and access database files. TheSQLiteDatabase provides static methods for opening/creating database files and general data access.Additionally, applications may choose to subclass theSQLiteOpenHelper class which provides mechanisms for performing database migrations, as well as general data access.

SQLCipher for Android may also integrate with the Room API via theSupportOpenHelperFactory, an example is given below:

System.loadLibrary("sqlcipher");Stringpassword ="Password1!";FiledatabaseFile =context.getDatabasePath("demo.db");SupportOpenHelperFactoryfactory =newSupportOpenHelperFactory(password.getBytes(StandardCharsets.UTF_8));db =Room.databaseBuilder(context,AppDatabase.class,databaseFile.getAbsolutePath())        .openHelperFactory(factory).build();

Logging may occur in 3 distinct areas within this library:

1. Within the Java client library
2. Within the JNI interop layer
3. Within SQLCipher core

By default, logging within the Java client library is routed to Logcat. If you wish to disable this logging entirely, you may utilizetheNoopTarget instead:

Logger.setTarget(newNoopTarget());

You can instead provide a custom logging target by registering a different target that implements theLogTarget interface.

There are two different compile-specific options available to alter the logging output from the JNI layer. To removeINFO,DEBUG, andVERBOSE log messages from the JNI layer, include-DNDEBUG with CFLAGS; this will allowWARN andERROR logs to output to logcat. Alternatively, to exclude all log output from JNI, build the library using-DSQLCIPHER_OMIT_LOG.

To manage the logging produced from SQLCipher core, please review the runtime configurations:PRAGMA cipher_log,PRAGMA cipher_log_level, andPRAGMA cipher_log_source.

Currently, SQLCipher for Android uses NDK version "25.2.9519653".

This repository is not batteries-included. Specifically, you will need to buildlibcrypto.a, the static library from OpenSSL using the NDK for thesupported platforms, and bundle the top-levelinclude folder from OpenSSL. Additionally, you will need to build a SQLCipher amalgamation. These files will need to be placed in the following locations:

<project-root>/sqlcipher/src/main/jni/sqlcipher/android-libs/armeabi-v7a/libcrypto.a<project-root>/sqlcipher/src/main/jni/sqlcipher/android-libs/x86/libcrypto.a<project-root>/sqlcipher/src/main/jni/sqlcipher/android-libs/x86_64/libcrypto.a<project-root>/sqlcipher/src/main/jni/sqlcipher/android-libs/arm64-v8a/libcrypto.a<project-root>/sqlcipher/src/main/jni/sqlcipher/android-libs/include/<project-root>/sqlcipher/src/main/jni/sqlcipher/sqlite3.c<project-root>/sqlcipher/src/main/jni/sqlcipher/sqlite3.h

To build the AAR package, either build directly within Android Studio, or from the command line:

./gradlew assembleRelease