Files
ssw-mpc/CLAUDE.md
T
rong b7263bcd26 feat: P3 OP-TEE —— nax-tee 进 TEE(core/proto/TA/CA 三层 + QEMU 脚本)
- nax-tee 转 no_std + alloc(mock 锁 std feature),Cargo.toml 显式写死
  不走 workspace 继承(拷进 teaclave-sdk examples workspace 后解析不崩)
- optee/core.rs:HKDF + AES-GCM + 设备 DNA 的 seal/unseal 逻辑(no_std)
- optee/proto.rs:CA↔TA 参数格式与错误码
- ta/ + ca/:薄壳 TA(参数搬运 + secure storage)与 TEEC 客户端
- build/:OP-TEE QEMU 构建与运行脚本(build_optee.sh / p3_optee_qemu.sh / run_qemu.py)
- CLAUDE.md:项目铁律与快速验证入口
2026-10-29 17:24:47 +08:00

5.6 KiB
Raw Blame History

CLAUDE.md

项目是什么

nax(N-arty Arithmetic eXecution)的 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 自己的帧协议。

快速验证

cargo test --workspace                              # 129 用例
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 会话、帧协议对接
  ↓
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 号持有公开值"。
  • 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 向量

.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

QEMU OP-TEE 验证(P3)

# 需要 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 参考实现(只读)