Files
ssw-mpc/docs/ARCHITECTURE.md
T
admin e01c7f9419 docs: 按新定位重写中文描述,修复参考实现路径误改
- 中文定位从「Rust 重写 Python 算术执行引擎」改为「多方数据协同、数据不出域的安全计算框架」;README/CLAUDE/ARCHITECTURE/GAP_PLAN 同步,沿革小节写明新旧语义差别
- 修复机械替换引入的功能 bug:gen_golden.py / check_psi.py / bench_numpy.py 的 refs/mpc/mpc 路径改回 refs/nax/nax(参考实现真实目录,CI 不跑这些脚本故未暴露)
- 恢复 Python 参考实现包名 import nax;mpc-python 统一改称「Python 参考实现」;远端仓库描述同步
2026-11-05 15:17:28 +08:00

313 lines
16 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 架构
本文描述 ssw-mpc 的工程分层(多方安全计算能力的承载方式),回答三个问题:**分几层、Ray 放哪、TEE 干什么**。
每个结论后面都跟着"为什么不是另一种做法",因为选错这三件事的代价是重写。
---
## 1. 分层
```
┌──────────────────────────────────────────────────────────────┐
│ mpc-cli │
│ 单二进制入口:run / plan / audit / attest │
├──────────────────────────────────────────────────────────────┤
│ mpc-node │
│ 一方一个进程。承载:明文域(Site)、密文分片、会话、审计 │
│ 对外只有 mpc-proto 定义的帧;不暴露任何语言运行时 │
├──────────────────────────────────────────────────────────────┤
│ mpc-vault │
│ 协议编排:Beaver 乘 / 截断 / BitLT / sigmoid,含交互轮次 │
├──────────────────────────────────────────────────────────────┤
│ mpc-ml / mpc-sql ← 两个消费者,协议都走图 │
│ 纵向 LR 的一次迭代 / 掩码 WHERE + 聚合:建图 → 编译 → 执行 │
├──────────────────────────────────────────────────────────────┤
│ mpc-ir ← 编译期,运行期可不用 │
│ 算子图:Vis(公开/秘密)+ 定点尺度 k + 强制 Lift + base/end │
│ 产出「几轮往返」,本身不做密码学 │
├──────────────────────────────────────────────────────────────┤
│ mpc-core ← 已完成 │
│ 纯数据变换:u64 环算术、分享、PRG、SHA-256、比较的本地步骤 │
│ 零依赖 / no_std / 零分配 / 与 Python 版逐位一致 │
├──────────────────────────────────────────────────────────────┤
│ mpc-tee ← 交叉层 │
│ HAL:seal / unseal / attest / sign / device_key │
│ 实现:mock / optee / sev-snp / tdx │
└──────────────────────────────────────────────────────────────┘
```
**边界铁律**:`mpc-core` 里出现的每一个符号都必须能在 `no_std` + 无线程 +
无分配器 + 单核 armv7 的环境里跑。任何一个 `Vec`、`tokio`、`String` 混进来,
TEE 那条路就断了。这条规则靠 CI 守(`cargo build -p mpc-core --no-default-features`)。
`mpc-vault` 单独成层,是因为**交互不是算子**。Beaver 乘法要把
`d = x − a`、`e = y − b` 公开出去再拿回来;`open` 要过网络、过审计、
过 TEE 签名。把这些塞进算子核,等于让密码学库自己管 socket。
`mpc-ir` 在 `mpc-vault` **之上**、`mpc-cli` 之下,是唯一一层「不碰密码学」的:
它只回答「这份计算图里有几个算子必须过网络、能合并成几轮」。
不引它也能跑(`mpc-vault` 的调用序列可以手写),引它是为了让轮数可算、
让「公开值只能出现一次」从口头约束变成图里的一个节点。详见 `docs/IR.md`。
---
## 2. 为什么不是"每方一个 Ray Actor"
参考实现的 `RayBackend` 是这么干的:把 Python 函数当参数传给远端 Actor 执行。
```python
out = actor.run.options(num_returns=1).remote(fn, packed_args, packed_kwargs, *refs)
```
这条路径上有四个东西让它无法二进制化:
| 东西 | 问题 |
|---|---|
| `fn` 要序列化 | `cloudpickle` 要序列化**函数 + 闭包 + 它引用的所有模块**;无法预先静态确定 payload |
| `ray.get` 返回 Python 对象 | 对象所有权在 object store,driver 侧必须先拿到 Python 运行时 |
| Actor 生命周期由 GCS 管 | 要一个额外的协调服务进程组(GCS + raylet + dashboard) |
| 错误跨语言传播 | Ray 的异常是 Python 异常对象 |
**结论**:Ray 留在部署层,用它的调度能力,不用它的计算路径。
---
## 3. Ray 放在哪一层
Ray 真正不可替代的只有一条:**自定义资源把参与方钉在指定物理机**。
```bash
# 在 alice 的机器上
ray start --address=ray://head:10001 --resources='{"alice_node": 1}'
# 在 bob 的机器上
ray start --address=ray://head:10001 --resources='{"bob_node": 1}'
```
ssw-mpc 用它来**拉起 mpc-node 进程并保证落点**,计算走 mpc 自己的帧:
```yaml
# deploy/ray/mpc-cluster.yaml(骨架,见该目录)
entrypoint: |
mpc node --listen 0.0.0.0:9443 \
--site ${MPC_SITE} \
--session-key-file /run/secrets/mpc-session
```
对比一下两条路径的每次调用开销:
| | Ray Actor 调用 | mpc-node 帧 |
|---|---|---|
| 序列化 | cloudpickle(函数图,KB~MB) | 手写帧(payload 就是 u64 数组) |
| 传输 | object store(共享内存 / 网络) | 一次 TCP/gRPC 写 |
| 反序列化 | 要 Python 解释器 | memcpy |
| 失败模式 | Python 异常对象 | 错误码 |
如果将来确实需要 Ray 的自动扩缩 / dashboard,加一个 `--features ray` 的可选
后端即可(走 ray-cpp 绑定),**默认构建不含 Ray**。
---
## 4. TEE 干什么(以及不干什么)
### 4.1 一个必须先拆掉的误解
**TEE 不给 MPC 提速。** SGX/SEV/TDX 保护的是"数据在内存里不被宿主看到",
它不会让密文乘法变快 —— 密文乘法本来就不需要保护,分片是随机的。
TEE 补的是半诚实模型**最虚的两个环**:
| 缺口 | 现状(参考实现) | TEE 之后 |
|---|---|---|
| **输入一致性** | 假设各方老实输入自己的真实数据,无法验证 | 数据进 enclave → 算 commitment → enclave 签名。伪造输入 = 验签失败 |
| **出域策略强制** | `policy/guard.py` 是 Python 层检查,改代码就绕过 | `check_fetch` 在 enclave 内执行并签名,绕过即对不上审计链 |
这两个才是隐私计算真实事故的来源:不是密码学被攻破,而是
"某一方喂了假数据" 或 "某个运维把结果导出来了"。
### 4.2 分工:控制平面在 TEE,计算平面在 TEE 外
```text
TEE(enclave / TA) TEE 外(宿主 / 普通进程)
┌─────────────────────────┐ ┌──────────────────────────────┐
│ 设备绑定密钥 │ │ MPC 密文算子(mpc-core) │
│ seal / unseal │ │ 分片存储与传输 │
│ 输入 commitment + 签名 │ │ 网络、磁盘、调度 │
│ 出域策略判定 + 签名 │ │ Beaver 三元组生成(可放外面, │
│ attestation 报告 │ │ 因为物料与数据无关) │
│ 审计链锚点 │ │ │
└─────────────────────────┘ └──────────────────────────────┘
```
**为什么计算不放进 TEE**:enclave 内存有限(SGX 起步 128 MB,SEV 要看 VM 规格),
而 MPC 的中间态是 O(样本数 × 特征数) 的 u64 矩阵;加上 EPC 换页的开销,
把密文计算塞进 enclave 是负优化。TEE 只做"小、关键、必须可信"的事。
**为什么三元组可以放外面**:Beaver 三元组是与数据无关的随机物料,
泄露它不泄露任何输入。所以离线阶段可以完全在 TEE 外批量生成。
### 4.3 可信度梯度(这是关键设计)
不要做"全有或全无"的 TEE 方案 —— 现实里经常是一方有、一方没有。
ssw-mpc 定义四级,**同一套协议栈**,按参与方的 TEE 能力自动降级:
| Level | 条件 | 谁被保护 | MPC 的角色 |
|---|---|---|---|
| **L0** | 双方都无 TEE | 靠 MPC 数学保证 | 主力 |
| **L1** | 单方有 TEE | 有 TEE 那方的明文与策略被硬件保护 | 主力 |
| **L2** | 双方有 TEE + attestation 互验 | 双方都被保护 | **可退化为直算**:数据在 enclave 内合明文计算,MPC 只留审计与承诺 |
| **L3** | 双方有 TEE 但互不信任同一厂商 | 各自保护自己 | MPC 保底,TEE 保输入 |
**L2 是被低估的一条**:如果双方都能验证对方的 enclave 跑的是同一份已签名代码,
那"数据不出域"这个前提就已经满足了 —— 直接把明文合到一起算就是最优解,
MPC 的通信开销全部省掉。这时候 MPC 的作用退化成"可审计的承诺链"。
这条路径的取舍必须让客户明示选择,不能默认。协议栈里用 `TrustPlan` 表达:
```rust
pub enum TrustPlan {
MpcOnly, // L0
TeeAssisted { tee_sides: Vec<SiteId> }, // L1:**多个**方可以各自有 TEE
MutualAttested { min_tcb: TcbLevel }, // L2
TeePerParty, // L3
}
// n 方由「各方状况 + 客户策略」算出,而不是手工挑一个变体
TrustPlan::for_parties(&[PartyTee], TrustPolicy) -> Result<TrustPlan, TeeError>
```
上表用的是"双方"措辞,这是两方的说法。n 方时 **L2 的判据变严**:
要求**每一方**都 attest 通过,不是"有人在用 TEE"—— 因为明文合并之后,
那份明文对执行计算的那一方完全可见,只要有一个不受信方,全体数据就都在
它眼前。判据与证据见 [`N_PARTY.md`](N_PARTY.md#trustplan-在-n-方是什么)。
---
## 5. 平台路线:OP-TEE 先通,SNP/TDX 设计
### 5.1 为什么是这个顺序
| 平台 | 现状 | 能验证什么 | 能跑什么 |
|---|---|---|---|
| **OP-TEE**(Zynq-7015 / QEMU arm32) | ✅ 全链已验证(见 `../op-tee-test`) | 设备绑定密钥、密封存储、TA 签名验收 | 小规模 MPC + 控制平面 |
| **AMD SEV-SNP** | 需 EPYC 7003+ | 生产级 VM 级隔离 + 远程证明 | 控制 + 大算力计算 |
| **Intel TDX** | 需 SPR+ | 同上 | 同上 |
| **海光 CSV** | 国产化项目常要求 | x86 兼容路线 | 同上 |
Zynq-7015 是**双核 Cortex-A9 @ 667 MHz**,没有可用的 64 位整数 SIMD。
但"没有 SIMD"不等于"跑不了"——实测折算下来它比 i5 慢 8–12×,
而不是 50×:
| 负载 | i5 实测 | A9 估算 |
|---|---|---|
| `matmul` 64³ | 0.26 ms | ~2.5 ms |
| `matmul` 128³ | 2.2 ms | ~22 ms |
| 纵向 LR 400×7 × 40 轮 | ~15 ms | ~150 ms |
| PSI 1 万条 | — | ~8–15 s |
所以定位是:**小规模、安全优先、时间不敏感的场景直接在板上跑**;
规模上去(大矩阵密文训练、10 万级 PSI)再横扩到 x86 + SNP。
完整预算与部署形态见 [`docs/ZYNQ.md`](ZYNQ.md)。
**两档用同一份二进制、同一套协议**,差别只在 `TrustPlan` 与规模配置。
### 5.2 复用 `op-tee-test` 的什么
| 复用 | 说明 |
|---|---|
| `syvault-core` 的范式 | no_std + 宿主可测 + TA 只做参数搬运 |
| HKDF 派生 + AES-GCM 密封 | 直接搬进 `mpc-tee/src/optee/` |
| TA 签名公钥进 `tee.bin` | 默认密钥签的 TA 被拒 —— 这条验收标准要保留 |
| `build/p0_qemu_arm32.sh` | QEMU arm32 一键全链,改动最小 |
| 设备 DNA 绑定 | Zynq SLCR 读 DNA,模拟环境用编译期种子 |
**不要做的**:把 MPC 算子搬进 TA。TA 里只跑
`seal/unseal/sign/verify/derive_key` 这几个入口,每个入口的数据量都是 KB 级。
### 5.3 SNP/TDX 的接口设计(先设计后实现)
`mpc-tee` 的 trait 按 SNP 的 attestation 报告格式设计,这样 x86 实现落地时
不用改上层:
```rust
pub trait Tee {
/// 平台身份(厂商 + 版本),用于 L2 的 min_tcb 判定
fn platform(&self) -> Platform;
/// 密封:输出密文 + 绑定到当前平台的 AAD
fn seal(&self, plaintext: &[u8], aad: &[u8]) -> Result<SealedBlob>;
/// 解封:只能在本平台/本 VM 解开
fn unseal(&self, blob: &SealedBlob) -> Result<Vec<u8>>;
/// 远程证明:产出可被对端验证的报告(SNP: REPORT + VCEK 证书链)
fn attest(&self, user_data: &[u8; 64]) -> Result<Attestation>;
/// 用设备密钥对策略判定结果签名
fn sign(&self, msg: &[u8]) -> Result<Signature>;
}
```
关键点:`attest` 的 `user_data` 是 **64 字节定长**,因为 SNP 的
`report_data` 就是 64 字节。这样上层把 "会话公钥 hash + 代码度量 hash"
塞进去,对端用 `verify(报告, 期望度量)` 就能确认"对面跑的确实是这份二进制"。
---
## 6. 协议栈要点(从参考实现继承什么)
保留:
- **Site / Vault / SecretRef 三层**:明文域、安全域、分片引用分离,是对的。
- **三个出域关口**:`check_exec` / `check_transfer` / `check_fetch`,
每一处留审计。这是把"不会泄露"从纪律变成类型约束的关键。
- **受限 SQL 的拒绝语义**:`SELECT *`、裸机密列、未声明取值域的 GROUP BY 一律报错。
**拒绝比支持更重要**。
- **原始 0/1 位 vs 定点尺度**分开:比较结果在原始位上游走,`select`/`and`/`or`
全程不吃截断误差。
改动:
| 项 | 参考实现 | ssw-mpc | 理由 |
|---|---|---|---|
| 跨方传函数 | cloudpickle | 预定义 opcode + 数据帧 | 二进制化的前提 |
| `dry_run` | contextvars 切换 | 显式 `TrustPlan` / `Mode` 参数 | 隐式全局状态在异步/多会话下会串 |
| 审计日志 | Python 对象,进程内 | 追加写 + TEE 签名链 | 否则审计可被篡改 |
| 大数运算 | 纯 Python int | Rust 定长大数(Montgomery) | Paillier 28 ms → 目标 0.1 ms |
| 曲线 | 纯 Python 手写 | curve25519(或自写 fe 运算) | X25519 3.16 ms → 目标 60 μs |
---
## 7. 路线图
| 阶段 | 内容 | 验收 |
|---|---|---|
| **P0(已完成)** | `mpc-core` 算子核 | 37 单测 + 215 逐位对照 + 基准可复现 |
| **P1(骨架已完成)** | `mpc-proto` 帧 + `mpc-vault` 协议编排 + `mpc-node` TCP | ✅ 两进程经真实 TCP 跑出正确结果(见下) |
| **P1.5(已完成)** | PSI(X25519 ECDH-PSI) | ✅ 两进程实测交集正确 + 与参考实现语义对照 |
| **P1.6** | n 方(>2)分片分发 | 需要先定拓扑(mesh / star),见下 |
| **P2** | `mpc-cli` 纵向 LR 端到端 | 训练 AUC 与参考实现一致 |
| **P3** | `mpc-tee` 的 OP-TEE 实现 | QEMU arm32 里 `seal/unseal/attest` 全通 |
| **P4** | 大数(Paillier)+ 曲线(X25519) | Paillier ≤ 0.2 ms/元素,X25519 ≤ 80 μs |
| **P5** | Ray 部署编排 + k8s | `ray job submit` 拉起两方集群 |
| **P6** | SNP/TDX 后端 | 有硬件时验证远程证明 |
**P1.5 的验收证据**(PSI,两个独立进程):
```bash
mpc psi --site bob --sites alice,bob --listen 127.0.0.1:9445 --ids 3,4,5,6,7
mpc psi --site alice --sites alice,bob --connect 127.0.0.1:9445 --ids 1,2,3,4,5
# 双方各自输出:交集 3 条: 3,4,5
```
**P1 的验收证据**(2026-10-29 实测,两个独立进程):
```bash
mpc node --site bob --sites alice,bob --listen 127.0.0.1:9444 --data 4,5,6
mpc node --site alice --sites alice,bob --connect 127.0.0.1:9444 --data 1,2,3
# 双方各自输出:会话结果: 35
```
`35 = (1·4+1) + (2·5+1) + (3·6+1)`。整个过程走了
**分片交换 → Beaver 乘(2 次 open)→ 定点截断(1 次 open)→ 求和 → 还原(1 次 open)**,
协议栈的每一层都被穿过一次。