Citadel

加密优先的嵌入式数据库引擎，性能超越未加密的 SQLite。

每一页在写入磁盘前都会进行加密和身份验证。数据库文件始终是不透明的。在所有 15 个基准测试中，Citadel 在相同的缓存预算下均优于未加密的 SQLite。 ## 功能 - **静态加密** - 每页使用 AES-256-CTR + HMAC-SHA256 加密，在解密前进行验证 - **SQL** - 支持 JOIN、子查询、CTE（递归）、UNION/INTERSECT/EXCEPT、窗口函数、视图、聚合、索引、约束、ALTER TABLE、预编译语句 - **ACID** - 复制写入 B+ 树、影子分页、无 WAL。支持并发读器的快照隔离 - **P2P 同步** - 基于 Noise 加密通道与 PSK 认证的 Merkle 树表差异同步 - **CLI** - 支持制表符补全和语法高亮的 SQL Shell，支持 .backup、.verify、.rekey、.sync、.dump 等点命令 - **三层密钥层级** - 口令 -> Argon2id -> 主密钥 -> AES-KW -> REK -> HKDF -> DEK + MAC - **FIPS 140-3** - 在需要合规时使用 PBKDF2-HMAC-SHA256 + AES-256-CTR - **审计日志** - 基于 HMAC-SHA256 的链式、防篡改日志 - **热备份** - 通过 MVCC 提供一致性的快照，不阻塞写入 - **溢出页** - 透明处理大值，无大小限制 - **跨平台** - 支持 Windows、Linux、macOS。提供 C FFI（37 个函数）和 WebAssembly 绑定 - **2,490+ 测试** - 包含单元测试、集成测试和压力测试，覆盖 10 个 crate ## 基准测试 Citadel 与 SQLite 在 10 万行（INTEGER、TEXT、INTEGER）数据上的单线程性能对比： ``` Benchmark Citadel SQLite Ratio ----------------------------------------------------- count 186 ns 37.1 us 200x view_point 3.30 us 48.5 us 14.7x point 1.10 us 16.6 us 15.1x group_by 2.53 ms 12.1 ms 4.8x cte 1.61 ms 6.62 ms 4.1x window_agg 37.1 ms 87.4 ms 2.4x filter 936 us 2.28 ms 2.4x view_filter 2.18 ms 5.03 ms 2.3x sort 1.46 ms 3.09 ms 2.1x window_rank 75.0 ms 140 ms 1.9x insert 94.8 us 164 us 1.7x scan 9.42 ms 15.1 ms 1.6x sum 1.68 ms 2.34 ms 1.4x join 107 us 133 us 1.2x recursive_cte 128 us 132 us 1.03x ```

方法论

- **count** - `SELECT COUNT(*) FROM t` - **group_by** - `SELECT age, COUNT(*) FROM t GROUP BY age` - **filter** - `SELECT * FROM t WHERE age = 42` - **sort** - `SELECT * FROM t ORDER BY age LIMIT 10` - **sum** - `SELECT SUM(age) FROM t` - **point** - `SELECT * FROM t WHERE id = 50000` - **scan** - `SELECT * FROM t`（全表扫描 10 万行） - **insert** - 单事务插入 100 行 - **join** - `SELECT a.id, b.data FROM a INNER JOIN b ON a.id = b.a_id`（1K x 1K） - **cte** - `WITH filtered AS (SELECT ... WHERE age < 50) SELECT age, COUNT(*) FROM filtered GROUP BY age` - **recursive_cte** - `WITH RECURSIVE seq(x) AS (SELECT 1 UNION ALL SELECT x+1 FROM seq WHERE x < 1000) SELECT SUM(x) FROM seq` - **window_rank** - `SELECT id, name, age, ROW_NUMBER() OVER (PARTITION BY age ORDER BY id), RANK() OVER (PARTITION BY age ORDER BY name) FROM t` - **window_agg** - `SELECT id, age, SUM(age) OVER (ORDER BY id ROWS 50 PRECEDING), MIN(age) OVER (ORDER BY id ROWS 50 PRECEDING) FROM t` - **view_filter** - 先执行 `CREATE VIEW v AS SELECT * FROM t`，然后 `SELECT * FROM v WHERE age = 42` - **view_point** - 先执行 `CREATE VIEW v AS SELECT * FROM t`，然后 `SELECT * FROM v WHERE id = 50000` SQLite 配置：`journal_mode=OFF, synchronous=OFF, cache_size=8000`（约 32 MB）。 Citadel 配置：`SyncMode::Off, cache_size=4096`（约 32 MB）。 两者均在禁用持久化的情况下运行，以测量纯引擎开销，而非磁盘 I/O。 使用 `cargo bench -p citadeldb-sql --bench h2h_bench` 复现。

