Files
ssw-mpc/CLAUDE.md
T
admin 660e5712c3 feat(tee): 真机双机实跑复验,固化 /opt 物料基线与本机重建条件
用户要求「跑一遍,确保本地资源能用,别两台机器重启就找不到了」。
按固化的三步重跑(env 样例 → 预检 → e2e)在两台真机上实跑:

- 正向 e2e 全绿:从源码重编 musl mpc → 重新导出 alpine rootfs → 重新打
  initrd → 分发 → 双 KBS → 双 guest,TEE_PAIR_OK + TEE_ATTEST_GATE_OK
  + TEE_PAIR_ATTEST_OK,两侧还原 35.000000(2m05s)。
- 负向矩阵全绿:篡改度量 pin ⇒ 403 拒证明、guest fail-closed 拿不到密钥;
  恢复 pin ⇒ 又拿到(TEE_ATTEST_NEGATIVE_OK,exit=0)。
  ★ 修掉旧版单独跑报「缺少 MPC_TEE_MANIFEST」:负向脚本现在自动从
    ${MPC_TEE_WORK}/image 用同一份 oci-image.py verify 重算并断言 64 hex,
    不手抄;两个构造样例验证非法值 / 无产物都 exit=2。

持久化保障(回答「重启就找不到」):
- 实测两台真机 / 是 ext4 / xfs 持久根盘、无独立 /tmp tmpfs;远端三个
  /tmp 运行时目录本来全为空,e2e 每次重铺 ⇒ 丢了不影响重跑。
- 新增 host-materials.sh + nodes/host-materials.sha256(入仓基线 18 条:
  AMD 3 / 海光 15,sha256 + size):--verify 逐台比对,缺文件/被替换/
  被升级一律 FAIL 并打印 diff;--self-test 6 个构造样例证明非恒绿;
  另用「篡改清单一条 hash」端到端破坏验证(精确判红 exit=1)。
  ★ 清单只记路径/大小/哈希,不搬 69MB qemu / 78MB initrd 进仓库;
  清单本身由 git 保护。换机/升级后 --collect 重采。
- 预检新增「本机重建条件」检查:alpine:3.18 镜像、musl target、
  oci-image.py、guest/init.sh、fixtures、物料基线;缺一项即 FAIL。
  完整预检 29/0(含远端),离线 25/0 SKIP=1,自测 7/0,
  lint-shell-vars 34 脚本无隐患。

文档:真机 README 增「机器重启 / 换机后怎么办」分工表与症状速查一条;
INDEX §2/§3/§6 登记新资产与第 11 条纪律;CLAUDE.md 部署段加指针;
env 样例 H 段写明 manifest 两处都不许手抄。
校验:ci.sh 语法、判据零依赖自测 22/0、diff --check、密钥扫描全过。
门禁条数仍为 22(未改 ci.sh)。
2026-11-08 20:01:22 +08:00

37 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 与本地同一份闸门(22 条)

主门禁 ./tools/ci.sh 共 22 条:全量测试(必须带 --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)、 真 TEE 双 guest 会话判据自测(第 19 条;测的是真机上实际调用的那一份 check-pair-verdict.py,每条判据用构造样例逐条破坏,验证它能真的把结论推翻)、 真 TEE 证明门控判据自测(第 20 条;测的是真机上实际调用的那一份 check-attest-verdict.py;与第 19 条分开是因为两者互不蕴含 —— 会话跑成 ≠ 密钥是证明后给的)、 国密链真交易编码 / sendTransaction 判据(第 21 条;TARS 二进制、 r‖s‖pub 128B 签名、status==0 才成功)、 国密链真合约部署 / 调用 / 读回 / 负向矩阵(第 22 条; tools/selftest-fisco-contract.py,零依赖 --self-test 每次必跑;真链环境齐备时 真上链核对 isRecorded / hardRuleSummary,缺环境显式 FISCO_REALNODE_SKIPPED

  • 逐项缺失,绝不打印通过)。 明细以脚本自身为准(闸门不扫自己就是盲区)。

