mrcord77/rust_citadel
GitHub: mrcord77/rust_citadel
一个基于 Rust 的后量子混合加密与密钥管理服务器，通过 REST API 为应用提供遵循 NIST 标准的数据加密和全生命周期密钥管理。
Stars: 2 | Forks: 0
# Citadel
后量子混合加密与密钥管理服务器。
Citadel 结合 X25519 + ML-KEM-768 进行密钥封装，并使用 AES-256-GCM 进行数据加密，遵循 NIST 为后量子过渡提出的混合方案。应用程序通过 REST API 加密和解密数据。Citadel 负责管理密钥——包括生成、轮换、撤销、访问控制和审计日志。
**状态：** 可用的实现。未经审计。无生产环境部署记录。请参阅下方的[安全性](#security)。
## 功能说明
```
Your Application Citadel Database
| | |
|-- POST /encrypt ------->| |
| |-- hybrid KEM (X25519+ML-KEM) |
| |-- derive AES-256 key (HKDF) |
| |-- encrypt with AES-256-GCM |
|<-- encrypted blob ------| |
| |
|-- store blob ------------------------------------------>|
```
你的应用程序永远不会接触原始密钥材料。加密后的数据块是自包含的——它包含已包装的密钥、算法标识符和密文。你可以将其存储在任何数据库中。解密时只需将其连同相同的 AAD 和上下文发送回 Citadel 即可。
## 架构
```
citadel-envelope Hybrid encryption core (X25519 + ML-KEM-768 + AES-256-GCM)
citadel-keystore Key lifecycle management, 4-level hierarchy, threat-adaptive policies
citadel-api HTTP server, scoped API key auth, rate limiting, real-time dashboard
```
## 快速开始
### Docker（推荐）
```
# Clone
git clone https://github.com/mrcord77/rust_citadel.git
cd rust_citadel
# 设置你的 admin API key
echo -n "your-secret-key" | sha256sum | cut -d' ' -f1
# 复制 hash
# 开始
CITADEL_API_KEY_HASH= docker compose up -d
# 验证
curl http://localhost:3000/health
# {"status":"ok","version":"0.2.0"}
```
Dashboard: http://localhost:3000
### 从源码构建
需要 Rust 1.75+。
```
cargo build --release -p citadel-api
CITADEL_API_KEY="your-secret-key" CITADEL_SEED_DEMO=true ./target/release/citadel-api
```
## 使用方法
### Python
```
import requests
api = "http://localhost:3000"
headers = {"Authorization": "Bearer your-secret-key"}
# Encrypt
r = requests.post(f"{api}/api/keys/{dek_id}/encrypt", headers=headers, json={
"plaintext": "sensitive data",
"aad": "record-001", # binds ciphertext to this record
"context": "patient-records" # domain separation
})
blob = r.json()
# Decrypt
r = requests.post(f"{api}/api/decrypt", headers=headers, json={
"blob": blob,
"aad": "record-001",
"context": "patient-records"
})
plaintext = r.json()["plaintext"]
```
请参阅 [citadel_example.py](citadel_example.py) 获取包含 AAD 绑定、密钥轮换和威胁感知应用程序行为的完整工作示例。
### curl
```
# 状态
curl http://localhost:3000/api/status -H "Authorization: Bearer $KEY"
# 列出 keys
curl http://localhost:3000/api/keys -H "Authorization: Bearer $KEY"
# Encrypt
curl -X POST http://localhost:3000/api/keys/$DEK_ID/encrypt \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{"plaintext":"hello","aad":"test","context":"demo"}'
```
## API 端点
| 端点 | 方法 | 权限范围 | 描述 |
|----------|--------|-------|-------------|
| `/health` | GET | — | 健康检查 |
| `/api/status` | GET | read | 威胁级别、密钥数量 |
| `/api/metrics` | GET | read | 安全指标 |
| `/api/keys` | GET | read | 列出所有密钥 |
| `/api/keys` | POST | manage | 生成新密钥 |
| `/api/keys/:id` | GET | read | 获取密钥详情 |
| `/api/keys/:id/activate` | POST | manage | 激活待定密钥 |
| `/api/keys/:id/rotate` | POST | manage | 轮换密钥（新版本） |
| `/api/keys/:id/revoke` | POST | manage | 永久撤销密钥 |
| `/api/keys/:id/destroy` | POST | manage | 销毁密钥材料 |
| `/api/keys/:id/encrypt` | POST | encrypt | 加密数据 |
| `/api/decrypt` | POST | encrypt | 解密数据 |
| `/api/threat` | GET | read | 威胁情报详情 |
| `/api/policies` | GET | read | 活动的密钥策略 |
| `/api/auth/whoami` | GET | read | 当前 API 密钥信息 |
| `/api/auth/keys` | GET | admin | 列出 API 密钥 |
| `/api/auth/keys` | POST | admin | 创建 API 密钥 |
| `/api/auth/keys/:id` | DELETE | admin | 撤销 API 密钥 |
## 密钥层级
```
Root Key
└── Domain Key (per environment / business unit)
└── KEK — Key Encrypting Key (wraps DEKs)
└── DEK — Data Encrypting Key (encrypts application data)
```
遵循 NIST SP 800-57 标准。每个层级都限制了泄露的影响范围——如果某个 DEK 泄露，不会暴露其他 DEK，因为 KEK 是独立的。
## API 密钥权限范围
| 权限范围 | 权限 |
|-------|-------------|
| `read` | 查看密钥、状态、指标、威胁级别 |
| `encrypt` | 加密和解密数据 |
| `manage` | 创建、轮换、撤销、销毁密钥 |
| `admin` | 包含上述所有权限 + 管理 API 密钥 |
`admin` 隐含包含所有其他权限范围。遵循最小权限原则：为监控 Dashboard 分配 `read`，为应用服务分配 `read + encrypt`，为管理工具分配 `admin`。
## 自适应威胁系统
Citadel 监控安全事件并自动调整密钥策略：
| 级别 | 触发条件 | 响应措施 |
|-------|---------|----------|
| LOW | 正常操作 | 标准加密周期 |
| GUARDED | 轻微异常 | 略微缩短轮换周期 |
| ELEVATED | 可疑模式 | 压缩轮换计划 |
| HIGH | 活跃威胁指标 | 强制轮换，降低使用限制 |
| CRITICAL | 遭受攻击 | 实施最大限制 |
会提高威胁级别的事件：身份验证失败、解密失败、频繁的访问模式、手动升级。分数会随时间衰减。
## 密码学
| 组件 | 算法 | 标准 |
|-----------|-----------|----------|
| 密钥封装（经典） | X25519 ECDH | RFC 7748 |
| 密钥封装（后量子） | ML-KEM-768 | FIPS 203 |
| 数据加密 | AES-256-GCM | NIST SP 800-38D |
| 密钥派生 | HKDF-SHA256 | NIST SP 800-56C |
混合构造：将两个共享密钥连接起来并送入 HKDF 处理。只要 X25519 或 ML-KEM-768 **任一**保持安全，整体安全性就能成立。
### 传输格式
```
version[1] || suite_kem[1] || suite_aead[1] || flags[1] || kem_ct_len[2] ||
x25519_ephemeral_pk[32] || mlkem768_ct[1088] || nonce[12] || aead_ct[variable]
```
自描述、带版本号、无需协商（可防止降级攻击）。请参阅 [SPEC.md](SPEC.md) 获取完整规范。
### 安全特性
- **常数时间比较** — 通过 `subtle` crate 进行 API 密钥验证，防止时序攻击
- **清零操作** — 所有共享密钥和 AES 密钥都封装在 `Zeroizing` 中，在 drop 时清零
- **统一的错误返回** — 解密失败返回相同的错误信息（防止成为解密预言机）
- **完整性链式审计日志** — SHA-256 哈希链可检测日志篡改
- **速率限制** — 基于 IP 的令牌桶算法，违规时会提升威胁级别
## 安全性
**Citadel 是未经审计的软件。**
该实现通过成熟的 Rust crate（`ml-kem`、`x25519-dalek`、`aes-gcm`、`hkdf`）使用 NIST 标准化的原语。它本身不实现任何密码学算法。其价值在于正确的组合，而非新颖的数学原理。
已完成的工作：
- 包含已知答案测试的全面测试套件
- 对传输格式解析器和完整解密路径的模糊测试
- 对加密/解密操作的时间分析
- 统一的错误处理以防止解密预言机
未完成的工作：
- 独立的安全审计
- 形式化验证
- FIPS 验证
- 生产环境部署
**未经独立审查，请勿用于敏感数据。** 有关漏洞报告，请参阅 [SECURITY.md](SECURITY.md)。
## 合规性
映射了 34 项 NIST SP 800-57 控制措施：26 项满足，7 项部分满足，1 项缺失。请参阅 [COMPLIANCE_MATRIX.md](COMPLIANCE_MATRIX.md) 获取完整映射。
相关框架：NIST SP 800-57（密钥管理）、CNSA 2.0（PQC 时间表）、HIPAA（静态数据加密）、SOC 2（访问控制与审计）。
## 项目结构
```
rust_citadel/
├── citadel-envelope/ # Core hybrid encryption library
│ ├── src/
│ │ ├── envelope.rs # Encrypt/decrypt operations
│ │ ├── kem.rs # X25519 + ML-KEM-768 hybrid KEM
│ │ ├── kdf.rs # HKDF-SHA256 key derivation
│ │ ├── wire.rs # Wire format encode/decode
│ │ ├── aead.rs # AES-256-GCM wrapper
│ │ ├── aad.rs # Additional authenticated data
│ │ ├── error.rs # Uniform error types
│ │ └── sdk.rs # High-level API
│ ├── tests/ # KAT + roundtrip tests
│ └── fuzz/ # Fuzz targets
├── citadel-keystore/ # Key lifecycle management
│ └── src/
│ ├── keystore.rs # Key CRUD + state machine
│ ├── policy.rs # Crypto-period policies
│ ├── threat.rs # Adaptive threat intelligence
│ ├── storage.rs # File-based key storage
│ ├── audit.rs # Integrity-chained audit log
│ └── types.rs # Key types and states
├── citadel-api/ # HTTP server
│ └── src/
│ ├── main.rs # API routes, auth, rate limiting
│ └── dashboard.html # Real-time security dashboard
├── citadel_example.py # Python integration example
├── Backup-Citadel.ps1 # Backup/restore tooling
├── docker-compose.yml # Development deployment
├── docker-compose-production.yml # Production with TLS
├── SPEC.md # Wire format specification
├── THREAT_MODEL.md # Security goals and attacker model
├── COMPLIANCE_MATRIX.md # NIST 800-57 control mapping
└── CITADEL_OVERVIEW.md # Commercial overview
```
## 文档
| 文档 | 目标读者 |
|----------|----------|
| [SPEC.md](SPEC.md) | 传输格式规范 |
| [THREAT_MODEL.md](THREAT_MODEL.md) | 安全目标与假设 |
| [COMPLIANCE_MATRIX.md](COMPLIANCE_MATRIX.md) | NIST 800-57 合规性映射 |
| [CITADEL_OVERVIEW.md](CITADEL_OVERVIEW.md) | 商业定位 |
| [SECURITY.md](SECURITY.md) | 漏洞报告 |
| [API_FREEZE.md](API_FREEZE.md) | API 稳定性保证 |
| [DEPLOYMENT.md](DEPLOYMENT.md) | 生产环境部署指南 |
| [QUICKSTART.md](QUICKSTART.md) | 入门指南 |
## 许可证
本项目采用双重许可：
- **GNU Affero General Public License v3 (AGPL)** — 用于开源用途
- **商业许可证** — 用于专有或商业用途
如果你在商业环境中使用此软件，或不愿遵守 AGPL 条款，则必须获取商业许可证。
有关商业条款，请参阅 [COMMERCIAL_LICENSE.md](COMMERCIAL_LICENSE.md)。
AGPL 的全文见 [AGPL-3.0.txt](AGPL-3.0.txt) 和 [COPYING](COPYING)。
联系方式：commit@reposignal.io
## 作者
Andre Cordero — andre.cordero36@gmail.com
标签：KMS, REST API, Rust, 可视化界面, 后量子加密, 密码学, 手动系统调用, 数据加密, 网络流量审计, 请求拦截, 通知系统