## 快速开始 ### 库 ``` use citadel::DatabaseBuilder; use citadel_sql::Connection; let db = DatabaseBuilder::new("my.db") .passphrase(b"secret") .create()?; let mut conn = Connection::open(&db)?; conn.execute("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT NOT NULL);")?; conn.execute("INSERT INTO users (id, name) VALUES (1, 'Alice');")?; let result = conn.query("SELECT * FROM users;")?; // Key-value API let mut wtx = db.begin_write()?; wtx.insert(b"key", b"value")?; wtx.commit()?; let mut rtx = db.begin_read(); assert_eq!(rtx.get(b"key")?.unwrap(), b"value"); // Named tables let mut wtx = db.begin_write()?; wtx.create_table(b"sessions")?; wtx.table_insert(b"sessions", b"token-abc", b"user-42")?; wtx.commit()?; // In-memory (no file I/O - useful for testing and WASM) let mem_db = DatabaseBuilder::new("") .passphrase(b"secret") .create_in_memory()?; ``` ### 命令行工具 ``` citadel --create my.db citadel> CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT NOT NULL); citadel> INSERT INTO users (id, name) VALUES (1, 'Alice'), (2, 'Bob'); citadel> SELECT * FROM users; +----+-------+ | id | name | +----+-------+ | 1 | Alice | | 2 | Bob | +----+-------+ citadel> .backup mydb.bak citadel> .verify citadel> .stats citadel> .audit verify citadel> .rekey citadel> .compact clean.db citadel> .dump users # P2P 同步 citadel> .keygen citadel> .listen 4248 # Terminal A citadel> .sync 127.0.0.1:4248 # Terminal B ``` ## SQL **语句** - CREATE/DROP TABLE、ALTER TABLE（ADD/DROP/RENAME COLUMN、RENAME TABLE）、CREATE/DROP INDEX、CREATE/DROP VIEW、INSERT（VALUES、SELECT）、SELECT、UPDATE、DELETE、BEGIN/COMMIT/ROLLBACK、EXPLAIN **约束** - PRIMARY KEY、NOT NULL、UNIQUE、DEFAULT、CHECK（列级与表级）、FOREIGN KEY（RESTRICT/NO ACTION） **类型** - INTEGER、REAL、TEXT、BLOB、BOOLEAN **子句** - JOIN（INNER、LEFT、RIGHT、CROSS）、子查询（标量、IN、EXISTS）、CTE（WITH / WITH RECURSIVE）、UNION/INTERSECT/EXCEPT [ALL]、CASE、BETWEEN、LIKE、DISTINCT、GROUP BY/HAVING、ORDER BY、LIMIT/OFFSET **窗口函数** - ROW_NUMBER、RANK、DENSE_RANK、NTILE、LAG、LEAD、FIRST_VALUE、LAST_VALUE、SUM/COUNT/AVG/MIN/MAX OVER，配合 PARTITION BY、ORDER BY、ROWS/RANGE 帧 **视图** - CREATE/DROP VIEW、OR REPLACE、IF NOT EXISTS / IF EXISTS、列别名、嵌套视图 **函数** - COUNT、SUM、AVG、MIN、MAX、LENGTH、UPPER、LOWER、SUBSTR、ABS、ROUND、COALESCE、NULLIF、CAST、TYPEOF、HEX、TRIM、REPLACE、RANDOM、IIF、GLOBAL **预编译语句** - 使用 `$1, $2, ...` 位置参数，并带有 LRU 语句缓存 ## 安全 **磁盘上无明文** - 每一页在写入前加密，在读取前进行身份验证。 **独立密钥文件** - 加密密钥存储在 `{dbname}.citadel-keys` 中，不在数据库内。口令通过 Argon2id（或 FIPS 模式下的 PBKDF2）在内存中派生出主密钥，永不落盘。 **密钥备份** - 可导出使用独立恢复口令加密的密钥备份，无需重新加密整个数据库即可恢复访问。 **即时重加密** - 更改口令会重新封装根加密密钥，无需重新加密页面，无论数据库大小均瞬时完成。 **加密同步** - 使用 Noise 协议（`NNpsk0_25519_ChaChaPoly_BLAKE2s`）和 256 位预共享密钥。每个会话使用临时的 Curve25519 密钥以实现前向安全性。 ## 架构 ``` +-------------+---------------+---------------+ | citadel-cli | citadel-ffi | citadel-wasm | CLI, C FFI, WebAssembly +-------------+---------------+---------------+ | citadel-sql | SQL parser, planner, executor +---------------------------------------------+ | citadel | Database API, builder, sync +--------------+--------------+---------------+ | citadel-txn | citadel-sync | citadel-crypto| Transactions, replication, keys +--------------+--------------+---------------+ |citadel-buffer| citadel-page | Buffer pool (SIEVE), page codec +--------------+------------------------------+ | citadel-io | File I/O, fsync, io_uring +---------------------------------------------+ | citadel-core | Types, errors, constants +---------------------------------------------+ ``` ### 页布局（8,208 字节） ``` +----------+--------------------+----------+ | IV 16B | Ciphertext 8160B | MAC 32B | +----------+--------------------+----------+ ``` 每个页面使用随机生成的 IV，并在解密前验证 HMAC。 ### 提交协议 使用“上帝字节”的影子分页——一个字节用于选择活动的提交槽位。无 WAL 的原子提交： 1. 将脏页写入新位置（CoW） 2. 从底向上计算 Merkle 哈希 3. 更新非活动的提交槽位 4. 翻转“上帝字节” ## 语言绑定 ### C / C++ 提供静态或动态库，并附带自动生成的 `citadel.h`（通过 cbindgen）。所有 37 个函数均具备 panic-safe 特性。 ``` #include "citadel.h" CitadelDb *db = NULL; citadel_create("my.db", "secret", 6, &db); CitadelWriteTxn *wtx = NULL; citadel_write_begin(db, &wtx); citadel_write_put(wtx, (const uint8_t*)"key", 3, (const uint8_t*)"val", 3); citadel_write_commit(wtx); CitadelSqlConn *conn = NULL; citadel_sql_open(db, &conn); CitadelSqlResult *result = NULL; citadel_sql_execute(conn, "SELECT * FROM users;", &result); citadel_close(db); ``` ### WebAssembly ``` import { CitadelDb } from "@citadeldb/wasm"; const db = new CitadelDb("secret"); db.execute("CREATE TABLE t (id INTEGER PRIMARY KEY, name TEXT);"); db.execute("INSERT INTO t (id, name) VALUES (1, 'Alice');"); const result = db.query("SELECT * FROM t;"); // { columns: ["id", "name"], rows: [[1, "Alice"]] } db.put(new Uint8Array([1, 2, 3]), new Uint8Array([4, 5, 6])); ``` 构建命令：`wasm-pack build crates/citadel-wasm --target web` ## 构建 需要 Rust 1.75+。 ``` git clone https://github.com/yp3y5akh0v/citadel.git cd citadel cargo build --release ``` ### 功能标志 | 标志 | 描述 | |------|------| | `audit-log` | HMAC 链式防篡改审计日志（默认开启） | | `fips` | 仅使用 FIPS 40-3：PBKDF2 + AES-256-CTR | | `io-uring` | Linux 的 io_uring 异步 I/O | ## 许可证 [MIT](LICENSE-MIT) 或 [Apache-2.0](LICENSE-APACHE)

标签：ACID, AES-256 加密, AES-KW, AI工具, Argon2id, B+ 树, Cilium, Copy-on-Write, Crates.io, DEK, FIPS 140-3, HKDF, HMAC-SHA256, HTTP 参数枚举, KDF, Merkle 树, MVCC, Noise 协议, NPM, P2P 同步, REK, Rust 数据库, SQLite 替代, SQL 数据库, 主密钥加密密钥, 加密存储, 加密数据库, 加密认证, 可视化界面, 审计日志, 密钥层次, 嵌入式数据库, 数据保密性, 数据库 CLI, 数据库事务, 数据库同步, 数据库备份, 数据库完整性, 数据库引擎, 数据库索引, 数据库约束, 数据库视图, 数据库转储, 溢出页处理, 热备份, 窗口函数, 端到端加密, 语法高亮, 透明分页, 递归 CTE, 通知系统, 重新密钥, 验证备份, 高性能数据库