当前状态总览与文档索引见 docs/INDEX.md。链端点已迁至 k8s (192.168.1.26|27|29:30100,账本落 nfs-wuguirong PVC),配置见 tools/fisco-realnode/example.chain.json;本机 fisco-gm 已停、保留可回滚。

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
                    / fisco_tx(TARS 编码 + SM2 预哈希签名)/ opa(bundle 签发与判定)
              ★ 存证 fail-open(outbox 等补链),成员准入 fail-closed(缓存过期即拒),**两侧不许混**
              ★ 3.x **自有**端点:提交 `sendTransaction`(4 参 `[groupID,nodeName,data,requireProof]`)、
                读 `call` / `getTransactionReceipt`;`eth_call` / `eth_getTransactionReceipt`
                实测 method-not-found,别再按「eth_ 兼容端点」写。HTTP 200 + error 字段 = 失败
              ★ fisco_tx:交易编码是 **TARS 二进制不是 RLP**;`TransactionData` 哈希按固定字段
                顺序拼值再 SM3(零值字段也参与,与编码省略默认值相反);
                签名 = `r‖s‖pub` **128B**(后 64B 裸公钥不带 `04` 前缀);
                ★★ 签名对象是 32B `dataHash` 但节点 `fast_sm2_verify` 用
                `e = SM3(ZA‖dataHash)`(distid=`1234567812345678`,ZA 的曲线 `a=p-3` 末字节 `fc`
                须从 OpenSSL 曲线读,不许手抄),**不是签裸摘要** ⇒ `10008 InvalidSignature` 的真根因
              ★ 真链能力(2026-11-08 已实证):`mpc chain contract deploy|call|read`
                + `tools/selftest-fisco-contract.py`(第 22 条)在 FISCO 国密链上
                部署 `MpcHardRule.sol` → `recordHardRule` → 读回 → 负向矩阵,22/22 全绿
              ★ 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,域分隔不同、字段互相禁止
              ★ 仍**未落地**:真实 bcos-rpc 的 TLCP 通道(gate 18 服务端是环回 echo)、
                硬件模组 provider、OPA 在 guest 内执行、撤销链读后端、decision 上链。
                ★ 软件签名器私钥可导出 ⇒ **密评不可过**,真链能上链 ≠ 生产可用
              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 二进制有三种形态,别混(2026-11-07):mpc-cli 同时是宿主 CLI 与 TEE guest 里的静态代理。

形态 编译命令 跑在哪 含什么
宿主 默认(control-plane) 开发机 / 站点 hostd + link + chain
guest --no-default-features TEE enclave 内 只有 guest 命令族
host --no-default-features --features host-only TEE 真机上的 hostd 加 hostd,不含 chain
  • guest 端只用 mpc tee attest-collect|attest-post|attest-check|kbs-get|verify|selfcheck 这一族,全部在 main.rs。宿主端才有 mpc hostd / link / chain 与 mpc tee up|ps|attest|down。
  • host 形态为什么存在:TEE 真机(海光 / AMD)没有 Rust 工具链, 而 hostd 必须跑在真机上(要 qemu、要起 guest 进程)⇒ 需要一份自包含静态二进制。 mpc-hostd 依赖里只有 axum/tokio/reqwest(reqwest 关默认特性 ⇒ 不带 TLS), 只有 mpc-chain 带 openssl ⇒ openssl 不能进 musl 依赖图 (进了会让 openssl-sys 的 pkg-config 抢先于 compile_error! 守卫 ⇒ 守卫变假判据)。
  • build.rs 算出两个 cfg:mpc_control_plane(hostd+link,musl 可静态编)与 mpc_chain_plane(chain,要 OpenSSL,musl 不可进)。源码不抄八遍条件。
  • 交叉编译 guest 必须 --no-default-features。忘了加会被 main.rs 的 compile_error! 明确挡下。
  • 判据唯一真相源 tools/check-guest-artifact.py(主门禁第 4 条): deps 验依赖树边界(含 musl+host-only)、guard 验编译期拒绝且带 期望特征、binary 验 ELF 无 PT_INTERP + guest 标识全在 / 控制面标识全不在。 ★★ 标识串按归属分五组(guest 族 / hostd 独有 / hostd 链接 / 链路层 / 链上层), 且 binary 同时吃两份产物(guest + host)做交叉对照:
    • 「guest 里找不到 X」是否定式判据,天然有恒为真的风险 (release+strip+LTO 会把串裁掉 ⇒ 探针坏了照样绿);
    • 用 host 产物先证明「X 确实会进二进制」,再据此在 guest 上跑否定判据;
    • host 产物里找不到 ⇒ 探针失效 ⇒ 直接 FAIL,绝不「安静地跳过」;
    • ★ 不能拿「main.rs 帮助文本里提到过的词」当负向标记 (mpc-hostd / allow-remote 在 guest 产物里也会有,那是帮助文本不是代码链接);
    • ★ eth_sendRawTransaction / 1234567812345678 在 musl host 产物里也找不到 (host 不含 chain)⇒ 拿它们判 guest 必然恒为真,不许用。
  • 真机脚本里 MPC_BIN 指向的就是这份 musl 产物,宿主 KBS 也用它跑 attest-check —— 两边要的命令都不依赖控制面,切分不影响「先验证明才给密钥」。

