Files
ssw-mpc/CLAUDE.md
T
admin ccf74fc3cd feat(opa): 链上撤销状态位读取落契约,未接入即 fail-closed 拒
- opa.rs 新增 RevocationViewSource{CallerSupplied,ChainRead} + ChainRevocationReader
  + UnconfiguredRevocationReader + resolve_revocation;decide 撤销来源二选一
- 链读后端未接入时声明 chain 必拒(REVOCATION_CHAIN_UNVERIFIED),
  绝不默认 revoked=false 放行;撤销仍 fail-closed 且无缓存
- CLI 支持 --revocation chain,输出区分 chain-read / 本地桩两种来源标注
- 第 17 条判据扩到 41 真闭环 + 22 零依赖,新增链读 fail-closed 负向
- CLAUDE.md / INTEGRATION_ANALYSIS.md / MEMORY.md 同步撤销来源与诚实边界
2026-11-07 19:58:18 +08:00

20 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
# ★ guest 静态产物:musl 目标必须显式 --no-default-features
cargo build --release -p mpc-cli --target x86_64-unknown-linux-musl --no-default-features
./tools/ci.sh                                     # CI 与本地同一份闸门(18 条)

主门禁 ./tools/ci.sh 共 18 条:全量测试(必须带 --features secure)、 -Dwarnings 零告警(作用于 test/bench/example 目标)、mpc-core / mpc-tee no_std 双守 + TA UUID 对拍、musl 跨目标零告警 + guest 边界探针、12 示例冒烟、 shell 卫生、OCI 链、KBS、ash 语法、SNP 验签器、OP-TEE 判据逻辑、 hostd / 链路层 / 链上层端到端桩自测、国密签名与治理形状自测、 GmSSL TLCP 真握手 / TA 密钥分级 / FISCO 真机对拍契约(第 16 条)、 阶段 3 OPA bundle 签发 / 真判定 / decision 存证(第 17 条; 缺环境一律显式 *_SKIPPED + 逐项缺失,绝不静默通过)、 TLCP 进程通道环回实证(第 18 条;Rust 侧 spawn gmssl tlcp_client 经 TLCP 收发真实 JSON-RPC 给环回 echo 服务端,断言往返一致; realChainVerified 恒 false,输出 BCOS_RPC_NOT_VERIFIED)。 明细以脚本自身为准(闸门不扫自己就是盲区)。

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)
              session(证明绑定)/ schedule(准入)/ site_admit(站点侧)/ link(链路判据)
              TrustPlan 四级可信度,**按 n 方算**:for_parties(&[PartyTee], TrustPolicy)
                L0 全体无 TEE / L1 部分方有 / L2 全体互验(可明文直算)/ L3 全有但不开直算
              ★ 零 crates.io 依赖:要被拷进 OP-TEE SDK 做 armv7 离线交叉编译
  ───────────
mpc-hostd     宿主控制面(两层控制面的宿主层):e2b 兼容 API + TeeRuntime + /attestation
              ★ 带第三方依赖的两个 crate 之一:axum / tokio / reqwest(见「依赖」)
              模块:api / server / client / protocol / runtime / json / link(EasyTier 进程层)
              ★ link 只 spawn 外部二进制,绝不链接 easytier-* crate(LGPL,见「依赖」)
  ───────────
