Module cipher 

sqlite3mc encryption configuration.

Encryption flow

This crate uses sqlite3mc (SQLite3 Multiple Ciphers) to encrypt SQLite databases at rest. The encryption is transparent to SQL – once a database is opened and keyed, all reads and writes are automatically encrypted/decrypted by the SQLite pager layer.

The flow when opening a database is:

1. Open – sqlite3_open_v2 creates or opens the database file. At this point the file is opaque (encrypted) and no data can be read.

2. Configure cipher – PRAGMA cipher = 'chacha20' fixes the on-disk cipher before the key activates it.

3. Detect and encrypt or unlock – A read from sqlite_master succeeds for a plaintext (or new) database. Such a database is moved out of WAL mode and atomically encrypted with PRAGMA rekey. If the read returns SQLITE_NOTADB, the database is treated as encrypted and unlocked with PRAGMA key. Both PRAGMAs receive the 32-byte K_intermediate as a raw hex key, bypassing the passphrase KDF.

4. Verify – We read from sqlite_master after rekeying or keying. A wrong key returns SQLITE_NOTADB because the decrypted page header does not match the expected SQLite magic bytes.

5. Configure connection – The target-specific journal mode and every connection-level invariant are set and verified.

The default cipher is ChaCha20-Poly1305 (authenticated encryption). All crypto is built into the sqlite3mc amalgamation – no OpenSSL or other external crypto library is needed on any platform.

Functions

export_plaintext_copy

Creates a plaintext (unencrypted) copy of an already-open encrypted database.

import_plaintext_copy

Imports data from a plaintext (unencrypted) database into an already-open encrypted database.

integrity_check

Runs PRAGMA integrity_check and returns whether the database is healthy.

open_encrypted

Opens a writable database, applies the encryption key, and configures the connection.