★ hostd 服务端鉴权(2026-11-07 落地,之前是真缺口): 改之前 client.rs 只在客户端拼 Authorization: Bearer 头,服务端根本不验; 之所以没出事只因默认只听回环。现在 crates/mpc-hostd/src/auth.rs:

  • 回环信任模式(未配共享密钥):不带凭据放行,带了任何凭据一律 401; 凭据模式(已配):每个请求都必须带正确 Bearer token,缺/错一律 401。
  • 服务端不存明文,只存 sha256(secret);客户端送明文,服务端算摘要再比 ⇒ 摘要不能反向当 token 用(有单测钉死)。最低 32 字节,低于则启动期硬拒; 比对用 mpc_core::hmac::ct_eq(常量时间)。
  • 对外不区分「没带」与「带错了」(public_reason() 统一文案,细分只进日志) —— 否则等于给攻击者「差多少」的反馈。
  • ★ 鉴权先于路由:任何端点(含 /health)都先过凭证判定; 业务端点 POST /sandboxes 也必须受保护(只护 /health 是假安全)。
  • 非回环监听必须同时有共享密钥 + 显式 --allow-remote,两者互为兜底 (只有 --allow-remote 时它只是一句声明,不构成任何保护)。
  • ★ 共享密钥是静态的,只能证明「你是我认识的那个站点端」; 设计中的「站点端签发的短期 token」(session_admit() 产物)还没落地。 hostd 仍是明文 HTTP,密钥在网路上是明文传输(除非走 EasyTier/内网)。
  • ★ DELETE /sandboxes/{id} 必须真删记录(runtime.remove():先 stop 收进程、 再删记录与子进程句柄,顺序反了会留僵尸)。原来只调 stop() ⇒ 删完还能在 GET /sandboxes 里看到它 —— 症状极静默(204 看着成功,列表越积越多)。

★ 真机实证结论(2026-11-07,两台真机实测) —— 详见 docs/REAL_MACHINE_FINDINGS.md:

  • 海光 CSV 官方 SM2 签名不覆盖 MAC 字段:把报告 MAC(0x9D4 起)末字节翻转后, 官方 verify-attestation 输出与原报告逐字节相同、仍 verify success。 ⇒ 仓库 wrapper 里那条 attestation report MAC verify failed 是永不命中的死判据, 已去掉虚假安全感措辞,并把该边界固化成判据 (selftest-csv-verify.py 的「已知边界:MAC 不在 SM2 签名覆盖内」)。
  • 海光官方验签器缺证书时会联网从 cert.hygon.cn 下载 hrk/hsk_cek, 下载成功就报 validata cert chain successful ⇒ 「我们提供的信任材料」根本没参与 链验证,链结论其实来自网络。⇒ wrapper 在链校验模式强制 unshare -rn 断网, unshare 不可用就拒(不退回联网模式),并本地前置校验关键证书齐全。
  • AMD SNP 侧用当前 HEAD 的五关闭环已在真机跑通(双向替换:initrd 里的 guest mpc 与 KBS 判定器都用当前 HEAD 的 musl 产物 ⇒ 验证方与放行方同源): 采报告 ok → KBS 判定 ok=True structure_ok=True bound_ok=True chip=verified → 凭 token 取 3 把密钥全 200 → key_source=kbs;guest 自检 5 项全过。 负向逐条被拒:错 pubkey(重放)/ 错 session / 错 manifest(度量 pin)/ TCB 门槛。
  • ★ TCB 关必须单独可达:设 MPC_TEE_MIN_TCB=99 时拒在更早一层 (mpc tee plan 节点准入),根本没走到 KBS。要测到 KBS 侧的 TCB 关, 必须 --tcb 3(实际值,参与绑定值重算)+ --min-tcb 99(门槛)—— 两者混用会把「参数漏传」报成「重放攻击」。
  • ★ 跨平台:同一份代码派生的 user_data 前半段(代码度量+平台标签+TCB) 在 AMD SNP 与海光 CSV 上逐字节相同;验证方必须用同一份 node 描述重算。
  • 诚实边界:CSV 侧没跑「先验证明才给密钥」全链路(只到采报告+验签+负向); AMD 机是 SNP guest 虚机(内核 6.13.0-snp-guest),不是裸机。

