Files
ssw-mpc/CLAUDE.md
T
admin 535c63a690
ci / gate (push) Waiting to run
refactor(domain): 协议域分隔常量统一到 mpc-core::domain,nax → mpc
- 20 个 KDF/HMAC/PSI/TEE/分片/作业种子标签全量换 mpc 前缀,集中到 mpc-core::domain 唯一真相源,业务代码不再写裸字符串
- 等长替换,消息格式与长度不变;mpc-tee 的 COMMIT/EGRESS 消息长度改由 label.len() 计算,避免写死数字漂移
- 不兼容变更:会话密钥、TEE 封存 blob、PSI 盲化点、缓存指纹、分片流全部换钥,参与方须同步升级,旧 blob/缓存/离线物料作废;不提供旧 nax 标签兼容读取
- README/CLAUDE/OPT_PLAN 重写兼容约定与迁移清单;仍保留 refs/nax 路径与 Python 包名 import nax(独立只读仓库真实路径)
- golden 向量(ring/paillier/zkp)是纯数学、check_psi.py 只比语义,均不依赖这些标签,无需重生成
- CI 三条闸门全绿(全量测试 / -Dwarnings / mpc-core no_std)
2026-11-05 15:29:33 +08:00

11 KiB
Raw Blame History

CLAUDE.md

项目是什么

ssw-mpc(尚数网-多方安全计算 / Secure Multi-Party Computation):面向多方数据协同的安全计算框架, 各方原始数据不出域,以秘密分享、隐私求交、同态加密与 TEE 可信根参与联合计算。 Rust 实现,单二进制、低依赖、可编进 TEE。 参考实现在 refs/nax/(Python/numpy/Ray,独立 git 仓库,目录名沿用前身未改),只读,不参与构建,仅作行为基线与性能对照组。

改名约定(前身 nax-rs → ssw-mpc):crate mpc-*、二进制 mpc、环境变量 MPC_*。 旧名指「N 方算术执行引擎(Rust 重写 Python 参考实现)」,新名指「多方数据协作下的安全计算」, 定位不同;叙述以新名语义为准,Python 参考实现只作行为基线。 协议域分隔常量已统一到 mpc-core::domain(唯一真相源,mpc/... 前缀),2026-11-05 由 nax/... 全量切换。 新增用途只在 domain 加常量,业务代码不要写裸字符串;改任一标签都是协议 breaking change: 它参与会话密钥 / TEE 封存 / PSI 盲化 / 分片流派生,必须全参与方同步升级,并同步更新 README 迁移清单 (旧 blob、缓存、离线物料作废)。golden 向量是纯数学,不依赖这些标签。 仍禁止改名的是 refs/nax/ 路径与 Python 包名 import nax —— 独立只读仓库的真实目录 (golden 脚本按此加载)。详见 README「命名沿革与兼容约定」。

三条铁律(优先级高于一切)

  1. mpc-core 必须能 no_std 编译。CI 守:cargo build -p mpc-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 不进计算路径。只用于部署期把 mpc-node 钉到各方物理机 (resources={"<site>_node": 1}),计算走 mpc 自己的帧协议。

快速验证

cargo test --workspace --features secure          # 471 用例(不带 secure 只有 415,漏 56 条)
cargo build -p mpc-core --no-default-features     # no_std 守线
cargo check --workspace --target armv7-unknown-linux-gnueabihf  # 交叉编译守线
cargo build --release -p mpc-cli && ./target/release/mpc selftest
./tools/ci.sh                                     # CI 与本地同一份闸门

CI 守三条:全量测试(必须带 --features secure)、-Dwarnings 零告警 (作用于 test/bench/example 目标)、mpc-core no_std。

crate 分层

mpc-cli       单二进制入口(selftest / node / psi / lr 四个子命令)
  ↓
mpc-node      一方一进程:TCP 会话、帧协议对接
              TcpTransport(两方单连接,PSI 用)/ TcpMesh(n 方全网状,各一对直连)
  ↓
mpc-vault     协议编排:Beaver 乘 / 定点截断 / open / reveal(交互在这里,不在算子核)
  ↓
mpc-core      算子核:Z_2^64 环算术、加性分享、Beaver 三元组、PRG、SHA-256、比较
              零依赖 / no_std / 零分配(slice-in/slice-out)
              模块:ring / share / prg / hash / compare
  ───────────
mpc-he        大数 Paillier + OLE + PIR + n 方 Beaver 三元组(无可信发牌方)
              手写 bigint(Montgomery CIOS 模幂 / Knuth D / Miller-Rabin)
              模块:bigint / paillier / ole / pir / triple
              no_std + alloc,零外部依赖
  ───────────
mpc-psi       X25519 ECDH-PSI(唯一允许外部密码学 crate 的地方:curve25519-dalek)
              模块:blind / reblind / match_points / resolve / strict(抗恶意硬化)
  ───────────
