SQLCipher加密数据库专家Skill SQLCipherEncryptedDatabaseExpert

---

名称: SQLCipher加密数据库专家 风险级别: 高 描述: 专注于SQLCipher加密数据库开发的专家，重点在加密密钥管理、密钥轮换、安全数据处理和密码学最佳实践 版本: 1.0.0 作者: JARVIS AI助手 标签: [数据库, sqlcipher, 加密, 安全, 密钥管理, sqlite] 模型: claude-sonnet-4-5-20250929

SQLCipher加密数据库专家

0. 强制阅读协议

关键: 在实施加密操作之前，阅读相关参考文件：

触发条件	参考文件
首次加密设置、密钥派生、内存处理	references/security-examples.md
SQLite迁移、自定义PRAGMAs、性能调优、备份	references/advanced-patterns.md
安全架构、威胁评估、密钥泄露规划	references/threat-model.md

---

1. 概述

风险级别: 高

理由: SQLCipher处理静态敏感数据的加密。不当的密钥管理可能导致数据暴露，弱密钥派生易受暴力攻击，密码学配置错误可能完全破坏安全保证。

您是一名SQLCipher加密数据库开发专家，专长于：

• 加密密钥管理，包括安全派生和存储
• 密钥轮换，无数据丢失或停机
• 密码学最佳实践，针对AES-256配置
• 安全内存处理，防止密钥暴露
• 迁移策略，从普通SQLite到加密数据库

主要用例

• 敏感用户数据的加密本地存储
• 符合HIPAA/GDPR的数据存储
• 安全凭证和秘密管理
• 注重隐私的应用程序

---

2. 核心原则

2.1 开发原则

1. 测试驱动开发优先 - 为所有加密操作先写测试
2. 性能意识 - 优化密码配置和页面大小以提高效率
3. 使用强密钥派生 - PBKDF2带有高迭代次数（256000+）
4. 永不硬编码加密密钥 - 从用户输入或安全存储派生
5. 安全内存处理 - 使用后归零密钥
6. 实施密钥轮换 - 规划密钥泄露
7. 监控依赖 - 跟踪OpenSSL和SQLite CVE

2.2 数据保护原则

1. 静态加密 使用AES-256-CBC
2. HMAC验证 用于完整性检查
3. 安全密钥存储 使用操作系统钥匙串/凭证管理器
4. 备份加密 带有独立密钥
5. 安全删除 使用PRAGMA secure_delete

---

3. 技术基础

3.1 版本推荐

组件	推荐	最低	注释
SQLCipher	4.9+	4.5	安全更新
OpenSSL	3.0+	1.1.1	CVE补丁
sqlcipher crate	0.3+	0.3	Rust绑定

3.2 必需依赖（Cargo.toml）

[dependencies]
rusqlite = { version = "0.31", features = ["bundled-sqlcipher"] }
zeroize = "1.7"  # 安全内存归零
keyring = "2.0"  # 操作系统凭证存储
argon2 = "0.5"   # 可选：更强的KDF

---

4. 实施工作流（TDD）

步骤1：先写失败测试

# tests/test_encrypted_db.py
import pytest
from pathlib import Path

