Files
ssw-mpc/README.md
T
rong 5d385ccd60 feat: P4 大数 Paillier + HE-OLE —— 无可信发牌方的 Beaver 物料
- nax-he(零外部依赖,no_std + alloc):手写 bigint(Montgomery CIOS
  模幂 / Knuth D 除法 / Miller-Rabin)+ Paillier + OLE + PIR + n 方三元组
- 50 条 golden 逐位对照 Python(显式 r 的密文 / 解密 / 同态链 /
  负明文 % 向下取整 / n//2 边界),13 条协议语义测试
- 三元组输出布局与 share::mul_triple_into 一致,可直接接 nax-vault
- 性能实测修正:Paillier 加密 n=1024 是 21ms→7.3ms(2.9×),
  不是早前预估的 280×;HE 真正收益是可用性 + TEE 可编入
- 修复:MontCtx::modpow 未归约底数(大底数被静默截断)、
  小指数走 1-bit 幂梯(mul_plain 360→159μs)
- 110 用例全绿,no_std + armv7 全通过
2026-10-29 12:35:24 +08:00

269 lines
12 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.
# nax-rs
**N**-arty **A**rithmetic e**X**ecution 的 Rust 重写 —— 隐私计算框架,单二进制、低依赖、可编进 TEE。
参考实现(Python/numpy/Ray)在 `refs/nax/`,只作为**行为基线与性能对照组**,不参与构建。
---
## 一句话定位
| | 参考实现 `refs/nax` | 本仓库 `nax-rs` |
|---|---|---|
| 运行时 | Python 3 + numpy + pandas + (Ray) | **无**(静态链接单二进制) |
| 部署形态 | `pip install` + 解释器 | `nax` 一个文件,`scp` 上去就能跑 |
| 算子层 | numpy u64(BLAS 帮不上) | Rust 手写环算术 + AVX2 |
| 集群 | Ray Actor(cloudpickle 序列化函数) | 自研 gRPC 帧;Ray 只做**部署编排** |
| TEE | 无 | `nax-tee` HAL,OP-TEE 已验证范式可直接复用 |
| 依赖树 | numpy / pandas / ray | **nax-core 零依赖** |
---
## 现状(2026-10-29)
| 模块 | 状态 |
|---|---|
| `nax-core` 算子核 | ✅ 零依赖 `no_std`,37 单测 + 215 条 Python 逐位对照全绿 |
| `nax-proto` 帧协议 | ✅ 手写编解码,11 单测(含粘包/半包/恶意长度) |
| `nax-vault` 协议编排 | ✅ Beaver 乘 + 定点截断 + open/reveal,7 单测 |
| `nax-node` TCP 会话 | ✅ 3 单测(真实 TCP,含 10 万元素粘包 + PSI 端到端) |
| `nax-psi` 隐私求交 | ✅ X25519 ECDH-PSI,10 单测(含 RFC 7748 向量、1 万条求交) |
| `nax-ml` 纵向 LR | ✅ sigmoid 奇多项式 + 矩阵 Beaver SGD,明文对照 >0.95 |
| `nax-he` Paillier/OLE | ✅ 无可信发牌方 Beaver 物料 + PIR,50 条 Python 逐位对照 + 13 语义测试 |
| `nax-tee` HAL | ✅ trait + Mock 实现(11 单测),OP-TEE 待接 |
| `nax-cli` | ✅ 单二进制 **499 KB**,`selftest` / `node` / `psi` / `lr` 四个子命令 |
| armv7 交叉编译 | ✅ 全 workspace `cargo check --target armv7-unknown-linux-gnueabihf` |
```bash
cargo test --workspace # 110 用例
cargo build --release -p nax-cli && ./target/release/nax selftest
cargo check --workspace --target armv7-unknown-linux-gnueabihf
```
### P1 验收:两个进程经真实 TCP 算出结果
```bash
# 终端 1
nax node --site bob --sites alice,bob --listen 127.0.0.1:9444 --data 4,5,6
# 终端 2
nax 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 次)**。
```
nax node · site=alice · 127.0.0.1:9444 · 3 个元素 · fxp=18
本方 alice 是 0 号,持有 3 个元素
分片交换完成
密文乘法完成(2 次 open)
还原完成: [9175040]
会话结果: 35
```
### P1.5 验收:两进程 PSI
```bash
# 终端 1
nax psi --site bob --sites alice,bob --listen 127.0.0.1:9445 --ids 3,4,5,6,7
# 终端 2
nax psi --site alice --sites alice,bob --connect 127.0.0.1:9445 --ids 1,2,3,4,5
```
两侧都输出 `交集 3 条: 3,4,5`。网络上流动的全是 X25519 曲线点,
反推 ID 等价于解离散对数;每轮发送前洗牌,切断"位置 ↔ 原始记录"的对应。
与 Python 参考实现的语义对照:`.venv/bin/python tools/check_psi.py` → `PASS`。
> 唯一的例外依赖:`nax-psi` 引了 `curve25519-dalek`。
> 理由不是省事 —— 手写 X25519 **做不到恒定时间**,按比特分支的 ladder
> 会被时序侧信道把私钥一位位读走。参考实现的 Python 版自己在注释里承认
> 非常数时间。这种地方"自己造"是埋一个测试永远抓不到的洞。
### P2 验收:两进程纵向 LR
```bash
# 终端 1(特征已标准化到 ±1)
nax 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
nax 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` 那一步出域。
- `nax-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)
`nax-core::share::Dealer` 是半诚实可信第三方 —— 它只要记下发出的 `a`,
对照在线阶段公开的 `d = x - a` 就能还原任何输入。`nax-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` 完全一致,
可以直接喂给 `nax-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 nax-he # 23 用例
cargo test --release -p nax-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`、没有线程、没有通用分配器。
`nax-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/nax-core/examples/bench.rs`、`tools/bench_numpy.py`
与 `cargo test --release -p nax-he --test bench_he -- --ignored`,同机同规模,可复现。
---
## 保真策略:golden vectors,不给误差留口子
Rust 重写最大的风险不是性能,是**语义漂移**:一处舍入模式、一个符号位处理、
一个截断时机不同,结果就在小数第 8 位分叉,而"看起来差不多"的测试抓不到。
所以凡是确定性算子,都从参考实现导出一份逐位基线:
```bash
.venv/bin/python tools/gen_golden.py
# -> crates/nax-core/tests/golden_vectors.rs (环算子,215 条)
# -> crates/nax-he/tests/golden_paillier.rs (Paillier/大数,50 条)
cargo test -p nax-core --test golden_vectors
cargo test -p nax-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` 边界。
---
## 目录
```
crates/
├── nax-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 组装)
├── nax-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 三元组协商
├── nax-psi/ X25519 ECDH-PSI(唯一外部依赖 curve25519-dalek)
├── nax-ml/ 纵向联邦 LR(sigmoid 奇多项式 + 矩阵 Beaver SGD)
├── nax-tee/ TEE HAL:seal / unseal / attest / sign
├── nax-proto/ 帧编解码(手写,不引 protobuf)
├── nax-vault/ 协议编排:Beaver / 截断 / open / reveal
├── nax-node/ 节点服务:承载一方明文域 + 分片
└── nax-cli/ 单二进制 CLI
refs/nax/ 参考实现(独立仓库,仅作基线)
tools/ golden 生成 + numpy 基准
docs/ 架构与 TEE 设计
```
---
## 与参考实现的关系
`refs/nax` 是独立 git 仓库,只读引用。nax-rs **不打算**做"逐行翻译":
- 保留:`Site` / `Vault` / `SecretRef` / `Handle` 这套概念划分、
三个出域关口、受限 SQL 方言的拒绝语义 —— 这些是对的设计。
- 丢弃:`Backend` 把 Python 函数当参数传给远端执行(cloudpickle 依赖)、
`dry_run` 靠 contextvars 切换、审计日志写进 Python 对象。
- 重做:调度(gRPC 帧 + 会话)、TEE(控制平面)、算子(SIMD)。
---
## License
Apache-2.0