★ 异地站点端 → TEE 真机的控制面闭环(2026-11-07 实测): 沙箱(CubeSandbox)当异地站点端,通过 e2b 兼容 HTTP 面驱动海光真机上的 hostd, up/ps/attest/down 全链路跑通,鉴权正负向矩阵全绿。

  • ★ 沙箱不能走 SSH:无 ssh/sshpass(openssh-client 无安装候选)、DNS 完全不通、 pip install paramiko 失败;更根本的是明文密码不能进沙箱 ⇒ 只能走 HTTP 面。
  • ★ hostd 必须跑在真机(要 qemu / TEE 设备、要起 guest 进程),沙箱是站点端。
  • ★ CubeSandbox 数据面三要素缺一不可:CUBE_API_URL + CUBE_API_KEY + CUBE_PROXY_NODE_IP=192.168.1.30 + CUBE_PROXY_PORT_HTTP=80 (缺后两个 ⇒ SDK 回落直连 49983-<id>.cube.app,本机 DNS NXDOMAIN ⇒ httpx.ConnectError: [Errno 8] nodename nor servname provided)。
  • ★ egress 策略是「替换不是补丁」:update_network({"allow_out": ["192.168.1.0/24"], "allow_internet_access": False}) 才放通内网;默认策略下所有目标 Connection refused 且耗时 0.00s(立即拒绝 ≠ 网络不可达,判读时必须区分)。
  • ★ 沙箱驱动的实例不是真 TEE enclave(起的是真机上的普通进程)⇒ 四布尔必然全 false。 这验证的是控制面编排,不是 TEE 证明链 —— 别混淆。

★ 真 TEE 全流程:跨物理机双 guest 密文会话(2026-11-07 首次跑通): AMD SEV-SNP(192.168.1.7,alice)与海光 CSV(192.168.1.102,bob)跨两台物理机, 各自在真加密 VM 内完成 PSK 双向认证 + ChaCha20-Poly1305 密文会话, 两侧都还原出 value | 35.000000,判据 TEE_PAIR_OK。 一键复现:deploy/tee/real-machine/tee-pair-e2e.sh。

  • ★ guest halt 之后 qemu 不退出 ⇒ 前台 ssh 起 guest 会永久挂死 (会话其实已成功、判据一行没跑到 ⇒ 假红)。起 guest 一律走 guest-watch.sh:后台起 + 轮询串口里的 MPC TEE GUEST DONE + 显式 kill qemu。
  • ★ guest 的 stdout 默认会丢(框架 argv 是 -nographic + -serial stdio, 两个前端抢同一个 stdio)⇒ env.sh 必须注入 MPC_TEE_SERIAL_LOG, run-guest.py 把串口换成 chardev file 后端。
  • ★ 采集回来的日志会被掩码:xop 的密钥泄漏防护把 root 误判成密钥片段, rootfs_files: verified → ro****【xop禁止将密钥泄漏】fs_files: verified ⇒ 判据只认稳定后缀 fs_files / fs_links。
  • ★ 判定只有一份实现:deploy/tee/real-machine/check-pair-verdict.py (pair-run.sh 与主门禁第 19 条自测调的是同一份;两份实现等于没有门禁)。 每条判据都被 tools/selftest-tee-pair-verdict.py 逐条破坏过 (验证它能真的把结论推翻)—— 负向判据自指是常态,不是意外。
  • ★ 本轮跑的是离线演练密钥(key_source=offline-demo)⇒ 不宣称密钥分发链路; pair-run.sh 不做芯片证明互验 ⇒ 不宣称两端互验过对方芯片报告。 详见 docs/REAL_MACHINE_FINDINGS.md 第 9 节。

