sqlcipher命令行如何正确打开加密数据库？

Question

使用sqlcipher命令行工具打开加密数据库时，常见的问题是：未正确设置密钥导致数据库无法解密。用户执行 `sqlcipher encrypted.db` 后直接输入SQL语句，却报错“file is encrypted or is not a database”。这是因为sqlcipher不会自动读取密钥，必须在打开数据库后、执行任何操作前，先通过 `PRAGMA key = 'your_password';` 提供正确的密码。此外，若使用了不同版本的加密算法（如v3到v4升级），还需设置兼容模式（如 `PRAGMA cipher_compatibility = 3;`）。忽略这些步骤将导致无法访问数据。

Answer 1

1. 问题背景与常见现象

在使用 sqlcipher 命令行工具操作加密的 SQLite 数据库时，许多开发者会遇到一个经典错误：

file is encrypted or is not a database

该错误通常出现在用户执行如下命令后直接尝试查询数据：

sqlcipher encrypted.db
SELECT * FROM users;

尽管数据库文件确实存在且格式正确，但由于未提供解密密钥，sqlcipher 无法识别其内容。这并非程序异常，而是加密机制的安全设计所致。SQLCipher 不会在启动时自动读取密码，必须显式通过 PRAGMA 指令设置密钥。

2. 核心原理：SQLCipher 的加密工作机制

• SQLCipher 使用 AES-256 加密算法对整个数据库文件进行透明加密。
• 每次打开数据库时，必须先提供正确的密钥才能解密页头并验证文件完整性。
• 密钥通过 PRAGMA key = 'your_password'; 在会话中设置。
• 若未设置或密钥错误，SQLCipher 将拒绝访问，返回“file is encrypted”错误。
• 从 v4 版本起，默认采用更安全的密钥派生方式（HMAC-SHA512），与旧版本不兼容。

因此，即使密码正确，若版本迁移未配置兼容模式，仍会导致解密失败。

3. 典型错误操作流程示例

步骤	命令	结果
1	sqlcipher encrypted_v3.db	成功启动 CLI
2	SELECT count(*) FROM sqlite_master;	error: file is encrypted or is not a database
3	PRAGMA key = 'mypassword';	无输出（但已设密钥）
4	SELECT count(*) FROM sqlite_master;	正常返回表数量

可见，关键在于密钥设置必须早于任何数据库读取操作。

4. 解决方案分步指南

1. 启动 sqlcipher 并加载数据库文件：
   sqlcipher encrypted.db
2. 立即设置解密密钥：
   PRAGMA key = 'your_strong_password';
3. 如怀疑版本不兼容，设置 cipher_compatibility 模式：
   PRAGMA cipher_compatibility = 3;
4. 验证是否可访问元数据：
   PRAGMA database_list;
5. 执行任意 SQL 查询确认解密成功。

注意：密钥设置必须在第一个 SELECT、ATTACH 或其他触发 I/O 的语句之前完成。

5. 版本兼容性深度解析

SQLCipher 自 v4 起改变了默认的加密协议，主要变化包括：

• 密钥派生函数由 PBKDF2-HMAC-SHA1 升级为 PBKDF2-HMAC-SHA512。
• 页大小和随机盐处理逻辑变更。
• 旧版数据库（v1-v3）需手动启用兼容模式。

可通过以下指令切换兼容级别：

-- 支持 legacy v3 格式
PRAGMA cipher_compatibility = 3;

-- 回退到最老格式（谨慎使用）
PRAGMA cipher_compatibility = 1;

推荐策略：优先尝试 cipher_compatibility = 3，若失败再逐步降低。

6. 自动化脚本中的最佳实践

在 shell 脚本中批量处理加密数据库时，建议将密钥和兼容性设置合并为一条命令：

sqlcipher encrypted.db << EOF
PRAGMA key = 'secret123';
PRAGMA cipher_compatibility = 3;
SELECT name FROM sqlite_master WHERE type='table';
EOF

也可通过环境变量传递密钥（注意安全性）：

export KEY="secret123"
sqlcipher encrypted.db -cmd "PRAGMA key='$KEY'; .dump"

避免交互式输入，提升自动化可靠性。

7. 故障排查流程图

graph TD
    A[启动 sqlcipher encrypted.db] --> B{能否执行查询?}
    B -- 否 --> C[报错: file is encrypted]
    C --> D[设置 PRAGMA key = 'password']
    D --> E{仍报错?}
    E -- 是 --> F[尝试 PRAGMA cipher_compatibility = 3]
    F --> G{成功?}
    G -- 否 --> H[降级至 compatibility=2 或 1]
    G -- 是 --> I[正常访问数据]
    E -- 否 --> I
    B -- 是 --> J[无需额外操作]

此流程覆盖了绝大多数密钥相关故障场景。

8. 安全注意事项与高级技巧

• 避免在命令行历史中明文记录密码，可使用 .read 命令从受控文件加载密钥。
• 定期审计数据库加密状态：
  PRAGMA cipher_provider; 和 PRAGMA cipher_version;
• 对于高敏感数据，结合操作系统级权限控制与应用层密钥管理（如 KMS）。
• 测试环境中可用空密码加密：PRAGMA key = '';，但生产环境禁用。

理解底层加密行为有助于快速定位跨平台迁移中的兼容问题。