Files
ssw-mpc/README.md
T
admin 49b421c23a feat(examples): 新增 mpc-examples,12 个场景对齐 nax/examples
- 新 workspace 成员 examples/(crate mpc-examples,publish = false):一场景一 bin,
  跑法 cargo run -p mpc-examples --bin 03_vertical_lr;src/lib.rs 只提供参与方启动、
  定点编解码、输出与断言,算法全在正文,调的是 mpc-* 真接口
- 12 个场景:01 密文四则/矩阵/sigmoid、02 PSI、03 纵向 LR、04 FedAvg、05 出域策略、
  06 DP-FedAvg、07 密文推理、08 PIR、09 SCQL、10 分箱 WOE/IV、11 试跑、12 两方部署
- 12 的部署物在 examples/12_k8s_two_party/:多阶段 Dockerfile + namespace /
  alice(Headless Service + Job,--listen)/ bob(Job,--connect)+ README;
  单二进制一条 TCP,不经 Ray,调度交给 k8s
- tools/ci.sh 加第 4 关「示例冒烟」,调新增的 tools/examples.sh:逐 bin 跑,
  判据为退出码 0 且输出无 [!!](check() 只打印不中断,只看退出码会漏断言)
- 正文记录三条实测契约:matmul_trunc 两入参都须是分片,否则结果翻倍;
  sigmoid_poly 只在 ±6 内有效,越界发散到 1e6;多项式输出须先 reveal 再解码
- 实测:07 密文与明文偏差 1.97e-5 且 AUC 一致;09 密态与明文逐组一致;
  11 同为 4 组 GROUP BY,逐组比较 156 轮 vs 整数码 23 轮
2026-11-05 20:55:07 +08:00