mpc-chain     链上层:对象规范编码 / SM3 / JSON-RPC / 幂等 outbox / 准入 / 国密签名 / 治理形状
              模块:objects / rpc / outbox / admission / signer / sm2 / tlcp / policy
              ★ 存证 fail-open(outbox 等补链),成员准入 fail-closed(缓存过期即拒),**两侧不许混**
              ★ 3.x RPC 是 eth_ 兼容端点(EthMethods.h);HTTP 200 + error 字段 = 失败
              ★ sm2:OpenSSL 软件 SM2 真签名(DER→raw r||s 64B);distid 唯一真相源在 mpc-core
              ★ signer:SoftwareDev / HardwareModule 两档;生产策略只认硬件模组,
                软件签名器密评不可过、必须显式选 DevelopmentSoftware 并透出警告
              ★ tlcp:双证书契约 + 环境探测 + fail-closed;本机 GmSSL 环回通道已实证可达
                (LoopbackReachable,gate 18 进程通道),但真实 bcos-rpc 通道未通
              ★ policy:硬规则进合约 / 业务合规策略走 OPA,域分隔不同、字段互相禁止
              ★ RLP 编码 / 真实 bcos-rpc TLCP 通道 / 硬件模组 provider **未落地**:Rust 侧
                TLCP 进程通道环回实证已落地(gate 18,服务端是环回 echo 不是真节点);
                flush 仍发规范字节,不是已签名交易。本期不宣称能上链。
              serde_json + reqwest + openssl 只落在本 crate(见「依赖」)
  ───────────
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)。

依赖

核心计算层零外部依赖:mpc-core / mpc-tee / mpc-he 等全部手写, mpc-psi 的 curve25519-dalek 是唯一允许的外部密码学 crate(X25519 必须恒定时间实现, 手写会被时序侧信道攻击)。

两个例外是 mpc-hostd 与 mpc-chain(2026-11-07):宿主控制面用 axum + tokio + reqwest 接管 HTTP/1.1(约 100 个传递依赖);链上层用 serde_json + reqwest 做 JSON-RPC。都只许待在各自的独立 crate 里。

[修正] mpc-chain 现在引 openssl(用户 2026-11-07 拍板「先用 openssl 做」): SM2 签名走系统 OpenSSL 的 EVP 接口(openssl crate 链接系统库,本机 4.0.3 实测可签)。 边界要说准 —— 这是系统 OpenSSL 的软件签名,不是国密模组 FFI、不是 Tongsuo TLCP:

  • 软件私钥可导出、密评不可过;SignerPolicy::ProductionModule 一律拒绝它;

  • 国密模组 provider(独立 OSSL_LIB_CTX、私钥不可导出)与 Tongsuo TLCP 握手 FFI 仍未落地,到位后也只加在 mpc-chain 这一层;

  • 依赖仍不许扩散到 mpc-core / mpc-tee / TA 侧。

  • 硬理由:build/build_optee.sh 会把整个 crates/mpc-tee 拷进 OP-TEE SDK 的 workspace 做 armv7 离线交叉编译。哪怕把依赖标成 optional,Cargo 解析阶段 仍要能拿到 crate,没网就挂。所以 mpc-tee 连 build.rs 都不留。

  • 自查:cargo tree -p mpc-tee --no-default-features 应只剩 mpc-core。

  • 禁止把 HTTP/异步运行时/JSON 依赖扩散到 mpc-core / mpc-tee / TA 侧。

  • mpc-chain 的 .no_proxy() 不许删:控制面只连配置里的 host:port, 系统代理会把这一跳端点换掉(也让国密 TLS 的实测结论失效),门禁第 14 条有回归探针。

  • --transport / --policy 没有默认值:明文传输与软件签名器都必须显式选择, 不许留「没传就悄悄降级」的后门。门禁第 15 条有回归探针。

  • 国密链提交方法是自有 sendTransaction(4 参)。eth_sendRawTransaction 是 secp256k1 + keccak256 的 web3 端点,国密链禁用(rpc.rs 守卫 + 第 14 条 4 条判据);上一版「sendTransaction 搜不到」是搜索假阴性,勿回退。 sm2Verify(bytes32,bytes,bytes32,bytes32) 是 4 入参,message 为 32B 摘要, distid 不在 ABI(链上不可配),只能链下对齐 + 真机对拍。

  • GmSSL 3.2.0 让本机 TLCP 环回真握手跑通(第 16 条 19 判据: Protocol: TLCP / Version: TLCP (0101) / 双证书)。但 3.x 不与 OpenSSL ABI 兼容,不能当 provider 喂给 reqwest;本机握手通过 ≠ bcos-rpc 通道已通, TlcpReadiness 已从 NeedsFfi 推进到 LoopbackReachable(第 18 条进程通道: Rust 侧 spawn gmssl tlcp_client 经 TLCP 收发真实 JSON-RPC,环回 echo 实证可达), 但仍非 Ready、ready 恒 false、发真交易仍 fail-closed。软件实现不能过密评。

  • TA 签名密钥三级硬拒绝已落地:build_optee.sh --check-only 在 SDK 检查之前 解析,prod 缺密钥绝不回落 default_ta.pem;第 16 条 16 判据在没 SDK 时也测得到。

  • 阶段 3 第一段已落地,但不是「阶段 3 完成」:mpc_chain::opa 对真的 opa build 产物做 SM2 真签 + SM3 hash pin,真 opa eval 判定,decision 幂等落 outbox。★ undefined 输出({})必须拒绝,不许当默认 deny(策略没加载 ≠ 策略拒绝);input 缺 source 在调 OPA 之前拒;合规判定 fail-closed 且无缓存; 撤销来源分两类:调用方本地桩(每次显式给、新鲜度有 TTL)或 --revocation chain 声明走链上撤销状态位读取(ChainRevocationReader + UnconfiguredRevocationReader)。 ★ 链读后端未接入 ⇒ 声明 chain 即 fail-closed 拒(REVOCATION_CHAIN_UNVERIFIED), 绝不默认 revoked=false 放行。★ 诚实边界:OPA 跑在宿主/控制面不在 guest 内,撤销链读后端未接入,decision 未签名未上链。 第 17 条 41 判据 + 22 条零依赖自测,成功也只输出 OPA_GUEST_NOT_VERIFIED / CHAIN_NOT_VERIFIED。软件签名器生产策略仍必拒。

