Files
admin 4a750785f8 feat(cluster): pending 证明超时回收(默认 900 秒,可配可禁用)
- reconciler:可注入时钟 + 唯一判定 pending_timed_out(saturating_sub 防回拨);超时真调 destroy、释放容量、/report 留带原因失败、本轮不重建(下轮按期望态重试)

- 修真 bug:PendingSession.created_at 曾写 now_secs(),与判定时钟分叉 ⇒ 超时永不触发,单测直接抓到

- ControlPlaneConfig / CLI:--pending-timeout SECS(0=显式禁用),默认值只有 DEFAULT_PENDING_TIMEOUT_SECS 一份常量;help 数字由守卫测试对拍

- 新增 8 个构造用例 + 跨文件判据自测 16 条 / 破坏实验 15 条,并入主门禁第 25 条(分母仍 25)

- 文档:ARCH §1.6/§8、FINDINGS §12、README/INDEX/CLAUDE/真机 README/env 样例/MEMORY 同步;HTML 重新生成并校验

- 诚实边界:未做真机验证、真机 musl 产物未更新、超时后下一轮重试不是永久隔离
2026-11-09 21:22:53 +08:00

550 lines
36 KiB
Markdown
Raw Permalink 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 算子基线 + 2026-11-08 增量)
### 2026-11-08 增量:TEE 真机 / 国密链 / 智能合约 / k8s 持久化
> 这一节是当前能力的**活状态**。权威入口与逐条硬证据见 [docs/INDEX.md](docs/INDEX.md)。
| 能力 | 状态 | 权威入口 / 硬证据 |
|---|---|---|
| 真 TEE 跨物理机双 guest 密文会话 | ✅ 跑通 | 海光 CSV + AMD SNP 两侧还原 `35.000000`;`deploy/tee/real-machine/tee-pair-attest-e2e.sh`,判据 `TEE_PAIR_OK` |
| 芯片证明链与密文会话**同一次运行**合流 | ✅ 跑通 | `attest-collect → attest-post(KBS 芯片验签放行)→ key_source=kbs → 跨物理密文会话`;判据 `TEE_ATTEST_GATE_OK`,负向也真绿;见 `docs/REAL_MACHINE_FINDINGS.md` 第 10 节 |
| 集群端点公布门禁(真 KBS 验签后才公布) | ✅ 跑通 | AMD SNP + 海光 CSV 双节点自报 → 非回环暴露(共享密钥 + `--allow-remote`)→ 真 KBS 芯片验签 → 9p 手牌回传证明包 → hostd 独立判定 → `GET /sessions` 公布 `192.168.1.7:3010`;负向 `epg-bad` 零外泄 + `/report` 带原因,收尾端点收回;判据 `CLUSTER_ENDPOINT_GATE_OK`(20/0),见 `docs/REAL_MACHINE_FINDINGS.md` 第 11 节 |
| pending 超时回收 | ✅ 离线实证 | 证明迟迟不落 ⇒ 真调 `destroy` 回收 guest、释放容量、`/report` 留带原因失败;默认 900 秒(`--pending-timeout SECS`,`0` = 禁用),判定只有一份且防时钟回拨。**未做真机验证**,见 `docs/REAL_MACHINE_FINDINGS.md` 第 12 节 |
| FISCO 国密链**真交易**(TARS 编码 + SM2 `ZA‖dataHash` 签名) | ✅ 跑通 | 提交走自有 `sendTransaction`(4 参);签名为 `r‖s‖pub` 128B;真相源 `docs/FISCO_UPSTREAM_TRUTH.md` |
| 智能合约真链**部署 / 调用 / 读回** | ✅ 跑通 | `contracts/MpcHardRule.sol`;`tools/selftest-fisco-contract.py` 部署→`recordHardRule`→读回→负向矩阵,**22 项判据全绿**(主门禁第 22 条;零依赖 `--self-test` 每次必跑) |
| 链节点与管理节点**持久化** | ✅ 已迁 k8s | FISCO 链连同现有账本迁入 wuguirong,`nfs-wuguirong` PVC;历史区块哈希逐个一致、删 Pod 重建后高度不变;见 `deploy/k8s/fisco/README.md` |
| MPC 站点 `mpc-demo` | ✅ 已在 k8s | NodePort `30082`,`/tmp` 挂 NFS PVC;见 `demo/k8s/README.md` |
| 主门禁 | **25 条** | `./tools/ci.sh`;第 21 条真交易编码判据、第 22 条真链合约判据、第 23 条 SA 扩展模式、第 24 条零种子守卫、第 25 条集群判据自测 + 破坏实验(自报 / 端点公布 / pending 超时回收**三份成对覆盖**:端点 25+14 项、超时回收 16+15 项);缺环境一律显式 `*_SKIPPED`,绝不静默通过 |
**仍然不宣称的边界**(别被上面「跑通」冲掉):软件 OpenSSL 签名器私钥可导出 ⇒
**密评不可过**,生产必须换硬件模组签名器;真实 `bcos-rpc` 的 **TLCP 通道未通**(第 18 条服务端是环回 echo);
`hostd` **执行面仍在 TEE 真机**(需 qemu + `/dev/sev` 直通,项目铁律禁止编排层),进 k8s 的只是台账;
TEE 证明**未上链**、链上撤销状态位读取后端未接入、OPA 不在 guest 内、decision 未签名未上链。
### 算子与协议基线(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 CA↔TA 范式已落地,**QEMU 实跑已通过**(2026-11-09:全流程 selftest + 跨设备解封被拒 + 跨重启 unseal 成功;**模拟环境,非真板**) |
| `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 --no-default-features
# -> 687 KB 静态 ARM EABI5 hard-float,拷到板上直接跑,不绑 glibc 版本
# 链接器走 rust-lld + link-self-contained,无需外部交叉 gcc(见 .cargo/config.toml)
#
# ★ --no-default-features 不能省:mpc-cli 默认带 control-plane(mpc-hostd 的
# axum/tokio/reqwest + mpc-chain 的 OpenSSL),那是宿主控制面,不属于板上
# 的 guest 静态产物;musl 目标忘了加会被 main.rs 的 compile_error! 明确拒绝。
# 宿主端 mpc 保持默认 feature,mpc hostd / link / chain 才可用。
```
### 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 的示例,三个月后就是一批编译不过的摆设。
---
## TEE 直接调度(AMD SEV-SNP / 海光 CSV)
`mpc-tee` 现在支持**直接调度 TEE**:框架自己判断节点够不够格,输出平台中立的
`LaunchSpec`,部署侧据此用 qemu 直接启动 guest,把 `mpc` 作为 guest 内原生负载跑。
**不生成 Pod、不设运行时类、不依赖集群调度器** —— 运行时差异属于部署适配层,
不该进计算框架的 HAL。
- `mpc tee paths` 列出两条路径的实测规格(guest policy、KBC、证明通道、qemu 对象、配额);
- `mpc tee plan --node FILE` 读宿主预检结果做 fail-closed 准入,输出会话绑定证明与 qemu argv;
- `deploy/tee/preflight.sh` 产出节点描述,`deploy/tee/launch.sh` 直接 exec qemu。
关键区别在于**证明绑定本轮会话**:64 字节 `user_data` 由会话标识、参与方、会话公钥、
代码度量、平台与 TCB 共同派生,启动时钉进 guest,证明代理与 `GuestTee` 各自复核,
拒绝跨会话重放。框架不做芯片验签(验证方 / KBS 的职责),也不拿软件替身冒充 TEE。
完整设计、真机参数对照与能力边界见 [docs/TEE_DIRECT_LAUNCH.md](docs/TEE_DIRECT_LAUNCH.md),
部署契约见 [deploy/tee/README.md](deploy/tee/README.md)。
**真机实证状态(2026-11-08)**:这套直接调度已在 `192.168.1.102`(海光 CSV)与
`192.168.1.7`(AMD SNP)跑通——芯片证明采集 → KBS 验签放行 → `key_source=kbs`
→ 跨物理机双 guest 密文会话在**同一次运行**里完成,两侧还原 `35.000000`;
判据 `TEE_PAIR_OK` + `TEE_ATTEST_GATE_OK`,负向样例也逐条破坏过。入口
`deploy/tee/real-machine/tee-pair-attest-e2e.sh`,硬事实见
[docs/REAL_MACHINE_FINDINGS.md](docs/REAL_MACHINE_FINDINGS.md) 第 10 节。
注意 `hostd` 执行面**始终在真机**(要 qemu + `/dev/sev` 直通,不走编排层)。
## 目录
```
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
│ platform.rs 平台能力表 / session.rs 会话绑定证明 / schedule.rs fail-closed 准入
│ guest.rs guest 内原生接入(std)/ optee/ OP-TEE / mock.rs 软件替身
├── 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-hostd/ 宿主控制面(仅 control-plane):TeeRuntime + e2b 兼容 API + link 进程层
├── mpc-chain/ 链上层(仅 control-plane):TARS 交易编码 / SM2 ZA 签名 / JSON-RPC / OPA / outbox
└── mpc-cli/ 单二进制 CLI;tee / hostd / link / chain 子命令族
examples/ 12 个教学示例(独立 crate,一个场景一个 bin;进 CI)
contracts/ MpcHardRule.sol(链上硬规则合约,真链部署过)
build/contracts/ solc 产物 combined.json(abi/bin,第 22 条判据输入)
deploy/tee/ TEE 直接启动:宿主预检 → 节点准入 → qemu argv(无容器编排层)
deploy/tee/real-machine/ 两台真机证明门控 + 双 guest 密文会话 e2e 与判据
deploy/k8s/fisco/ FISCO 国密链 k8s:镜像 / PVC / 账本迁移 / 常驻守卫 / 完整 SOP
demo/ 尚数网算子集市站点(Rust 单二进制,已在 k8s NodePort 30082)
demo/k8s/ 站点部署清单 + NFS PVC 持久化说明
ray/ mpc_ray_shim.cc + build.sh(复用 pip wheel 的 _raylet.so,不走 bazel)
refs/nax/ 参考实现(独立仓库,仅作基线)
tools/ golden 生成 + numpy 基准 + 主门禁 ci.sh(25 条)+ 各判据脚本
tools/fisco-realnode/ 真链复现工具与审计轨迹(SDK 发送器 / JNI 交叉验证 / TARS 辅助)
docs/ 架构、专题设计与真相源;**总入口 `INDEX.md`**;
`ARCHITECTURE_SYSTEM.md` 是系统架构当前形态(另有同名 .html 分享版);
`ARCHITECTURE.md` 只讲计算分层;
`FISCO_UPSTREAM_TRUTH.md` 是国密链上游逐条核对的唯一真相源;
`REAL_MACHINE_FINDINGS.md` 是两台真机硬事实;
`INTEGRATION_ANALYSIS.md` 是 2026-11-07 决策定稿(历史快照)
```
---
## 与参考实现的关系
`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