Files
ssw-mpc/README.md
T
rong 4bb573d98c feat: Ray C++ 内核接进 nax Rust + armv7 真交叉编译
Ray 这条线不绕 bazel:
- wheel 里的 ray/_raylet.so 就是编好的 C++ core(34113 个导出符号,
  3638 个 ray:: 符号 default 可见,含 CoreWorkerProcess::Initialize)
- ray/nax_ray_shim.cc:259 行 C ABI shim,复用 process_helper 的初始化路径
- 实测跑通:Rust 二进制作为 driver 接入真实 GCS+raylet,
  拿到 raylet 分配的 node_id(d190801c…),probe 通过

踩坑(都已固化进 ray/build.sh):
- raylet 只编了 Python worker pool → 注册时语言声明 PYTHON
- Ray C++ 是旧 ABI → -D_GLIBCXX_USE_CXX11_ABI=0
- fmt v9/v11 撞车 → FMT_HEADER_ONLY
- Debian absl 固定自家 optional → 影子头直通 std::optional
- _raylet.so 是 CPython 扩展(253 个 Py 符号)→ build.rs 自动链 libpython
- GcsNodeInfo 手写 wire format 解析,避免 protobuf 跨 ABI

armv7 交叉编译修正(原结论有误):
- 换 armv7-unknown-linux-musleabihf + rust-lld/link-self-contained
- 不再需要外部交叉 gcc,macOS 本机 83 秒出 687 KB 静态二进制
- .cargo/config.toml 固化,无需 export 任何变量

其他:nax-orch 告警清理;README/ZYNQ 文档对齐实测。
2026-10-30 11:31:02 +08:00

328 lines
16 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 序列化函数) | 自研 TCP 帧 + `nax-orch`(661 行纯 std);Ray 可选做**成员与放置** |
| TEE | 无 | `nax-tee` HAL,OP-TEE 已验证范式可直接复用 |
| 依赖树 | numpy / pandas / ray | **nax-core 零依赖** |
---
## 现状(2026-10-30)
| 模块 | 状态 |
|---|---|
| `nax-core` 算子核 | ✅ 零依赖 `no_std`,37 单测 + 215 条 Python 逐位对照全绿 |
| `nax-proto` 帧协议 | ✅ 手写编解码,11 单测(含粘包/半包/恶意长度) |
| `nax-vault` 协议编排 | ✅ Beaver 乘 + 定点截断 + open/reveal,7 单测 |
| `nax-node` TCP 会话 | ✅ 网状 n 方 + 两方便捷路径,5 单测(真实 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` 四个子命令 |
| `nax-orch` 编排 | ✅ 661 行纯 std,PLAN 协议 + 两阶段提交,7 单测;本机三进程跑通 |
| `nax-ray` Ray C++ 内核 | ✅ 链接 `_raylet.so` 接入真实集群(拿到 raylet 分配的 node id),见 `docs/RAY_CORE.md` |
| armv7 交叉编译 | ✅ **真出二进制**:musl 静态 687 KB,`file` 显示 `ARM, EABI5, statically linked` |
```bash
cargo test --workspace # 134 用例
cargo build --release -p nax-cli && ./target/release/nax selftest
cargo check --workspace --target armv7-unknown-linux-gnueabihf
```
### 交叉编译到 Zynq(armv7,任意宿主都能出)
```bash
rustup target add armv7-unknown-linux-musleabihf
cargo build --release -p nax-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
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.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"
nax node --site alice --sites $S --listen 127.0.0.1:9450 --peers "$P" --data 2 &
nax node --site bob --sites $S --listen 127.0.0.1:9451 --peers "$P" --data 3 &
nax 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/nax_cluster.py --sites alice,bob,carol \
--data alice=2,bob=3,carol=5 --nax ./target/release/nax --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
```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/ 节点服务:一方一进程,承载明文域 + 分片
│ TcpTransport(两方单连接)/ TcpMesh(n 方全网状)
├── nax-orch/ 集群编排:PLAN 文本协议 + 两阶段提交(纯 std,零依赖)
├── nax-ray/ Ray C++ core 绑定(可选,std-only;默认不链接,见 docs/RAY_CORE.md)
└── nax-cli/ 单二进制 CLI
ray/ nax_ray_shim.cc + build.sh(复用 pip wheel 的 _raylet.so,不走 bazel)
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