Module sqlcipher 

SQLCipher at-rest decryption → a plaintext SQLite byte stream the reader (crate::Database::open) consumes unchanged.

What SQLCipher does (and how we undo it)

A SQLCipher database is an ordinary page-structured SQLite file whose every page is encrypted with AES-256-CBC and authenticated with a per-page HMAC. The first 16 bytes of the file are a random salt (in place of the SQLite format 3\0 magic). Key material is derived with PBKDF2:

• encryption key: PBKDF2(passphrase, salt, kdf_iter, 32) — or a raw 32-byte key used directly (PRAGMA key = "x'<64 hex>'");
• HMAC key: PBKDF2(encryption_key, salt ^ 0x3a, 2, 32).

Each page’s tail holds [ IV(16) | HMAC | padding ] occupying reserve bytes. The HMAC authenticates ciphertext || IV || page_no_le32. Page 1’s first 16 bytes (the salt) are not encrypted; on decrypt we prepend the standard magic to reconstruct a valid plaintext page 1. The plaintext header carries SQLCipher’s own reserved-space byte, so the reader computes the correct usable size with no further help.

Version detection

The two shipped profiles are the SQLCipher v4 and v3 defaults; they differ in PBKDF2/HMAC digest (SHA-512 vs SHA-1), iteration count, default page size, and reserve. Because nothing in the header is readable before decryption, the version is detected by HMAC verification on page 1: the first profile whose page-1 tag matches the derived key is the correct one. A wrong key/parameters matches no profile and fails loud (DecryptError::KeyOrParametersMismatch) — never a silent wrong-output.

Crypto provenance

Every primitive is an audited RustCrypto crate (pbkdf2, hmac, sha1, sha2, aes, cbc). Nothing here is hand-rolled.

Structs

Decrypted

A decrypted database: the reconstructed plaintext bytes plus the profile that decrypted them.

Enums

DecryptError

Why decryption could not proceed. Every variant is a loud, recoverable failure — decryption never panics and never emits plausible-but-wrong bytes.

SqlCipherKey

The key supplied by the caller.

SqlCipherVersion

The SQLCipher default profile detected for a database.

Functions

decrypt

Decrypt a SQLCipher database into a plaintext SQLite byte stream, detecting the cipher version by page-1 HMAC verification.