★★ 证明门控合流:芯片证明链与密文会话在同一次运行里打通(2026-11-08): AMD SNP(alice)+ 海光 CSV(bob)两侧各自完成 attest-collect → attest-post(KBS 芯片验签放行)→ key_source=kbs → 跨物理机密文会话, 两侧都还原出 value | 35.000000,判据 TEE_PAIR_OK + TEE_ATTEST_GATE_OK,EXIT=0。 一键复现:deploy/tee/real-machine/tee-pair-attest-e2e.sh; 负向:tee-pair-attest-negative.sh(度量 pin 不符 ⇒ 证明被拒且拿不到密钥, 恢复后又能拿到,带期望的拒绝特征,不是只判 rc≠0)。 详见 docs/REAL_MACHINE_FINDINGS.md 第 10 节。

  • ★ 两张网卡不能合成一张:跨 guest 会话走 qemu socket(二层点对点, 只要 IP 无路由),访问宿主 KBS 走 tap(三层,必须有同网段地址)。 合成一张 ⇒「会话通了但取不到密钥」或「密钥到手但会话不通」, 两种症状都像 KBS 挂了,排查方向会被整个带偏。
  • ★ 网卡按 MAC 认,不按枚举顺序:/sys/class/net 顺序 = PCI slot 顺序, 会漂 ⇒ 认错卡 ⇒ 偶发失败(比稳定失败难查得多)。认不到就 die。 两侧数据面 MAC 必须不同(同一二层域里抢同一个链路层地址 ⇒ IPv6 冲突, 而且会话照样跑通 —— 没判据等于没这回事)。
  • ★ 两侧各起一个 KBS(不共用):KBS 要在本机做芯片验签,验签器与证书链 只在本机 /opt 下才有。共用 ⇒「把海光的报告拿到 AMD 机上验」,验的就不是本机的芯片。
  • ★★ 框架层真缺陷:连接等待窗口两侧不对称(本轮最深的坑)。 被动方(--listen)原来无限等,主动方(--connect)硬编码 50 × 200ms = 10 秒 —— 而被动方要先做 SNP 证明验签(联网拉 KDS 证书链, 首次可达 90s)才 bind ⇒ 必然 Connection refused。 症状极具误导性(像「网络不通」,实为窗口配小)且看运气 (KDS 链有缓存时跑绿、缓存一失效就必挂)。 修法:mpc_node::SESSION_WAIT_BUDGET_SECS = 180,两侧同一常量, 新增 connect_within / accept_within(按时长给预算,不是「次数 × 间隔」), CLI 侧 wait_budget() 可用 MPC_SESSION_WAIT_SECS 覆盖(两侧必须一致)。 accept 不再无限等 ⇒ 「对端永远不来」能报错,而不是挂死到看门狗 (挂死只看到 GUEST_TIMEOUT = 被杀的表象,不是原因)。 3 条守卫测试钉死(注释挡不住任何人把 50 改回去)。
  • ★ 编排层的「假就绪信号」:等「宿主 qemu 端口进 LISTEN」不等于 「guest 内 mpc 已 bind」—— qemu 一启动就 listen。guest 内 mpc 的就绪时点 = 芯片证明验签完成之后。
  • ★ 手抄 hex 常量的长度必须程序断言:本轮手写三个密钥长度是 66/65/63 (正确 64),报错说「格式不对」,真实原因是「抄错一个字符」—— 误导会把排查带偏。
  • ★ 证明提交超时必须大于 KBS 判定超时:guest 读 10s < KBS 判定 30s ⇒ guest 必然先超时,症状 os error 11(EAGAIN,不像超时,极易误判成「KBS 挂了」)。 已改 ATTEST_POST_TIMEOUT_SECS = 90。

链路层不引任何 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/INDEX.md:仓库文档体系的分类(活真相源 / 专题设计 / 历史阶段快照)、 当前状态总览、权威入口表、容易读错的旧结论对照、更新纪律都在那里。 找不到东西先看它,不要在正文里翻。

