簡(jiǎn)介SQLCipher 3.0.1 Windows 版本是一套面向數(shù)據(jù)庫(kù)開(kāi)發(fā)者的加密工具包基于 SQLite 提供透明加密能力適合需要在桌面應(yīng)用中集成數(shù)據(jù)庫(kù)加密功能的初中級(jí)開(kāi)發(fā)者使用。壓縮包內(nèi)共 18 個(gè)文件約 5.16MB涵蓋 32 位與 64 位可執(zhí)行程序exe、配套鏈接庫(kù)lib、調(diào)試符號(hào)文件pdb以及必要的頭文件h并附帶了兩個(gè)示例數(shù)據(jù)庫(kù)db和說(shuō)明文檔txt結(jié)構(gòu)清晰便于按需選用。工具包同時(shí)提供 debug 版本方便開(kāi)發(fā)階段跟蹤問(wèn)題正常發(fā)布時(shí)可選用 release 版本。目前已有 623 人學(xué)習(xí)下載說(shuō)明其在 SQLite 數(shù)據(jù)庫(kù)加密場(chǎng)景中具有較高的參考價(jià)值。跟隨內(nèi)含教程開(kāi)發(fā)者可以快速掌握 SQLCipher 的編譯連接、庫(kù)替換與數(shù)據(jù)庫(kù)加密/解密流程減少環(huán)境配置踩坑。1. sqlcipher 3.0.1 是什么給 SQLite 加一層你不能省掉的加密殼sqlcipher 3.0.1 是 SQLite 的加密分支在 Windows 上以預(yù)編譯二進(jìn)制加使用教程的形式提供。核心價(jià)值一句話它對(duì)數(shù)據(jù)庫(kù)文件做 AES-256 透明加密應(yīng)用層 SQL 不用改一行加密邏輯全在存儲(chǔ)層完成。很多項(xiàng)目把用戶表、訂單表明文丟在磁盤上數(shù)據(jù)庫(kù)文件被人拷走任意 SQLite 工具都能直接打開(kāi)連密碼都不需要。這套資源解決的就是這個(gè)痛點(diǎn)尤其適合 Windows 桌面軟件、工控?cái)?shù)據(jù)采集和老業(yè)務(wù)系統(tǒng)升級(jí)。它自帶命令行工具和使用教程新手能照著建庫(kù)、加密、遷移熟手可以直接拿來(lái)做批量密鑰管理和存量庫(kù)轉(zhuǎn)換。要注意它不是 SQLite 的替代品而是同一套語(yǔ)法的加密版運(yùn)行時(shí)后面很多坑都源于這一句。2. 加密原理與版本選型為什么 3.0.1 仍值得用它和 SQLite 到底差在哪2.1 透明加密的真實(shí)機(jī)制SQLCipher 的加密不是在 SQL 層做的而是在 pager 層。每個(gè)數(shù)據(jù)庫(kù)頁(yè)面在落盤前被加密讀取時(shí)先解密再交給上層。這意味著你的 SQL 語(yǔ)句、ORM 框架完全不需要知道加密的存在只要在連接建立后執(zhí)行一次PRAGMA key之后的一切讀寫都是透明的。默認(rèn)情況下每個(gè)數(shù)據(jù)庫(kù)頁(yè)是 4096 字節(jié)加密算法是 AES-256-CBC密鑰由用戶提供的 passphrase 通過(guò) PBKDF2-HMAC-SHA1 派生而來(lái)。3.0.1 的默認(rèn) KDF 迭代次數(shù)是 4000 次。這里有第一個(gè)容易誤解的點(diǎn)PRAGMA key abc里那串字符串并不是最終的加密密鑰它只是派生密鑰的輸入材料。派生參數(shù)迭代次數(shù)、頁(yè)面大小、HMAC 算法只要有一個(gè)不一致哪怕 passphrase 一字不差也解不開(kāi)庫(kù)。我在幫某開(kāi)發(fā)者排查一個(gè)打不開(kāi)的庫(kù)時(shí)發(fā)現(xiàn)就是源庫(kù)用 2.x 的老默認(rèn)參數(shù)創(chuàng)建而新工具開(kāi)了 3.x 的默認(rèn)參數(shù)密碼完全對(duì)不上。另一個(gè)機(jī)制是每庫(kù)隨機(jī) salt。每個(gè)加密庫(kù)創(chuàng)建時(shí)都會(huì)寫入隨機(jī)鹽值所以同樣的 passphrase 加密出來(lái)的兩個(gè)庫(kù)文件頭內(nèi)容也不一樣。這就排除了一個(gè)常見(jiàn)幻想想通過(guò)比對(duì)文件頭判斷兩個(gè)庫(kù)是否同密碼。實(shí)際做法是把兩個(gè)庫(kù)分別用同一個(gè) key 打開(kāi)用PRAGMA schema_version這類命令驗(yàn)證會(huì)話是否建立成功這個(gè)驗(yàn)證思路在第 6 章會(huì)展開(kāi)。3.0.1 生成的庫(kù)文件頭前 16 字節(jié)仍然保留SQLite format 3這個(gè)標(biāo)識(shí)。這意味著普通 SQLite 工具能把它識(shí)別為一個(gè) SQLite 文件但第 16 字節(jié)之后全部是加密數(shù)據(jù)識(shí)別完就被打回原形。如果你用十六進(jìn)制工具翻開(kāi)一個(gè)加密庫(kù)看到前 16 字節(jié)正常、后面全是高熵亂碼那才是加密真正生效的樣子。2.2 3.0.1 與 4.x 的差異維護(hù)老庫(kù)時(shí)最容易踩的版本坑加密庫(kù)是版本綁定的這是我從一次數(shù)據(jù)恢復(fù)事故里換來(lái)的教訓(xùn)。某跨平臺(tái)系統(tǒng)的數(shù)據(jù)庫(kù)用了 SQLCipher 3.x 加密運(yùn)維同學(xué)在網(wǎng)上下了一個(gè)最新 4.x 命令行工具去打開(kāi)結(jié)果報(bào)file is not a database當(dāng)場(chǎng)以為數(shù)據(jù)庫(kù)損壞了。其實(shí)只是 4.x 的默認(rèn)派生參數(shù)和 3.x 完全不同需要先切換兼容模式。核心差異集中在三處KDF 迭代次數(shù)、HMAC 算法、默認(rèn)頁(yè)面大小。3.0.1 默認(rèn)是 4000 次迭代加 HMAC-SHA1頁(yè)面 4096 字節(jié)4.x 默認(rèn)是 256000 次迭代加 HMAC-SHA512頁(yè)面仍然是 4096。4.x 為了向前兼容提供了PRAGMA cipher_compatibility 3打開(kāi) 3.x 庫(kù)前先執(zhí)行這一句就能識(shí)別但反過(guò)來(lái)3.0.1 里并沒(méi)有這個(gè) pragma你要做的反而是用PRAGMA kdf_iter 4000、PRAGMA cipher_page_size 4096這類參數(shù)去對(duì)齊源庫(kù)創(chuàng)建時(shí)的設(shè)置。更老的 2.x 庫(kù)默認(rèn)頁(yè)面是 1024 字節(jié)3.0.1 打開(kāi)時(shí)必須先設(shè)cipher_page_size 1024否則 HMAC 計(jì)算對(duì)不齊照樣報(bào)錯(cuò)。簡(jiǎn)單記憶越老的工具打開(kāi)新庫(kù)基本無(wú)解新工具打開(kāi)老庫(kù)得靠參數(shù)對(duì)齊。下面這張表寫清了各世代的關(guān)鍵差異也是我排查「密碼對(duì)但打不開(kāi)」問(wèn)題的對(duì)照表版本默認(rèn)頁(yè)面大小默認(rèn) KDF 迭代HMAC 算法打開(kāi) 3.x 庫(kù)1.x/2.x10244000HMAC-SHA1需設(shè) page_size10243.0.140964000HMAC-SHA1默認(rèn)即可4.x4096256000HMAC-SHA512設(shè) cipher_compatibility32.3 資源包內(nèi)容清單與適用邊界這類預(yù)編譯包通常包含幾類東西一個(gè)改名的命令行程序本質(zhì)是內(nèi)置了 SQLCipher 的 sqlite3 shell、配套的 OpenSSL 運(yùn)行庫(kù)、一份或多份使用教程文檔有的包還會(huì)帶上編譯好的 DLL 供 C/C 調(diào)用。標(biāo)題里已經(jīng)寫明含使用教程具體文件數(shù)量和格式以包內(nèi)為準(zhǔn)我拿到手第一步是把整個(gè)目錄固定放到一個(gè)單獨(dú)的文件夾里不要急著拷貝 exe 到 System32——原因后面 DLL 那節(jié)會(huì)說(shuō)。適用邊界也要先劃清。這套包能解決「本地文件加密、命令行管理、存量明文庫(kù)轉(zhuǎn)加密」這三類訴求它不解決跨版本互通不解決 ODBC/JDBC 驅(qū)動(dòng)集成那需要額外編譯對(duì)應(yīng)驅(qū)動(dòng)也不保證你的程序語(yǔ)言庫(kù)能直接用——很多語(yǔ)言的 sqlite3 模塊是官方 SQLite不是 SQLCipher你需要在程序側(cè)換成 SQLCipher 的編譯版本或者走命令行/擴(kuò)展接口。先確認(rèn)你的運(yùn)行時(shí)是哪一個(gè)再動(dòng)手。3. 環(huán)境搭建與命令行實(shí)戰(zhàn)讓加密庫(kù)能開(kāi)、能寫、能關(guān)3.1 目錄結(jié)構(gòu)與 PATH 配置先把壓縮包解壓到一個(gè)無(wú)中文、無(wú)空格的路徑下比如某臺(tái) Windows 機(jī)器上的C:\sqlcipher301。注意加入 PATH 時(shí)也優(yōu)先用這個(gè)短路徑避免某些老版本命令行工具在帶空格的路徑下解析參數(shù)出問(wèn)題。我一般會(huì)用set PATHC:\sqlcipher301;%PATH%設(shè)置會(huì)話級(jí)環(huán)境變量只在當(dāng)前窗口生效而不是永久寫進(jìn)系統(tǒng)環(huán)境變量——原因是這臺(tái)機(jī)器上可能還有其他 SQLite 工具PATH 寫死容易造成名字沖突。驗(yàn)證安裝是否正常核心看兩步。第一步執(zhí)行版本檢查sqlcipher -version正常會(huì)輸出類似3.0.1和一個(gè)日期如果你看到的是SQLite 3.x之類不帶 SQLCipher 標(biāo)識(shí)的輸出說(shuō)明你調(diào)用的根本不是 SQLCipher 版本而是系統(tǒng)里另一個(gè) sqlite3.exe。第二步直接啟動(dòng)交互式 shell 并執(zhí)行一句PRAGMA cipher_version;sqlcipher test.db sqlite PRAGMA cipher_version;能返回一串版本號(hào)字符串說(shuō)明這個(gè) shell 確實(shí)內(nèi)嵌了加密組件。如果返回 unknown 或者干脆報(bào)錯(cuò)說(shuō)明二進(jìn)制包不完整或依賴缺失先回第 5 章查 DLL 問(wèn)題別往下走。這一步有兩個(gè)細(xì)節(jié)值得養(yǎng)成習(xí)慣。一是始終用全名調(diào)用不要圖省事把 sqlcipher.exe 改名為 sqlite3.exe因?yàn)楹罄m(xù)你會(huì)同時(shí)用到官方 sqlite3.exe 做對(duì)比測(cè)試兩個(gè)文件同名會(huì)把你自己繞暈二是test.db這個(gè)名字只是占位SQLite 系工具對(duì)不存在的文件會(huì)自動(dòng)新建對(duì)已存在的文件會(huì)用當(dāng)前 key 嘗試打開(kāi)理解了這個(gè)行為后面很多「怎么打不開(kāi)」的問(wèn)題就有一半答案了。3.2 首次建庫(kù)PRAGMA key 的兩種寫法進(jìn)入交互式 shell 之后第一件事不是建表而是設(shè)置 key。這條順序是硬性的必須在任何讀寫操作之前設(shè)置 key。我見(jiàn)過(guò)有人在建表之后才想起來(lái)設(shè) key結(jié)果整個(gè)庫(kù)前半段是明文元數(shù)據(jù)后半段才開(kāi)始加密磁盤上落了一個(gè)半加密的畸形文件。sqlcipher encrypted.db sqlite PRAGMA key my-decent-passphrase; sqlite CREATE TABLE user ( id INTEGER PRIMARY KEY, name TEXT NOT NULL, email TEXT ); sqlite INSERT INTO user (name, email) VALUES (A同學(xué), aexample.com); sqlite .quit這段沒(méi)有任何建庫(kù)動(dòng)作但文件已經(jīng)生成了。PRAGMA key可以接受兩種形式普通字符串和 64 字符的十六進(jìn)制串。字符串會(huì)被 PBKDF2 派生適合人類記憶的密碼十六進(jìn)制串則被當(dāng)作 256 位原始密鑰直接使用跳過(guò) KDF 派生過(guò)程。兩者不可混用同一個(gè)庫(kù)用字符串 key 創(chuàng)建就不可能用對(duì)應(yīng)的 hex 值打開(kāi)因?yàn)檫M(jìn)的是兩條完全不同的密鑰處理路徑。參數(shù)選擇上如果業(yè)務(wù)方要求「密碼好記」就用字符串 key 配上 4000 次迭代的默認(rèn)派生如果是程序內(nèi)部硬編碼的密鑰我傾向于PRAGMA key x...這種 hex 形式——它不依賴派生算法的一致性未來(lái)升級(jí)到 4.x 時(shí)哪怕 KDF 默認(rèn)值變了只要原始密鑰串一致兼容性風(fēng)險(xiǎn)小得多。代價(jià)是這串 64 位 hex 必須妥善保管丟了你沒(méi)有任何找回手段。3.3 關(guān)閉后重開(kāi)驗(yàn)證 key 是否真正生效建好庫(kù)以后必須做一次完整的關(guān)閉重開(kāi)驗(yàn)證。很多新手在同一個(gè)會(huì)話里測(cè)試全程都帶著 key感覺(jué)一切正常直到程序重啟才發(fā)現(xiàn)密碼根本對(duì)不上。標(biāo)準(zhǔn)做法是退出 shell重新啟動(dòng)用同一個(gè) passphrase 打開(kāi)然后執(zhí)行一條查詢sqlcipher encrypted.db sqlite PRAGMA key my-decent-passphrase; sqlite SELECT * FROM user;能讀出剛才插入的那行數(shù)據(jù)說(shuō)明 key 和派生參數(shù)全都正確。更該做的是反向測(cè)試故意輸錯(cuò)一個(gè)字符再執(zhí)行同樣的查詢。如果實(shí)現(xiàn)符合預(yù)期你會(huì)看到file is encrypted or is not a database之類的錯(cuò)誤如果你輸錯(cuò)了密碼居然還能查出數(shù)據(jù)那說(shuō)明這個(gè)庫(kù)根本沒(méi)有加密——這類情況通常是你把加密命令后綴的CREATE TABLE建到了別的文件里或者環(huán)境變量指向了錯(cuò)誤的運(yùn)行時(shí)。反向測(cè)試雖然反直覺(jué)但它的價(jià)值是它驗(yàn)證的是「加密邊界」而不是「數(shù)據(jù)內(nèi)容」。正向查詢證明密碼對(duì)反向查詢證明數(shù)據(jù)確實(shí)不可讀兩層都過(guò)了這個(gè)庫(kù)才算真正交付。我每次給業(yè)務(wù)方演示加密效果時(shí)都做這兩步用后者做演示效果比任何 PPT 都直觀。4. 業(yè)務(wù)遷移實(shí)戰(zhàn)把明文庫(kù)完整轉(zhuǎn)成加密庫(kù)的兩種路徑4.1 ATTACH 方案官方說(shuō)的標(biāo)準(zhǔn)遷移大多數(shù)存量項(xiàng)目手里都有一個(gè)長(zhǎng)期未加密的 SQLite 文件比如data.db里面幾十張表帶索引、觸發(fā)器不可能手工重建。SQLCipher 提供了一條官方遷移路徑sqlcipher_export()配合 ATTACH把主庫(kù)的全部?jī)?nèi)容導(dǎo)出到另一個(gè)庫(kù)。主庫(kù)是新建的加密空庫(kù)目標(biāo)庫(kù)是那個(gè)明文老庫(kù)導(dǎo)出方向別搞反我最初就干反過(guò)一次調(diào)了半天發(fā)現(xiàn)明文庫(kù)越導(dǎo)越大。sqlcipher new_encrypted.db sqlite PRAGMA key migration-pass-2024; sqlite ATTACH DATABASE data.db AS plaintext KEY ; sqlite SELECT sqlcipher_export(plaintext); sqlite DETACH DATABASE plaintext; sqlite .quit第一行打開(kāi)了一個(gè)新的空庫(kù)并設(shè)好 key此時(shí)庫(kù)文件雖然存在但還沒(méi)有任何表結(jié)構(gòu)。第三行的ATTACH ... KEY 是關(guān)鍵空字符串表示目標(biāo)庫(kù)是明文 SQLite不參與加密如果你這里漏掉了 KEY 子句或者寫了個(gè)非空密碼老庫(kù)會(huì)以加密身份被掛進(jìn)來(lái)導(dǎo)出立刻報(bào)錯(cuò)。sqlcipher_export(plaintext)會(huì)讀取主庫(kù)的 schema 和數(shù)據(jù)寫入到 attached 的明文庫(kù)里之后 detach 分離關(guān)閉會(huì)話。整個(gè)過(guò)程中data.db是被寫的那一方而new_encrypted.db那個(gè)空庫(kù)只是數(shù)據(jù)源的概念容器。導(dǎo)出完成后要檢查三樣?xùn)|西行數(shù)、索引、觸發(fā)器。我一般會(huì)這樣驗(yàn)證sqlcipher data.db sqlite SELECT COUNT(*) FROM user;再對(duì)導(dǎo)出的加密庫(kù)做同樣的查詢兩邊行數(shù)對(duì)比。更進(jìn)一步要對(duì)比索引是否完整因?yàn)閟qlcipher_export對(duì)大多數(shù)對(duì)象都覆蓋但個(gè)別版本對(duì)sqlite_sequence、PRAGMA user_version這類元數(shù)據(jù)不見(jiàn)得完整遷移。程序代碼里如果依賴user_version做 schema 版本判斷遷移后要單獨(dú)執(zhí)行一次PRAGMA user_version 原來(lái)的值;補(bǔ)上否則程序啟動(dòng)時(shí)可能誤判庫(kù)版本觸發(fā)重建邏輯。4.2 兼容模式老庫(kù)打不開(kāi)時(shí)先查這兩個(gè)參數(shù)如果手頭是更老的 SQLCipher 1.x/2.x 庫(kù)4.1 的流程會(huì)卡在第一步ATTACH或打開(kāi)時(shí)報(bào)file is encrypted or is not a database。問(wèn)題往往不是密碼錯(cuò)而是老庫(kù)創(chuàng)建時(shí)的默認(rèn)參數(shù)和 3.0.1 不一致。2.x 時(shí)代的默認(rèn)頁(yè)面大小是 1024 字節(jié)KDF 迭代同樣 40003.0.1 默認(rèn)是 4096。HMAC 計(jì)算、頁(yè)內(nèi)加密都是按頁(yè)做的頁(yè)面大小對(duì)不上解密頭和后續(xù)頁(yè)全部錯(cuò)位。打開(kāi)這類老庫(kù)前先執(zhí)行兩個(gè) PRAGMA 對(duì)齊參數(shù)sqlcipher legacy.db sqlite PRAGMA cipher_page_size 1024; sqlite PRAGMA kdf_iter 4000; sqlite PRAGMA key old-passphrase; sqlite SELECT COUNT(*) FROM sqlite_master;參數(shù)設(shè)置必須在設(shè)置 key 之前完成因?yàn)镻RAGMA key觸發(fā)的派生過(guò)程會(huì)直接消費(fèi)這些參數(shù)。順序錯(cuò)了的話key 已經(jīng)用錯(cuò)誤的迭代次數(shù)派生完畢你再改 kdf_iter 也不會(huì)重新派生。如果你手頭這批老庫(kù)頁(yè)面大小不是 1024可以試著用 512、2048、4096 逐個(gè)試每次都要新建會(huì)話再設(shè)參數(shù)因?yàn)閹?kù)打開(kāi)失敗后當(dāng)前會(huì)話的加密上下文已經(jīng)不可信繼續(xù)在同一會(huì)話里改參數(shù)通常不起作用。這套「先參數(shù)、后密碼、再驗(yàn)證」的操作順序?qū)λ锌绨姹緢?chǎng)景都適用。遇到打開(kāi)失敗第一反應(yīng)不是懷疑密碼錯(cuò)了而是先確認(rèn)源庫(kù)是在哪個(gè) SQLCipher 版本下創(chuàng)建的。資源包里的使用教程如果附帶了版本變更說(shuō)明里面通常會(huì)寫參數(shù)對(duì)照那才是第一手依據(jù)。4.3 改密碼與多密鑰切換rekey 和 key 的正確時(shí)機(jī)運(yùn)行中的業(yè)務(wù)系統(tǒng)需要定期改密這是常見(jiàn)需求。SQLCipher 里改密碼用PRAGMA rekey而不是重新建庫(kù)導(dǎo)數(shù)據(jù)sqlcipher encrypted.db sqlite PRAGMA key old-passphrase; sqlite PRAGMA rekey new-passphrase; sqlite .quitrekey本質(zhì)上是對(duì)全庫(kù)逐頁(yè)重新加密頁(yè)數(shù)多時(shí)耗時(shí)明顯期間一旦斷電或進(jìn)程被殺庫(kù)文件可能處于新舊 key 交錯(cuò)的中間狀態(tài)。我的習(xí)慣是改密前強(qiáng)制復(fù)制一份 .db 文件做備份再執(zhí)行 rekey改完立刻做一次關(guān)閉重開(kāi)驗(yàn)證。有一個(gè)場(chǎng)景容易翻車數(shù)據(jù)庫(kù)開(kāi)啟了 WAL 模式而 WAL 文件里還殘留著用舊 key 寫入的日志頁(yè)rekey 只處理了主庫(kù)文件沒(méi)處理 WAL。這時(shí)程序重啟后讀取 WAL 里的舊頁(yè)可能報(bào)錯(cuò)或讀出亂碼。解決方式是 rekey 前先執(zhí)行一次PRAGMA wal_checkpoint(TRUNCATE);把 WAL 內(nèi)容合入主庫(kù)并清空日志文件再執(zhí)行 rekey。多密鑰切換則是另一個(gè)邏輯一個(gè)進(jìn)程內(nèi)同時(shí)要訪問(wèn)兩個(gè)不同 key 的庫(kù)。PRAGMA key只作用于當(dāng)前主庫(kù)連接第二個(gè)庫(kù)可以通過(guò) ATTACH 掛進(jìn)來(lái)并單獨(dú)指定 keysqlcipher main.db sqlite PRAGMA key main-pass; sqlite ATTACH DATABASE other.db AS other KEY other-pass; sqlite SELECT * FROM other.user;這樣主庫(kù)和附加庫(kù)用各自獨(dú)立的密碼互不干擾。有一個(gè)隱藏細(xì)節(jié)ATTACH 語(yǔ)句里的 KEY 子句使用的是與主庫(kù)PRAGMA key相同的派生參數(shù)配置。也就是說(shuō)如果主庫(kù)設(shè)了cipher_page_size 1024附加庫(kù)也會(huì)用 1024 去嘗試解密如果附加庫(kù)實(shí)際上是 4096 默認(rèn)創(chuàng)建的你需要在 ATTACH 之前把參數(shù)切回去或者接受它對(duì)不上。多庫(kù)混用時(shí)最好讓所有庫(kù)用同版本、同參數(shù)創(chuàng)建否則就得按 4.2 那套逐庫(kù)對(duì)齊的路子來(lái)。5. 常見(jiàn)問(wèn)題與避坑Windows 下的六個(gè)翻車現(xiàn)場(chǎng)5.1 啟動(dòng)即閃退或報(bào)缺少 DLL現(xiàn)象雙擊或命令行啟動(dòng) sqlcipher 時(shí)提示缺少libeay32.dll、ssleay32.dll或者彈窗提示程序無(wú)法正常啟動(dòng)有時(shí)啟動(dòng)不報(bào)錯(cuò)但執(zhí)行PRAGMA key后程序直接退出。原因3.0.1 的 Windows 預(yù)編譯版通常依賴 OpenSSL 1.0.x 運(yùn)行庫(kù)系統(tǒng)里沒(méi)有對(duì)應(yīng) DLL或者 PATH 中存在另一份更高版本的 OpenSSL名字相同但符號(hào)不兼容。SQLCipher 啟動(dòng)時(shí)加載到錯(cuò)的依賴Crash 在加密初始化階段。解決把資源包內(nèi)自帶的 DLL 與 exe 放在同一個(gè)目錄下優(yōu)先保證 exe 先在本地目錄找到依賴。確認(rèn)方法用where libeay32.dll查看當(dāng)前實(shí)際加載路徑如果在 System32 或其他軟件目錄里找到了另一份就調(diào)整 PATH 順序或者在啟動(dòng)腳本里先用全路徑把程序目錄釘死。命令行方式可以直接寫set PATHC:\sqlcipher301;%PATH% C:\sqlcipher301\sqlcipher.exe test.db注意全路徑調(diào)用 exe避免系統(tǒng)目錄下的同名程序搶先。如果還閃退繼續(xù)做一次純粹的依賴檢查。5.2 官方 sqlite3 工具打不開(kāi)加密庫(kù)現(xiàn)象用系統(tǒng)里的 sqlite3.exe 打開(kāi)加密數(shù)據(jù)庫(kù)文件報(bào)file is encrypted or is not a database但同一個(gè)文件用 sqlcipher 加正確密碼就能正常讀。原因這是正?，F(xiàn)象而不是故障。官方 SQLite 沒(méi)有解密能力加密庫(kù)在它眼里就是非法格式。SQLCipher 3.x 保留了前 16 字節(jié)的SQLite format 3標(biāo)識(shí)所以它還能識(shí)別出這是 SQLite 家族的文件但再往后全是密文只能報(bào)錯(cuò)。這個(gè)報(bào)錯(cuò)信息是「不是數(shù)據(jù)庫(kù)」和「是加密的數(shù)據(jù)庫(kù)」的合并結(jié)果。解決這一步不需要修只需要確認(rèn)你操作加密庫(kù)時(shí)永遠(yuǎn)使用 sqlcipher 運(yùn)行時(shí)。項(xiàng)目代碼里也要排查是否誤引用了官方 sqlite3 的驅(qū)動(dòng)——很多語(yǔ)言默認(rèn)的 sqlite 模塊就是官方版沒(méi)有 SQLCipher 編譯選項(xiàng)時(shí)連接加密庫(kù)必現(xiàn)此錯(cuò)。處理方式是換用 SQLCipher 的驅(qū)動(dòng)或增加 shell 調(diào)用層。另外我在做文件備份時(shí)會(huì)把 .db 和 -wal、-shm 文件一起備份千萬(wàn)別只拷主文件WAL 里的最近提交會(huì)丟。5.3 密碼明明正確卻提示解密失敗現(xiàn)象PRAGMA key correct-pass正常執(zhí)行但一執(zhí)行SELECT立刻報(bào)file is encrypted or is not a database。換了密碼、重裝了工具都沒(méi)用。原因密碼字符串經(jīng)過(guò) KDF 派生后的結(jié)果不對(duì)。最常見(jiàn)的因素是kdf_iter或cipher_page_size與庫(kù)創(chuàng)建時(shí)不匹配。另一個(gè)隱蔽原因是密碼前后混入了不可見(jiàn)字符比如從配置文件中讀出的密碼帶\r\n換行符或者交互式 shell 里復(fù)制粘貼時(shí)帶了空格。還有一種情況源庫(kù)創(chuàng)建時(shí)密碼不是字符串、而是 hex 形式的原始密鑰那么你拿字符串形式的密碼去解走的派生路徑完全不同。解決先查創(chuàng)建時(shí)機(jī)的配置確認(rèn)是哪個(gè) SQLCipher 版本建的庫(kù)、默認(rèn)參數(shù)是多少。2.x 庫(kù)按 4.2 的步驟設(shè)cipher_page_size10243.x 庫(kù)確認(rèn) 4096。然后檢查密碼的精確字節(jié)我一般用十六進(jìn)制查看配置文件末尾確認(rèn)沒(méi)有隱形換行。最后新建一個(gè)同版本空庫(kù)用同一個(gè) key 創(chuàng)建、關(guān)閉、重開(kāi)如果這個(gè)流程能打開(kāi)說(shuō)明參數(shù)沒(méi)問(wèn)題問(wèn)題出在源庫(kù)的創(chuàng)建參數(shù)上。5.4 rekey 改密后舊密碼還能打開(kāi)一部分?jǐn)?shù)據(jù)現(xiàn)象執(zhí)行完P(guān)RAGMA rekey new-pass后退出程序重新啟動(dòng)用新密碼打開(kāi)部分表或部分行讀取異常用舊密碼反倒能正常打開(kāi)。原因rekey 執(zhí)行時(shí)數(shù)據(jù)庫(kù)開(kāi)啟了 WAL 模式日志文件里還殘留舊 key 加密的頁(yè)。主庫(kù)文件已經(jīng)被新 key 重寫但程序啟動(dòng)時(shí)先從 WAL 恢復(fù)日志頁(yè)而這些頁(yè)是舊 key 加密的于是出現(xiàn)新舊交錯(cuò)的讀寫異常。舊密碼能打開(kāi)是因?yàn)槿罩卷?yè)還是舊 key恰好能把 WAL 讀完。解決改密前先執(zhí)行PRAGMA wal_checkpoint(TRUNCATE);把 WAL 合入主庫(kù)并清空再執(zhí)行 rekey。改完之后再執(zhí)行一次 checkpoint 并關(guān)閉所有連接。如果已經(jīng)發(fā)生交錯(cuò)狀態(tài)先把當(dāng)前庫(kù)文件整體備份然后嘗試用舊密碼打開(kāi)執(zhí)行PRAGMA wal_checkpoint(TRUNCATE)把殘留頁(yè)合并再用新密碼執(zhí)行一次 rekey。這個(gè)恢復(fù)流程不保證 100% 成功所以 rekey 前做文件備份是我的固定動(dòng)作從不跳過(guò)。5.5 把明文庫(kù)改名就當(dāng)加密完成現(xiàn)象把data.db改成data.db.sqlcipher或者用壓縮工具打包加密實(shí)際上文件內(nèi)容還是明文結(jié)構(gòu)用官方 sqlite3 工具照樣能打開(kāi)讀出全部表。原因文件改名只是改了擴(kuò)展名數(shù)據(jù)庫(kù)頁(yè)內(nèi)容沒(méi)有任何變化壓縮包的加密是外層加密解壓后 file 內(nèi)容本身還是明文。SQLCipher 的透明加密不是對(duì)文件整體做一次 AES而是逐頁(yè)加密必須用 sqlcipher 命令行或sqlcipher_export重寫整個(gè)文件。解決按 4.1 的 ATTACH 方案走一遍生成真正逐頁(yè)加密的新文件。驗(yàn)證方法用 hexdump 查看新文件數(shù)據(jù)區(qū)應(yīng)該看不到可讀文本而改名后的老文件的數(shù)據(jù)區(qū)里能直接看到CREATE TABLE之類的 SQL 文本殘留。這個(gè)驗(yàn)證成本極低卻是我每次交付前必做的一步。5.6 字符串 key 與 hex key 混淆現(xiàn)象A 機(jī)器用PRAGMA key abc123加密B 機(jī)器改用PRAGMA key x616263313233想打開(kāi)結(jié)果失敗。兩邊的運(yùn)維都認(rèn)為是同一個(gè)密碼各自都確認(rèn)沒(méi)寫錯(cuò)。原因前者是 passphrase需要 KDF 派生后者是 24 字節(jié)的原始密鑰直接作為 256 位密鑰的一部分使用位數(shù)不足時(shí)按規(guī)則補(bǔ)齊。兩種模式從密鑰生成第一步就分道揚(yáng)鑣唯一的共同點(diǎn)是它們都叫 key實(shí)際卻是完全不同的兩樣?xùn)|西。解決統(tǒng)一約定一種形式并且寫進(jìn)項(xiàng)目文檔里。程序側(cè)無(wú)論是配置文件還是啟動(dòng)參數(shù)都要在 key 字符串前加明確的類型標(biāo)記。排查時(shí)先問(wèn)一句當(dāng)初建庫(kù)用的是字符串密碼還是 hex 密鑰通常這一句就能定位問(wèn)題。順帶建議hex 密鑰長(zhǎng)度必須是 64 個(gè)十六進(jìn)制字符少于或多于都會(huì)導(dǎo)致 SQLCipher 內(nèi)部報(bào)錯(cuò)不要用短字符串去硬湊 hex 格式。6. 驗(yàn)證技巧用十分鐘確認(rèn)加密真的生效加密庫(kù)的交付不能只靠「PRAGMA key 沒(méi)報(bào)錯(cuò)」來(lái)判斷那只能說(shuō)明密鑰設(shè)置成功不能證明數(shù)據(jù)已經(jīng)密文落盤。我給業(yè)務(wù)方演示時(shí)固定跑一遍三件套驗(yàn)證第一件是十六進(jìn)制查看頭部第二件是文本提取掃描第三件是錯(cuò)誤密碼探測(cè)。先看文件頭形態(tài)hexdump -C -n 64 new_encrypted.db正常輸出是這樣的形態(tài)前 16 字節(jié)是53 51 4c 69 74 65 20 66 6f 72 6d 61 74 20 33 00即SQLite format 3的 ASCII 碼但從第 16 字節(jié)開(kāi)始也就是 salt 區(qū)和第一個(gè)頁(yè)的起始處全部是隨機(jī)高熵字節(jié)沒(méi)有任何可讀 ASCII 字符串。對(duì)比一下明文庫(kù)的同一位置你能看到CREATE TABLE的 ASCII 文本直接暴露在數(shù)據(jù)區(qū)。這一步基本就能確認(rèn)加密范圍覆蓋到了數(shù)據(jù)頁(yè)。再做一次全文件文本掃描strings encrypted.db | head -20加密庫(kù)輸出里如果還能看到表名、字段名之類的業(yè)務(wù)詞說(shuō)明有部分區(qū)域未被加密——常見(jiàn)原因是庫(kù)創(chuàng)建時(shí)先建了表、再設(shè)置的 key或者 attach 導(dǎo)出時(shí)目標(biāo)庫(kù)帶上了老 schema 的明文殘留。我遇到過(guò)一次一個(gè)庫(kù)能打開(kāi)但 strings 輸出里能看到完整的建表語(yǔ)句最后定位是程序代碼里把PRAGMA key放在了建表語(yǔ)句之后庫(kù)的 sqlite_master 區(qū)域以明文寫入。這種庫(kù)嚴(yán)格說(shuō)是半加密狀態(tài)雖然實(shí)際數(shù)據(jù)行已經(jīng)加密但表結(jié)構(gòu)元數(shù)據(jù)泄露了。處理方法是按 4.1 重新導(dǎo)出一次生成規(guī)范的全加密文件。第三件是錯(cuò)誤密碼探測(cè)sqlcipher encrypted.db sqlite PRAGMA key wrong-pass; sqlite SELECT name FROM sqlite_master LIMIT 1;理想結(jié)果是任何查詢都報(bào)錯(cuò)或返回空說(shuō)明數(shù)據(jù)確實(shí)被 key 鎖住。如果這一句能返回表名立刻停下檢查要么是庫(kù)沒(méi)加密要么是設(shè)置 key 的會(huì)話上下文沒(méi)有落在當(dāng)前連接上——有些客戶端庫(kù)在連接池里把 key 設(shè)置到了一條連接查詢走了另一條連接導(dǎo)致你看到「能查出來(lái)」的假象實(shí)際是連接錯(cuò)位。從那以后我每次拿到一個(gè)新的加密庫(kù)第一件事就是跑這三板斧hexdump 看頭、strings 掃文本、錯(cuò)誤密碼探查詢?nèi)歼^(guò)了才敢把庫(kù)交付給業(yè)務(wù)方改密、遷移、升級(jí)版本時(shí)也強(qiáng)制走一遍不省略不跳步。這套流程幫我擋掉了至少三次「以為加密了、其實(shí)裸奔」的事故。這次分享的 sqlcipher 3.0.1 Windows 包解法路徑都在上面了參數(shù)和坑位對(duì)照著排應(yīng)該能省你不少時(shí)間希望幫到你。本文還有配套的精品資源點(diǎn)擊獲取