mpc-ir        算子图 IR:Vis(公开/秘密,挂在值上)+ 定点尺度 k + 强制 Lift + 轮次规划
              模块:graph(形状/可见性/尺度)/ compile(base-end 排程)/ exec(落 vault)
              **不改协议、不进 mpc-core**:只做三态标注与同阶段 open 合并
              `Vis` 与 `scale` 都是**值的属性**;`Open` 之后是公开,乘公开系数是本地运算
  ───────────
mpc-ml        纵向联邦 LR:sigmoid 多项式 + SGD,全程密文分片
              一次迭代 = 一张图(`build_epoch`),图建一次跑 epochs 遍;`mpc plan` 报轮数
  ───────────
mpc-sql       SCQL 受限 SQL:AST / 解析器 / 明文执行语义
              密态路径(`feature = "secure"`):掩码 WHERE + 聚合,走 `mpc-ir` 建图
              两段式(`AVG` 的除数 `COUNT` 要执行后才公开);`mpc sql-plan` 报轮数
  ───────────
mpc-tee       TEE HAL:seal / unseal / attest / sign
              模块:mock(std-only)/ optee(core + proto + TA + CA)
              TrustPlan 四级可信度,**按 n 方算**:for_parties(&[PartyTee], TrustPolicy)
                L0 全体无 TEE / L1 部分方有 / L2 全体互验(可明文直算)/ L3 全有但不开直算
  ───────────
mpc-proto     帧协议:12 字节头 + 定长消息体,手写编解码(不引 protobuf/serde)

关键设计决策

  • 公开值在分片重建里只能出现一次。栽过两次:truncate 的 cs、sigmoid 的 c₀。 修法都是"只有 0 号持有公开值"。现在 mpc-ir 用显式 Lift 节点把这条钉住: 公开值进密态表达式必须经过它,落成「0 号带明文、其余方持 0」。 把它改成每方都带,lifted_constant_appears_exactly_once 立刻报「被加了 2 次」。
  • 四方拓扑必须全网状,不能星型。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,否则管道断/死锁。
  • 定点尺度挂到 IR 的值上。mpc 的密文是 真实值 · 2^((k+1)·fxp),k 是尺度。 乘公开系数把 k 推到 1,必须 trunc 才回 0;漏了不是崩溃,是结果差 2^fxp 倍。 现在 add 会拒「k=3 与 k=2 相加」,构造期就报。 整数系数走 ScaleInt(裸乘,0 轮),不是 Scale —— 第一版搞混过,差 2^fxp 倍。
  • 协议序列不再手写。mpc-ml 与 mpc-sql::secure 都改成「建图 → 编译 → 执行」, 轮数由 Plan::rounds() 报(mpc plan / mpc sql-plan)。 改这些 crate 的计算逻辑时,图和手写序列之间的迁移回归在 crates/*/tests/migration.rs:帧序列相同 + 数值在舍入预算内。 判据不是「逐位相同」 —— truncate 是随机舍入,同一段手写代码换 seed 结果都变。

性能基线(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/mpc-core/tests/golden_vectors.rs (215 条)
                                         # → crates/mpc-he/tests/golden_paillier.rs (50 条)
cargo test -p mpc-core --test golden_vectors
cargo test -p mpc-he --test golden_paillier

n 方(P1.2)与 Ray 编排(P5)

# 三方本机
python3 deploy/ray/mpc_cluster.py --sites alice,bob,carol \
    --data alice=2,bob=3,carol=5 --mpc ./target/release/mpc --local
# 只看参数(不起进程)
... --dry-run
# 真集群(actor 按 {site}_node 资源标签落机器)
... --address ray://<head>:10001

--local 是刻意保留的:编排里唯一容易写错的是端口分配/peers 字符串/命令拼装, 这些与 Ray 无关。能本机验证的先本机验证,别让"参数拼错"和"Ray 没配好"混在一起排查。

Ray 模式尚未在真实多机上验证过。

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

  • mpc-tee TA/CA。判据:正常世界串口 ALL OK(provision → seal → unseal → 篡改被拒 → sign → attest)。

依赖

全项目唯一外部依赖:curve25519-dalek(在 mpc-psi)。 理由:X25519 必须恒定时间实现,手写会被时序侧信道攻击。 mpc-he 手写 bigint 零外部依赖。

文档

  • docs/ARCHITECTURE.md — 分层、Ray 定位、TEE 定位(每条结论附"为什么不是另一种做法")
  • docs/IR.md — mpc-ir:为什么需要这一层、轮数怎么数(含踩过的坑)、变异验证
  • docs/COMPARE_SECRETFLOW.md — 与隐语全栈逐层对照 + 缺口分档
  • docs/ZYNQ.md — Zynq-7015 性能预算、交叉编译、部署形态
  • refs/nax/ — Python 参考实现(只读)