★ mpc 二进制有两种 profile,别混(2026-11-07):mpc-cli 同时是宿主 CLI 与 TEE guest 里的静态代理。宿主端 mpc(默认 control-plane)才有 mpc hostd / link / chain 与 mpc tee up|ps|attest|down;guest 端 只用 mpc tee attest-collect|attest-post|attest-check|kbs-get|verify|selfcheck 这一族,全部在 main.rs。因此:

  • mpc-hostd / mpc-chain 是 control-plane 的可选依赖,且按 [target.'cfg(not(target_env = "musl"))'.dependencies] 排除 musl; build.rs 算出唯一 cfg mpc_control_plane,源码不抄八遍条件。
  • 交叉编译必须 --no-default-features。忘了加会被 main.rs 的 compile_error! 明确挡下;因为 musl 下 openssl-sys 根本不进依赖图, 守卫能被真正执行到,不会先撞上含混的 pkg-config 报错。
  • 判据唯一真相源 tools/check-guest-artifact.py(主门禁第 4 条): deps 验依赖树边界(不依赖 target 是否安装)、guard 验编译期拒绝且带 期望特征、binary 验 ELF 无 PT_INTERP + guest 标识全在 / 控制面标识全不在。 ★ 三条都做「标识串源码存在性自检」,防止改名后探针退化成空判据。
  • 真机脚本里 MPC_BIN 指向的就是这份 musl 产物,宿主 KBS 也用它跑 attest-check —— 两边要的命令都不依赖控制面,切分不影响「先验证明才给密钥」。

链路层不引任何 EasyTier crate:mpc_hostd::link 只 Command::spawn 外部二进制 (独立程序 + CLI/RPC 是 LGPL 明确许可的用法),mpc_tee::link 是 no_std 协议层。 静态链接 easytier-* 会把整个 mpc 二进制拖进 LGPL —— 这是唯一不能碰的一档。 分发 EasyTier 二进制时须随包附 LGPL 文本与源码获取方式。

  • 决策过程与取舍见 docs/INTEGRATION_ANALYSIS.md 第 6 节。

文档

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