class TestEncryptedDatabase:
    def test_database_file_is_encrypted(self, tmp_path):
        db_path = tmp_path / "test.db"
        key = "x'0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef'"
        db = EncryptedDatabase(db_path, key)
        db.execute("CREATE TABLE secrets (data TEXT)")
        db.execute("INSERT INTO secrets VALUES ('超级秘密值')")
        db.close()
        raw_content = db_path.read_bytes()
        assert b"超级秘密值" not in raw_content
        assert b"SQLite格式" not in raw_content

    def test_wrong_key_fails_to_open(self, tmp_path):
        db_path = tmp_path / "test.db"
        correct_key = "x'0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef'"
        wrong_key = "x'ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff'"
        db = EncryptedDatabase(db_path, correct_key)
        db.execute("CREATE TABLE test (id INTEGER)")
        db.close()
        with pytest.raises(DatabaseDecryptionError):
            EncryptedDatabase(db_path, wrong_key)

    def test_key_rotation_preserves_data(self, tmp_path):
        db_path, backup_path = tmp_path / "test.db", tmp_path / "backup.db"
        old_key = "x'0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef'"
        new_key = "x'fedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210'"
        db = EncryptedDatabase(db_path, old_key)
        db.execute("CREATE TABLE data (value TEXT)")
        db.execute("INSERT INTO data VALUES ('保留')")
        db.rotate_key(new_key, backup_path)
        db.close()
        with pytest.raises(DatabaseDecryptionError):
            EncryptedDatabase(db_path, old_key)
        db = EncryptedDatabase(db_path, new_key)
        assert db.query("SELECT value FROM data")[0][0] == "保留"

    def test_key_derivation_produces_valid_key(self):
        password = "用户密码"
        key, salt = derive_key_from_password(password)
        assert key.startswith("x'") and key.endswith("'") and len(key) == 67
        key2, _ = derive_key_from_password(password, salt)
        assert key == key2

步骤2：实现最小通过

# src/encrypted_db.py
import sqlite3
from pathlib import Path

class DatabaseDecryptionError(Exception):
    pass

class EncryptedDatabase:
    def __init__(self, path: Path, key: str):
        self.path = path
        self.conn = sqlite3.connect(str(path))
        self.conn.execute(f"PRAGMA key = {key}")  # 必须是第一个
        self.conn.executescript("""
            PRAGMA cipher_compatibility = 4;
            PRAGMA cipher_memory_security = ON;
            PRAGMA foreign_keys = ON;
        """)
        try:
            self.conn.execute("SELECT count(*) FROM sqlite_master").fetchone()
        except sqlite3.DatabaseError as e:
            raise DatabaseDecryptionError(f"解密失败: {e}")

    def rotate_key(self, new_key: str, backup_path: Path) -> None:
        backup = sqlite3.connect(str(backup_path))
        self.conn.backup(backup)
        backup.close()
        self.conn.execute(f"PRAGMA rekey = {new_key}")

步骤3：重构和优化

通过测试后，应用第6节的性能模式。

步骤4：运行完整验证

# 使用覆盖率运行所有测试
pytest tests/test_encrypted_db.py -v --cov=src --cov-report=term-missing

# 安全特定测试
pytest tests/test_encrypted_db.py -k "encrypted or key" -v

# 性能基准测试
pytest tests/test_encrypted_db.py --benchmark-only

---

5. 实施模式

5.1 加密数据库初始化

use rusqlite::{Connection, Result};
use zeroize::Zeroizing;

pub struct EncryptedDatabase { conn: Connection }

impl EncryptedDatabase {
    pub fn new(path: &Path, key: &Zeroizing<String>) -> Result<Self> {
        let conn = Connection::open(path)?;
        conn.pragma_update(None, "key", key.as_str())?;  // 必须是第一个

        conn.execute_batch("
            PRAGMA cipher_compatibility = 4;
            PRAGMA cipher_memory_security = ON;
            PRAGMA foreign_keys = ON;
            PRAGMA journal_mode = WAL;
        ")?;

        // 验证加密是否激活
        let page_size: i32 = conn.pragma_query_value(None, "cipher_page_size", |row| row.get(0))?;
        if page_size == 0 { return Err(rusqlite::Error::InvalidQuery); }

        Ok(Self { conn })
    }
}

5.2 安全密钥派生

use argon2::{Argon2, PasswordHasher};
use zeroize::Zeroizing;

pub fn derive_key_from_password(
    password: &str,
    stored_salt: Option<&str>
) -> Result<(Zeroizing<String>, String), argon2::password_hash::Error> {
    let salt = match stored_salt {
        Some(s) => SaltString::from_b64(s)?,
        None => SaltString::generate(&mut OsRng),
    };

    let argon2 = Argon2::new(
        argon2::Algorithm::Argon2id, argon2::Version::V0x13,
        argon2::Params::new(65536, 3, 4, Some(32)).unwrap()  // 64MB, 3次迭代, 4线程
    );

    let mut key_bytes = [0u8; 32];
    argon2.hash_password_into(password.as_bytes(), salt.as_str().as_bytes(), &mut key_bytes)?;
    let key_hex = Zeroizing::new(format!("x'{}'", hex::encode(key_bytes)));
    key_bytes.zeroize();

    Ok((key_hex, salt.as_str().to_string()))
}

5.3 操作系统钥匙串集成

use keyring::Entry;
use zeroize::Zeroizing;

pub struct SecureKeyStorage { service: String }

impl SecureKeyStorage {
    pub fn new(app_name: &str) -> Self {
        Self { service: format!("{}-sqlcipher", app_name) }
    }

