Comparing changes

SQLCipher now uses sqlite3_vfs and sqlite3_file shims instead of a pager Codec hook. The VFS is registered at initialization time and allows SQLCipher to transparently intercept file I/O for encryption and decryption. This VFS implementation supports encryption of the main database, journal files, WAL files, and statement journals using dedicated read/write handlers that implement appropriate logic for each file type and the variety of special cases for each. This change includes a substantial refactoring and realignment with upstream code: - All uses of CODEC* macros are removed - Internal "codec" structs and functions have renamed and refactored - The family of key and rekey PRAGMAs are moved out of pragma.c - Status pragmas are relocated to VFS File Control so they are only invoked when the VFS is active - Many files that were previously modified or extended to support SQLCipher have been reverted to unmodified SQLite sources - Keying :memory: databases is now an explicit misuse - Significantly expanded test coverage - Requires compile time -DSQLITE_DIRECT_OVERFLOW_READ=0

Authenticated Encryption with Associated Data (AEAD) is the new default. SQLCipher uses AES-256-GCM and per-page subkeys generated by a KBKDF (SP 800-108 counter mode KDF using AES-256-CMAC). This replaces the old approach that used AES-256-CBC + HMAC-SHA512. This adds AEAD and KBKDF functions to the SQLCipher provider interface which must be implemented in any custom cryptographic providers. Implementations have been added for OpenSSL and LibTomCrypt. An implementation has not been added for CommonCrypto because the library does not support GCM. If AEAD is not in use (i.e. explicitly disabled), SQLCipher will no longer perform an extra HMAC key derivationstep by default. Instead, the HMAC key is derived at the same time as the encryption key by getting extra bytes from PBKDF2. When using PBKDF2-HMAC-SHA512 It is a beneficial optimization to eliminate the second, low-iteration PBKDF2 operation. The default AEAD mode is not transparently backwards-compatibile with previous SQLCipher v4 databases, however, the cipher_compatibility and cipher_migrate PRAGMAs allow opening old databases or migrating to the new settings respectively. Accordingly, all legacy modes are still supported for compatibility with older SQLCipher versions. The CommonCrypto provider is now deprecated and requires a special override define to compile. A reference database and expanded test coverage for new settings are included.

…xt conversion In addition to the new features, error handling and test cases are singificantly expanded upon and improved.

…EC macro w/ OMIT_SQLCIPHER) Previously, SQLCipher would only be enabled in the codebase if the SQLITE_HAS_CODEC macro was set at compile time. If that was not defined, then standard SQLite would be built instead. This was confusing. Now, SQLCipher will be enabled by default, and it will only be omitted from the build if OMIT_SQLCIPHER is defined. The latter can be used when full tests, fuzzing, or behavior comparisons against stock SQLite are required.

- PRAGMA cipher_store_pass - PRAGMA cipher - PRAGMA fast_kdf_iter - PRAGMA cipher_hmac_pgno - PRAGMA cipher_hmac_salt_mask - PRAGMA rekey_cipher - PRAGMA rekey_kfd_iter

The previous 4096 byte page size used in SQLCipher 4 was based on the SQLite default adopted in 2016. Updating to a larger page size provides more balanced performance for SQLCipher especially with mixed workloads on modern flash storage, and reduces the relative overhead for encryption and decryption operations. Benchmarking shows that 8192 bytes is a relative sweet spot that performs very well for large/bulk operations without imposing a significant penalty on smaller operations. The 8K default page size is not transparently backwards-compatible with previous v4 databases but the cipher_compatibility and cipher_migrate operations allow opening old databases or migrating to the new setting.

SQLite calculates and stores checksums over page content in rollback journal and WAL files. Because SQLCipher is now a VFS instead of a CODEC hook, the checksums are calculated on the plaintext page. This commit introduces shielding of the checksums before they are written to the rollback journal or WAL.

Navigation Menu

Uh oh!

Comparing changes

Open a pull request

Uh oh!

Commits on Sep 11, 2026

This comparison is taking too long to generate.

Uh oh!