P1.2(n>2 分片)
- nax-vault::Transport 从单连接升为按 party 索引的 send_to/recv_from,
send/recv 保留为两方便捷路径(PSI 与旧测试不动)
- Vault::open 改为广播:向 n-1 方各发一次自己的分片再统一收,
通信量 O(n^2);inbox 按来源 party 分桶(混在一起会把两方分片加错对象)
- send_share / 新增 recv_share_from 按 party 定向,recv_share 在 n>2 时
显式报错而非猜一个对端
- nax-node 新增 TcpMesh:n 方全网状(每对一条直连),建连规则「小编号主动
connect 大编号」,accept 方靠 4 字节 party 下标握手认人
- run_session 改链式乘 z = x0·x1·…·x(n-1),每轮 1 次 Beaver 乘 + 1 次截断
- CLI 放开两方限制,新增 --peers name=addr,...(与 --listen 搭配)
为什么必须全网状而不是星型:Shares 帧里是真实输入分片,星型让 head 转发
等于把一方输入读给中转节点看。n 是跨机构参与方个数,n(n-1)/2 条直连不是瓶颈。
P5(Ray 编排)
- deploy/ray/nax_cluster.py:两阶段提交(actor 先报本机 IP,driver 拼出
peers 表再起进程),actor 按 {site}_node 资源标签落机器
- 三种后端:--dry-run 打印计划 / --local 本机并行(不需 Ray)/ 默认连集群
- launch.sh 改为透传;README 补两阶段时序、排序为什么是协议要求
验证:三方 2·3·5+1=31、四方浮点(1.5·2·0.5·4 与 2.25·4·(-1)·0.125)
三方/四方输出一致;整数域四方 3·5·7·2+1=211 精确。
cargo test --workspace 134 全绿(vault 10 / node 5),no_std 与 armv7 交叉
编译守线通过。Ray 集群模式未在真实多机验证,已在 README 标注。
147 lines
7.1 KiB
Markdown
147 lines
7.1 KiB
Markdown
# CLAUDE.md
|
||
|
||
## 项目是什么
|
||
|
||
nax(**N**-arty **A**rithmetic e**X**ecution)的 Rust 重写:隐私计算框架,单二进制、低依赖、TEE 可编入。
|
||
参考实现在 `refs/nax/`(Python/numpy/Ray,独立 git 仓库),**只读,不参与构建**,仅作行为基线与性能对照组。
|
||
|
||
## 三条铁律(优先级高于一切)
|
||
|
||
1. **`nax-core` 必须能 no_std 编译**。CI 守:`cargo build -p nax-core --no-default-features`。
|
||
任何 `Vec` / `tokio` / `String` / `std::` 混进来就等于断了 TEE 那条路。
|
||
已知坑:`f64::round_ties_even` 是 std-only,已自实现。
|
||
|
||
2. **与 Python 参考实现逐位一致**。改任何确定性算子后必须重跑
|
||
`.venv/bin/python tools/gen_golden.py && cargo test`。
|
||
**不要为了让测试变绿去放宽断言** —— 先确认哪边对。
|
||
已知对齐点:`np.rint` 银行家舍入、uint64 回绕语义、算术右移有符号语义、`np.matmul` 整数也回绕。
|
||
|
||
3. **Ray 不进计算路径**。只用于部署期把 `nax-node` 钉到各方物理机
|
||
(`resources={"<site>_node": 1}`),计算走 nax 自己的帧协议。
|
||
|
||
## 快速验证
|
||
|
||
```bash
|
||
cargo test --workspace # 134 用例
|
||
cargo build -p nax-core --no-default-features # no_std 守线
|
||
cargo check --workspace --target armv7-unknown-linux-gnueabihf # 交叉编译守线
|
||
cargo build --release -p nax-cli && ./target/release/nax selftest
|
||
```
|
||
|
||
## crate 分层
|
||
|
||
```
|
||
nax-cli 单二进制入口(selftest / node / psi / lr 四个子命令)
|
||
↓
|
||
nax-node 一方一进程:TCP 会话、帧协议对接
|
||
TcpTransport(两方单连接,PSI 用)/ TcpMesh(n 方全网状,各一对直连)
|
||
↓
|
||
nax-vault 协议编排:Beaver 乘 / 定点截断 / open / reveal(交互在这里,不在算子核)
|
||
↓
|
||
nax-core 算子核:Z_2^64 环算术、加性分享、Beaver 三元组、PRG、SHA-256、比较
|
||
零依赖 / no_std / 零分配(slice-in/slice-out)
|
||
模块:ring / share / prg / hash / compare
|
||
───────────
|
||
nax-he 大数 Paillier + OLE + PIR + n 方 Beaver 三元组(无可信发牌方)
|
||
手写 bigint(Montgomery CIOS 模幂 / Knuth D / Miller-Rabin)
|
||
模块:bigint / paillier / ole / pir / triple
|
||
no_std + alloc,零外部依赖
|
||
───────────
|
||
nax-psi X25519 ECDH-PSI(唯一允许外部密码学 crate 的地方:curve25519-dalek)
|
||
模块:blind / reblind / match_points / resolve
|
||
───────────
|
||
nax-ml 纵向联邦 LR:sigmoid 多项式 + SGD,全程密文分片
|
||
───────────
|
||
nax-tee TEE HAL:seal / unseal / attest / sign
|
||
模块:mock(std-only)/ optee(core + proto + TA + CA)
|
||
TrustPlan 四级可信度:L0 纯 MPC / L1 单方 TEE / L2 双方互验 / L3 双方 TEE 互不信任
|
||
───────────
|
||
nax-proto 帧协议:12 字节头 + 定长消息体,手写编解码(不引 protobuf/serde)
|
||
```
|
||
|
||
## 关键设计决策
|
||
|
||
- **公开值在分片重建里只能出现一次**。栽过两次:truncate 的 `cs`、sigmoid 的 `c₀`。
|
||
修法都是"只有 0 号持有公开值"。
|
||
- **四方拓扑必须全网状,不能星型**。`Shares` 帧是真实输入分片,
|
||
经第三方转发等于把输入泄露给它。`n(n-1)/2` 条直连,n 是参与方个数。
|
||
- **建连规则:小编号主动连大编号**(`i<j` 时 i connect j,j accept)。
|
||
保证每对恰好一条连接,不会出现两条背向连接互相等消息。
|
||
accept 方靠 4 字节 party 下标握手认人(对端可以任意顺序连上来)。
|
||
- **party 索引 = 含本方的全局下标**,不用"去掉自己后重新编号"的 peer 下标。
|
||
两套编号并存时映射错了**不报错**,分片会发给错误的参与方。
|
||
- **排序是协议的一部分**:Vault 内部按字典序编号,第 p 片投递给排序后第 p 个。
|
||
端口分配、peers 字符串、`--sites` 必须是同一个排序。
|
||
- **`MontCtx::modpow` 必须归约底数**。Montgomery 乘只读 `k` 个 limb,
|
||
未归约的大底数被静默截断(decrypt 的 1024-bit 密文给 512-bit 模数上下文)。
|
||
- **小指数走 1-bit 幂梯**,不要建 16 项窗口表(`mul_plain` 曾比 Python 还慢)。
|
||
- **分片随机流每轮换 label**(递增 `share_round`),否则 `share₁ − share₂` 泄露差值。
|
||
- **`reveal` 是双方同步 open**,测试里双方都必须走完 reveal,否则管道断/死锁。
|
||
|
||
## 性能基线(i5-5250U,2026-10-29 同机实测)
|
||
|
||
| 算子 | Python | Rust | 倍数 |
|
||
|---|---|---|---|
|
||
| matmul 256³ u64 | 83.1 ms | 18.0 ms (AVX2) | 4.6× |
|
||
| 逐元素 mul 16M | 101 ms | 58.7 ms | 1.7× |
|
||
| Paillier 加密 n=1024 | 21.1 ms | 7.3 ms | 2.9× |
|
||
| Paillier 解密 n=1024 | 6.3 ms | 2.8 ms | 2.3× |
|
||
| OLE 全流程/元素 | ~48 ms | 15.8 ms | ~3× |
|
||
|
||
**别再用旧的 "280×" 估计** —— 纯 Python 大数 pow 本来就走 C 循环,手写 Montgomery 只有 2–3.6×。
|
||
HE 的真正收益是可用性(10 万元素预处理 80 分钟 → 16 分钟)+ 能编进 TEE。
|
||
|
||
## Zynq-7015 性能预算
|
||
|
||
A9 @667MHz 比 i5-5250U 慢 8–12×(不是 50×):
|
||
matmul 64³ ~2.5ms、纵向 LR ~150ms、PSI 1 万条 8–15s。
|
||
**小规模场景完全可以在板上跑**。大矩阵密文训练横扩 x86 + SEV-SNP/TDX/海光 CSV。
|
||
|
||
## golden 向量
|
||
|
||
```bash
|
||
.venv/bin/python tools/gen_golden.py # → crates/nax-core/tests/golden_vectors.rs (215 条)
|
||
# → crates/nax-he/tests/golden_paillier.rs (50 条)
|
||
cargo test -p nax-core --test golden_vectors
|
||
cargo test -p nax-he --test golden_paillier
|
||
```
|
||
|
||
## n 方(P1.2)与 Ray 编排(P5)
|
||
|
||
```bash
|
||
# 三方本机
|
||
python3 deploy/ray/nax_cluster.py --sites alice,bob,carol \
|
||
--data alice=2,bob=3,carol=5 --nax ./target/release/nax --local
|
||
# 只看参数(不起进程)
|
||
... --dry-run
|
||
# 真集群(actor 按 {site}_node 资源标签落机器)
|
||
... --address ray://<head>:10001
|
||
```
|
||
|
||
`--local` 是刻意保留的:编排里唯一容易写错的是端口分配/peers 字符串/命令拼装,
|
||
这些与 Ray 无关。能本机验证的先本机验证,别让"参数拼错"和"Ray 没配好"混在一起排查。
|
||
|
||
Ray 模式尚未在真实多机上验证过。
|
||
|
||
## QEMU OP-TEE 验证(P3)
|
||
|
||
```bash
|
||
# 需要 cube-sandbox(16C/16G toolchain 模板)
|
||
xop --secret CUBE_API_KEY=llm_key -- python3 -u build/run_qemu.py < /dev/null
|
||
```
|
||
|
||
构建链:OP-TEE 4.11 + u-boot v2024.10 + ATF v2.11 + Linux 6.6 + rustup nightly-2026-08-05
|
||
+ nax-tee TA/CA。判据:正常世界串口 `ALL OK`(provision → seal → unseal → 篡改被拒 → sign → attest)。
|
||
|
||
## 依赖
|
||
|
||
全项目**唯一**外部依赖:`curve25519-dalek`(在 `nax-psi`)。
|
||
理由:X25519 必须恒定时间实现,手写会被时序侧信道攻击。
|
||
`nax-he` 手写 bigint 零外部依赖。
|
||
|
||
## 文档
|
||
|
||
- `docs/ARCHITECTURE.md` — 分层、Ray 定位、TEE 定位(每条结论附"为什么不是另一种做法")
|
||
- `docs/ZYNQ.md` — Zynq-7015 性能预算、交叉编译、部署形态
|
||
- `refs/nax/` — Python 参考实现(只读)
|