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

16 KiB
Raw Permalink Blame History

架构

本文描述 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 执行。

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 真正不可替代的只有一条:自定义资源把参与方钉在指定物理机。

# 在 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 自己的帧:

# 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 外

        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 表达:

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。


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。

两档用同一份二进制、同一套协议,差别只在 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 实现落地时 不用改上层:

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,两个独立进程):

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 实测,两个独立进程):

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), 协议栈的每一层都被穿过一次。