libSQL 中 SQLite3MultipleCiphers 加密扩展全版本演进解析密码算法、配置参数与兼容性变更指南【免费下载链接】libsqllibSQL is a fork of SQLite that is both Open Source, and Open Contributions.项目地址: https://gitcode.com/GitHub_Trending/li/libsql本篇文章以 libSQL 仓库中捆绑的 SQLite3MultipleCiphers 加密扩展的 CHANGELOG.md 为骨架系统梳理该扩展从 1.0.0 到 1.9.0 的完整演进脉络覆盖支持的密码算法、关键配置参数mc_legacy_wal、hmac_algorithm_compat、legacy_page_size等、WAL 模式兼容性、rekey 行为与编译期选项。读者阅读后可掌握该加密扩展的版本差异、参数语义以及在 libSQL 中通过multiple-ciphers特性启用加密能力的具体方式。一、扩展背景SQLite 3.32 之后的 VFS 式加密实现SQLite3MultipleCiphers 是随 libSQL 捆绑在 libsql-ffi/bundled/SQLite3MultipleCiphers/ 目录下的 SQLite 加密扩展其前身是 wxSQLite3 项目内附带的加密扩展后独立成库。2020 年 2 月 7 日SQLite 官方提交了移除不受支持且未文档化的SQLITE_HAS_CODEC编译选项的改动并从 SQLite 3.32.0 起生效这使旧有加密扩展无法简单支持新版 SQLite。SQLite3MultipleCiphers 采用基于 SQLite VFS 与 sqlite3mc_vfs.h 中其余密码算法实现则按算法拆分如 cipher_sqlcipher.c、cipher_chacha20.c、cipher_wxaes128.c、cipher_wxaes256.c、cipher_sds_rc4.c、cipher_ascon.c 以及 cipher_common.c。二、支持的密码算法一览自 1.0.0基于 SQLite 3.33.0首次发布起扩展即宣称支持多种密码算法覆盖了当时主流 SQLite 加密实现的文件格式算法说明兼容目标AES-128-CBC无 HMAC兼容 wxSQLite3 加密格式wxSQLite3AES-256-CBC无 HMAC兼容 wxSQLite3 加密格式wxSQLite3ChaCha20-Poly1305HMAC默认密码方案sqleetAES-256-CBC SHA1/SHA256/SHA512 HMAC支持数据库版本 1、2、3、4SQLCipherRC4无 HMAC兼容旧版加密 APISystem.Data.SQLite此后算法家族持续扩充1.8.02023-11-23新增密码方案Ascon-128实现位于 src/ascon/ 目录aead、permutations、pbkdf2 等模块并在 cipher_ascon.c 中接入统一密码框架。1.7.12023-10-09新增编译期选项以省略 AES 硬件支持x86/AArch64 平台上的 AES 硬件加速代码自 1.1.0/1.1.3 引入见 aes_hardware.c。默认密码方案在编译期可通过 sqlite3mc_config.h 中的CODEC_TYPE符号选择可选值CODEC_TYPE_AES128、CODEC_TYPE_AES256、CODEC_TYPE_CHACHA20、CODEC_TYPE_SQLCIPHER、CODEC_TYPE_RC4未定义时默认取CODEC_TYPE_CHACHA20。每种内建密码均可用HAVE_CIPHER_*宏逐一裁剪且编译期会校验“至少启用一种密码”否则抛出No built-in cipher scheme enabled!警告。三、版本演进时间线与核心变更CHANGELOG 完整记录了从 1.0.0 到 1.9.0 的每个版本版本号遵循语义化版本规范Semantic Versioning。当前捆绑版本为1.9.0基于 SQLite 3.47.0这一点可在 sqlite3mc_version.h 中得到印证SQLITE3MC_VERSION_STRING SQLite3 Multiple Ciphers 1.9.0。以下按功能主线归纳各阶段1. 架构与构建能力1.1.x ~ 1.6.x1.1.0 / 1.1.3分别在 x86、ARM 平台加入 AES 硬件支持代码1.1.3 起引入 GitHub Actions 做 CI。1.6.0加入 CMake 构建支持新增自动 VFS shim 实例化。在此之前非默认 VFS 上使用加密需要手动接入 shim此后只需以multipleciphers-前缀指定真实 VFS 名称通过 URI 参数vfs或sqlite3_open_v2()的第 4 个参数扩展会自动完成 shim 实例化。1.6.1将 Unix 平台MAX_PATHNAME原 SQLite 固定为 512改为可在编译期通过符号SQLITE3MC_MAX_PATHNAME上调如 Linux 常见的 4096。1.3.5将编译期配置选项迁移到独立头文件即如今的 sqlite3mc_config.h并将版本信息暴露在 amalgamation 头文件中。2. 安全特性1.3.x ~ 1.7.x1.3.10新增PRAGMA hexkey/PRAGMA hexrekey允许以十六进制形式设置密钥与重设密钥便于与外部密钥管理系统对接。1.7.0新增PRAGMA memory_security在内存被释放前主动清零可降低敏感密钥残留在堆内存中的风险该特性对性能影响较大默认关闭。1.3.4允许PRAGMA key使用空口令允许通过定义SQLITE_USER_AUTHENTICATION0完全禁用用户认证扩展1.8.4 起默认禁用 user authentication 扩展。3. 可扩展性1.5.x ~ 1.9.x1.5.0新增动态注册密码方案的能力允许第三方算法以插件形式接入统一框架同时加入 WebAssembly 目标支持对应 issues #88、#89。1.9.0修改了密码方案接口方法GenerateKey的签名——仅影响动态密码方案的开发者若自行实现动态密码方案升级到 1.9.0 后需要同步调整该方法实现。四、关键配置参数详解含源码佐证CHANGELOG 中反复出现的配置参数大多能在源码的参数表中找到对应定义与校验逻辑。1.mc_legacy_walWAL 日志加密的旧格式兼容开关这是 1.3.2 引入的最重要参数之一。背景是1.3.0 引入的新 WAL 日志加密实现使得与旧版≤1.2.5遗留的 WAL 日志互不兼容同时 1.3.0/1.3.1 在 WAL 模式下存在已知缺陷issue #39因此参数值为 1 时使用旧版 WAL 日志加密格式用于无数据损失地恢复旧版本遗留的 WAL 日志默认值可通过编译期符号SQLITE3MC_LEGACY_WAL设定默认 0运行期可经由PRAGMA mc_legacy_wal或 URI 参数mc_legacy_wal覆盖。源码 cipher_common.c 中参数表定义为{ mc_legacy_wal, SQLITE3MC_LEGACY_WAL, SQLITE3MC_LEGACY_WAL, 0, 1 }取值范围 01cipher_common.h 的注释明确警告原则上可长期使用 WAL legacy 模式但强烈建议仅在恢复旧版遗留 WAL 日志时使用。URI 解析与 PRAGMA 分发逻辑位于 cipher_config.csqlite3_uri_boolean(dbFileName, mc_legacy_wal, 0)与sqlite3mc_config(db, mc_legacy_wal, ...)。2.hmac_algorithm_compat与原始 SQLCipher 的 HMAC 兼容开关1.9.0 修复了一个兼容性缺陷此前若用户为 SQLCipher 方案配置了不同的 KDF 算法与 HMAC 算法如 KDF 用 SHA512、HMAC 用 SHA1生成的数据库与原始 SQLCipher 库不兼容。1.9.0 起默认行为改为与原始 SQLCipher 保持一致若需要恢复旧的不兼容的行为可将参数hmac_algorithm_compat设为 0。在 cipher_sqlcipher.c 的参数表中hmac_algorithm_compat定义于kdf_algorithm/hmac_algorithm之后取值范围 01默认取编译期值SQLCIPHER_HMAC_ALGO_COMPAT。3.legacy_page_size与plaintext_header_size参数取值约束1.8.6 起对两个参数增加了严格校验校验逻辑实现在 cipher_config.c 的checkParameterValue()中legacy_page_size只接受合法页大小即满足512 value SQLITE_MAX_PAGE_SIZE且为 2 的幂((value - 1) value) 0plaintext_header_size只接受 16 的倍数value % 16 0上限 100 字节限制在数据库头大小范围内见 cipher_sqlcipher.c 参数表。这两个参数分别用于兼容旧版页大小设置与允许部分明文头部便于识别文件类型的场景配置时需注意上述取值约束。4. SQLCipher 方案的完整参数表围绕 SQLCipher 兼容方案cipher_sqlcipher.c 给出了完整参数族理解它们有助于把握 1.9.0 兼容性修复的影响面参数默认值取值范围说明legacySQLCIPHER_LEGACY_DEFAULT0 ~SQLCIPHER_VERSION_MAX选择 SQLCipher 数据库版本1/2/3/4legacy_page_size4096新版默认512 ~SQLITE_MAX_PAGE_SIZE2 的幂兼容旧版页大小kdf_iter256000新版/ 64000旧版1 ~ 0x7fffffffKDF 迭代次数fast_kdf_iterSQLCIPHER_FAST_KDF_ITER1 ~ 0x7fffffff快速 KDF 迭代次数hmac_useSQLCIPHER_HMAC_USE0 ~ 1是否启用 HMAChmac_pgno大端LE0 ~ 2HMAC 页码字节序hmac_salt_maskSQLCIPHER_HMAC_SALT_MASK0x00 ~ 0xffHMAC 盐掩码kdf_algorithmSHA512新版/ SHA1旧版0 ~ 2KDF 哈希算法hmac_algorithmSHA512新版/ SHA1旧版0 ~ 2HMAC 哈希算法hmac_algorithm_compatSQLCIPHER_HMAC_ALGO_COMPAT0 ~ 1与原始 SQLCipher 行为是否一致plaintext_header_size00 ~ 10016 的倍数明文头部字节数五、重要修复与使用注意事项按版本提炼WAL 模式的历史缺陷与收敛1.3.0 / 1.3.1WAL 日志模式存在缺陷issue #39WAL 日志因引用了错误的 codec 指针而损坏1.3.1 起在 WAL 模式下禁止执行PRAGMA rekey因为 WAL 模式下重设密钥可能导致数据库损坏。1.3.0为兼容旧版应用基于SQLITE_HAS_CODEC加密 API、SQLite 3.32.0 的应用在 WAL 模式下建立了与旧实现的兼容机制issue #37同时修复设置新口令后未清空 pager 缓存导致数据库头未重新读取的问题issue #36。1.3.2引入mc_legacy_wal参数完成新旧 WAL 格式的桥接详见上文。升级提示若你的部署长期运行在 WAL 模式且曾使用 ≤1.2.5 版本升级后首次访问旧 WAL 日志时应临时启用mc_legacy_wal1完成恢复随后切回默认值。rekey 相关修复1.4.8修复PRAGMA rekey可能导致的崩溃issue #85。1.8.6修复rekey错误消息的返回issue #164强制在 rekey 时执行页大小与每页保留字节数issue #165备份操作增加源库与目标库加密兼容性校验issue #158。内存与并发安全修复1.8.6修复 MMAP_SIZE 0 时数据库损坏issue #156、数组越界访问issue #160、非对齐数据读写issue #162、VFS 错误上报issue #167。1.7.4防止因未初始化的密码表导致的崩溃。1.4.0移除全局 VFS 结构以解决 issue #73多连接并发场景下的冲突。1.3.5在SQLITE_DEBUG下报告解密错误时同步设置 pager 错误状态避免断言失败issue #55。其他兼容性修复1.9.0修复 KDF/HMAC 算法组合导致的 SQLCipher 不兼容见上文hmac_algorithm_compat。1.8.1应用多处改动以改善 SQLite3 WASM 支持修复缺失的 API 符号issue #133。1.5.1⚠️ 重要提示——1.5.0 与 1.5.1 在省略部分内建密码方案的构建中存在密码配置参数表获取缺陷issue #90启用加密时会崩溃1.5.2 修复。1.5.0⚠️ 重要提示——该版本关闭代码存在缺陷调用sqlite3_shutdown时可能崩溃。1.3.1修复用户认证扩展阻止 VACUUM 或 rekey 的问题。六、在 libSQL 中的集成方式SQLite3MultipleCiphers 随 libSQL 的 C FFI 层捆绑提供。集成入口在 libsql-ffi/build.rslibsql-ffi/Cargo.toml 中定义了multiple-ciphers []特性并将bundled/SQLite3MultipleCiphers目录加入 crate 的 exclude 列表排除 build/test 子目录。libsql-ffi/build.rs 中当启用multiple-ciphers特性时会声明对该目录的 rerun 依赖cargo:rerun-if-changed{BUNDLED_DIR}/SQLite3MultipleCiphers并在wasmtime-bindings特性同时启用时跳过默认的 bundled 构建改为copy_multiple_ciphers(out_path)复制加密扩展生成的头文件与绑定。换言之使用 libSQL 时通过 Cargo 特性组合即可启用加密能力# Cargo.toml 示例依赖声明示意 libsql-ffi { path libsql-ffi, features [multiple-ciphers] }启用后即可通过PRAGMA key/PRAGMA rekey、sqlite3_key/sqlite3_rekey以及各类mc_*、legacy_*参数进行加密配置。另外test/ 目录下还保留了sqlcipher-1.1.8-testkey.db、sqlcipher-2.0-be/le-testkey.db、sqlcipher-2.0-beta-testkey.db、sqlcipher-3.0-testkey.db、sqlcipher-4.0-testkey.db等各版本 SQLCipher 测试库及sqlciphertest.sql、test1.sql、test2.sql可用于验证与不同 SQLCipher 版本数据库文件的互操作结果。七、升级与迁移建议基于 CHANGELOG 的历史教训可归纳出以下实践要点WAL 模式升级要谨慎从 ≤1.2.5 升级前备份旧 WAL 日志并在首次访问时评估是否需要mc_legacy_wal1日常运行保持默认值 0。rekey 操作注意模式限制WAL 模式下 rekey 曾被禁止1.3.1当前版本虽已修复相关崩溃但执行PRAGMA rekey前仍建议切换到 rollback journal 模式或先备份。SQLCipher 互操作关注算法组合1.9.0 起默认与原始 SQLCipher 对齐 KDF/HMAC 算法组合若发现升级后生成的库与既有 SQLCipher 生态工具不兼容需检查hmac_algorithm_compat的设置。自定义密码方案注意接口变化若基于 1.5.0 的动态密码方案接口开发了第三方算法升级到 1.9.0 时必须适配GenerateKey的新签名。编译期裁剪要留足余地从 1.5.1 的教训看裁剪内建密码方案后务必回归测试“激活加密连接”的路径避免配置参数表访问缺陷。页大小与明文头部参数校验严格化1.8.6 起legacy_page_size必须为 512 至最大页大小之间的 2 的幂plaintext_header_size必须为 16 的倍数配置脚本中如硬编码了非法值需同步修正。八、结语SQLite3MultipleCiphers 的 CHANGELOG 不仅是一份版本记录更浓缩了 SQLite 加密生态二十余年兼容性博弈的经验从SQLITE_HAS_CODEC的消亡到 VFS 式新架构从 WAL 格式分裂到mc_legacy_wal桥接从多算法并存到 SQLCipher 严格互操作。理解这些变更能帮助你在 libSQL 中正确选型密码方案、规避 rekey 与 WAL 陷阱并在跨库迁移时少走弯路。本文引用的全部源码与配置均位于 libsql-ffi/bundled/SQLite3MultipleCiphers/ 目录可据此继续深入。【免费下载链接】libsqllibSQL is a fork of SQLite that is both Open Source, and Open Contributions.项目地址: https://gitcode.com/GitHub_Trending/li/libsql创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考