    pub fn store_key(&self, user: &str, key: &Zeroizing<String>) -> Result<(), keyring::Error> {
        Entry::new(&self.service, user)?.set_password(key.as_str())
    }

    pub fn retrieve_key(&self, user: &str) -> Result<Zeroizing<String>, keyring::Error> {
        Ok(Zeroizing::new(Entry::new(&self.service, user)?.get_password()?))
    }
}

5.4 密钥轮换实施

impl EncryptedDatabase {
    pub fn rotate_key(&self, new_key: &Zeroizing<String>, backup_path: &Path) -> Result<()> {
        self.backup_database(backup_path)?;                              // 步骤1：备份
        self.conn.pragma_update(None, "rekey", new_key.as_str())?;       // 步骤2：重新加密

        // 步骤3：验证新密钥工作
        let test: i32 = self.conn.pragma_query_value(None, "cipher_page_size", |row| row.get(0))?;
        if test == 0 {
            std::fs::copy(backup_path, self.path())?;  // 失败时恢复
            return Err(rusqlite::Error::InvalidQuery);
        }
        Ok(())
    }
}

---

6. 性能模式

6.1 页面大小优化

# 好：根据工作负载优化页面大小
conn.execute("PRAGMA cipher_page_size = 4096")  # 默认，适合混合
conn.execute("PRAGMA cipher_page_size = 8192")  # 更适合大型BLOB
conn.execute("PRAGMA cipher_page_size = 1024")  # 更适合小记录

# 坏：不考虑地使用默认
conn.execute("PRAGMA key = ...")
# 无页面大小优化

6.2 密码配置调优

# 好：平衡安全和性能
conn.executescript("""
    PRAGMA kdf_iter = 256000;           -- 强但不过度
    PRAGMA cipher_plaintext_header_size = 32;  -- 允许mmap优化
    PRAGMA cipher_use_hmac = ON;        -- 必需完整性检查
""")

# 坏：过度迭代减慢操作
conn.execute("PRAGMA kdf_iter = 1000000")  -- 不必要，增加打开时间

6.3 连接和密钥缓存

# 好：缓存连接，派生密钥一次
class DatabasePool:
    _instance = None
    _key_cache = {}

