Files
ssw-mpc/docs/ARCHITECTURE.md
T
ssw c5b2cf69a5 feat: nax-rs P0/P1/P1.5 —— Rust 重写隐私计算框架
算子核(nax-core):零依赖 no_std
- Z_2^64 定点算术 + AVX2 矩阵乘,与 Python 参考实现 215 条逐位一致
- 加性分享 / Beaver 三元组 / 截断对 / edaBit,ChaCha20 PRG,SHA-256
- 自实现银行家舍入(f64::round_ties_even 是 std-only,no_std 编不过)

协议栈
- nax-proto:手写帧协议(12 字节头 + u64 payload),无 protobuf 依赖
- nax-vault:Beaver 乘 / 定点截断 / open / reveal
- nax-node:TCP 传输 + 密文会话 + PSI 会话
- nax-psi:X25519 ECDH-PSI(唯一外部依赖 dalek,因恒定时间约束)
- nax-tee:HAL trait(seal/unseal/attest/sign)+ Mock + TrustPlan 四级降级

验收
- 83 用例全绿;armv7 全 workspace 编译通过
- 两进程密文计算:(1·4+1)+(2·5+1)+(3·6+1) = 35
- 两进程 PSI:[1..5] ∩ [3..7] = {3,4,5}
- 单二进制 450 KB,零运行时依赖

文档
- docs/ARCHITECTURE.md:分层、Ray 定位、TEE 分工与降级梯度
- docs/ZYNQ.md:A9 性能预算(比 i5 慢 8-12x,非 50x)与部署形态
2026-10-29 11:10:54 +08:00

293 lines
14 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.
# 架构
本文回答三个问题:**分几层、Ray 放哪、TEE 干什么**。
每个结论后面都跟着"为什么不是另一种做法",因为选错这三件事的代价是重写。
---
## 1. 分层
```
┌──────────────────────────────────────────────────────────────┐
│ nax-cli │
│ 单二进制入口:run / plan / audit / attest │
├──────────────────────────────────────────────────────────────┤
│ nax-node │
│ 一方一个进程。承载:明文域(Site)、密文分片、会话、审计 │
│ 对外只有 nax-proto 定义的帧;不暴露任何语言运行时 │
├──────────────────────────────────────────────────────────────┤
│ nax-vault(待建) │
│ 协议编排:Beaver 乘 / 截断 / BitLT / sigmoid,含交互轮次 │
├──────────────────────────────────────────────────────────────┤
│ nax-core ← 已完成 │
│ 纯数据变换:u64 环算术、分享、PRG、SHA-256、比较的本地步骤 │
│ 零依赖 / no_std / 零分配 / 与 Python 版逐位一致 │
├──────────────────────────────────────────────────────────────┤
│ nax-tee ← 交叉层 │
│ HAL:seal / unseal / attest / sign / device_key │
│ 实现:mock / optee / sev-snp / tdx │
└──────────────────────────────────────────────────────────────┘
```
**边界铁律**:`nax-core` 里出现的每一个符号都必须能在 `no_std` + 无线程 +
无分配器 + 单核 armv7 的环境里跑。任何一个 `Vec`、`tokio`、`String` 混进来,
TEE 那条路就断了。这条规则靠 CI 守(`cargo build -p nax-core --no-default-features`)。
`nax-vault` 单独成层,是因为**交互不是算子**。Beaver 乘法要把
`d = x − a`、`e = y − b` 公开出去再拿回来;`open` 要过网络、过审计、
过 TEE 签名。把这些塞进算子核,等于让密码学库自己管 socket。
---
## 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}'
```
nax-rs 用它来**拉起 nax-node 进程并保证落点**,计算走 nax 自己的帧:
```yaml
# deploy/ray/nax-cluster.yaml(骨架,见该目录)
entrypoint: |
nax node --listen 0.0.0.0:9443 \
--site ${NAX_SITE} \
--session-key-file /run/secrets/nax-session
```
对比一下两条路径的每次调用开销:
| | Ray Actor 调用 | nax-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 密文算子(nax-core) │
│ seal / unseal │ │ 分片存储与传输 │
│ 输入 commitment + 签名 │ │ 网络、磁盘、调度 │
│ 出域策略判定 + 签名 │ │ Beaver 三元组生成(可放外面, │
│ attestation 报告 │ │ 因为物料与数据无关) │
│ 审计链锚点 │ │ │
└─────────────────────────┘ └──────────────────────────────┘
```
**为什么计算不放进 TEE**:enclave 内存有限(SGX 起步 128 MB,SEV 要看 VM 规格),
而 MPC 的中间态是 O(样本数 × 特征数) 的 u64 矩阵;加上 EPC 换页的开销,
把密文计算塞进 enclave 是负优化。TEE 只做"小、关键、必须可信"的事。
**为什么三元组可以放外面**:Beaver 三元组是与数据无关的随机物料,
泄露它不泄露任何输入。所以离线阶段可以完全在 TEE 外批量生成。
### 4.3 可信度梯度(这是关键设计)
不要做"全有或全无"的 TEE 方案 —— 现实里经常是一方有、一方没有。
nax-rs 定义四级,**同一套协议栈**,按参与方的 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_side: SiteId }, // L1
MutualAttested { min_tcb: TcbLevel }, // L2
TeePerParty, // L3
}
```
---
## 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 密封 | 直接搬进 `nax-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 的接口设计(先设计后实现)
`nax-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`
全程不吃截断误差。
改动:
| 项 | 参考实现 | nax-rs | 理由 |
|---|---|---|---|
| 跨方传函数 | 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(已完成)** | `nax-core` 算子核 | 37 单测 + 215 逐位对照 + 基准可复现 |
| **P1(骨架已完成)** | `nax-proto` 帧 + `nax-vault` 协议编排 + `nax-node` TCP | ✅ 两进程经真实 TCP 跑出正确结果(见下) |
| **P1.5(已完成)** | PSI(X25519 ECDH-PSI) | ✅ 两进程实测交集正确 + 与参考实现语义对照 |
| **P1.6** | n 方(>2)分片分发 | 需要先定拓扑(mesh / star),见下 |
| **P2** | `nax-cli` 纵向 LR 端到端 | 训练 AUC 与参考实现一致 |
| **P3** | `nax-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
nax psi --site bob --sites alice,bob --listen 127.0.0.1:9445 --ids 3,4,5,6,7
nax 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
nax node --site bob --sites alice,bob --listen 127.0.0.1:9444 --data 4,5,6
nax 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)**,
协议栈的每一层都被穿过一次。