Instructions for a build newbie for building SQLCipher on Debian Stretch (Debian v.9, the current stable version).

Tested on Jan 8, 2019.

Introduction

SQLCipher is SQLite3 with the SQLCipher encrypting extension included. In other words, it works exactly as SQLite3, but includes extra functionalities needed for encryption.

If you run the SQLCipher command-line interface, it looks like this:

    SQLCipher version 3.26.0 2018-12-01 12:34:55
    Enter ".help" for usage hints.
    Connected to a transient in-memory database.
    Use ".open FILENAME" to reopen on a persistent database.
    sqlite>

..which is a bit confusing, because the version number is the version number of SQLite3 used to build SQLCipher, not that of SQLCipher. To get the version number of SQLCipher itself, you need to enter a special PRAGMA statement:

    sqlite> PRAGMA cipher_version;
    4.0.1 community
    sqlite>

For all SQLCipher PRAGMAs and functions, see SQLCipher’s website. There is a good example of how to encrypt a database using the command line interface

Prerequisites

Check that the following packages are installed. All are available in the normal Debian Stretch repositories.

• git
• make
• the following pieces of the so-called GNU Compilation Collection (GCC): gcc and gcc-6 (installing gcc should bring gcc-6 as dependency)
• OpenSSL libraries: libssl1.1 and libssl-dev with their dependencies

Note If you later on want to remove your own SQLCipher build, install also the checkinstall package. It makes removal easier - see this StackOverflow question.

Steps

Step 1: Clone (=copy) the Github repository to your computer

Open a terminal session and navigate to the directory to which you want to copy the source files. For instance, your home directory. Or a temp directory created under the home directory.

Then run

    $ git clone https://github.com/sqlcipher/sqlcipher.git

This creates a directory sqlcipher, fetches the files from Github and saves them to the directory and its subdirectories. Download may take a while, because over 100 MB needs to be fetched.

Step 2: Run the configure script

The following has been adapted from instructions on SQLCipher’s Github page:

To build the SQLCipher using the default SQLite3 compile-time options, run the configure script in the sqlcipher directory:

    ./configure CFLAGS="-DSQLITE_HAS_CODEC -DSQLITE_TEMP_STORE=2" LDFLAGS="-lcrypto"

Alternatively, the SQLITE_TEMP_STORE=2 compile-time option can also be set with the --enable-tempstore=yes switch:

    ./configure --enable-tempstore=yes CFLAGS="-DSQLITE_HAS_CODEC" LDFLAGS="-lcrypto"

The -lcrypto flag tells to link dynamically to the OpenSSL libcrypto.a file (the file is included in the Debian libssl-dev package).

Alternatively, you can give a static path:

    ./configure --enable-tempstore=yes CFLAGS="-DSQLITE_HAS_CODEC" LDFLAGS="/path/to/libcrypto.a"

Note: The instructions on SQLCipher’s website only list the options required by SQLCipher. If you want to include other SQLite compile-time options, you need to list them here as well. Each option has to be preceded by -D.

Here is an example listing for copy-paste:

./configure CFLAGS="-DSQLITE_HAS_CODEC -DSQLITE_TEMP_STORE=2 -DSQLITE_THREADSAFE=0 -DSQLITE_DEFAULT_MEMSTATUS=0 -DSQLITE_OMIT_DEPRECATED -DSQLITE_OMIT_GET_TABLE -DSQLITE_OMIT_TRACE -DSQLITE_OMIT_TCL_VARIABLE -DSQLITE_OMIT_PROGRESS_CALLBACK -DSQLITE_DEFAULT_FOREIGN_KEYS=1 -DSQLITE_DEFAULT_WAL_SYNCHRONOUS=1 -DSQLITE_USE_URI=1 -DSQLITE_ENABLE_COLUMN_METADATA -DSQLITE_ENABLE_UPDATE_DELETE_LIMIT -DSQLITE_ENABLE_JSON1 -DSQLITE_INTROSPECTION_PRAGMAS" LDFLAGS="-lcrypto"

It is also possible to manually edit the Makefile file generated by the configure script before running make. However, as different types of options seem go to different places in the Makefile file, you would also need to know where to put what.

Anyway, you can inspect the Makefile file to see that all your desired options got included.

Step 3: Run make

Run make in the sqlcipher directory:

    $ make

This takes probably less than a minute. The log looks quite messy in the eyes of a non-expert, but if it completes without errors, there should be a number of new files in the sqlcipher directory, for instance the command line interface sqlcipher and various other files.

Step 4: Install SQLCipher

Step 4a: Normal make install (more difficult to remove)

Run the following command in the sqlcipher directory:

    $ sudo make install

The following files will be installed:

    /usr/local/bin/sqlcipher            (= the command line interface)
    /usr/local/lib/libsqlcipher.la
    /usr/local/lib/libsqlcipher.so.0.8.6
    /usr/local/lib/libsqlcipher.so      (= symlink to libsqlcipher.so.0.8.6)
    /usr/local/lib/libsqlcipher.so.0    (= symlink to libsqlcipher.so.0.8.6)
    /usr/local/lib/pkgconfig/sqlcipher.pc
    /usr/local/include/sqlcipher/sqlite3.h
    /usr/local/include/sqlcipher/sqlite3ext.h

Step 4b: Install with checkinstall (easy to remove)

Instead of the sudo make install command, run:

    $ sudo checkinstall

It will first ask to enter a description for the package. This description will be shown e.g. in the Synaptic Package Manager, so you could e.g. enter something like this:

    >>SQLCipher v4.0.1 (SQLite3 v3.26), build date 2019-01-08

You can also update version (also shown in Synaptic) and licence.

Once you accept, checkinstall will create a *.deb package in the sqlcipher directory and install the files as above. You can then later remove installation with Synaptic or command line, if needed:

    $ sudo dpkg -r sqlcipher

Note: If you don’t yet have a directory named /usr/local/include, this may fail with the the error message /usr/bin/install: cannot create directory ‘/usr/local/include’: No such file or directory Create the directory manually or run first sudo make install, which is able to create the directory if it doesn’t exist.

If something went wrong or you want to repeat with diffent options

Run

    $ make clean

This deletes the generated build files. Then, you can start again with ./configure.

Step 5: Compile DB Browser for SQLite with your newly built SQLCipher

You can now compile DB Browser for SQLite using this version of SQLCipher instead of the standard Debian SQLCipher packages as per these instructions.

If you have the standard Debian SQLCipher packages installed, uninstall them first. Other changes are not needed.

Note: At the time of writing, encrypting a database with DB Browser for SQLite compiled with SQLCipher 4.0.1 does not work (see Issue #1690). However, you can encrypt the database using the SQLCipher command line interface and then use it with DB Browser for SQLite.

Step 6: Clean up

Once you are happy with the result, you can delete the sqlcipher directory. It is not needed any more unless you want to repeat the build process with exactly the same source files.

However, if you created a *.deb package with checkinstall, move it first somewhere so you can reinstall exactly the same build later, if needed:

    $ sudo dpkg -i /path/to/the/deb/package/name_of_sqlcipher_deb_package.deb