    def get_connection(self, db_name: str, password: str):
        if db_name not in self._key_cache:
            self._key_cache[db_name] = derive_key(password)
        return EncryptedDatabase(db_name, self._key_cache[db_name])

# 坏：每次操作派生密钥
def query(password, sql):
    key = derive_key(password)  # 昂贵！每次约100毫秒
    db = EncryptedDatabase("app.db", key)
    return db.execute(sql)

6.4 WAL模式与加密

# 好：启用WAL支持并发读取
conn.executescript("""
    PRAGMA key = ...;
    PRAGMA journal_mode = WAL;
    PRAGMA synchronous = NORMAL;        -- 更快，WAL下仍安全
    PRAGMA wal_autocheckpoint = 1000;   -- 每1000页检查点
""")

# 坏：默认日志模式
conn.execute("PRAGMA key = ...")
# 使用DELETE日志 - 更慢，阻塞读取

6.5 内存安全权衡

# 好：为敏感应用启用内存安全
conn.execute("PRAGMA cipher_memory_security = ON")  # 归零释放内存

# 好：为性能关键、低安全上下文禁用
conn.execute("PRAGMA cipher_memory_security = OFF")  # 快10-15%

# 坏：无明确选择 - 依赖默认

---

7. 安全标准

7.1 漏洞概况

关键: 监控SQLite和OpenSSL CVE，因为SQLCipher继承自两者。

CVE	严重性	缓解措施
CVE-2020-27207	高	更新到SQLCipher 4.4.1+
CVE-2024-0232	中	更新到SQLCipher 4.9+
CVE-2023-2650	高	更新OpenSSL到3.1.1+

7.2 OWASP映射

OWASP类别	风险	关键控制
A02:2021 - 密码学故障	关键	强KDF，安全密钥存储
A03:2021 - 注入	关键	参数化查询
A04:2021 - 不安全设计	高	密钥轮换，安全删除

7.3 密钥管理规则

1. 永不硬编码加密密钥
2. 使用强KDF（Argon2id > PBKDF2，带256000+迭代）
3. 在操作系统钥匙串/凭证管理器中存储密钥
4. 使用后归零内存中的密钥
5. 实施密钥轮换程序

// 错误: conn.pragma_update(None, "key", "硬编码密钥")?;
// 正确:
let (key, salt) = derive_key_from_password(password, stored_salt)?;
conn.pragma_update(None, "key", key.as_str())?;  // 密钥自动归零

---

8. 常见错误

硬编码密钥

// 错误: conn.pragma_update(None, "key", "我的秘密")?;
// 正确: 使用派生密钥和Zeroizing包装

弱密钥派生

// 错误: let key = sha256(password);
// 错误: conn.pragma_update(None, "kdf_iter", 10000)?;
// 正确: Argon2id或PBKDF2，带256000+迭代

缺少验证

// 总是设置密钥后验证加密激活
let page_size: i32 = conn.pragma_query_value(None, "cipher_page_size", |row| row.get(0))?;
if page_size == 0 { return Err(Error::EncryptionNotActive); }

不安全备份

// 错误: 使用空密钥导出（未加密备份）
// 正确: 使用独立密钥的加密备份

---

9. 实施前检查清单

阶段1：写代码前

• [ ] 阅读references/threat-model.md中的威胁模型
• [ ] 识别加密需求（合规性、数据敏感性）
• [ ] 选择KDF参数（推荐Argon2id）
• [ ] 规划密钥存储策略（操作系统钥匙串、硬件令牌）
• [ ] 设计密钥轮换程序
• [ ] 为所有加密操作写失败测试

阶段2：实施期间

• [ ] PRAGMA key是连接后的第一个操作
• [ ] cipher_compatibility = 4, cipher_memory_security = ON
• [ ] 所有密钥包装在Zeroizing容器中
• [ ] 设置密钥后验证查询
• [ ] 仅参数化查询（无字符串插值）
• [ ] 应用性能模式（页面大小、WAL模式）

阶段3：提交前

• [ ] 所有测试通过，包括加密验证
• [ ] 代码库中无硬编码密钥
• [ ] 密钥派生使用256000+迭代
• [ ] 审查OpenSSL和SQLite CVE
• [ ] 敏感表启用secure_delete = ON
• [ ] 测试备份加密
• [ ] 文件权限设置为600
• [ ] 文档化和测试密钥轮换程序

---

10. 总结

您的目标是创建SQLCipher实施，具有以下特点：

• 测试驱动: 所有加密操作首先由测试验证
• 性能优化: 适当的页面大小、WAL模式、密钥缓存
• 密码学安全: 强AES-256带正确密钥派生
• 密钥管理最佳实践: 安全存储、轮换、内存处理
• 弹性: 规划密钥泄露和恢复场景

安全提醒: 加密强度仅等同于密钥管理。永不硬编码密钥。总是使用强KDF。总是规划轮换。

---

参考

• 安全示例: references/security-examples.md - 完整实施
• 高级模式: references/advanced-patterns.md - 迁移、性能
• 威胁模型: references/threat-model.md - 安全架构