479 lines
29 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(尚数网-多方安全计算 / Secure Multi-Party Computation)
面向多方数据协同的安全计算框架:各方原始数据不出域,以秘密分享、隐私求交、同态加密和 TEE 可信根参与联合查询与建模,框架负责协议编排、轮次规划与出域审计。Rust 实现,单二进制、低依赖、可编进 TEE。
参考实现(Python/numpy/Ray)在 `refs/nax/`(独立只读仓库,目录名沿用前身、未随本次改名),只作为**行为基线与性能对照组**,不参与构建。
## 命名沿革与兼容约定
前身 `nax-rs`(N-arty Arithmetic eXecution,N 方算术执行引擎),2026-11-05 改名为 `ssw-mpc`:
18 个 crate 与目录统一 `mpc-*`、主二进制 `mpc`、环境变量 `MPC_*`。
**定位同时变了**:旧名描述的是「把 Python 参考实现的算术执行引擎用 Rust 重写」;
新名「尚数网-多方安全计算」描述的是多方数据协作场景下的安全计算能力 ——
数据不出域、以密态参与运算,Python 参考实现退为行为基线,不再是复刻目标。
改名前基线 tag `nax-rs-final`,改名提交 tag `ssw-mpc-rename`,CI 全绿首版 tag `ssw-mpc-v0.1.0`。
### 协议域分隔常量:已全量切换(不兼容变更)
2026-11-05 把 `nax/...`、`nax-psi-v1`、`nax-v1/derive` 等全部换成 `mpc` 前缀,
并**集中到 `mpc-core::domain`**(唯一真相源,业务代码不再写裸字符串;改动纪律见该模块文档)。
这些标签参与会话密钥、TEE 封存密钥、PSI 盲化点、缓存指纹与分片随机流的派生,
**改一个字节就等于换钥**,因此:
- 新旧版本**混跑会静默出错**(交集变空 / AEAD 解不开 / 分片和不回去),不会干净报错 ——
所有参与方必须同时升级,不能灰度。
- 已 provision 的 TEE 板子:`K_root` 对象名与派生密钥都变了,需重新 provision,旧 blob 作废。
- PSI 缓存指纹变了,旧表按设计自动作废;跨版本复用的离线物料 / 分片需全量重生成。
- 不提供旧 `nax` 标签的兼容读取 —— 双读只会让「这次到底走哪套」变成新的混乱源。
- golden 向量(ring / paillier / zkp)是纯数学,**不依赖**这些标签,无需重生成;
`check_psi.py` 只比交集语义,也不受影响。
### 仍保留的 `nax`(不要顺手清理)
| 类别 | 例子 | 原因 |
|---|---|---|
| 参考实现路径与包名 | `refs/nax/nax/...`、`import nax` | 独立只读仓库的真实目录与 Python 包名(`.gitignore` 已排除);`gen_golden.py` / `check_psi.py` / `bench_numpy.py` 按此路径加载,改了 golden 向量就生成不出来 |
| 沿革说明里的历史名 | `nax-rs`、`nax-rs-final`、`NAX_*` | 记录迁移来源,不是现行标识 |
部署迁移:`NAX_*` → `MPC_*`、`libnax_ray.so` → `libmpc_ray.so`、远端 `ssw/nax-rs.git` → `ssw/ssw-mpc.git`。
---
## 定位与形态
ssw-mpc 解决的是**互不信任的多方如何一起算**:数据留在各自域内,以分片、盲化或密文参与运算,
框架负责协议编排(`mpc-vault`)、轮次规划(`mpc-ir`)、隐私求交(`mpc-psi`)、
受限 SQL(`mpc-sql`)与联邦建模(`mpc-ml` / `mpc-fl`),并以 TEE 提供设备可信根与出域审计。
与 Python 参考实现的形态差异:
| | 参考实现 `refs/nax` | 本仓库 `ssw-mpc` |
|---|---|---|
| 运行时 | Python 3 + numpy + pandas + (Ray) | **无**(静态链接单二进制) |
| 部署形态 | `pip install` + 解释器 | `mpc` 一个文件,`scp` 上去就能跑 |
| 算子层 | numpy u64(BLAS 帮不上) | Rust 手写环算术 + AVX2 |
| 集群 | Ray Actor(cloudpickle 序列化函数) | 自研 TCP 帧 + `mpc-orch`(661 行纯 std);Ray 可选做**成员与放置** |
| TEE | 无 | `mpc-tee` HAL,OP-TEE 已验证范式可直接复用 |
| 依赖树 | numpy / pandas / ray | **mpc-core 零依赖** |
---
## 现状(2026-10-30)
| 模块 | 状态 |
|---|---|
| `mpc-core` 算子核 | ✅ 零依赖 `no_std`,37 单测 + 215 条 Python 逐位对照全绿 |
| `mpc-proto` 帧协议 | ✅ 手写编解码,11 单测(含粘包/半包/恶意长度) |
| `mpc-vault` 协议编排 | ✅ Beaver 乘 + 定点截断 + open/reveal + **批量路径**(`mul_batch` / `truncate_batch` / `bit_lt_batch`:k 个乘 1 个往返,k 次比较 9 轮封顶);安全比较(edaBit + BitLT + msb)+ 原始 0/1 位代数(lt/eq/and/or/xor/mask/select),30 单测(含 64 组随机化对拍、批量与逐次的逐位一致);**n 方(n=3)算子全覆盖**:open / 乘 / 截断 / 矩阵乘 / 比较,见 `docs/N_PARTY.md` |
| `mpc-node` TCP 会话 | ✅ 网状 n 方 + 两方便捷路径,7 单测(真实 TCP,含**三方端到端 + PSK 加密链路**、**三方 PSI 与"无公共元素"反例**、10 万元素粘包) |
| `mpc-psi` 隐私求交 | ✅ X25519 ECDH-PSI,**n 方环协议**(n=2 退化为两轮交换、开销不变),21 单测(含 RFC 7748 向量、1 万条求交、两两求交≠n 方求交的反例)+ **抗恶意硬化**(低阶点拒绝 / 点集自检 / 会话绑定 domain,8 测) |
| `mpc-zkp` 零知识证明 | ✅ Schnorr 身份证明 + Pedersen 承诺/表示证明,逐位 golden(5 测,含篡改必败) |
| `mpc-fl` 联邦聚合 + DP + FedAvg | ✅ 安全聚合责任链(Clip/Zero/SecureSum/Mean/GaussianNoise)+ 差分隐私(RDP 记账)+ 横向 FedAvg(local_train/metrics/加权均值/收敛轨迹),12 测含 4 逐位 golden;`--features secure` 另有 2 方 Vault 密态加权均值端到端 1 测 |
| `mpc-ml` 纵向 LR + MLP + 分箱 | ✅ sigmoid 奇多项式 + Beaver SGD(明文对照 >0.95);MLP 4 测;异构分箱 + WOE/IV + 互补抑制 6 测;密文 `Mᵀ@y` 箱计数 1 测 |
| `mpc-data` 数据层 | ✅ Frame(选择/矩阵/列和)+ 明文统计(均值/方差/协方差/相关)+ mock(确定性主键/schema 合成/DP)+ CSV,16 测 |
| `mpc-sql` SCQL 引擎 | ✅ 手写解析器 + 掩码式 WHERE + 聚合/GROUP BY/k-匿名/投影约束/JOIN/HAVING/ORDER BY,15 测;`--features secure` 另有密态 WHERE/复合谓词(AND/OR/NOT)/IN/**列 vs 列**/GROUP BY/k-匿名 9 测 + **JOIN×PSI 端到端 6 测**(PSI → 按键字节序对齐 → 密态聚合,对拍明文 JOIN)+ **n 方竖向列交换 2 测** + **迁移对拍 6 测**(手写协议序列留作 oracle:`COUNT`/`SUM`/`MIN`/`MAX` 逐位相同、轮数不增)+ **整数分组码 12 测**(前缀和路径与逐组比较对拍、越界/非整数码契约、8 组 162→92 轮)。协议序列已改由 `mpc-ir` 编译,`mpc sql-plan` 可查轮数 |
| `mpc-policy` 策略/审计 | ✅ 出域守卫(exec/transfer/fetch)+ Label 六档 + 审计日志(过滤/汇总/裁剪),9 测 |
| `mpc-runtime` 执行模式 | ✅ dry_run / real_run(线程局部 + RAII 嵌套恢复),4 测 |
| `mpc-ir` 算子图与轮次规划 | ✅ `Vis`(公开/秘密)与**定点尺度 `k`** 都挂在值上 + 强制 `Lift` 节点 + `base/end` 排程 + **同阶段同类批量**(乘 / 截断 / open / 比较各自合成一个往返);`mpc plan` / `mpc sql-plan` 可查。39 测含**两方真 Vault 端到端**、调用序验证、`cmp` 轮数实测(`CMP_ROUNDS=9`),见 `docs/IR.md` |
| `mpc-he` Paillier/OLE | ✅ 无可信发牌方 Beaver 物料 + PIR,50 条 Python 逐位对照 + 13 语义测试 |
| `mpc-tee` HAL | ✅ trait + Mock 实现;`TrustPlan` 是 **n 方计算函数**(`for_parties` + `TrustPolicy`,L0–L3),`mpc trust` 可查;OP-TEE 待接 |
| `mpc-cli` | ✅ 单二进制,`selftest` / `trust` / `plan` / `node` / `psi` / `lr` / `lr-vertical` / `fl` 子命令;`--features secure` 另加 `mpc sql`(in-process)、`mpc sql-plan`(把聚合查询编成计划报轮数,不联网不需要数据;`--group-mode coded` 走整数码前缀和,8 组 13→12 轮)与 `mpc sql-join`(真 TCP 两进程 JOIN×PSI×密态 SQL) |
| `mpc-orch` 编排 | ✅ 661 行纯 std,PLAN 协议 + 两阶段提交,7 单测;本机三进程跑通 |
| `mpc-ray` Ray C++ 内核 | ✅ 链接 `_raylet.so` 接入真实集群(拿到 raylet 分配的 node id),见 `docs/RAY_CORE.md` |
| Ray 1.0.1 跨架构 | ✅ x86_64 原生 + armv7(qemu) 同集群,两端各自注册成 driver,跨架构 MPC 结果一致,见 `docs/RAY_CORE_101.md` |
| armv7 交叉编译 | ✅ **真出二进制**:musl 静态 687 KB,`file` 显示 `ARM, EABI5, statically linked` |
```bash
cargo test --workspace --features secure # 471 用例(含 n 方:vault 三方算子 / 真 TCP 三方会话与 PSI / 列交换 / 纵向 LR;mpc-ir 39 条含两方真 Vault 端到端;mpc-sql 的 coded 12 条对拍整数分组码 + MIN/MAX 树形归约 2 条;mpc-vault 的批量路径 4 条(乘/比较的往返数与逐位一致))
cargo test -p mpc-sql --features secure # 52 用例(含 JOIN×PSI 端到端 + 列 vs 列 + n 方列交换 + 迁移对拍 + 整数分组码对拍)
cargo build --release -p mpc-cli && ./target/release/mpc selftest
cargo check --workspace --target armv7-unknown-linux-gnueabihf
```
### 交叉编译到 Zynq(armv7,任意宿主都能出)
```bash
rustup target add armv7-unknown-linux-musleabihf
cargo build --release -p mpc-cli --target armv7-unknown-linux-musleabihf
# -> 687 KB 静态 ARM EABI5 hard-float,拷到板上直接跑,不绑 glibc 版本
# 链接器走 rust-lld + link-self-contained,无需外部交叉 gcc(见 .cargo/config.toml)
```
### P1 验收:两个进程经真实 TCP 算出结果
```bash
# 终端 1
mpc node --site bob --sites alice,bob --listen 127.0.0.1:9444 --data 4,5,6
# 终端 2
mpc node --site alice --sites alice,bob --connect 127.0.0.1:9444 --data 1,2,3
```
两侧都输出 `会话结果: 35` —— `(1·4+1)+(2·5+1)+(3·6+1)`。
链路上跑的是分片,走完 **Beaver 乘(2 次 open)→ 定点截断(1 次)→ 求和 → 还原(1 次)**。
```
mpc node · site=alice · 127.0.0.1:9444 · 3 个元素 · fxp=18
本方 alice 是 0 号,持有 3 个元素
分片交换完成
密文乘法完成(2 次 open)
还原完成: [9175040]
会话结果: 35
```
### P1.2 验收:n 方(3 方 / 4 方)网状直连
两方之外每一方都要能和所有其他人说话,`open` 从"发一个对端"变成"广播给 n−1 方"。
```bash
P="alice=127.0.0.1:9450,bob=127.0.0.1:9451,carol=127.0.0.1:9452"
S="alice,bob,carol"
mpc node --site alice --sites $S --listen 127.0.0.1:9450 --peers "$P" --data 2 &
mpc node --site bob --sites $S --listen 127.0.0.1:9451 --peers "$P" --data 3 &
mpc node --site carol --sites $S --listen 127.0.0.1:9452 --peers "$P" --data 5
# 三方都输出 31 = 2·3·5 + 1
```
或用编排脚本(同一套计划,本地/Ray 两种后端):
```bash
python3 deploy/ray/mpc_cluster.py --sites alice,bob,carol \
--data alice=2,bob=3,carol=5 --mpc ./target/release/mpc --local
```
**拓扑必须是全网状,不能星型。** 星型让 head 转发 `Shares` 帧,而帧里是
真实输入分片 —— 转发一次就等于把一方的输入读给中转节点看了。
n 是参与方个数(跨机构,个位数),`n(n−1)/2` 条直连不是瓶颈。
**建连规则:小编号连大编号。** 对每一对 `(i, j)` 且 `i < j`,由 `i` 主动
connect `j`,`j` 等着 accept。每对恰好一条连接,不会出现两条背向连接
互相等消息。accept 方拿到连接时不知道对方是谁(对端可以任意顺序连上来),
所以连上后立刻交换 4 字节 party 下标做身份握手。
**排序是协议的一部分。** 参与方按字典序编号,第 p 片分片投递给"排序后第 p 个"。
端口分配、peers 字符串、`--sites` 顺序都必须用同一个排序 ——
换了顺序各方对 party 编号的理解就不一致,分片投错对象,
**结果静默算错**:不崩、不报错,就是数不对。
n 方乘是链式的(每方按同一 party 顺序做 n−1 次两方 Beaver 乘):
```text
z = x₀ · x₁ · … · xₙ₋₁, 每一轮 1 次 Beaver 乘(2 次 open)+ 1 次截断
```
运营商离线物料、`d·e` 只落 0 号、截断的公开值 `cs` 只由 0 号持有 ——
这三条规则在 n 方下不变,也正是 n 方正确的原因:`Σzᵢ = (a+d)(b+e) = x·y`
对任意 n 成立。
### P1.5 验收:PSI(两方与 n 方)
```bash
# 终端 1
mpc psi --site bob --sites alice,bob --listen 127.0.0.1:9445 --ids 3,4,5,6,7
# 终端 2
mpc psi --site alice --sites alice,bob --connect 127.0.0.1:9445 --ids 1,2,3,4,5
```
两侧都输出 `交集 3 条: 3,4,5`。网络上流动的全是 X25519 曲线点,
反推 ID 等价于解离散对数;每轮发送前洗牌,切断"位置 ↔ 原始记录"的对应。
n 方用同一条命令加 `--peers`(网状拓扑)。协议是**环协议**:集合沿环走
n−1 跳,每跳被当前持有者用自己的密钥再幂一次,最后汇总广播 —— 这样
每个 ID 都经过全部 n 把密钥,得到可比较的指纹:
```bash
S=alice,bob,carol
P=alice=127.0.0.1:9450,bob=127.0.0.1:9451,carol=127.0.0.1:9452
mpc psi --site alice --sites $S --listen 127.0.0.1:9450 --peers $P --ids 1,2,3,4,5 &
mpc psi --site bob --sites $S --listen 127.0.0.1:9451 --peers $P --ids 3,4,5,6,7 &
mpc psi --site carol --sites $S --listen 127.0.0.1:9452 --peers $P --ids 4,5,6,7,8
```
三方都输出 `4,5`。**不能拿两两求交拼**:两两会给出 `3,4,5,6,7`(多出只在
某两方共有的元素)。n=2 时环协议退化为原来的两轮交换,开销逐项不变。
与 Python 参考实现的语义对照:`.venv/bin/python tools/check_psi.py` → `PASS`。
> 唯一的例外依赖:`mpc-psi` 引了 `curve25519-dalek`。
> 理由不是省事 —— 手写 X25519 **做不到恒定时间**,按比特分支的 ladder
> 会被时序侧信道把私钥一位位读走。参考实现的 Python 版自己在注释里承认
> 非常数时间。这种地方"自己造"是埋一个测试永远抓不到的洞。
### JOIN × PSI 验收:密态 SQL 的纵向对齐
两方各持半张表(alice: `id, balance`;bob: `uid, spend, region`),
跑 `SELECT COUNT(*), SUM(balance), SUM(spend) FROM bank JOIN shop ON bank.id = shop.uid`:
```text
PSI(mpc-node::run_psi_session)→ 本方交集下标(本地行序升序)
→ 按键字节序重排 ← 两方唯一能共享的全序
→ 各列切分片并交换(mpc-sql::secure::exchange_split_columns)
→ 掩码 WHERE / 聚合 / GROUP BY → reveal
```
**PSI 不给共享顺序,这就是坑的全部。** 它只回答"本方哪几条在交集里",
下标按本地行序;而纵向聚合要求两方第 i 行是同一个人。所以两边必须按同一个
全序重排 —— 不排就是行错位,结果不崩、不报错,就是数不对
(测试里把排序删掉:`WHERE balance >= 250 AND spend < 40` 的 COUNT 立刻从 1 变 2)。
`cargo test -p mpc-sql --features secure` 里 6 测对拍明文 `Engine` 的等价 JOIN
(COUNT/SUM、跨方复合 WHERE、GROUP BY)。`mpc-sql` 的**库**依赖里没有
`mpc-node`/`mpc-psi`:PSI 与对齐属于调用方,SQL 层只吃"已对齐的分片"。
密态 WHERE 还支持**列 vs 列**(`WHERE balance > spend`),走 `Pred::CmpCol` ——
右值是密文分片不过 `vault.constant`,开销与列 vs 常量相同。
`mpc sql-join` 子命令(`--features secure`)走真 TCP 两进程跑完整链路,
`--schema` 约定全局列序(竖向切分里两方各持不同列,按槽位落位而非简单拼接)。
### P2 验收:两进程纵向 LR
```bash
# 终端 1(特征已标准化到 ±1)
mpc lr --site bob --sites alice,bob --listen 127.0.0.1:9448 \
--data-x -1,-1,0,0,1,1 --data-y 0,1,0 --n 3 --d 2 --epochs 20
# 终端 2
mpc lr --site alice --sites alice,bob --connect 127.0.0.1:9448 \
--data-x -1,-1,0,0,1,1 --data-y 0,1,0 --n 3 --d 2 --epochs 20
```
两侧输出一致:`w = [0.000008, 0.000000, 0.659542]`。
全程密文(特征、标签、梯度、权重都是加性分片),只有最后 `reveal` 那一步出域。
**纵向 LR 已接 PSI 对齐**(`run_lr_vertical_session`),并且是 **n 方**:
各方各持不同客户名单、不同特征列,先 `align_by_key` 求交排序对齐,
再按**列块清单**(`alice:0:1,bob:1:1,carol:2:1`)广播分片、0 分片拼接,
最后密态训练。8 测,其中两条做过变异检验(列块落点、标签累加)。
```bash
# 三方,各方持 1 列,标签由 bob 提供
mpc lr-vertical --site alice --sites alice,bob,carol \
--listen 127.0.0.1:39301 \
--peers alice=127.0.0.1:39301,bob=127.0.0.1:39311,carol=127.0.0.1:39321 \
--col-blocks alice:0:1,bob:1:1,carol:2:1 --label-owner bob \
--data-ids 7,2,4,1,8,3,9,5 --data-x 0,-0.75,-0.25,-1,0.75,-0.5,1,0
```
实测:同一份全局特征矩阵,切成 1+2(两方)与 1+1+1(三方)训练出的权重
**逐位相同** —— 纵向切分方式不影响结果,这正是它应该的样子。
- `mpc-ml`:sigmoid 奇多项式逼近(与参考实现 `SIGMOID_FITS` 逐位一致)+ SGD 训练循环
- 每轮 2 次矩阵 Beaver 乘 + 1 次 sigmoid 逼近(5 次 mul_trunc + 2 次 truncate)
- 明文对照测试:密文权重与精确 sigmoid 明文训练的相关系数 > 0.95
**499 KB** 这个数字要和参考实现放一起看:Python 版需要 Python 3.13 +
numpy(~20 MB)+ pandas + ray(装完 GB 级)。这不是"更小",是"能不能交付"的区别。
### Zynq-7015
已在 `docs/ZYNQ.md` 给出性能预算与部署路径:A9 比 i5 慢 **8–12×**(不是 50×),
所以 `matmul 64³ ≈ 2.5 ms`、纵向 LR 400×7×40 轮 ≈ 150 ms、PSI 1 万条 ≈ 8–15 s,
**小规模场景完全可以在板上跑**。大矩阵密文训练再横扩 x86 + SNP。
### P4 验收:无可信发牌方的 Beaver 物料(HE-OLE)
`mpc-core::share::Dealer` 是半诚实可信第三方 —— 它只要记下发出的 `a`,
对照在线阶段公开的 `d = x - a` 就能还原任何输入。`mpc-he` 用 Paillier
加法同态跑 OLE 把这个假设**整个删掉**:
```text
(Σaᵢ)(Σbᵢ) = Σᵢ aᵢbᵢ + Σ_{i<j} (aᵢbⱼ + aⱼbᵢ)
```
每对参与方做两次 OLE,发起方拿 `aᵢbⱼ − t`、响应方拿 `t`,没有任何实体
见过 `a` 或 `b` 的真值。输出布局与 `share::mul_triple_into` 完全一致,
可以直接喂给 `mpc-vault` 在线阶段。对应参考实现的 `Vault(triples="he")`。
- `bigint`:手写大整数(Montgomery 模幂 / Knuth D 除法 / Miller-Rabin),零外部依赖
- `paillier`:与 Python **逐位一致**(50 条 golden:显式 `r` 的密文、解密、
同态链、负明文的 `%` 向下取整语义、`n//2` 边界)
- `ole` / `pir` / `triple`:OLE 响应、1-out-of-N 隐匿查询、n 方三元组协商
(2 方 / 3 方 / 矩阵版语义测试全绿)
```bash
cargo test -p mpc-he # 23 用例
cargo test --release -p mpc-he --test bench_he -- --ignored --nocapture
```
已知边界:与参考实现同级的**非常数时间**实现(私钥操作生产放 TEE);
HE 物料给不出截断对(`(r, r>>f)` 是非线性关联),该模式下截断退化为本地右移。
---
## 为什么重做
三件事在 Python 里做不到,而不是"想换成 Rust":
**1. 交付物必须是二进制。**
隐私计算的客户是银行、医院、政务云,进场要求通常是"给个可执行文件 + 校验和",
而不是"装个 Python 3.9+ 再 pip install 一堆包"。Python 方案在这里过不了验收。
**2. Ray 不能出现在计算路径上。**
Ray 是 C++ 内核 + Python 驱动 + GCS/raylet/object store 一整组进程,
`pip install ray` 之后 site-packages 是 GB 级;计算要靠 `cloudpickle` 把函数图
序列化到远端 worker。它不可替代的价值只有一条:**用自定义资源把参与方钉在指定
物理机**(`resources={"alice_node": 1}`)。所以 Ray 留在部署层,不进计算路径。
详见 [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md#3-ray-放在哪一层)。
**3. TEE 要求密码学核心能 `no_std` 编译。**
OP-TEE 的 TA 里没有 `std`、没有线程、没有通用分配器。
`mpc-core` 从第一行代码起就是零依赖、零分配的 slice-in/slice-out 形态,
因此它**同一份源码**既能编进 Linux 用户态,也能编进 armv7 的 TA。
---
## 性能:真正的大头不在矩阵乘
本机实测(i5-5250U / Broadwell / 2C4T,数字越小越好):
| 算子 | Python 参考 | Rust | 倍数 |
|---|---|---|---|
| `matmul` 256³ u64 | 83.1 ms | **18.0 ms**(AVX2) | **4.6×** |
| `matmul` 64³ | 0.363 ms | **0.158 ms** | 2.3× |
| 逐元素 `mul` 16M | 101 ms | **58.7 ms** | 1.7× |
| 算术右移 16M | 79.3 ms | **38.5 ms** | 2.1× |
| Paillier 加密(n=1024 bit) | 21.1 ms | **7.3 ms** | 2.9× |
| Paillier 解密(n=1024 bit) | 6.3 ms | **2.8 ms** | 2.3× |
| Paillier 加密(n=2048 bit) | 150 ms | **44 ms** | 3.4× |
| OLE 全流程 / 元素(n=1024) | ~48 ms | **15.8 ms** | ~3× |
**结论要说清楚**(2026-10-29 实测修正):
- 环算术(加减乘/matmul)只有 **1.6–4.6×**。numpy 的 u64 路径已经是 C 循环,
Rust 换不来数量级;剩下的差距是 SIMD 和去掉了 numpy 迭代器开销。
- **Paillier 是 2-3.6×,不是数量级**。早前"~280×"的估计是错的 ——
纯 Python 的 `pow` 对大整数本来就走 C 循环,手写 Montgomery 模幂
在这台 2015 年的 i5 上只能到 4-5 ms/次。要数量级得上 Karatsuba/汇编/GPU,
那是下一步的优化空间,不是现在的事实。
- **HE 路径的真正收益不是倍数,是"能不能用"**:Python 版
`triples="he"` 每元素 ~48 ms,预处理 10 万元素要 80 分钟;
Rust 降到 ~16 分钟,且**能编进 TEE**(Python 根本进不了 TA)。
- **更大的收益在架构层**:去掉 Python 解释器启动、cloudpickle 序列化、
跨进程 RPC。这部分不是"算子快多少倍",而是"不再有这些开销"。
基准代码:`crates/mpc-core/examples/bench.rs`、`tools/bench_numpy.py`
与 `cargo test --release -p mpc-he --test bench_he -- --ignored`,同机同规模,可复现。
---
## 保真策略:golden vectors,不给误差留口子
从 Python 参考实现移植到 Rust 时,最大的风险不是性能,是**语义漂移**:一处舍入模式、一个符号位处理、
一个截断时机不同,结果就在小数第 8 位分叉,而"看起来差不多"的测试抓不到。
所以凡是确定性算子,都从参考实现导出一份逐位基线:
```bash
.venv/bin/python tools/gen_golden.py
# -> crates/mpc-core/tests/golden_vectors.rs (环算子,215 条)
# -> crates/mpc-he/tests/golden_paillier.rs (Paillier/大数,50 条)
cargo test -p mpc-core --test golden_vectors
cargo test -p mpc-he --test golden_paillier
```
215 条环算子用例硬比 `u64`,含这些容易错的地方:
- `np.rint` 是**银行家舍入**(round-half-to-even)→ Rust 侧必须用
`f64::round_ties_even()`,不能是 `f64::round()`
- numpy `uint64` 运算的**回绕语义** → Rust `wrapping_*`
- 算术右移按**有符号**语义 → `(x as i64) >> n`
- `np.matmul` 对整数也会回绕 → 分块累加必须 `wrapping_add`
Paillier 的 50 条用例硬比密文 hex(给定相同明文与显式随机因子 `r`),
覆盖负明文的 Python `%` 向下取整语义与 `decrypt_signed` 的 `n//2` 边界。
---
## 示例:12 个场景
`examples/` 是一个独立 crate,一个场景一个 bin,共用一层只做「起参与方 / 定点编解码 /
打印 / 校验」的脚手架 —— 算法全在示例正文里,调的都是 `mpc-*` 的真接口。
```bash
cargo run -p mpc-examples --bin 03_vertical_lr # 单个
tools/examples.sh # 全部(CI 第 4 关)
tools/examples.sh 09 10 # 按名字过滤
```
| # | 场景 | 讲什么 |
|---|---|---|
| 01 | 密文四则 / 矩阵 / sigmoid | 定点、加性分片、`scale_public` 要自己截断、多项式逼近的收敛 |
| 02 | PSI | ECDH 双盲、交集之外的人谁都不知道 |
| 03 | 纵向 LR | 各方持不同列,PSI → 对齐 → 密态梯度下降 |
| 04 | FedAvg | 横向联邦聚合 + 责任链 |
| 05 | 出域策略 | exec / transfer / fetch 三个关口 + 审计留痕 |
| 06 | DP-FedAvg | 裁剪、加噪、RDP 记账;噪声太大 AUC 直接掉到随机 |
| 07 | 密文推理 | MLP 明文训练 + 密文前向;`matmul_trunc` 的两个入参都必须是分片 |
| 08 | PIR | Paillier 同态加权求和,问「第几条」但不告诉对方 |
| 09 | SCQL | JOIN 走 PSI、WHERE 是掩码不是过滤、明文引擎对拍、护栏拒绝越界查询 |
| 10 | 分箱 / WOE / IV | 切点不出方、one-hot 进密态、一次矩阵乘出全部箱计数、互补抑制 |
| 11 | 试跑 | `query_rounds` 报轮数(整数码 156→23 轮)、行数不影响轮数、定点乘法静默回绕 |
| 12 | 两方部署 | k8s 清单 + 本地等价演练 + 清单自检(站点顺序 / fxp / 端口 / PSK) |
示例的断言失败会让脚本非零退出:`check()` 打 `[!!]`,`tools/examples.sh` 扫这一行。
这是防止示例 rot 的唯一办法 —— 不挂 CI 的示例,三个月后就是一批编译不过的摆设。
---
## 目录
```
crates/
├── mpc-core/ 算子核:零依赖 no_std
│ ├── ring.rs Z_2^64 定点算术 + 矩阵乘(AVX2 可选)
│ ├── share.rs 加性分享 / Beaver 三元组 / 截断对 / edaBit
│ ├── prg.rs ChaCha20 流(成对掩码 / 零和分享)
│ ├── hash.rs SHA-256(commitment / 种子派生)
│ └── compare.rs 安全比较的本地步骤(BitLT / MSB 组装)
├── mpc-he/ Paillier 同态 + HE-OLE 物料(无可信发牌方)
│ ├── bigint.rs 手写大整数:Montgomery / Knuth D / Miller-Rabin
│ ├── paillier.rs 加解密 / 同态算子(与 Python 逐位一致)
│ ├── ole.rs OLE 响应(逐元素 + 矩阵)
│ ├── pir.rs 1-out-of-N 隐匿查询
│ └── triple.rs n 方 Beaver 三元组协商
├── mpc-psi/ X25519 ECDH-PSI(n 方环协议 + strict 抗恶意硬化;唯一外部依赖 curve25519-dalek)
├── mpc-ml/ 纵向联邦 LR + 明文 MLP(mlp)+ 异构分箱(binning,WOE/IV + 互补抑制)
├── mpc-data/ 数据层:Frame 数值表 + 明文统计 + mock 合成(确定性主键/schema/DP)+ CSV
├── mpc-sql/ SCQL 受限 SQL:AST + 手写解析器 + 掩码式执行语义
│ `secure.rs`(密态算子入口)/ `secure_graph.rs`(建图,走 mpc-ir)
├── mpc-policy/ 出域守卫(exec/transfer/fetch)+ 审计日志
├── mpc-runtime/ 执行模式:dry_run / real_run(线程局部 + RAII 嵌套恢复)
├── mpc-ir/ 算子图 IR:Vis + 定点尺度 k(都挂在值上)+ 强制 Lift + base/end 排程
│ `mpc plan`(纵向 LR)/ `mpc sql-plan`(掩码聚合)报交互轮数;
│ 分组可选 `--group-mode coded`(整数码前缀和,8 组 13→12 轮)
├── mpc-fl/ 联邦聚合 + 差分隐私 + 横向 FedAvg(聚合责任链 + RDP 记账 + fedavg/linear/metrics,对齐 ml/aggregators, privacy/dp, ml/fedavg)
├── mpc-tee/ TEE HAL:seal / unseal / attest / sign
├── mpc-proto/ 帧编解码(手写,不引 protobuf)
├── mpc-vault/ 协议编排:Beaver / 截断 / open / reveal
├── mpc-node/ 节点服务:一方一进程,承载明文域 + 分片
│ TcpTransport(两方单连接)/ TcpMesh(n 方全网状)
├── mpc-orch/ 集群编排:PLAN 文本协议 + 两阶段提交(纯 std,零依赖)
├── mpc-ray/ Ray C++ core 绑定(可选,std-only;默认不链接)
│ 2.59 → docs/RAY_CORE.md;1.0.1(armv7 唯一可选)→ docs/RAY_CORE_101.md
└── mpc-cli/ 单二进制 CLI
examples/ 12 个教学示例(独立 crate,一个场景一个 bin;进 CI)
ray/ mpc_ray_shim.cc + build.sh(复用 pip wheel 的 _raylet.so,不走 bazel)
refs/nax/ 参考实现(独立仓库,仅作基线)
tools/ golden 生成 + numpy 基准
docs/ 架构与 TEE 设计;`N_PARTY.md` 是 n 方能力矩阵(哪些真支持、哪些是协议限制)
```
---
## 与参考实现的关系
`refs/nax` 是独立 git 仓库,只读引用,定位是**行为基线与性能对照组**,不是 ssw-mpc 要复刻的产品形态。
前身以「对齐 Python 参考实现」为起点,改名后以多方安全计算场景为准,因此 **不打算**做"逐行翻译":
- 保留:`Site` / `Vault` / `SecretRef` / `Handle` 这套概念划分、
三个出域关口、受限 SQL 方言的拒绝语义 —— 这些是对的设计。
- 丢弃:`Backend` 把 Python 函数当参数传给远端执行(cloudpickle 依赖)、
`dry_run` 靠 contextvars 切换、审计日志写进 Python 对象。
- 重做:调度(gRPC 帧 + 会话)、TEE(控制平面)、算子(SIMD)。
---
## License
Apache-2.0