活状态与唯一真相源

  • README.md — 项目门面;「现状(2026-10-30 算子基线 + 2026-11-08 增量)」是当前能力总表
  • docs/INDEX.md — 文档索引 + 当前状态快照(本文所指)
  • docs/ARCHITECTURE_SYSTEM.md — 系统架构当前形态:组件清单 / 双层控制面 / 会话主键 / 端到端数据流 / 部署拓扑 / 平台矩阵 / 诚实边界;拆解自 INTEGRATION_ANALYSIS.md,用 [实证][桩验][设计][禁用] 区分实证与蓝图。 docs/ARCHITECTURE.md 只讲计算分层「为什么」,别混着读
  • docs/ARCHITECTURE_SYSTEM.html — 上者的可分享单文件 HTML,由 tools/render-share-html.py 生成;派生产物勿手改,改 md 后跑 python3 tools/render-share-html.py --check 校验同步
  • docs/FISCO_UPSTREAM_TRUTH.md — 国密链上游事实唯一真相源:TARS 编码、 e = SM3(ZA‖dataHash) 签名口径、sendTransaction 4 参、status==0、selector 二元数组
  • docs/REAL_MACHINE_FINDINGS.md — 两台真机硬事实;第 10 节是证明门控合流 (第 7 / 9.4 节是 11-07 当时边界,已加状态锚点)
  • tools/ci.sh — 门禁条数以脚本为准(22 条),任何文档写的条数都以此校准
  • tools/selftest-fisco-contract.py — 真链验收唯一权威脚本(第 22 条)
  • tools/fisco-realnode/example.chain.json — 链配置(k8s 192.168.1.26:30100)

专题设计(结论稳定,不含进度)

  • docs/ARCHITECTURE.md — 分层、Ray 定位、TEE 定位
  • docs/IR.md / docs/N_PARTY.md / docs/COMPARE_SECRETFLOW.md / docs/ZYNQ.md
  • docs/TEE_DIRECT_LAUNCH.md / docs/TEE_OCI_PATH.md / docs/OPTEE_VERIF_PLAN.md
  • docs/RAY_CORE.md / docs/RAY_CORE_101.md / docs/RAY_ARMV7.md / docs/PG.md
  • docs/OPT_PLAN.md / docs/GAP_PLAN.md(后者是 2026-10-30 改名前缺口计划,已加归档声明)

历史阶段快照(读之前先看顶部状态提示,别当现状)

  • docs/INTEGRATION_ANALYSIS.md — 2026-11-07 决策定稿与实施方案;决策台账仍生效, 但「18 条门禁 / 不宣称能上链 / 合约部署未做」已被后续提交推进,顶部有对照表

部署与复现

  • deploy/k8s/fisco/README.md — 链迁 k8s 的 SOP、账本迁移、持久化证据、回滚与边界

  • deploy/tee/real-machine/README.md — 真机证明门控 + 双 guest 会话 e2e 复现; 开头「重跑前先看」 有重跑三步、参数真相源、症状 → 根因 → 处置速查表

  • deploy/tee/real-machine/real-machines.env.example — 双机参数唯一集中入口 (IP / xop 键名 / MAC / 网段 / 端口 / 超时),脱敏可 source;换机器改这一份, 别逐个脚本 export。real-machines.env 是本地实际配置,已 gitignore

  • deploy/tee/real-machine/preflight-real-machine.sh — 重跑前一次性报缺 (工具 / xop 键 / 本机重建条件 / 参数一致性 / 远端物料);--self-test 负向矩阵, 缺环境显式 SKIP/FAIL

  • deploy/tee/real-machine/host-materials.sh + nodes/host-materials.sha256 — 两台真机 /opt 不可再生物料的入仓基线(18 条 sha256);重启后 --verify 逐台比对,换机 / 升级后 --collect 重采。远端 /tmp 是每次 e2e 重铺的运行时目录, 丢了不用管;README「机器重启 / 换机后怎么办」有完整分工表

  • demo/k8s/README.md — 站点部署与 PVC 持久化

  • tools/fisco-realnode/README.md — 真链复现工具索引、环境变量、审计轨迹、密钥边界

  • refs/nax/ — Python 参考实现(只读)