SQLCipher

SQLCipher is a standalone fork of the SQLite database library that adds 256 bit AES encryption of database files and other security features like:

on-the-fly encryption
tamper detection
memory sanitization
strong key derivation

SQLCipher is based on SQLite and stable upstream release features are periodically integrated. While SQLCipher is maintained as a separate version of the source tree, the project minimizes alterations to core SQLite code whenever possible.

SQLCipher is maintained by Zetetic, LLC, and additional information and documentation is available on the official SQLCipher site.

Features

Fast performance with as little as 5-15% overhead for encryption on many operations
100% of data in the database file is encrypted
Good security practices (CBC mode, HMAC, key derivation)
Zero-configuration and application level cryptography
Support for multiple cryptographic providers

Compatibility

SQLCipher maintains database format compatibility within the same major version number so an application on any platform can open databases created by any other application provided the major version of SQLCipher is the same between them. However, major version updates (e.g. from 3.x to 4.x) often include changes to default settings. This means that newer major versions of SQLCipher will not open databases created by older versions without using special settings. For example, SQLCipher 4 introduces many new performance and security enhancements. The new default algorithms, increased KDF iterations, and larger page size mean that SQLCipher 4 will not open databases created by SQLCipher 1.x, 2.x, or 3.x by default. Instead, an application would either need to migrate the older databases to use the new format or enable a special backwards-compatibility mode. The available options are described in SQLCipher's upgrade documentation.

SQLCipher is also compatible with standard SQLite databases. When a key is not provided, SQLCipher will behave just like the standard SQLite library. It is also possible to convert from a plaintext database (standard SQLite) to an encrypted SQLCipher database using ATTACH and the sqlcipher_export() convenience function.

Contributions

The SQLCipher team welcomes contributions to the core library. All contributions including pull requests and patches should be based on the prerelease branch, and must be accompanied by a contributor agreement. We strongly encourage discussion of the proposed change prior to development and submission.

Compiling

Building SQLCipher is similar to compiling a regular version of SQLite from source, with a few small exceptions. You must:

define SQLITE_HAS_CODEC
define SQLITE_TEMP_STORE=2 or SQLITE_TEMP_STORE=3 (or use configure's --with-tempstore=yes option)
define SQLITE_EXTRA_INIT=sqlcipher_extra_init and SQLITE_EXTRA_SHUTDOWN=sqlcipher_extra_shutdown
define SQLITE_THREADSAFE to 1 or 2 (enabled automatically by configure)
compile and link with a supported cryptographic provider (OpenSSL, LibTomCrypt, CommonCrypto/Security.framework, or NSS)

The following examples demonstrate use of OpenSSL, which is a readily available provider on most Unix-like systems. Note that, in this example, --with-tempstore=yes is setting SQLITE_TEMP_STORE=2 for the build, and SQLITE_THREADSAFE has a default value of 1.

$ ./configure --with-tempstore=yes CFLAGS="-DSQLITE_HAS_CODEC -DSQLITE_EXTRA_INIT=sqlcipher_extra_init -DSQLITE_EXTRA_SHUTDOWN=sqlcipher_extra_shutdown" \
	LDFLAGS="-lcrypto"
$ make

Testing

The full SQLite test suite will not complete successfully when using SQLCipher. In some cases encryption interferes with low-level tests that require access to database file data or features which are unsupported by SQLCipher. Those tests that are intended to support encryption are intended for non-SQLCipher implementations. In addition, because SQLite tests are not always isolated, if one test fails it can trigger a domino effect with other failures in later steps.

As a result, the SQLCipher package includes it's own independent tests that exercise and verify the core functionality of the SQLCipher extensions. This test suite is intended to provide an abbreviated verification of SQLCipher's internal logic; it does not perform an exhaustive test of the SQLite database system as a whole or verify functionality on specific platforms. Because SQLCipher is based on stable upstream builds of SQLite, it is considered a basic assumption that the core SQLite library code is operating properly (the SQLite core is almost untouched in SQLCipher). Thus, the additional SQLCipher-specific test provide the requisite verification that the library is operating as expected with SQLCipher's security features enabled.

To run SQLCipher specific tests, configure as described here and run the following to execute the tests and receive a report of the results:

$ ./configure --with-tempstore=yes --enable-fts5 CFLAGS="-DSQLITE_HAS_CODEC -DSQLITE_EXTRA_INIT=sqlcipher_extra_init -DSQLITE_EXTRA_SHUTDOWN=sqlcipher_extra_shutdown -DSQLCIPHER_TEST" \
	LDFLAGS="-lcrypto"
$ make testfixture
$ ./testfixture test/sqlcipher.test

Encrypting a database

To specify an encryption passphrase for the database via the SQL interface you use a PRAGMA. The passphrase you enter is passed through PBKDF2 key derivation to obtain the encryption key for the database

PRAGMA key = 'passphrase';

Alternately, you can specify an exact byte sequence using a blob literal. If you use this method it is your responsibility to ensure that the data you provide is a 64 character hex string, which will be converted directly to 32 bytes (256 bits) of key data without key derivation.

PRAGMA key = "x'2DD29CA851E7B56E4697B0E1F08507293D761A05CE4D1B628663F411A8086D99'";

To encrypt a database programmatically you can use the sqlite3_key function. The data provided in pKey is converted to an encryption key according to the same rules as PRAGMA key.

int sqlite3_key(sqlite3 *db, const void *pKey, int nKey);

PRAGMA key or sqlite3_key should be called as the first operation when a database is open.

Changing a database key

To change the encryption passphrase for an existing database you may use the rekey PRAGMA after you've supplied the correct database password;

PRAGMA key = 'passphrase'; -- start with the existing database passphrase
PRAGMA rekey = 'new-passphrase'; -- rekey will reencrypt with the new passphrase

The hex rekey pragma may be used to rekey to a specific binary value

PRAGMA rekey = "x'2DD29CA851E7B56E4697B0E1F08507293D761A05CE4D1B628663F411A8086D99'";

This can be accomplished programmatically by using sqlite3_rekey;

sqlite3_rekey(sqlite3 *db, const void *pKey, int nKey)

Support

The primary source for complete documentation (design, API, platforms, usage) is the SQLCipher website:

https://www.zetetic.net/sqlcipher/documentation

The primary avenue for support and discussions is the SQLCipher discuss site:

https://discuss.zetetic.net/c/sqlcipher

Issues or support questions on using SQLCipher should be entered into the GitHub Issue tracker:

https://github.com/sqlcipher/sqlcipher/issues

Please DO NOT post issues, support questions, or other problems to blog posts about SQLCipher as we do not monitor them frequently.

If you are using SQLCipher in your own software please let us know at support@zetetic.net!

Community Edition Open Source License

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of the ZETETIC LLC nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY ZETETIC LLC ''AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL ZETETIC LLC BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Begin SQLite README.md

<h1 align="center">SQLite Source Repository</h1>

This repository contains the complete source code for the SQLite database engine, including many tests. Additional tests and most documentation are managed separately.

See the on-line documentation for more information about what SQLite is and how it works from a user's perspective. This README file is about the source code that goes into building SQLite, not about how SQLite is used.

Version Control

SQLite sources are managed using Fossil, a distributed version control syste

Sqlcipher

Install / Use

README