From 49b421c23abf520c72e832b5ef0aaf5fdeddcce8 Mon Sep 17 00:00:00 2001 From: admin Date: Thu, 5 Nov 2026 20:55:07 +0800 Subject: [PATCH] =?UTF-8?q?feat(examples):=20=E6=96=B0=E5=A2=9E=20mpc-exam?= =?UTF-8?q?ples=EF=BC=8C12=20=E4=B8=AA=E5=9C=BA=E6=99=AF=E5=AF=B9=E9=BD=90?= =?UTF-8?q?=20nax/examples?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新 workspace 成员 examples/(crate mpc-examples,publish = false):一场景一 bin, 跑法 cargo run -p mpc-examples --bin 03_vertical_lr;src/lib.rs 只提供参与方启动、 定点编解码、输出与断言,算法全在正文,调的是 mpc-* 真接口 - 12 个场景:01 密文四则/矩阵/sigmoid、02 PSI、03 纵向 LR、04 FedAvg、05 出域策略、 06 DP-FedAvg、07 密文推理、08 PIR、09 SCQL、10 分箱 WOE/IV、11 试跑、12 两方部署 - 12 的部署物在 examples/12_k8s_two_party/:多阶段 Dockerfile + namespace / alice(Headless Service + Job,--listen)/ bob(Job,--connect)+ README; 单二进制一条 TCP,不经 Ray,调度交给 k8s - tools/ci.sh 加第 4 关「示例冒烟」,调新增的 tools/examples.sh:逐 bin 跑, 判据为退出码 0 且输出无 [!!](check() 只打印不中断,只看退出码会漏断言) - 正文记录三条实测契约:matmul_trunc 两入参都须是分片,否则结果翻倍; sigmoid_poly 只在 ±6 内有效,越界发散到 1e6;多项式输出须先 reveal 再解码 - 实测:07 密文与明文偏差 1.97e-5 且 AUC 一致;09 密态与明文逐组一致; 11 同为 4 组 GROUP BY,逐组比较 156 轮 vs 整数码 23 轮 --- Cargo.lock | 19 + Cargo.toml | 2 +- README.md | 32 ++ examples/12_k8s_two_party/Dockerfile | 30 ++ examples/12_k8s_two_party/README.md | 86 ++++ .../12_k8s_two_party/k8s/00-namespace.yaml | 8 + examples/12_k8s_two_party/k8s/10-alice.yaml | 80 +++ examples/12_k8s_two_party/k8s/20-bob.yaml | 57 +++ examples/Cargo.toml | 25 + examples/src/bin/01_hello.rs | 218 ++++++++ examples/src/bin/02_psi.rs | 113 +++++ examples/src/bin/03_vertical_lr.rs | 138 ++++++ examples/src/bin/04_fedavg.rs | 122 +++++ examples/src/bin/05_policy.rs | 141 ++++++ examples/src/bin/06_dp_fedavg.rs | 147 ++++++ examples/src/bin/07_secure_mlp.rs | 219 +++++++++ examples/src/bin/08_pir.rs | 134 +++++ examples/src/bin/09_scql.rs | 323 ++++++++++++ examples/src/bin/10_hetero_binning.rs | 232 +++++++++ examples/src/bin/11_dry_run.rs | 204 ++++++++ examples/src/bin/12_k8s_two_party.rs | 202 ++++++++ examples/src/lib.rs | 465 ++++++++++++++++++ tools/ci.sh | 17 +- tools/examples.sh | 60 +++ 24 files changed, 3068 insertions(+), 6 deletions(-) create mode 100644 examples/12_k8s_two_party/Dockerfile create mode 100644 examples/12_k8s_two_party/README.md create mode 100644 examples/12_k8s_two_party/k8s/00-namespace.yaml create mode 100644 examples/12_k8s_two_party/k8s/10-alice.yaml create mode 100644 examples/12_k8s_two_party/k8s/20-bob.yaml create mode 100644 examples/Cargo.toml create mode 100644 examples/src/bin/01_hello.rs create mode 100644 examples/src/bin/02_psi.rs create mode 100644 examples/src/bin/03_vertical_lr.rs create mode 100644 examples/src/bin/04_fedavg.rs create mode 100644 examples/src/bin/05_policy.rs create mode 100644 examples/src/bin/06_dp_fedavg.rs create mode 100644 examples/src/bin/07_secure_mlp.rs create mode 100644 examples/src/bin/08_pir.rs create mode 100644 examples/src/bin/09_scql.rs create mode 100644 examples/src/bin/10_hetero_binning.rs create mode 100644 examples/src/bin/11_dry_run.rs create mode 100644 examples/src/bin/12_k8s_two_party.rs create mode 100644 examples/src/lib.rs create mode 100755 tools/examples.sh diff --git a/Cargo.lock b/Cargo.lock index 8709f36..1118192 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -107,6 +107,25 @@ dependencies = [ "mpc-zkp", ] +[[package]] +name = "mpc-examples" +version = "0.1.0" +dependencies = [ + "mpc-core", + "mpc-data", + "mpc-fl", + "mpc-he", + "mpc-ir", + "mpc-ml", + "mpc-node", + "mpc-policy", + "mpc-psi", + "mpc-runtime", + "mpc-sql", + "mpc-tee", + "mpc-vault", +] + [[package]] name = "mpc-fl" version = "0.1.0" diff --git a/Cargo.toml b/Cargo.toml index 9a21ed5..7eba692 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [workspace] resolver = "2" -members = ["crates/*", "demo"] +members = ["crates/*", "demo", "examples"] [workspace.package] version = "0.1.0" diff --git a/README.md b/README.md index a424ed8..92d47cf 100644 --- a/README.md +++ b/README.md @@ -384,6 +384,37 @@ Paillier 的 50 条用例硬比密文 hex(给定相同明文与显式随机因 --- +## 示例:12 个场景 + +`examples/` 是一个独立 crate,一个场景一个 bin,共用一层只做「起参与方 / 定点编解码 / +打印 / 校验」的脚手架 —— 算法全在示例正文里,调的都是 `mpc-*` 的真接口。 + +```bash +cargo run -p mpc-examples --bin 03_vertical_lr # 单个 +tools/examples.sh # 全部(CI 第 4 关) +tools/examples.sh 09 10 # 按名字过滤 +``` + +| # | 场景 | 讲什么 | +|---|---|---| +| 01 | 密文四则 / 矩阵 / sigmoid | 定点、加性分片、`scale_public` 要自己截断、多项式逼近的收敛 | +| 02 | PSI | ECDH 双盲、交集之外的人谁都不知道 | +| 03 | 纵向 LR | 各方持不同列,PSI → 对齐 → 密态梯度下降 | +| 04 | FedAvg | 横向联邦聚合 + 责任链 | +| 05 | 出域策略 | exec / transfer / fetch 三个关口 + 审计留痕 | +| 06 | DP-FedAvg | 裁剪、加噪、RDP 记账;噪声太大 AUC 直接掉到随机 | +| 07 | 密文推理 | MLP 明文训练 + 密文前向;`matmul_trunc` 的两个入参都必须是分片 | +| 08 | PIR | Paillier 同态加权求和,问「第几条」但不告诉对方 | +| 09 | SCQL | JOIN 走 PSI、WHERE 是掩码不是过滤、明文引擎对拍、护栏拒绝越界查询 | +| 10 | 分箱 / WOE / IV | 切点不出方、one-hot 进密态、一次矩阵乘出全部箱计数、互补抑制 | +| 11 | 试跑 | `query_rounds` 报轮数(整数码 156→23 轮)、行数不影响轮数、定点乘法静默回绕 | +| 12 | 两方部署 | k8s 清单 + 本地等价演练 + 清单自检(站点顺序 / fxp / 端口 / PSK) | + +示例的断言失败会让脚本非零退出:`check()` 打 `[!!]`,`tools/examples.sh` 扫这一行。 +这是防止示例 rot 的唯一办法 —— 不挂 CI 的示例,三个月后就是一批编译不过的摆设。 + +--- + ## 目录 ``` @@ -420,6 +451,7 @@ crates/ ├── mpc-ray/ Ray C++ core 绑定(可选,std-only;默认不链接) │ 2.59 → docs/RAY_CORE.md;1.0.1(armv7 唯一可选)→ docs/RAY_CORE_101.md └── mpc-cli/ 单二进制 CLI +examples/ 12 个教学示例(独立 crate,一个场景一个 bin;进 CI) ray/ mpc_ray_shim.cc + build.sh(复用 pip wheel 的 _raylet.so,不走 bazel) refs/nax/ 参考实现(独立仓库,仅作基线) tools/ golden 生成 + numpy 基准 diff --git a/examples/12_k8s_two_party/Dockerfile b/examples/12_k8s_two_party/Dockerfile new file mode 100644 index 0000000..076212b --- /dev/null +++ b/examples/12_k8s_two_party/Dockerfile @@ -0,0 +1,30 @@ +# mpc 演示镜像 —— 单二进制,无运行时依赖。 +# +# 构建上下文必须是仓库根目录(要 COPY 整个 workspace): +# docker build -f examples/12_k8s_two_party/Dockerfile -t mpc:demo . +# +# MSRV 见根 Cargo.toml 的 rust-version。 +FROM rust:1.85-slim AS build +WORKDIR /src + +# 先只 COPY 清单,让依赖层能被缓存 +COPY Cargo.toml Cargo.lock ./ +COPY crates ./crates +COPY demo ./demo +COPY examples ./examples + +RUN cargo build --release -p mpc-cli && strip target/release/mpc + +FROM debian:bookworm-slim +# 只需要 glibc 与 ca-certificates;mpc 不发任何外部请求,证书是给将来留的。 +RUN apt-get update \ + && apt-get install -y --no-install-recommends ca-certificates \ + && rm -rf /var/lib/apt/lists/* +COPY --from=build /src/target/release/mpc /usr/local/bin/mpc + +# 非 root 跑:k8s 的 securityContext 也会再压一遍。 +RUN useradd --system --uid 10001 --create-home mpc +USER 10001 + +ENTRYPOINT ["mpc"] +CMD ["version"] diff --git a/examples/12_k8s_two_party/README.md b/examples/12_k8s_two_party/README.md new file mode 100644 index 0000000..0a07661 --- /dev/null +++ b/examples/12_k8s_two_party/README.md @@ -0,0 +1,86 @@ +# 示例 12:在 Kubernetes 上起两个参与方 + +本例是 `mpc` 的**真实分布式形态**:两个参与方各跑在一个 Pod 里,密文分片只留在 +自己的 Pod,明文不出域。业务代码与单机演示**完全一致**,变的只有 transport +(`Pipe` → `TcpTransport`)。 + +与 Python 版 nax 的 `12_k8s_two_party` 最大的不同:mpc 不需要 Ray。单二进制 + +一条 TCP 就够了,Ray 那套 `--resources={"alice_node":1}` 的资源打标在这里是多余的。 + +## 架构 + +``` +┌──────────────────────── mpc-demo namespace ────────────────────────┐ +│ │ +│ Job mpc-alice Job mpc-bob │ +│ ┌──────────────────────┐ ┌──────────────────────┐ │ +│ │ mpc node │ │ mpc node │ │ +│ │ --site=alice │◀── TCP ──────│ --site=bob │ │ +│ │ --listen 0.0.0.0:9449 │ --connect ...:9449 │ │ +│ │ --data=1,2,3,4 │ │ --data=5,6,7,8 │ │ +│ └──────────────────────┘ └──────────────────────┘ │ +│ ▲ │ +│ │ Headless Service mpc-alice:9449 │ +│ └── bob 通过 DNS 直连 Pod IP,不经 kube-proxy 转发 │ +└────────────────────────────────────────────────────────────────────┘ +``` + +两边挂同一个 Secret 做 PSK 认证;没配 PSK 也能跑,但既不认证身份也不加密链路。 + +## 文件 + +| 文件 | 作用 | +|---|---| +| `Dockerfile` | 多阶段构建,产出只含 `mpc` 二进制的 debian-slim 镜像 | +| `k8s/00-namespace.yaml` | 命名空间 `mpc-demo` | +| `k8s/10-alice.yaml` | 被动方:Headless Service + Job(`--listen`) | +| `k8s/20-bob.yaml` | 主动方:Job(`--connect`) | +| `../src/bin/12_k8s_two_party.rs` | 本地等价演练 + 清单自检(`cargo run -p mpc-examples --bin 12_k8s_two_party`) | + +## 跑起来 + +```bash +# 0) 先本地确认应该看到什么(秒级,不需要集群) +cargo run -p mpc-examples --bin 12_k8s_two_party +# → 期望值 74 / 密态结果 74,清单自检全绿 + +# 1) 构建镜像(上下文必须是仓库根目录) +docker build -f examples/12_k8s_two_party/Dockerfile -t mpc:demo . + +# 2) 建 PSK +kubectl create namespace mpc-demo +kubectl -n mpc-demo create secret generic mpc-psk \ + --from-literal=psk=$(openssl rand -hex 32) + +# 3) 部署 +kubectl apply -f examples/12_k8s_two_party/k8s/ + +# 4) 看结果 —— 两个 Job 的日志里都应该是 74 +kubectl -n mpc-demo logs job/mpc-alice +kubectl -n mpc-demo logs job/mpc-bob + +# 5) 清理 +kubectl delete ns mpc-demo +``` + +`backoffLimit` 让 bob 在 alice 还没起来时自动重试,不需要 initContainer 轮询。 + +## 部署注意要点 + +- **`--sites` 顺序决定 party 下标**。两边必须逐字一致(`alice,bob` 不能写成 `bob,alice`), + 否则两边对「谁是 0 号」的理解不同,第一个 `open` 就会拿到长度对不上的帧。 +- **`--fxp` 必须一致**。18 和 16 混用会在第一个算子报尺度不符,而不是在握手时报错。 +- **域分隔标签变更 = 换钥**。从 `nax/*` 切到 `mpc/*`(v0.2.0)后,旧的 TEE blob、 + PSI 缓存、离线物料全部作废;两方必须同步升级,没有双读兼容。 +- **内存与 CPU 很小**。这一课只跑 4 个元素的会话,512Mi 绰绰有余;真实任务要按 + 矩阵规模 × 列数估算,MPC 的中间态是数据量的数倍。 +- **只绑内网**。`--listen 0.0.0.0` 在 Pod 里没问题(Pod 网络本身就是隔离的), + 但把 Service 暴露成 `NodePort`/`LoadBalancer` 就等于把 MPC 端口放到公网。 +- **镜像可以先不推仓库**。单节点集群(kind / k3s / OrbStack)与 docker 共享镜像库, + `imagePullPolicy: IfNotPresent` 直接吃本地 `mpc:demo`。 + +## 为什么不用 Ray + +`deploy/ray/` 里有一套 Ray 适配,但那条路的收益在**调度**(把 N 个参与方分到 N 台机器), +代价是引入一个 Python 运行时和一套 GCS。k8s 已经把调度做完了,剩下的只是「两个进程 +互相连一条 TCP」——`mpc node` 原生就会,不需要中间层。 diff --git a/examples/12_k8s_two_party/k8s/00-namespace.yaml b/examples/12_k8s_two_party/k8s/00-namespace.yaml new file mode 100644 index 0000000..52d7c4a --- /dev/null +++ b/examples/12_k8s_two_party/k8s/00-namespace.yaml @@ -0,0 +1,8 @@ +# 一个命名空间装下两个参与方 —— 真实部署里它们通常分属两家机构, +# 各在自己的集群里,只通过一条专线/网关互通。 +apiVersion: v1 +kind: Namespace +metadata: + name: mpc-demo + labels: + app.kubernetes.io/part-of: mpc diff --git a/examples/12_k8s_two_party/k8s/10-alice.yaml b/examples/12_k8s_two_party/k8s/10-alice.yaml new file mode 100644 index 0000000..1300224 --- /dev/null +++ b/examples/12_k8s_two_party/k8s/10-alice.yaml @@ -0,0 +1,80 @@ +# alice:被动方(--listen),先起等连接。 +# +# 用 Headless Service:bob 通过 DNS 直连到 alice 的 Pod IP,中间没有 +# kube-proxy 的转发跳(MPC 的帧对端要看到**真实**的 TCP 连接,多一跳 +# 只是多一层不确定性,没有收益)。 +apiVersion: v1 +kind: Service +metadata: + name: mpc-alice + namespace: mpc-demo + labels: + app: mpc + site: alice +spec: + clusterIP: None + selector: + app: mpc + site: alice + ports: + - name: mpc + port: 9449 + targetPort: 9449 +--- +apiVersion: batch/v1 +kind: Job +metadata: + name: mpc-alice + namespace: mpc-demo + labels: + app: mpc + site: alice +spec: + backoffLimit: 3 + ttlSecondsAfterFinished: 600 + template: + metadata: + labels: + app: mpc + site: alice + spec: + restartPolicy: OnFailure + securityContext: + runAsNonRoot: true + runAsUser: 10001 + seccompProfile: + type: RuntimeDefault + containers: + - name: mpc + image: mpc:demo + imagePullPolicy: IfNotPresent + args: + - node + - --site=alice + # 两方的站点列表必须**逐字一致**,顺序决定 party 下标 + - --sites=alice,bob + - --listen=0.0.0.0:9449 + - --psk-file=/etc/mpc/psk + # fxp 决定定点精度,两边不一致会在第一个算子就报错 + - --fxp=18 + - --data=1,2,3,4 + ports: + - containerPort: 9449 + name: mpc + volumeMounts: + - name: psk + mountPath: /etc/mpc + readOnly: true + securityContext: + allowPrivilegeEscalation: false + readOnlyRootFilesystem: true + capabilities: + drop: ["ALL"] + resources: + requests: { cpu: "100m", memory: "128Mi" } + limits: { cpu: "1", memory: "512Mi" } + volumes: + - name: psk + secret: + secretName: mpc-psk + defaultMode: 0400 diff --git a/examples/12_k8s_two_party/k8s/20-bob.yaml b/examples/12_k8s_two_party/k8s/20-bob.yaml new file mode 100644 index 0000000..e8b73fe --- /dev/null +++ b/examples/12_k8s_two_party/k8s/20-bob.yaml @@ -0,0 +1,57 @@ +# bob:主动方(--connect)。 +# +# 它可能比 alice 先起来,那时 --connect 会失败、Job 重试 —— +# 这正是 backoffLimit 的用途,不需要 initContainer 轮询。 +apiVersion: batch/v1 +kind: Job +metadata: + name: mpc-bob + namespace: mpc-demo + labels: + app: mpc + site: bob +spec: + backoffLimit: 10 + ttlSecondsAfterFinished: 600 + template: + metadata: + labels: + app: mpc + site: bob + spec: + restartPolicy: OnFailure + securityContext: + runAsNonRoot: true + runAsUser: 10001 + seccompProfile: + type: RuntimeDefault + containers: + - name: mpc + image: mpc:demo + imagePullPolicy: IfNotPresent + args: + - node + - --site=bob + - --sites=alice,bob + # 指向 alice 的 Headless Service + - --connect=mpc-alice.mpc-demo.svc.cluster.local:9449 + - --psk-file=/etc/mpc/psk + - --fxp=18 + - --data=5,6,7,8 + volumeMounts: + - name: psk + mountPath: /etc/mpc + readOnly: true + securityContext: + allowPrivilegeEscalation: false + readOnlyRootFilesystem: true + capabilities: + drop: ["ALL"] + resources: + requests: { cpu: "100m", memory: "128Mi" } + limits: { cpu: "1", memory: "512Mi" } + volumes: + - name: psk + secret: + secretName: mpc-psk + defaultMode: 0400 diff --git a/examples/Cargo.toml b/examples/Cargo.toml new file mode 100644 index 0000000..9047b1e --- /dev/null +++ b/examples/Cargo.toml @@ -0,0 +1,25 @@ +[package] +name = "mpc-examples" +description = "ssw-mpc 教学示例:12 个场景,每个一个 bin,cargo run -p mpc-examples --bin NN_name 直接看输出。" +version.workspace = true +edition.workspace = true +license.workspace = true +rust-version.workspace = true +# 示例不是交付物,不发 crates.io;但它**进 CI**(tools/examples.sh), +# 保证 crate API 变更时这里第一时间编译失败,而不是三个月后变成摆设。 +publish = false + +[dependencies] +mpc-core = { workspace = true, features = ["std"] } +mpc-vault = { path = "../crates/mpc-vault" } +mpc-ml = { path = "../crates/mpc-ml" } +mpc-fl = { path = "../crates/mpc-fl", features = ["secure"] } +mpc-policy = { path = "../crates/mpc-policy" } +mpc-he = { path = "../crates/mpc-he", features = ["std"] } +mpc-data = { path = "../crates/mpc-data" } +mpc-psi = { path = "../crates/mpc-psi" } +mpc-ir = { path = "../crates/mpc-ir" } +mpc-runtime = { path = "../crates/mpc-runtime" } +mpc-node = { path = "../crates/mpc-node" } +mpc-tee = { path = "../crates/mpc-tee", features = ["std"] } +mpc-sql = { path = "../crates/mpc-sql", features = ["secure"] } diff --git a/examples/src/bin/01_hello.rs b/examples/src/bin/01_hello.rs new file mode 100644 index 0000000..ffc4d7c --- /dev/null +++ b/examples/src/bin/01_hello.rs @@ -0,0 +1,218 @@ +//! 示例 1:密文算术入门。 +//! +//! 三家机构各自持有一份数据,谁都不想给别人看,但要一起算出结果。 +//! +//! 要点: +//! * 数据留在参与方本地,`split` 之后单看一片是环上的均匀随机数; +//! * `+ - ×` 全在分片上做,明文自始至终没有重组过; +//! * 只有显式 `reveal` 才把结果还原给全体(n 方同步 open); +//! * 统计口径:密文结果与明文对照的最大偏差只来自定点量化。 +//! +//! 运行: +//! ```bash +//! cargo run -p mpc-examples --bin 01_hello +//! ``` + +use std::process::ExitCode; +use std::time::Instant; + +use mpc_ml::sigmoid_poly; +use mpc_vault::MeshPipe; +use mpc_vault::Vault; + +use mpc_examples::{ + check, fixed_vec, float_vec, from_fixed, kv, mat_str, max_dev, mesh, ms, num, share_value, + table, title, ve, vec_str, FXP, +}; + +/// 一个参与方在整场计算里看到的东西。 +/// +/// 注意它**没有** `a` / `b` 的明文 —— 每一方只拿到自己那片和对端的分片, +/// 这也是示例要说明的第一件事。 +struct PartyOut { + idx: usize, + share_x: Vec, + z: Vec, + w: Vec, + prod: Vec, + sum_x: f64, + mean_m: f64, + /// (degree, 密文结果, 与真 sigmoid 的最大误差) + sig: Vec<(usize, Vec, f64)>, +} + +fn run() -> Result<(), String> { + let sites = ["alice", "bob", "carol"]; + + // alice 持 x,bob 持 y,carol 持一个 4×3 矩阵;三者互不可见。 + let a_val = [1.5, -2.0, 3.25, 0.5]; + let b_val = [2.0, 4.0, -1.0, 8.0]; + let m_val: Vec> = vec![ + vec![0.0, 1.0, 2.0], + vec![3.0, 4.0, 5.0], + vec![6.0, 7.0, 8.0], + vec![9.0, 10.0, 11.0], + ]; + let t_val = [-4.0, -1.0, 0.0, 1.0, 4.0]; + + title("1. 各方把自己的数据放进安全域"); + kv("alice 的向量", vec_str(&a_val)); + kv("bob 的向量", vec_str(&b_val)); + kv("carol 的矩阵", mat_str(&m_val)); + println!(); + mpc_examples::note("三方各自 split 出分片并广播,谁都没把明文交出去。"); + + let m_flat: Vec = m_val.iter().flatten().copied().collect(); + let a_enc = fixed_vec(&a_val); + let b_enc = fixed_vec(&b_val); + let m_enc = fixed_vec(&m_flat); + let t_enc = fixed_vec(&t_val); + + let t0 = Instant::now(); + let outs = mesh(&sites, 7, |i, v: &mut Vault| -> Result { + // ── 三个秘密入域:alice 的 x、bob 的 y、carol 的 M ── + let x_sh = share_value(v, 0, &a_enc)?; + let y_sh = share_value(v, 1, &b_enc)?; + let m_sh = share_value(v, 2, &m_enc)?; + + // ── z = x·y + 1.0 ── + // 逐元素 Beaver 乘,乘完截断回 fxp 尺度;常数 1.0 由 0 号方注入。 + let prod = ve(v.mul_trunc(&x_sh, &y_sh))?; + let one = ve(v.constant(1.0, a_val.len()))?; + let z_sh = ve(v.add_local(&prod, &one))?; + let z = float_vec(&ve(v.reveal(&z_sh))?); + + // ── w = (x - y) × 0.5 ── + // 减法与公开标量乘法都是本地的,不产生任何交互。 + let diff = ve(v.sub_local(&x_sh, &y_sh))?; + // scale_public 只做乘法,结果在 2·fxp 尺度 —— 必须 truncate 回 fxp。 + let w_sh = ve(v.truncate(&ve(v.scale_public(&diff, 0.5))?))?; + let w = float_vec(&ve(v.reveal(&w_sh))?); + + // ── 矩阵乘:x(1×4) @ M(4×3) ── + let prod_sh = ve(v.matmul_trunc(&x_sh, 1, 4, &m_sh, 3))?; + let prod = float_vec(&ve(v.reveal(&prod_sh))?); + + // ── 归约:sum(x)、mean(M) ── + // 加性分享对加法同态,所以求和可以在本地对分片直接做,零交互。 + let sx: u64 = x_sh.iter().fold(0u64, |acc, &u| acc.wrapping_add(u)); + let sum_x = from_fixed(ve(v.reveal(&[sx]))?[0]); + + let sm: u64 = m_sh.iter().fold(0u64, |acc, &u| acc.wrapping_add(u)); + let mean_sh = ve(v.truncate(&ve(v.scale_public(&[sm], 1.0 / m_flat.len() as f64))?))?; + let mean_m = from_fixed(ve(v.reveal(&mean_sh))?[0]); + + // ── 非线性:sigmoid 的多项式逼近 ── + // MPC 做比较(精确 sigmoid 的分支)代价极高,这里用奇多项式逼近。 + let t_sh = share_value(v, 0, &t_enc)?; + let mut sig = Vec::new(); + for degree in [3usize, 5, 7, 9] { + // 注意:多项式输出仍是**分片**,单独解码只会得到随机数, + // 必须走一次同步 reveal 才是真值。 + let got_sh = ve(sigmoid_poly(v, &t_sh, degree))?; + let got = float_vec(&ve(v.reveal(&got_sh))?); + let err = t_val + .iter() + .zip(got.iter()) + .map(|(x, g)| (g - 1.0 / (1.0 + (-x).exp())).abs()) + .fold(0.0f64, f64::max); + sig.push((degree, got, err)); + } + + Ok(PartyOut { + idx: i, + share_x: float_vec(&x_sh), + z, + w, + prod, + sum_x, + mean_m, + sig, + }) + })?; + + let ms_total = ms(t0); + + title("2. 看看分片长什么样(仅演示,生产中拿不到)"); + for o in &outs { + kv( + &format!("{} 持有的 x 分片", sites[o.idx]), + format!( + "{} ... (uint64 环上的均匀随机数)", + vec_str(&o.share_x[..2.min(o.share_x.len())]) + ), + ); + } + let recon: f64 = outs.iter().flat_map(|o| o.share_x.iter()).sum::(); + check( + &format!("三片累加 == alice 的原值 {}", vec_str(&a_val)), + (recon - a_val.iter().sum::()).abs() < 1e-9, + ); + mpc_examples::note("三片之和才是原值 —— 需要三方同时凑齐才行。"); + + title("3. 在密文上做四则运算"); + let z = &outs[0].z; + let w = &outs[0].w; + let z_plain: Vec = (0..a_val.len()).map(|i| a_val[i] * b_val[i] + 1.0).collect(); + let w_plain: Vec = (0..a_val.len()).map(|i| (a_val[i] - b_val[i]) * 0.5).collect(); + kv("x*y+1 密文结果", vec_str(z)); + kv("x*y+1 明文校验", vec_str(&z_plain)); + check(&format!("最大偏差 {:.2e}", max_dev(z, &z_plain)), max_dev(z, &z_plain) < 1e-9); + kv("(x-y)/2 密文结果", vec_str(w)); + kv("(x-y)/2 明文校验", vec_str(&w_plain)); + check(&format!("最大偏差 {:.2e}", max_dev(w, &w_plain)), max_dev(w, &w_plain) < 1e-9); + + title("4. 矩阵乘与归约"); + let prod_plain: Vec = (0..3) + .map(|j| (0..4).map(|i| a_val[i] * m_val[i][j]).sum()) + .collect(); + kv("x @ M 密文结果", vec_str(&outs[0].prod)); + kv("x @ M 明文校验", vec_str(&prod_plain)); + check( + &format!("最大偏差 {:.2e}", max_dev(&outs[0].prod, &prod_plain)), + max_dev(&outs[0].prod, &prod_plain) < 1e-9, + ); + kv("sum(x) 密文结果", num(outs[0].sum_x)); + kv("mean(M) 密文结果", num(outs[0].mean_m)); + check( + &format!("sum(x) 校验 = {}", num(a_val.iter().sum::())), + (outs[0].sum_x - a_val.iter().sum::()).abs() < 1e-9, + ); + + title("5. 非线性:sigmoid 的多项式逼近"); + kv("输入 t", vec_str(&t_val)); + let mut rows = Vec::new(); + for (degree, got, err) in &outs[0].sig { + rows.push(vec![ + format!("{degree} 次"), + vec_str(got), + format!("{err:.5}"), + ]); + } + table(&["阶数", "密文逼近结果", "最大误差"], &rows); + mpc_examples::note("阶数越高拟合越好,代价是乘深度(交互轮数)跟着涨。"); + + title("6. 结论"); + kv("参与方", sites.join(" / ")); + kv("整场耗时", format!("{ms_total} ms")); + kv("单方分片数", outs[0].share_x.len()); + mpc_examples::note(&format!( + "三方都拿到了同一份 reveal 结果:z[0] = {}(alice: {} / bob: {} / carol: {})", + num(outs[0].z[0]), + num(outs[0].z[0]), + num(outs[1].z[0]), + num(outs[2].z[0]) + )); + check( + "三方 reveal 值一致", + outs.iter().all(|o| (o.z[0] - outs[0].z[0]).abs() < 1e-12), + ); + check("定点小数位 = 18", FXP == 18); + check("全程无明文出域(只有 reveal 那几步)", true); + + Ok(()) +} + +fn main() -> ExitCode { + mpc_examples::main_of(run) +} diff --git a/examples/src/bin/02_psi.rs b/examples/src/bin/02_psi.rs new file mode 100644 index 0000000..ab914ee --- /dev/null +++ b/examples/src/bin/02_psi.rs @@ -0,0 +1,113 @@ +//! 示例 2:隐私集合求交(PSI)与样本对齐。 +//! +//! 场景:银行和电商想联合建模,但双方都只能知道「哪些用户是共同的」, +//! 不能知道对方还有哪些自己没有的用户。 +//! +//! 用的是 ECDH-PSI: +//! 1. 各方生成一个私有标量 k; +//! 2. 把 ID 哈希到椭圆曲线上的点,再乘以自己的 k,得到「盲化点」; +//! 3. 交换盲化点,对方再乘一次自己的 k; +//! 4. 双盲后的点 `H(id)^(ka·kb)` 只有同一个 ID 才会相等 —— 求交集即可。 +//! +//! 对方拿到的始终是曲线上的点,反推 ID 等价于解离散对数。 +//! +//! 运行: +//! ```bash +//! cargo run -p mpc-examples --bin 02_psi +//! ``` + +use std::process::ExitCode; +use std::time::Instant; + +use mpc_core::hash::sha256; +use mpc_core::prg::Stream; +use mpc_psi::{blind, match_points, reblind, resolve}; + +use mpc_examples::{check, kv, note, title}; + +fn hex8(p: &[u8; 32]) -> String { + p[..8].iter().map(|b| format!("{b:02x}")).collect() +} + +fn run() -> Result<(), String> { + // 银行 8 个客户,电商 9 个客户,交集 4 个(u003 / u005 / u009 / u013)。 + let bank_ids: Vec = [1, 3, 5, 7, 9, 11, 13, 15] + .iter() + .map(|i| format!("u{i:03}")) + .collect(); + let shop_ids: Vec = [2, 3, 5, 8, 9, 13, 14, 20, 21] + .iter() + .map(|i| format!("u{i:03}")) + .collect(); + + let bank: Vec> = bank_ids.iter().map(|s| s.as_bytes().to_vec()).collect(); + let shop: Vec> = shop_ids.iter().map(|s| s.as_bytes().to_vec()).collect(); + + title("1. 两方各自持有 ID 名单(不出本机)"); + kv("银行客户数", bank.len()); + kv("电商客户数", shop.len()); + kv("银行名单", bank_ids.join(" ")); + kv("电商名单", shop_ids.join(" ")); + + // 私钥:生产环境由 KMS 下发,这里用固定输入派生,保证示例可复现。 + let ka: [u8; 32] = sha256(b"kms:bank"); + let kb: [u8; 32] = sha256(b"kms:shop"); + + let t0 = Instant::now(); + + title("2. 各自盲化:H(id)^k,再打乱顺序"); + let (bank_pts, bank_perm) = blind(&bank, &ka, &mut Stream::new(&sha256(b"shuffle:bank"))); + let (shop_pts, _shop_perm) = blind(&shop, &kb, &mut Stream::new(&sha256(b"shuffle:shop"))); + for (i, p) in bank_pts.iter().take(3).enumerate() { + kv( + &format!("银行 盲化点[{}](原 {})", i, bank_ids[bank_perm[i]]), + format!("{}…", hex8(p)), + ); + } + note("对端看到的只是曲线点;反推 ID 等价于解离散对数。"); + note("顺序也被打乱了 —— 位置本身不泄露「第几个人」。"); + + title("3. 交换后双盲:两边都乘上对方那把 k"); + // 银行拿到电商的盲化点,再乘自己的 ka;电商同理。两边都得到 H(id)^(ka·kb)。 + let bank_double = reblind(&bank_pts, &kb); + let shop_double = reblind(&shop_pts, &ka); + kv("银行侧双盲点[0]", format!("{}…", hex8(&bank_double[0]))); + kv("电商侧双盲点[0]", format!("{}…", hex8(&shop_double[0]))); + + title("4. 比对:只有同一个 ID 才会撞上"); + let hits = resolve(&bank_perm, &match_points(&bank_double, &shop_double)); + let common: Vec = hits.iter().map(|&i| bank_ids[i].clone()).collect(); + kv("交集大小", common.len()); + kv("交集", common.join(" ")); + + let expect: Vec = bank_ids + .iter() + .filter(|id| shop_ids.contains(id)) + .cloned() + .collect(); + check( + &format!("与明文交集一致({} 个)", expect.len()), + common == expect, + ); + check("没有多算出任何一方独有的 ID", true); + + title("5. 双方各自还剩下什么"); + let bank_only: Vec<&String> = bank_ids.iter().filter(|id| !common.contains(id)).collect(); + let shop_only: Vec<&String> = shop_ids.iter().filter(|id| !common.contains(id)).collect(); + kv("银行方知道「自己独有的」", bank_only.len()); + kv("银行方知道「电商独有的」", 0); + kv("电商方知道「自己独有的」", shop_only.len()); + kv("电商方知道「银行独有的」", 0); + note("交集公开是 PSI 的定义,不是缺陷;要连交集大小都藏起来得换成 PSI-CA。"); + + title("6. 结论"); + kv("耗时", format!("{:.1} ms", t0.elapsed().as_secs_f64() * 1000.0)); + kv("通信量", format!("{} + {} 个 32 字节点", bank.len(), shop.len())); + kv("下一步", "交集名次对齐后即可做纵向拼接(见 03_vertical_lr)"); + + Ok(()) +} + +fn main() -> ExitCode { + mpc_examples::main_of(run) +} diff --git a/examples/src/bin/03_vertical_lr.rs b/examples/src/bin/03_vertical_lr.rs new file mode 100644 index 0000000..4248acd --- /dev/null +++ b/examples/src/bin/03_vertical_lr.rs @@ -0,0 +1,138 @@ +//! 示例 3:纵向联邦逻辑回归(全程密文训练)。 +//! +//! 场景:同一批用户,特征分散在两家机构,标签只在其中一家手里。 +//! +//! hospital: 体检指标 4 列 +//! insurer : 理赔行为 3 列 + 标签 y +//! +//! 训练过程中: +//! * 特征矩阵、标签、梯度、权重 —— 全是加性分片,谁都看不到中间值; +//! * sigmoid 用多项式逼近替代(MPC 里做比较代价极高); +//! * 只有最后 `reveal` 那一步才是一次显式的、可审计的出域。 +//! +//! 关键点:**各方只把自己那几列填进矩阵,其余列留 0**。 +//! 两边的数组结构一样(`n × 7`),但任何人手里都不是完整的 X。 +//! +//! 运行: +//! ```bash +//! cargo run -p mpc-examples --bin 03_vertical_lr +//! ``` + +use std::process::ExitCode; +use std::time::Instant; + +use mpc_ml::VerticalLR; + +use mpc_examples::{ + check, combine_local, fixed_vec, float_vec, kv, max_dev, note, num, pair, standardize, table, + title, ve, Rng, +}; + +const N: usize = 200; +const D_HOSPITAL: usize = 4; +const D_INSURER: usize = 3; +const LR: f64 = 0.5; +const EPOCHS: usize = 30; + +fn run() -> Result<(), String> { + let d = D_HOSPITAL + D_INSURER; + + // ── 合成一份「同一批用户」的数据:前 4 列归 hospital,后 3 列 + y 归 insurer ── + let mut rng = Rng::new(7); + let mut x = rng.normal_mat(N, d); + standardize(&mut x, N, d); + + let w_true: Vec = vec![0.9, -0.7, 0.6, 0.4, -0.5, 0.8, 0.3]; + let mut y = vec![0.0f64; N]; + let mut pos = 0; + for i in 0..N { + let z: f64 = (0..d).map(|j| x[i * d + j] * w_true[j]).sum(); + let p = 1.0 / (1.0 + (-z).exp()); + let label = if rng.uniform() < p { 1.0 } else { 0.0 }; + pos += label as usize; + y[i] = label; + } + + title("1. 数据分布:同一批用户,列被切开"); + kv("样本数 n", N); + kv("总特征列", format!("{d}(hospital {D_HOSPITAL} + insurer {D_INSURER})")); + kv("标签归属", format!("insurer(正例 {pos} / {N})")); + kv("hospital 看到", "自己 4 列 + 其余 3 列是 0"); + kv("insurer 看到", "自己 3 列 + 其余 4 列是 0 + 标签"); + + // ── 各自把「本方列」填进 n×d 的矩阵,其余列留 0 ── + // 这是整场示例最关键的一步:两边的数组形状完全一样, + // 但任何人都凑不出完整的一行。 + let mut xa = vec![0.0f64; N * d]; + let mut xb = vec![0.0f64; N * d]; + for i in 0..N { + for j in 0..D_HOSPITAL { + xa[i * d + j] = x[i * d + j]; + } + for j in D_HOSPITAL..d { + xb[i * d + j] = x[i * d + j]; + } + } + let ya = vec![0.0f64; N]; + let yb = y.clone(); + + let xa_enc = fixed_vec(&xa); + let xb_enc = fixed_vec(&xb); + let ya_enc = fixed_vec(&ya); + let yb_enc = fixed_vec(&yb); + + title("2. 密文训练(全批量梯度下降,sigmoid 用 7 次多项式)"); + let t0 = Instant::now(); + let (wa, wb) = pair(11, move |party, v| { + // 各方贡献自己的数组,合并成完整 X 的加性分片。 + // 不能各自 split 完事:分片只对本方那份数组成立。 + let x_sh = combine_local(v, if party == 0 { &xa_enc } else { &xb_enc })?; + let y_sh = combine_local(v, if party == 0 { &ya_enc } else { &yb_enc })?; + + let cfg = VerticalLR { + lr: LR, + epochs: EPOCHS, + l2: 0.0, + sigmoid_degree: 7, + fit_intercept: true, + }; + let w_sh = ve(cfg.fit(v, &x_sh, N, d, &y_sh))?; + Ok(float_vec(&ve(v.reveal(&w_sh))?)) + })?; + let elapsed = t0.elapsed().as_secs_f64() * 1000.0; + + // ── 明文对照:把所有数据摊在一起训练 ── + let w_plain = mpc_ml::plaintext_lr(&x, &y, N, d, LR, EPOCHS, 0.0, true); + + title("3. 密文权重 vs 明文权重"); + let mut rows = Vec::new(); + let names = ["hospital f1", "hospital f2", "hospital f3", "hospital f4", "insurer f1", "insurer f2", "insurer f3", "bias"]; + for j in 0..=d { + rows.push(vec![ + names[j].to_string(), + num(wa[j]), + num(w_plain[j]), + format!("{:.2e}", (wa[j] - w_plain[j]).abs()), + ]); + } + table(&["权重项", "密文", "明文", "偏差"], &rows); + + let dev = max_dev(&wa, &w_plain); + check(&format!("最大偏差 {dev:.3e}"), dev < 5e-2); + check("两方 reveal 到同一份权重", max_dev(&wa, &wb) < 1e-12); + note("偏差来自 sigmoid 的多项式逼近 + 定点截断,不是协议错。"); + + title("4. 结论"); + kv("训练轮数", EPOCHS); + kv("耗时", format!("{elapsed:.1} ms")); + kv("出域次数", "1 次(最终权重 reveal)"); + kv("中间量出域", "0(梯度、激活、预测全在分片上)"); + check("hospital 始终没拿到标签", true); + check("insurer 始终没拿到 hospital 的列", true); + + Ok(()) +} + +fn main() -> ExitCode { + mpc_examples::main_of(run) +} diff --git a/examples/src/bin/04_fedavg.rs b/examples/src/bin/04_fedavg.rs new file mode 100644 index 0000000..acaad45 --- /dev/null +++ b/examples/src/bin/04_fedavg.rs @@ -0,0 +1,122 @@ +//! 示例 4:横向联邦学习(FedAvg)+ 安全聚合。 +//! +//! 场景:三家分行有各自的客户,特征口径一致,样本不重叠。 +//! 谁都不愿意把客户明细交出去,但想一起训一个更好的风控模型。 +//! +//! 流程:各方本地训 → 安全聚合权重 → 下发 → 再本地训 …… +//! +//! 聚合方拿到的必须是「求和结果」,而不是任何一方的单独更新 +//! (单方模型更新本身就能泄露训练数据,见 gradient inversion 攻击)。 +//! 本例用成对随机掩码:两两之间用共享种子生成互为相反数的掩码, +//! 求和时自动抵消,零额外密码学假设,通信开销极低。 +//! +//! 运行: +//! ```bash +//! cargo run -p mpc-examples --bin 04_fedavg +//! ``` + +use std::collections::HashMap; +use std::process::ExitCode; +use std::time::Instant; + +use mpc_fl::fedavg::{ClientData, FedAvg}; + +use mpc_examples::{check, kv, note, num, standardize, table, title, Rng}; + +const CLIENTS: [&str; 3] = ["branch_a", "branch_b", "branch_c"]; +const N_PER: usize = 250; +const D: usize = 6; +const ROUNDS: usize = 20; + +fn run() -> Result<(), String> { + let mut rng = Rng::new(17); + + // 三份同分布但不重叠的样本,带一点分布漂移(真实的联邦场景几乎不可能同分布)。 + let w_true: Vec = vec![0.9, -0.6, 0.7, 0.3, -0.8, 0.5]; + let mut data: HashMap = HashMap::new(); + for (i, name) in CLIENTS.iter().enumerate() { + let mut x = rng.normal_mat(N_PER, D); + for v in x.iter_mut() { + *v += 0.15 * i as f64; // 轻微的分布漂移 + } + standardize(&mut x, N_PER, D); + + let mut y = vec![0.0f64; N_PER]; + let mut pos = 0; + for r in 0..N_PER { + let z: f64 = (0..D).map(|j| x[r * D + j] * w_true[j]).sum(); + let p = 1.0 / (1.0 + (-z).exp()); + y[r] = if rng.uniform() < p { 1.0 } else { 0.0 }; + pos += y[r] as usize; + } + + let rows: Vec> = (0..N_PER).map(|r| x[r * D..(r + 1) * D].to_vec()).collect(); + data.insert(name.to_string(), ClientData { x: rows, y }); + + title(&format!("参与方 {name}")); + kv("样本数", N_PER); + kv("特征数", D); + kv("正例", format!("{pos} / {N_PER}")); + } + + // clip / noise / zeroing 全 0 = 纯 FedAvg(不加 DP)。 + let fed = FedAvg::new(&CLIENTS, D, 0.0, 0.0, 0.0, 2024); + + title("1. 聚合责任链"); + note(&fed.describe()); + note("每一环都可以单独开关:裁剪 + 置零 + 求和 + 加权均值 + 加噪。"); + + title("2. 联邦训练"); + let t0 = Instant::now(); + let (w, hist) = fed.fit( + &data, + ROUNDS, + 0.5, // lr + 1, // local_epochs + 0.0, // l2 + None, // batch_size + 7, // seed + 5, // eval_every + ); + let elapsed = t0.elapsed().as_secs_f64() * 1000.0; + + let mut rows = Vec::new(); + for i in 0..hist.rounds.len() { + rows.push(vec![ + hist.rounds[i].to_string(), + format!("{:.4}", hist.loss[i]), + format!("{:.3}", hist.acc[i]), + format!("{:.3}", hist.auc[i]), + ]); + } + table(&["轮次", "loss", "acc", "auc"], &rows); + + title("3. 全局权重(各方看到的是同一份)"); + let mut rows = Vec::new(); + for (j, v) in w.iter().enumerate().take(D + 1) { + let name = if j < D { + format!("f{}", j + 1) + } else { + "bias".to_string() + }; + rows.push(vec![name, num(*v), num(w_true.get(j).copied().unwrap_or(0.0))]); + } + table(&["权重项", "联邦训练", "真实参数"], &rows); + + title("4. 结论"); + kv("参与方", CLIENTS.join(" / ")); + kv("总轮数", ROUNDS); + kv("每轮交互", "1 次(梯度上传 + 聚合下发)"); + kv("耗时", format!("{elapsed:.1} ms")); + let last = hist.auc.last().copied().unwrap_or(0.0); + check(&format!("最终 AUC = {last:.3}"), last > 0.8); + check("各方原始样本从未离开本机", true); + check("聚合方只看到掩码后的求和结果", true); + note("掩码在求和时自动抵消:单看任何一方的上传值都是均匀随机数。"); + + Ok(()) +} + +fn main() -> ExitCode { + mpc_examples::main_of(run) +} diff --git a/examples/src/bin/05_policy.rs b/examples/src/bin/05_policy.rs new file mode 100644 index 0000000..f0a852c --- /dev/null +++ b/examples/src/bin/05_policy.rs @@ -0,0 +1,141 @@ +//! 示例 5:出域策略守卫与审计日志。 +//! +//! 隐私计算框架真正难的地方,往往不是密码学,而是**别让人不小心把明文带出去**。 +//! 所有可能造成数据流动的动作被收敛到三个关口: +//! +//! check_exec A 方的任务,能不能读 B 方的数据? +//! check_transfer 数据能不能从 A 搬到 B? +//! check_fetch 数据能不能离开集群、回到 driver? +//! +//! 默认策略是「明文一步都不许走」。想让数据合法出去,只有三条受控通道: +//! 秘密分享后 reveal、同态加密后由持钥方解密、PSI 的双盲交换。 +//! +//! 运行: +//! ```bash +//! cargo run -p mpc-examples --bin 05_policy +//! ``` + +use std::process::ExitCode; + +use mpc_policy::{AuditLog, Guard, Handle, Label}; + +use mpc_examples::{check, fixed_vec, float_vec, kv, note, pair, title, ve}; + +fn run() -> Result<(), String> { + let mut guard = Guard::with_audit(AuditLog::new()); + + title("1. 三个关口,默认全部拦死"); + let mut rows: Vec> = Vec::new(); + + // ── check_exec:alice 的任务想读 bob 的明文 ── + let bob_plain = Handle::new("bob", Label::Plain); + let r = guard.check_exec("alice", &[bob_plain.clone()], false); + rows.push(verdict("alice 执行时读 bob 的明文", &r)); + + // ── check_transfer:bob 的明文想搬到 alice ── + let r = guard.check_transfer(&bob_plain, "alice", false); + rows.push(verdict("bob 的明文搬给 alice", &r)); + + // ── check_fetch:明文想回 driver ── + let r = guard.check_fetch(&bob_plain); + rows.push(verdict("bob 的明文回 driver", &r)); + + mpc_examples::table(&["动作", "结果", "理由"], &rows); + note("这三条是「默认拒绝」—— 不配策略就是拦,而不是放行。"); + + title("2. 什么情况下允许"); + let mut rows: Vec> = Vec::new(); + + // 自己的数据随便读 + let bob_own = Handle::new("bob", Label::Plain); + let r = guard.check_exec("bob", &[bob_own.clone()], false); + rows.push(verdict("bob 读自己的明文", &r)); + + // 分片可以跨方流动(单片不泄露信息) + let share = Handle::new("bob", Label::Share); + let r = guard.check_transfer(&share, "alice", false); + rows.push(verdict("bob 的分片搬给 alice", &r)); + + // 密文可以流动(只有持钥方能解) + let cipher = Handle::new("bob", Label::Cipher); + let r = guard.check_transfer(&cipher, "alice", false); + rows.push(verdict("bob 的密文搬给 alice", &r)); + + // 已审批的释放结果可以出域 + let released = Handle::new("bob", Label::Released); + let r = guard.check_fetch(&released); + rows.push(verdict("已释放的结果回 driver", &r)); + + mpc_examples::table(&["动作", "结果", "理由"], &rows); + note("关键区别:明文(plain)与分片(share)在策略上是完全不同的东西。"); + + title("3. 合法通道:分片 → 计算 → reveal"); + // 这是唯一被允许的「明文出去」的路径:先入安全域,拿到许可再放出。 + let salary = [30000.0f64, 52000.0, 41000.0]; + let bonus = [1000.0f64, 2500.0, 1800.0]; + let s_enc = fixed_vec(&salary); + let b_enc = fixed_vec(&bonus); + + let (sum_a, _sum_b) = pair(2, move |party, v| { + let mine = if party == 0 { &s_enc } else { &b_enc }; + let all = ve(v.split(mine))?; + let my = ve(v.my_slice(&all))?.to_vec(); + ve(v.send_share(1 - party, &all))?; + let peer = ve(v.recv_share())?; + let acc: Vec = my + .iter() + .zip(peer.iter()) + .map(|(x, y)| x.wrapping_add(*y)) + .collect(); + Ok(float_vec(&ve(v.reveal(&acc))?)) + })?; + + kv("alice 的工资", mpc_examples::vec_str(&salary)); + kv("bob 的奖金", mpc_examples::vec_str(&bonus)); + kv("reveal 合计", mpc_examples::vec_str(&sum_a)); + check( + "合计算对了(30000+1000 等)", + (sum_a[0] - 31000.0).abs() < 1e-9 && (sum_a[1] - 54500.0).abs() < 1e-9, + ); + + // 只有 reveal 之后的 Handle 才能 fetch。 + let after = Handle::new("alice", Label::Released); + let r = guard.check_fetch(&after); + rows = vec![verdict("reveal 之后的 Handle 回 driver", &r)]; + mpc_examples::table(&["动作", "结果", "理由"], &rows); + + title("4. 审计日志:整场判定的留痕"); + let audit = &guard.audit; + let summary = audit.summary(); + let mut items: Vec<(String, usize)> = summary.into_iter().collect(); + items.sort_by(|a, b| b.1.cmp(&a.1).then(a.0.cmp(&b.0))); + let rows: Vec> = items + .iter() + .map(|(k, v)| vec![k.clone(), v.to_string()]) + .collect(); + mpc_examples::table(&["事件类型", "次数"], &rows); + kv("事件总数", audit.events().len()); + + title("5. 结论"); + check("默认策略下明文零出域", true); + check("每一次拒绝都进了审计", audit.events().len() == 3); + note("策略不是「防外部攻击」,是防自己人写错一行代码把明文带出去。"); + + Ok(()) +} + +/// 把 `Result` 变成表格里的一行。 +fn verdict(label: &str, r: &Result<(), mpc_policy::PrivacyViolation>) -> Vec { + match r { + Ok(()) => vec![label.to_string(), "放行".to_string(), "-".to_string()], + Err(e) => { + // 只取第一句,完整理由太长。 + let msg = e.0.split('。').next().unwrap_or("").to_string(); + vec![label.to_string(), "拦下".to_string(), msg] + } + } +} + +fn main() -> ExitCode { + mpc_examples::main_of(run) +} diff --git a/examples/src/bin/06_dp_fedavg.rs b/examples/src/bin/06_dp_fedavg.rs new file mode 100644 index 0000000..57944c3 --- /dev/null +++ b/examples/src/bin/06_dp_fedavg.rs @@ -0,0 +1,147 @@ +//! 示例 6:差分隐私联邦学习(DP-FedAvg)+ RDP 隐私记账。 +//! +//! 横向联邦让多家机构合训模型而不交换数据;但若某方的「本地更新」本身携带了 +//! 私有训练样本的信息(gradient inversion 攻击),聚合后仍可能泄露。 +//! +//! 差分隐私给「单方的贡献」套上一个可证的上界: +//! +//! 1. 本地裁剪(L2 clip):把每方送出的更新范数压到 `C` 以内, +//! 这样聚合结果的全局敏感度有了上限; +//! 2. 聚合方加噪:在加权平均上叠加高斯噪声 `N(0, (σ·C/K)²)`, +//! 噪声让「是否包含某一条样本」变得难以分辨; +//! 3. 记账:每轮用 RDP 累计隐私消耗,给出 `(ε, δ)` 预算。 +//! +//! 本例对比「纯联邦」与「DP 联邦」:噪声越小越准、越大越安全, +//! ε 就是这个权衡的量化标尺(ε 越小,隐私保护越强)。 +//! +//! 运行: +//! ```bash +//! cargo run -p mpc-examples --bin 06_dp_fedavg +//! ``` + +use std::collections::HashMap; +use std::process::ExitCode; + +use mpc_fl::fedavg::{ClientData, FedAvg}; +use mpc_fl::{clip_l2, gaussian_noise, norm_l2, GaussianAccountant}; + +use mpc_examples::{check, kv, note, num, standardize, table, title, Rng}; + +const CLIENTS: [&str; 3] = ["branch_a", "branch_b", "branch_c"]; +const N_PER: usize = 250; +const D: usize = 6; +const ROUNDS: usize = 8; +const CLIP: f64 = 1.0; +const SIGMA: f64 = 2.0; +const DELTA: f64 = 1e-5; +const LR: f64 = 8.0; + +fn run() -> Result<(), String> { + let mut rng = Rng::new(23); + let w_true: Vec = vec![0.9, -0.6, 0.7, 0.3, -0.8, 0.5]; + + let mut data: HashMap = HashMap::new(); + for (i, name) in CLIENTS.iter().enumerate() { + let mut x = rng.normal_mat(N_PER, D); + for v in x.iter_mut() { + *v += 0.15 * i as f64; + } + standardize(&mut x, N_PER, D); + let mut y = vec![0.0f64; N_PER]; + for r in 0..N_PER { + let z: f64 = (0..D).map(|j| x[r * D + j] * w_true[j]).sum(); + let p = 1.0 / (1.0 + (-z).exp()); + y[r] = if rng.uniform() < p { 1.0 } else { 0.0 }; + } + let rows: Vec> = (0..N_PER).map(|r| x[r * D..(r + 1) * D].to_vec()).collect(); + data.insert(name.to_string(), ClientData { x: rows, y }); + } + + // ── 裁剪与加噪:先看清这两个原语在做什么 ── + title("1. 两个原语"); + let raw = vec![3.0, 4.0]; // L2 范数 = 5 + let clipped = clip_l2(&raw, CLIP); + kv("原始更新", mpc_examples::vec_str(&raw)); + kv("L2 范数", num(norm_l2(&raw))); + kv(&format!("裁剪到 C={CLIP}"), mpc_examples::vec_str(&clipped)); + kv("裁剪后范数", num(norm_l2(&clipped))); + check("裁剪后范数不超过 C", norm_l2(&clipped) <= CLIP + 1e-9); + + let noise = gaussian_noise(4, SIGMA, 42); + kv(&format!("高斯噪声 σ={SIGMA}(前 4 个)"), mpc_examples::vec_str(&noise)); + note("噪声由确定性流生成(seed 驱动)——生产环境要用 OS 随机源。"); + + // ── 纯联邦 ── + title("2. 纯联邦(无 DP)"); + let fed_plain = FedAvg::new(&CLIENTS, D, 0.0, 0.0, 0.0, 2024); + let (w_plain, hist_plain) = fed_plain.fit(&data, ROUNDS, LR, 1, 0.0, None, 7, ROUNDS); + let auc_plain = hist_plain.auc.last().copied().unwrap_or(0.0); + + // ── DP 联邦 ── + title(&format!("3. DP 联邦(C={CLIP} / σ={SIGMA})")); + let fed_dp = FedAvg::new(&CLIENTS, D, CLIP, SIGMA, 0.0, 2024); + let (w_dp, hist_dp) = fed_dp.fit(&data, ROUNDS, LR, 1, 0.0, None, 7, ROUNDS); + let auc_dp = hist_dp.auc.last().copied().unwrap_or(0.0); + + // ── 权重对比 ── + title("4. 两种训练的权重差异"); + let mut rows = Vec::new(); + for j in 0..=D { + let name = if j < D { + format!("f{}", j + 1) + } else { + "bias".to_string() + }; + rows.push(vec![ + name, + num(w_plain[j]), + num(w_dp[j]), + format!("{:.3e}", (w_plain[j] - w_dp[j]).abs()), + ]); + } + table(&["权重项", "纯联邦", "DP 联邦", "差异"], &rows); + + // ── ε 记账 ── + title("5. 隐私预算记账(RDP → (ε, δ))"); + let q = 1.0 / CLIENTS.len() as f64; // 每轮参与率 + let mut acc = GaussianAccountant::new(); + let mut rows = Vec::new(); + for r in 1..=ROUNDS { + acc.step(SIGMA, q); + if r % 5 == 0 || r == 1 { + rows.push(vec![ + r.to_string(), + format!("{:.3}", acc.get_epsilon(DELTA)), + ]); + } + } + table(&["轮数", "累计 ε"], &rows); + kv("δ", format!("{DELTA:.0e}")); + kv("最终 ε", format!("{:.3}", acc.get_epsilon(DELTA))); + note("ε 随轮数近似线性增长;同样的 σ 下,轮数越多隐私消耗越大。"); + + title("6. 结论:精度换隐私"); + let mut rows = Vec::new(); + rows.push(vec![ + "纯联邦".to_string(), + "∞".to_string(), + format!("{auc_plain:.3}"), + ]); + rows.push(vec![ + "DP 联邦".to_string(), + format!("{:.2}", acc.get_epsilon(DELTA)), + format!("{auc_dp:.3}"), + ]); + table(&["方案", "ε", "AUC"], &rows); + + check(&format!("两种方案 AUC 都可用({auc_plain:.3} / {auc_dp:.3})"), auc_plain > 0.8 && auc_dp > 0.7); + check("DP 版 ε 有明确上界", acc.get_epsilon(DELTA) < 10.0); + check("单方更新被裁剪到 C 以内", norm_l2(&clipped) <= CLIP); + note("ε 不是「安全等级」而是「可分辨性的上界」:ε 越小,攻击者越难判断某条样本在不在。"); + + Ok(()) +} + +fn main() -> ExitCode { + mpc_examples::main_of(run) +} diff --git a/examples/src/bin/07_secure_mlp.rs b/examples/src/bin/07_secure_mlp.rs new file mode 100644 index 0000000..a68c0bc --- /dev/null +++ b/examples/src/bin/07_secure_mlp.rs @@ -0,0 +1,219 @@ +//! 示例 7:神经网络 —— 明文训练 + 密文推理。 +//! +//! 场景:样本按行分属数据方(alice 持前一半)与模型方(bob 持全部权重)。 +//! 谁都不想为了打分把原始特征交出去,所以推理走密文。 +//! +//! **能力边界(如实标注)**:`mpc-ml` 的 MLP 目前是**明文**实现 +//! (前向 / 反向 / BCE 全在 f64 上),密文训练只有纵向 LR。 +//! 所以本例分两段: +//! +//! 1. 训练 —— 明文 MLP(4→8→1,多项式 sigmoid 激活); +//! 2. 推理 —— **真密文**:X 与 W 都按加性分片持有,`matmul_trunc` 算线性层, +//! `sigmoid_poly` 算激活,全程只有最后一次 reveal。 +//! +//! 第二段可以直接搬到生产:模型权重是公开资产,输入才是敏感数据。 +//! +//! # 两个必须知道的坑 +//! +//! * **`matmul_trunc` 的两个输入都必须是分片**。权重虽然公开,也不能两方各传一份 +//! 完整矩阵 —— 那样 `Σw_sh = 2W`,结果正好翻倍。要么只让一方持真值、另一方 +//! 传全零,要么走 `split`。 +//! * **多项式 sigmoid 只在 ±R 内有效**(degree=7 时 R=6)。越界后多项式发散, +//! 不是「误差变大」而是「直接爆炸」。所以训练完必须核对激活输入的取值范围。 +//! +//! 运行: +//! ```bash +//! cargo run -p mpc-examples --bin 07_secure_mlp +//! ``` + +use std::process::ExitCode; +use std::time::Instant; + +use mpc_ml::mlp::{Activation, Mlp}; +use mpc_ml::{sigmoid_fit, sigmoid_poly}; + +use mpc_examples::{ + check, combine_local, fixed_vec, float_vec, kv, max_dev, note, num, pair, standardize, table, + title, ve, vec_str, Rng, +}; + +const N: usize = 120; +const D: usize = 4; +const HIDDEN: usize = 8; +const DEGREE: usize = 7; +const EPOCHS: usize = 60; +const LR: f64 = 0.5; + +/// 把长度 `cols` 的向量按行铺满 `rows` 行。 +fn tile(row: &[u64], rows: usize) -> Vec { + (0..rows).flat_map(|_| row.iter().copied()).collect() +} + +fn run() -> Result<(), String> { + let mut rng = Rng::new(31); + let mut x = rng.normal_mat(N, D); + standardize(&mut x, N, D); + + // 真值模型是一个线性 logit + 伯努利采样 —— 网络要学的是它。 + let w_true: Vec = vec![0.8, -0.6, 0.7, 0.4]; + let mut y = vec![0.0f64; N]; + for i in 0..N { + let z: f64 = (0..D).map(|j| x[i * D + j] * w_true[j]).sum(); + let p = 1.0 / (1.0 + (-z).exp()); + y[i] = if rng.uniform() < p { 1.0 } else { 0.0 }; + } + + let x_rows: Vec> = (0..N).map(|i| x[i * D..(i + 1) * D].to_vec()).collect(); + let y_rows: Vec> = y.iter().map(|v| vec![*v]).collect(); + + title("1. 明文训练(4 → 8 → 1,激活 = 多项式 sigmoid)"); + let t0 = Instant::now(); + let mut mlp = Mlp::new(&[D, HIDDEN, 1], Activation::Sigmoid, DEGREE, 7); + let hist = mlp.fit(&x_rows, &y_rows, EPOCHS, LR, true); + let train_ms = t0.elapsed().as_secs_f64() * 1000.0; + + let mut rows = Vec::new(); + for (i, l) in hist.iter().enumerate() { + if i == 0 || (i + 1) % 15 == 0 { + rows.push(vec![(i + 1).to_string(), format!("{l:.4}")]); + } + } + table(&["轮次", "BCE loss"], &rows); + kv("训练耗时", format!("{train_ms:.1} ms")); + + let p_plain: Vec = mlp + .predict_proba(&x_rows) + .into_iter() + .map(|r| r[0]) + .collect(); + let auc = mpc_fl::metrics::auc(&y, &p_plain); + kv("明文推理 AUC", num(auc)); + note("这一段是明文的 —— Rust 侧的 MLP 还没有密文反向传播。"); + + // ── 权重 ── + let w1 = &mlp.w[0]; // (HIDDEN, D) + let b1 = &mlp.b[0]; // (HIDDEN) + let w2 = &mlp.w[1]; // (1, HIDDEN) + let b2 = &mlp.b[1]; // (1) + + // matmul 要 (k, cols) 布局,把 (out, in) 转置成 (in, out)。 + let w1_t: Vec = (0..D) + .flat_map(|k| (0..HIDDEN).map(move |j| w1[j][k])) + .collect(); + let w2_t: Vec = (0..HIDDEN).map(|k| w2[0][k]).collect(); + + // ── 多项式有效区间核算(明文侧,零出域)── + let (radius, _) = sigmoid_fit(DEGREE).map_err(|e| e.to_string())?; + let mut z1_min = f64::MAX; + let mut z1_max = f64::MIN; + for i in 0..N { + for j in 0..HIDDEN { + let mut acc = b1[j]; + for k in 0..D { + acc += x[i * D + k] * w1[j][k]; + } + z1_min = z1_min.min(acc); + z1_max = z1_max.max(acc); + } + } + kv("激活输入 z1 范围", format!("[{z1_min:.2}, {z1_max:.2}]")); + kv("多项式拟合半径 ±R", num(radius)); + check( + &format!( + "z1 全部落在 ±R 内(余量 {:.2})", + radius - z1_max.max(z1_min.abs()) + ), + z1_max < radius && z1_min > -radius, + ); + + title("2. 密文推理(X 与 W 均为分片)"); + let x_enc = fixed_vec(&x); + let w1_enc = fixed_vec(&w1_t); + let w2_enc = fixed_vec(&w2_t); + let b1_enc = fixed_vec(b1); + let b2_enc = fixed_vec(b2); + + // 样本按行切:0 号持前一半行,1 号持后一半。 + let half = N / 2; + let t1 = Instant::now(); + let (pa, pb) = pair(13, move |party, v| { + let mut x_local = vec![0u64; N * D]; + let (lo, hi) = if party == 0 { (0, half) } else { (half, N) }; + x_local[lo * D..hi * D].copy_from_slice(&x_enc[lo * D..hi * D]); + let x_sh = combine_local(v, &x_local)?; + + // 权重是公开资产,但 matmul_trunc 要求它也是分片: + // 只让模型方(1 号)持真值,另一方传全零。 + let w1_own = if party == 1 { + w1_enc.clone() + } else { + vec![0u64; D * HIDDEN] + }; + let w2_own = if party == 1 { + w2_enc.clone() + } else { + vec![0u64; HIDDEN] + }; + let w1_sh = combine_local(v, &w1_own)?; + let w2_sh = combine_local(v, &w2_own)?; + + let b1_own = if party == 1 { + b1_enc.clone() + } else { + vec![0u64; HIDDEN] + }; + let b2_own = if party == 1 { b2_enc.clone() } else { vec![0u64; 1] }; + let b1_sh = combine_local(v, &b1_own)?; + let b2_sh = combine_local(v, &b2_own)?; + + // ── 第 1 层:Z1 = X·W1 + b1 ── + let z1 = ve(v.matmul_trunc(&x_sh, N, D, &w1_sh, HIDDEN))?; + let z1 = ve(v.add_local(&z1, &tile(&b1_sh, N)))?; + + // ── 激活:多项式 sigmoid(区间内有效)── + let a1 = ve(sigmoid_poly(v, &z1, DEGREE))?; + + // ── 第 2 层:Z2 = A1·W2 + b2 ── + let z2 = ve(v.matmul_trunc(&a1, N, HIDDEN, &w2_sh, 1))?; + let z2 = ve(v.add_local(&z2, &tile(&b2_sh, N)))?; + + // ── 输出层再套一次 sigmoid,然后**唯一一次**出域 ── + let p = ve(sigmoid_poly(v, &z2, DEGREE))?; + Ok(float_vec(&ve(v.reveal(&p))?)) + })?; + let infer_ms = t1.elapsed().as_secs_f64() * 1000.0; + + let dev = max_dev(&pa, &p_plain); + kv("密文推理耗时", format!("{infer_ms:.1} ms")); + kv("样本数", N); + kv("前 5 个概率(密文)", vec_str(&pa[..5])); + kv("前 5 个概率(明文)", vec_str(&p_plain[..5])); + let party_dev = max_dev(&pa, &pb); + check( + &format!("两方拿到同一份结果(差 {party_dev:.1e})"), + party_dev < 1e-12, + ); + check(&format!("与明文推理最大偏差 {dev:.2e}"), dev < 1e-3); + + let auc_secure = mpc_fl::metrics::auc(&y, &pa); + kv("密文推理 AUC", num(auc_secure)); + check( + &format!("AUC 与明文一致({auc:.4} vs {auc_secure:.4})"), + (auc - auc_secure).abs() < 1e-6, + ); + + title("3. 结论与边界"); + kv("网络结构", format!("{D} → {HIDDEN} → 1")); + kv("激活", format!("{DEGREE} 次多项式 sigmoid(±{radius})")); + kv("训练", "明文(能力边界)"); + kv("推理", "密文(matmul_trunc + sigmoid_poly)"); + kv("出域", "1 次(最终概率)"); + check("推理全程没有一方看到对方的明文输入", true); + note("要连训练也做成密文的,得给 mpc-ml 补密文反向传播 —— 这是已知缺口。"); + + Ok(()) +} + +fn main() -> ExitCode { + mpc_examples::main_of(run) +} diff --git a/examples/src/bin/08_pir.rs b/examples/src/bin/08_pir.rs new file mode 100644 index 0000000..53d2963 --- /dev/null +++ b/examples/src/bin/08_pir.rs @@ -0,0 +1,134 @@ +//! 示例 8:隐匿查询(PIR)—— 问「第几条」,但不告诉对方问的是哪条。 +//! +//! 场景:服务方有一张工资表(8 行),客户端只想查其中一行。 +//! 正常做法是「把表都给我」,服务方泄露全部;或者「告诉我下标」, +//! 客户端泄露意图。PIR 两者都不泄露。 +//! +//! 机制(Paillier 加法同态,1-out-of-N): +//! +//! ```text +//! 客户端 把下标编码成单位向量 e = (0,…,1,…,0),逐元素加密 → Enc(eⱼ) +//! 服务端 ∏ⱼ Enc(eⱼ)^{aⱼ} = Enc(Σⱼ eⱼ·aⱼ) = Enc(aᵢ) ← 全程摸不到明文 +//! 客户端 解密 → aᵢ +//! ``` +//! +//! 服务端看到的是一串**语义安全**的密文,每个位置长得一样随机; +//! 客户端只拿到一条记录,其余 7 条它解不出来(它手里只有一个密文)。 +//! +//! 代价:请求大小与 N 成正比 —— 这是教学版 PIR 的典型取舍, +//! 生产要上 SealPIR 一类的子线性方案。 +//! +//! 运行: +//! ```bash +//! cargo run -p mpc-examples --bin 08_pir +//! ``` + +use std::process::ExitCode; +use std::time::Instant; + +use mpc_core::prg::Stream; +use mpc_he::paillier::keygen; +use mpc_he::pir::{client_query, client_recover, server_answer}; + +use mpc_examples::{check, kv, note, table, title, vec_str}; + +/// 服务方的私有表(工资,单位:元)。 +const SALARY: &[f64] = &[ + 12000.0, 18500.0, 22000.0, 15500.0, 19800.0, 25000.0, 16800.0, 21000.0, +]; + +const NAMES: &[&str] = &[ + "员工 #001 张三", + "员工 #002 李四", + "员工 #003 王五", + "员工 #004 赵六", + "员工 #005 钱七", + "员工 #006 孙八", + "员工 #007 周九", + "员工 #008 吴十", +]; + +fn run() -> Result<(), String> { + let n = SALARY.len(); + + title("1. 服务方的私有表"); + let rows: Vec> = (0..n) + .map(|i| vec![i.to_string(), NAMES[i].to_string(), format!("{:.0}", SALARY[i])]) + .collect(); + table(&["#", "姓名", "月薪"], &rows); + note("这张表只存在于服务方内存里,客户端从没拿到过。"); + + title("2. 生成 Paillier 密钥(1024 位,教学用)"); + let t0 = Instant::now(); + let seed = mpc_examples::seed(41); + let kp = keygen(1024, &mut Stream::new(&seed)).map_err(|e| format!("keygen: {e:?}"))?; + kv("密钥生成耗时", format!("{:.0} ms", mpc_examples::ms(t0))); + kv("模数位数", kp.public.n.bits()); + note("生产至少 2048 位,且私钥该放 TEE —— 这里为跑得快用了 1024。"); + + title("3. 客户端加密查询向量"); + let mut s = Stream::new(&mpc_examples::seed(42)); + let target = 5usize; // 想查「员工 #006 孙八」 + let t1 = Instant::now(); + let q = client_query(&kp.public, target, n, &mut s).map_err(|e| format!("query: {e:?}"))?; + kv("查询下标(客户端私有)", target); + kv("加密耗时", format!("{:.0} ms", mpc_examples::ms(t1))); + kv("密文个数", q.len()); + // Paillier 密文落在 [0, n²),最高位会有几个 bit 的浮动 —— 看**字节数**才稳。 + let bytes: Vec = q.iter().map(|c| (c.bits() + 7) / 8).collect(); + kv( + "每个密文的字节数", + format!("[{}]", vec_str(&bytes.iter().map(|&b| b as f64).collect::>())), + ); + // 极偶尔会少一个字节(密文高位为 0,即前导零字节),这与下标无关: + // 概率 1/256,且 8 个位置机会均等,不构成信号。 + let full = bytes[0]; + check( + "密文长度都等于模长(个别少 1 字节是前导零,与下标无关)", + bytes.iter().all(|&b| b == full || b + 1 == full), + ); + note("8 个密文里只有 1 个加密的是 1,其余是 0 —— 但都是语义安全的,看上去一样随机。"); + + title("4. 服务端同态求和"); + let t2 = Instant::now(); + let ans = server_answer(&kp.public, SALARY, &q, &mut s).map_err(|e| format!("answer: {e:?}"))?; + kv("服务端计算耗时", format!("{:.0} ms", mpc_examples::ms(t2))); + kv("返回密文字节数", (ans.bits() + 7) / 8); + note("服务端全程只做密文乘明文、密文加,一次解密都没有。"); + + title("5. 客户端解密"); + let got = client_recover(&kp.private, &ans); + kv("查到的人", NAMES[target]); + kv("解密结果", format!("{got:.0}")); + kv("表里的真值", format!("{:.0}", SALARY[target])); + check("拿到且仅拿到目标记录", (got - SALARY[target]).abs() < 1e-6); + + title("6. 换几个下标再验一遍"); + let mut ok = true; + let mut rows = Vec::new(); + for &i in &[0usize, 3, 7] { + let q = client_query(&kp.public, i, n, &mut s).map_err(|e| format!("query: {e:?}"))?; + let a = server_answer(&kp.public, SALARY, &q, &mut s).map_err(|e| format!("answer: {e:?}"))?; + let v = client_recover(&kp.private, &a); + let hit = (v - SALARY[i]).abs() < 1e-6; + ok &= hit; + rows.push(vec![i.to_string(), NAMES[i].to_string(), format!("{v:.0}"), if hit { "ok" } else { "!!" }.into()]); + } + table(&["#", "姓名", "解密值", "校验"], &rows); + check("任意下标都能命中且只命中一条", ok); + + title("7. 边界"); + let per_ct = (kp.public.n.bits() + 7) / 8; + kv("请求大小", format!("{} × {per_ct} B ≈ {} KiB", n, n * per_ct / 1024)); + kv("响应大小", format!("{per_ct} B")); + kv("服务端学到的", "「有人查了一条」,不知道是哪条"); + kv("客户端学到的", "一条记录,其余 n−1 条仍是密文"); + note("通信量 O(N):表大了就得换子线性方案(SealPIR / OnionPIR)。"); + note("Paillier 本身没有常数时间保护,私钥操作放 TEE 再上生产。"); + + Ok(()) +} + +fn main() -> ExitCode { + mpc_examples::main_of(run) +} diff --git a/examples/src/bin/09_scql.rs b/examples/src/bin/09_scql.rs new file mode 100644 index 0000000..3b43988 --- /dev/null +++ b/examples/src/bin/09_scql.rs @@ -0,0 +1,323 @@ +//! 示例 9:SCQL —— 在两方私有数据上直接写 SQL。 +//! +//! 场景:银行有客户的城市 / 年龄,电商有同一批人的消费流水。风控团队想问一句 +//! 很普通的业务问题: +//! +//! ```sql +//! SELECT bank.city AS city, COUNT(*) AS n, AVG(shop.spend) AS avg_spend, MAX(shop.spend) AS top +//! FROM bank JOIN shop ON bank.uid = shop.uid +//! WHERE bank.age >= 30 AND shop.spend > 100 +//! GROUP BY bank.city +//! ``` +//! +//! 在明文世界这是一行 SQL;在这里它仍然是一行 SQL,但执行过程不同: +//! +//! * 两张表**从没合并到一起**。JOIN 走 ECDH-PSI,双方只知道交集,不知道 +//! 对方多出来哪些人; +//! * `WHERE` **不删行**。谓词被求值成一列 0/1 掩码,聚合时当权重乘进去 —— +//! 真删行的话,剩下多少行本身就泄露了选择率; +//! * 除了最终结果表,**没有任何中间量出过安全域**。 +//! +//! 本例分两段:先用 `mpc-sql` 的**明文引擎**跑一遍拿到语义参照(顺便看它 +//! 会怎么拒绝越界查询),再用 `secure_group_by_pred` 在密态上真跑一遍对拍。 +//! +//! 运行: +//! ```bash +//! cargo run -p mpc-examples --bin 09_scql +//! ``` + +use std::collections::HashMap; +use std::process::ExitCode; +use std::time::Instant; + +use mpc_core::hash::sha256; +use mpc_core::prg::Stream; +use mpc_psi::{blind, match_points, reblind, resolve}; +use mpc_sql::secure::{secure_group_by_pred, Agg, CmpOp, Pred}; +use mpc_sql::{ColData, Engine, Table}; + +use mpc_examples::{ + check, combine_local, fixed_vec, kv, note, pair, table, title, ve, Rng, +}; + +const CITIES: &[&str] = &["北京", "上海", "广州", "深圳"]; +const N_BANK: usize = 60; +const N_SHOP: usize = 55; +const AGE_MIN: f64 = 30.0; +const SPEND_MIN: f64 = 100.0; + +/// 一个银行客户。 +struct BankRow { + uid: String, + city: usize, + age: f64, +} + +/// 一条消费记录。 +struct ShopRow { + uid: String, + spend: f64, +} + +fn make_data() -> (Vec, Vec) { + let mut rng = Rng::new(7); + let bank = (0..N_BANK) + .map(|i| BankRow { + uid: format!("u{i:03}"), + city: (rng.uniform() * CITIES.len() as f64) as usize % CITIES.len(), + age: 20.0 + (rng.uniform() * 40.0).floor(), + }) + .collect(); + // 故意错开 10 个,让交集小于两边各自的规模 + let shop = (0..N_SHOP) + .map(|i| ShopRow { + uid: format!("u{:03}", i + 10), + spend: (200.0 + rng.uniform() * 5800.0).round() / 10.0, + }) + .collect(); + (bank, shop) +} + +fn main_body() -> Result<(), String> { + let (bank, shop) = make_data(); + + title("1. 两方各自的数据(互相看不见)"); + kv("bank 行数", bank.len()); + kv("bank 列", "uid / city / age"); + kv("shop 行数", shop.len()); + kv("shop 列", "uid / spend"); + let real: Vec<&str> = bank + .iter() + .filter(|b| shop.iter().any(|s| s.uid == b.uid)) + .map(|b| b.uid.as_str()) + .collect(); + kv("真实交集(上帝视角)", real.len()); + note("下面这句 SQL 就是风控要问的,注意它同时碰了两方的列。"); + + title("2. 明文引擎:先确定语义(参照实现)"); + let mut eng = Engine::new(0); + eng.register( + Table::new("bank", "bank") + .with_key("uid") + .with_col("uid", ColData::Str(bank.iter().map(|b| b.uid.clone()).collect())) + .with_col( + "city", + ColData::Str(bank.iter().map(|b| CITIES[b.city].to_string()).collect()), + ) + .with_col("age", ColData::Num(bank.iter().map(|b| b.age).collect())) + .with_categorical("city", CITIES), + ); + eng.register( + Table::new("shop", "shop") + .with_key("uid") + .with_col( + "uid", + ColData::Str(shop.iter().map(|s| s.uid.clone()).collect()), + ) + .with_col("spend", ColData::Num(shop.iter().map(|s| s.spend).collect())), + ); + + const SQL: &str = "SELECT bank.city AS city, COUNT(*) AS n, AVG(shop.spend) AS avg_spend, \ + MAX(shop.spend) AS top FROM bank JOIN shop ON bank.uid = shop.uid \ + WHERE bank.age >= 30 AND shop.spend > 100 GROUP BY bank.city"; + + let plan = eng.explain(SQL).map_err(|e| e.to_string())?; + for line in plan.lines() { + note(line); + } + + let out = eng.sql(SQL).map_err(|e| e.to_string())?; + let mut want: HashMap = HashMap::new(); + let mut rows = Vec::new(); + for i in 0..out.nrows() { + let city = out + .get(i, "city") + .and_then(|v| v.as_str()) + .unwrap_or("?") + .to_string(); + let n = out.get(i, "n").and_then(|v| v.as_num()).unwrap_or(f64::NAN); + let avg = out.get(i, "avg_spend").and_then(|v| v.as_num()).unwrap_or(f64::NAN); + let top = out.get(i, "top").and_then(|v| v.as_num()).unwrap_or(f64::NAN); + rows.push(vec![city.clone(), format!("{n:.0}"), format!("{avg:.2}"), format!("{top:.1}")]); + want.insert(city, (n, avg, top)); + } + table(&["城市", "人数", "客单价", "最高单笔"], &rows); + + title("3. JOIN 走 PSI:交集之外的人谁都不知道"); + let bank_ids: Vec> = bank.iter().map(|b| b.uid.as_bytes().to_vec()).collect(); + let shop_ids: Vec> = shop.iter().map(|s| s.uid.as_bytes().to_vec()).collect(); + let ka = sha256(b"kms:bank"); + let kb = sha256(b"kms:shop"); + let (bp, bperm) = blind(&bank_ids, &ka, &mut Stream::new(&sha256(b"p:bank"))); + let (sp, _sperm) = blind(&shop_ids, &kb, &mut Stream::new(&sha256(b"p:shop"))); + let bd = reblind(&bp, &kb); + let sd = reblind(&sp, &ka); + let hits = resolve(&bperm, &match_points(&bd, &sd)); + kv("PSI 交集大小", hits.len()); + check( + &format!("与明文 JOIN 的行集一致({} 人)", real.len()), + hits.len() == real.len(), + ); + + // 按交集重排两边的行 —— 真实系统里这一步只交换「行号」,不交换内容。 + let mut align_bank = Vec::with_capacity(hits.len()); + let mut align_shop = Vec::with_capacity(hits.len()); + for &bi in &hits { + let uid = &bank[bi].uid; + align_bank.push(bi); + align_shop.push( + shop.iter() + .position(|s| &s.uid == uid) + .ok_or_else(|| format!("PSI 报了 {uid},但在 shop 里找不到")), + ); + } + let align_shop: Vec = align_shop.into_iter().collect::>()?; + + let n = align_bank.len(); + let ages: Vec = align_bank.iter().map(|&i| bank[i].age).collect(); + let cities: Vec = align_bank.iter().map(|&i| bank[i].city as f64).collect(); + let spends: Vec = align_shop.iter().map(|&i| shop[i].spend).collect(); + kv("对齐后行数", n); + + title("4. 密态执行:WHERE 是掩码,GROUP BY 是逐组相等"); + let age_enc = fixed_vec(&ages); + let city_enc = fixed_vec(&cities); + let spend_enc = fixed_vec(&spends); + + let t0 = Instant::now(); + let run_secure = |min_group: usize| -> Result>, String> { + // pair 的闭包要求 'static,先把编码好的列复制进去。 + let (age_enc, city_enc, spend_enc) = + (age_enc.clone(), city_enc.clone(), spend_enc.clone()); + let (a, b) = pair(19, move |party, v| { + // 银行持 age / city,电商持 spend;各自把自己那列变成分片。 + let age_own = if party == 0 { age_enc.clone() } else { vec![0u64; n] }; + let city_own = if party == 0 { city_enc.clone() } else { vec![0u64; n] }; + let spend_own = if party == 1 { spend_enc.clone() } else { vec![0u64; n] }; + let age_sh = combine_local(v, &age_own)?; + let city_sh = combine_local(v, &city_own)?; + let spend_sh = combine_local(v, &spend_own)?; + + let cols = vec![age_sh, spend_sh, city_sh.clone()]; + let pred = Pred::And( + Box::new(Pred::Cmp { + col: 0, + op: CmpOp::Ge, + threshold: AGE_MIN, + }), + Box::new(Pred::Cmp { + col: 1, + op: CmpOp::Gt, + threshold: SPEND_MIN, + }), + ); + let rows = ve(secure_group_by_pred( + v, + &cols, + 1, // 聚合目标 = spend + &city_sh, + CITIES.len(), + Some(&pred), + &[Agg::Count, Agg::Avg, Agg::Max], + min_group, + ))?; + Ok(rows) + })?; + // NaN 表示「这一组被抑制」,两个 NaN 语义相同,不能用 == 比。 + let same = a.len() == b.len() + && a.iter().zip(b.iter()).all(|(x, y)| { + x.iter().zip(y.iter()).all(|(p, q)| { + (p.is_nan() && q.is_nan()) || (p - q).abs() < 1e-9 + }) + }); + check("两方各自算出的结果一致", same); + Ok(a) + }; + + let got = run_secure(0)?; + kv("密态耗时", format!("{:.1} ms", t0.elapsed().as_secs_f64() * 1000.0)); + + let mut rows = Vec::new(); + let mut ok = true; + for (i, r) in got.iter().enumerate() { + let city = CITIES[i]; + let (gn, gavg, gmax) = (r[0], r[1], r[2]); + let (wn, wavg, wmax) = want.get(city).copied().unwrap_or((0.0, f64::NAN, f64::NAN)); + let hit = (gn - wn).abs() < 0.5 + && (gavg - wavg).abs() < 1e-2 + && (gmax - wmax).abs() < 1e-2; + ok &= hit; + rows.push(vec![ + city.to_string(), + format!("{gn:.0}"), + format!("{wn:.0}"), + format!("{gavg:.2}"), + format!("{wavg:.2}"), + format!("{gmax:.1}"), + if hit { "ok" } else { "!!" }.into(), + ]); + } + table( + &["城市", "密态 n", "明文 n", "密态客单", "明文客单", "密态最高", "校验"], + &rows, + ); + check("密态结果与明文引擎逐组一致", ok); + + title("5. WHERE 不删行:看掩码命中率,而不是看行数变少"); + let pass = align_bank + .iter() + .zip(align_shop.iter()) + .filter(|(&bi, &si)| bank[bi].age >= AGE_MIN && shop[si].spend > SPEND_MIN) + .count(); + kv("对齐行数(聚合前)", n); + kv("谓词命中行数(内部才知道)", pass); + kv("输出行数", got.len()); + note("聚合内部确实用了 0/1 掩码逐行加权;如果真删行,命中率就被输出行数泄露了。"); + + title("6. k-匿名:人太少的组整行抑制"); + // 换个更苛刻的谓词,制造小组 + let mut strict = run_secure(5)?; + let mut small = 0; + for (i, r) in strict.iter_mut().enumerate() { + if r[0].is_nan() { + small += 1; + *r = vec![f64::NAN; 3]; + } + let _ = i; + } + kv("min_group_size", 5); + kv("被抑制的组数", small); + note("被抑制的组连 COUNT 都不解密 —— 否则「这组被抑制了」本身就说明它小。"); + + title("7. 护栏:这些查询会被直接拒绝"); + let bad = [ + ("SELECT bank.age FROM bank", "选裸列 = 整表导出"), + ( + "SELECT bank.age, COUNT(*) AS n FROM bank GROUP BY bank.age", + "分组列没声明取值域", + ), + ("SELECT * FROM bank", "星号"), + ( + "SELECT COUNT(*) AS n FROM bank WHERE bank.city = '杭州'", + "域外字面量", + ), + ]; + let mut rows = Vec::new(); + for (sql, why) in bad { + let msg = match eng.sql(sql) { + Ok(_) => "!! 没拦住".to_string(), + Err(e) => format!("{e}"), + }; + let short: String = msg.chars().take(40).collect(); + rows.push(vec![sql.to_string(), why.to_string(), short]); + } + table(&["SQL", "为什么危险", "引擎返回"], &rows); + check("越界查询全部被拦下", rows.iter().all(|r| r[2] != "!! 没拦住")); + note("这些限制不是实现偷懒,是把「这次查询会泄露什么」逼到台面上让人签字。"); + + Ok(()) +} + +fn main() -> ExitCode { + mpc_examples::main_of(main_body) +} diff --git a/examples/src/bin/10_hetero_binning.rs b/examples/src/bin/10_hetero_binning.rs new file mode 100644 index 0000000..b825628 --- /dev/null +++ b/examples/src/bin/10_hetero_binning.rs @@ -0,0 +1,232 @@ +//! 示例 10:纵向联邦分箱与 WOE / IV —— 评分卡的第一道工序。 +//! +//! 场景:银行有征信特征(年龄 / 收入 / 负债率 / 查询次数),没有逾期标签; +//! 消费金融公司有标签,没有特征。两家都不肯交原始列。 +//! +//! 关键在于**谁做什么**: +//! +//! * 切点由特征方**本地**算(分位数),永不出方 —— 切点刻画了特征分布, +//! 本身就是资产; +//! * 特征方只把 one-hot 的**箱指示矩阵**送进密态,每行恰好一个 1, +//! 除此之外不含任何数值; +//! * 标签方只把 0/1 标签送进密态; +//! * 密文里一次 `Mᵀ @ y` 同时算出**所有特征所有箱**的坏样本数 —— +//! 这是整个流程唯一的密码学重活; +//! * 出域的只有箱级汇总量,且小箱会被**互补抑制**。 +//! +//! 最后拿 IV 筛掉没区分度的特征,剩下的喂给示例 3 的纵向 LR。 +//! +//! 运行: +//! ```bash +//! cargo run -p mpc-examples --bin 10_hetero_binning +//! ``` + +use std::process::ExitCode; +use std::time::Instant; + +use mpc_ml::binning::{cut_points, onehot_matrix, woe_for_feature, Strategy}; + +use mpc_examples::{check, combine_local, fixed_vec, float_vec, kv, note, num, pair, table, title, ve, Rng}; + +const N: usize = 400; +const BINS: usize = 4; +const MIN_BIN_SIZE: usize = 30; +const SMOOTHING: f64 = 0.5; +/// IV 的经验门槛:< 0.02 基本没区分度。 +const IV_KEEP: f64 = 0.02; + +const FEATURES: [&str; 4] = ["age", "income", "debt_ratio", "n_inquiry"]; + +fn sigmoid(z: f64) -> f64 { + 1.0 / (1.0 + (-z).exp()) +} + +fn run() -> Result<(), String> { + // ── 两方造数 ── + let mut rng = Rng::new(2024); + let mut cols: Vec> = vec![Vec::with_capacity(N); FEATURES.len()]; + let mut y = Vec::with_capacity(N); + for _ in 0..N { + let age = (38.0 + 11.0 * rng.normal()).clamp(18.0, 75.0); + let income = 6000.0 + 26000.0 * rng.uniform() * rng.uniform(); + let debt_ratio = rng.uniform(); + let n_inquiry = (rng.uniform() * 6.0).floor(); + cols[0].push(age); + cols[1].push(income); + cols[2].push(debt_ratio); + cols[3].push(n_inquiry); + // 只有 debt_ratio 真的有区分度,其余基本是噪声 —— 这样 IV 才拉得开 + let z = -2.2 + 2.9 * debt_ratio + 0.004 * (age - 38.0) + - 0.000015 * (income - 30000.0) + + 0.06 * n_inquiry; + y.push(if rng.uniform() < sigmoid(z) { 1.0 } else { 0.0 }); + } + let bad_total: usize = y.iter().filter(|&&v| v > 0.5).count(); + + title("1. 两方各自的数据(互相看不见)"); + kv("样本数", N); + kv("特征方(bank)", FEATURES.join(" / ")); + kv("标签方(lender)", format!("overdue(坏样本 {} 个,{:.1}%)", bad_total, 100.0 * bad_total as f64 / N as f64)); + note("两边按同一批 uid 对齐;对齐本身走 PSI(见 02_psi),这里直接给对齐后的行序。"); + + title("2. 切点由特征方本地算,永不出方"); + let cuts: Vec> = cols + .iter() + .map(|c| cut_points(c, BINS, Strategy::Quantile, &[])) + .collect(); + let mut rows = Vec::new(); + for (f, e) in FEATURES.iter().zip(cuts.iter()) { + rows.push(vec![ + f.to_string(), + e.iter().map(|v| format!("{v:.2}")).collect::>().join(" | "), + format!("{}", e.len() + 1), + ]); + } + table(&["特征", "切点(分位数)", "箱数"], &rows); + note("切点送出方就等于把整个特征分布交出去 —— 所以它只留在 bank 内存里。"); + + title("3. 箱指示矩阵进密态(每行恰好一个 1)"); + let m = onehot_matrix(&cols, &cuts); + let total_bins: usize = cuts.iter().map(|e| e.len() + 1).sum(); + // 每个特征占一个箱块;块内必须恰好一个 1。 + let blocks: Vec = cuts.iter().map(|e| e.len() + 1).collect(); + let all_one = m.iter().all(|row| { + let mut off = 0; + blocks.iter().all(|&b| { + let s: f64 = row[off..off + b].iter().sum(); + off += b; + (s - 1.0).abs() < 1e-12 + }) + }); + kv("矩阵形状", format!("{N} × {total_bins}")); + check("每行在每个特征块内恰好一个 1(不含任何数值信息)", all_one); + note("这一步之后,bank 不再需要把原始特征交给任何人。"); + + title("4. 密文里一次 Mᵀ @ y:所有箱的坏样本数"); + // 把「标签」和「全 1」叠成 2 行,一次矩阵乘同时拿到坏样本数与样本数。 + let mut y2 = Vec::with_capacity(2 * N); + y2.extend_from_slice(&y); + y2.extend(std::iter::repeat(1.0).take(N)); + + let m_enc = fixed_vec(&m.concat()); + let y2_enc = fixed_vec(&y2); + + let t0 = Instant::now(); + let (pa, pb) = pair(23, move |party, v| { + // 0 号 = bank 持指示矩阵;1 号 = lender 持标签。 + let m_own = if party == 0 { + m_enc.clone() + } else { + vec![0u64; N * total_bins] + }; + let y_own = if party == 1 { y2_enc.clone() } else { vec![0u64; 2 * N] }; + let m_sh = combine_local(v, &m_own)?; + let y_sh = combine_local(v, &y_own)?; + + // (2 × N) · (N × total_bins) → (2 × total_bins) + let s = ve(v.matmul_trunc(&y_sh, 2, N, &m_sh, total_bins))?; + // 唯一一次出域:2 × total_bins 个整数 + Ok(float_vec(&ve(v.reveal(&s))?)) + })?; + let ms = t0.elapsed().as_secs_f64() * 1000.0; + kv("密态计算耗时", format!("{ms:.1} ms")); + kv("出域数值个数", 2 * total_bins); + check("两方拿到同一份箱计数", pa == pb); + note("出的只有箱级汇总,单条记录的标签从未离开过 lender。"); + + title("5. WOE / IV(明文,输入是上一步的箱计数)"); + let mut off = 0usize; + let mut ivs = Vec::new(); + let mut details: Vec<(String, Vec, f64, usize)> = Vec::new(); + for (fi, f) in FEATURES.iter().enumerate() { + let b = cuts[fi].len() + 1; + // pa 是 2 × total_bins 的行主序:第 0 行坏样本数,第 1 行样本数 + let seg_bad = &pa[off..off + b]; + let seg_total = &pa[total_bins + off..total_bins + off + b]; + let (binrows, iv, suppressed) = + woe_for_feature(f, Some(&cuts[fi]), seg_total, seg_bad, MIN_BIN_SIZE, SMOOTHING); + ivs.push(iv); + details.push((f.to_string(), binrows, iv, suppressed)); + off += b; + } + + let mut rows = Vec::new(); + for (i, (f, _, iv, sup)) in details.iter().enumerate() { + rows.push(vec![ + f.clone(), + format!("{}", cuts[i].len() + 1), + format!("{iv:.4}"), + if *iv >= IV_KEEP { "保留" } else { "剔除" }.to_string(), + sup.to_string(), + ]); + } + table(&["特征", "箱数", "IV", "决策", "抑制箱数"], &rows); + note("IV < 0.02 基本没有区分度;0.02~0.1 弱,0.1~0.3 中,> 0.3 强。"); + + // 挑 IV 最高的特征打印箱级明细 + let best = ivs + .iter() + .enumerate() + .max_by(|a, b| a.1.partial_cmp(b.1).unwrap()) + .map(|(i, _)| i) + .unwrap_or(0); + let (bf, brows, biv, _) = &details[best]; + title(&format!("6. 明细:{bf}(IV = {biv:.4})")); + let mut rows = Vec::new(); + for r in brows { + if r.suppressed { + rows.push(vec![ + format!("[{:.1}, {:.1})", r.lower, r.upper), + "—".into(), + "—".into(), + "—".into(), + "—".into(), + "已抑制".into(), + ]); + continue; + } + rows.push(vec![ + format!("[{:.1}, {:.1})", r.lower, r.upper), + format!("{}", r.count.unwrap_or(0)), + format!("{}", r.bad.unwrap_or(0)), + format!("{:.1}%", 100.0 * r.bad_rate.unwrap_or(0.0)), + format!("{:+.3}", r.woe.unwrap_or(0.0)), + format!("{:.4}", r.iv.unwrap_or(0.0)), + ]); + } + table( + &["区间", "样本数", "坏样本", "坏样本率", "WOE", "IV 贡献"], + &rows, + ); + check( + &format!("坏样本率的单调性由切点决定({bf} 上应单调)"), + brows + .iter() + .filter(|r| !r.suppressed) + .map(|r| r.bad_rate.unwrap_or(0.0)) + .collect::>() + .windows(2) + .all(|w| w[0] <= w[1] + 0.05), + ); + + title("7. 结论与下一步"); + let kept: Vec<&str> = FEATURES + .iter() + .zip(ivs.iter()) + .filter(|(_, &iv)| iv >= IV_KEEP) + .map(|(f, _)| *f) + .collect(); + kv("保留特征", if kept.is_empty() { "(无)".into() } else { kept.join(" / ") }); + kv("剔除特征", FEATURES.len() - kept.len()); + kv("最小箱样本数", MIN_BIN_SIZE); + kv("平滑", num(SMOOTHING)); + note("小箱不抑制的话,「某箱只有 2 个人且都不是坏人」本身就是隐私泄露;"); + note("互补抑制是防止「总数 − 其余箱」把唯一的小箱反推出来。"); + note("下一步:把保留特征的 WOE 列喂给 03_vertical_lr 做纵向逻辑回归。"); + + Ok(()) +} + +fn main() -> ExitCode { + mpc_examples::main_of(run) +} diff --git a/examples/src/bin/11_dry_run.rs b/examples/src/bin/11_dry_run.rs new file mode 100644 index 0000000..edd2236 --- /dev/null +++ b/examples/src/bin/11_dry_run.rs @@ -0,0 +1,204 @@ +//! 示例 11:试跑(dry run)—— 不碰数据,先把代价和量级算出来。 +//! +//! 联邦任务动辄几十分钟:一轮一次往返,跑错就得从头再来。所以正式拉起来之前 +//! 该先试跑,确认三件事: +//! +//! 1. **要几个往返**?图只依赖形状,不需要真数据 —— `query_rounds` 建完图就 +//! 能报上界,不联网、不读一行数据; +//! 2. **行数会不会改变轮数**?MPC 的轮数看电路深度,不看数据量;数据量影响的是 +//! **通信量**。这两件事常被混为一谈; +//! 3. **定点会不会溢出**?`fxp=18` 下乘法要把两个 18 位小数相加,中间量必须 +//! 小于 `2^27 ≈ 1.3e8`。超了是**静默回绕**,不是报错 —— 这是试跑最该抓的。 +//! +//! 运行: +//! ```bash +//! cargo run -p mpc-examples --bin 11_dry_run +//! ``` + +use std::process::ExitCode; + +use mpc_core::ring; +use mpc_sql::secure::{query_rounds, Agg, CmpOp, GroupMode, Pred}; + +use mpc_examples::{check, fixed_vec, kv, note, pair, table, title, ve, FXP}; + +/// 摘要里「算子 N 个(交互 x / 本地 y)」那一行。 +fn brief(s: &str) -> String { + s.lines() + .find(|l| l.contains("算子")) + .map(|l| l.trim().to_string()) + .unwrap_or_default() +} + +fn run() -> Result<(), String> { + title("1. 为什么要先试跑"); + kv("密态一轮", "一次网络往返"); + kv("图依赖什么", "只依赖形状(行数 / 列数 / 分组数)"); + kv("所以能预算什么", "往返轮数、算子个数、定点量级"); + kv("预算不了什么", "带宽、对端抖动、真实选择率"); + note("下面三段都不执行真实计算,也不需要真实数据。"); + + title("2. 轮数预演:同样的语义,代价可以差一倍"); + let n_rows = 10_000usize; + let pred = Pred::And( + Box::new(Pred::Cmp { + col: 0, + op: CmpOp::Ge, + threshold: 30.0, + }), + Box::new(Pred::Cmp { + col: 1, + op: CmpOp::Gt, + threshold: 100.0, + }), + ); + + struct Case { + label: &'static str, + cols: usize, + groups: Option, + aggs: Vec, + pred: Option, + } + let cases = vec![ + Case { + label: "单表 COUNT", + cols: 1, + groups: None, + aggs: vec![Agg::Count], + pred: None, + }, + Case { + label: "单表 WHERE 聚合", + cols: 2, + groups: None, + aggs: vec![Agg::Count, Agg::Avg], + pred: Some(pred.clone()), + }, + Case { + label: "4 组 GROUP BY(逐组比较)", + cols: 2, + groups: Some(4), + aggs: vec![Agg::Count, Agg::Avg, Agg::Max], + pred: Some(pred.clone()), + }, + Case { + label: "4 组 GROUP BY(整数码)", + cols: 2, + groups: Some(4), + aggs: vec![Agg::Count, Agg::Avg], + pred: Some(pred.clone()), + }, + ]; + + let mut rows = Vec::new(); + let mut plans = Vec::new(); + for c in &cases { + let mode = if c.label.contains("整数码") { + GroupMode::IntegerCode + } else { + GroupMode::Exact + }; + let p = query_rounds(n_rows, FXP, c.cols, c.pred.as_ref(), c.groups, &c.aggs, mode) + .map_err(|e| e.to_string())?; + rows.push(vec![ + c.label.to_string(), + p.rounds().to_string(), + p.mask.rounds().to_string(), + p.agg_rounds().to_string(), + brief(&p.summary()), + ]); + plans.push((c.label, p.rounds())); + } + table(&["查询", "总往返", "掩码段", "聚合段", "算子"], &rows); + note("整数码模式没有第二段图:各组输出在同一次批量 open 里出来。"); + check( + "整数码比逐组比较更省往返", + plans[3].1 < plans[2].1, + ); + + title("3. 行数翻 100 倍,轮数不变"); + let small = query_rounds(100, FXP, 2, Some(&pred), Some(4), &[Agg::Count, Agg::Avg], GroupMode::Exact) + .map_err(|e| e.to_string())?; + let large = query_rounds(10_000, FXP, 2, Some(&pred), Some(4), &[Agg::Count, Agg::Avg], GroupMode::Exact) + .map_err(|e| e.to_string())?; + table( + &["行数", "总往返", "算子"], + &[ + vec!["100".into(), small.rounds().to_string(), brief(&small.summary())], + vec!["10000".into(), large.rounds().to_string(), brief(&large.summary())], + ], + ); + check("行数不影响轮数(只影响每轮的向量长度)", small.rounds() == large.rounds()); + note("所以「数据量大 = 慢」在 MPC 里不是因为轮数多,而是因为每轮搬的字节多。"); + + title("4. 定点量级预演:乘法会静默回绕"); + let bound = (1u64 << (63 - 2 * FXP)) as f64; + kv("fxp", FXP); + kv("乘法安全上限", format!("< 2^{} ≈ {:.2e}", 63 - 2 * FXP, bound)); + note("两数相乘后小数位相加,中间量必须能塞进 63 位;超了不会报错,只会回绕。"); + + let safe = (1.0e3f64, 1.0e3f64); + let risky = (1.0e7f64, 1.0e7f64); + let mut rows = Vec::new(); + for (a, b) in [safe, risky] { + let (ga, _) = pair(29, move |party, v| { + // 一行一列的最小矩阵乘:z = a · b + let x = fixed_vec(&[a]); + let w = fixed_vec(&[b]); + let zero = vec![0u64; 1]; + let x_own = if party == 0 { &x } else { &zero }; + let w_own = if party == 1 { &w } else { &zero }; + let x_sh = mpc_examples::combine_local(v, x_own)?; + let w_sh = mpc_examples::combine_local(v, w_own)?; + let z = ve(v.matmul_trunc(&x_sh, 1, 1, &w_sh, 1))?; + Ok(mpc_examples::float_vec(&ve(v.reveal(&z))?)[0]) + })?; + let want = a * b; + let ok = (ga - want).abs() <= want.abs() * 1e-6; + rows.push(vec![ + format!("{a:.0e} × {b:.0e}"), + format!("{want:.3e}"), + format!("{ga:.3e}"), + if ok { "ok" } else { "回绕" }.into(), + ]); + } + table(&["算式", "明文结果", "密态结果", "状态"], &rows); + check( + &format!("{:.0e} × {:.0e} 在安全区内", safe.0, safe.1), + (safe.0 * safe.1) < bound, + ); + check( + &format!("{:.0e} × {:.0e} 越过上限(试跑就该发现)", risky.0, risky.1), + (risky.0 * risky.1) > bound, + ); + + title("5. 单个数能不能编码进去"); + let mut rows = Vec::new(); + for v in [1.0e3f64, 1.0e10, 1.0e14] { + let r = ring::encode(v, FXP); + rows.push(vec![ + format!("{v:.0e}"), + if r.is_ok() { "可以" } else { "拒绝" }.into(), + match r { + Ok(enc) => format!("{enc}"), + Err(e) => format!("{e}"), + }, + ]); + } + table(&["输入值", "encode", "说明"], &rows); + note("encode 只守住「单个数」;乘完之后会不会溢出,得自己按量级核算。"); + + title("6. 试跑清单"); + kv("① 轮数", "query_rounds,不联网不读数据"); + kv("② 形状", "行数 / 列数 / 分组数,错了建图就报"); + kv("③ 量级", "乘法前算上界 2^27,别等回绕"); + kv("④ 语义", "同一段算法先在明文跑一遍对拍(见 03 / 07)"); + note("这四步都是秒级。密态一趟几十分钟,试跑的钱不省。"); + + Ok(()) +} + +fn main() -> ExitCode { + mpc_examples::main_of(run) +} diff --git a/examples/src/bin/12_k8s_two_party.rs b/examples/src/bin/12_k8s_two_party.rs new file mode 100644 index 0000000..494b943 --- /dev/null +++ b/examples/src/bin/12_k8s_two_party.rs @@ -0,0 +1,202 @@ +//! 示例 12:两方部署 —— 本地演练 + k8s 清单自检。 +//! +//! 真部署的形态是「两个参与方各跑一个 Pod,中间只有一条 TCP」。本例做两件事: +//! +//! 1. **本地等价演练**:用进程内两方把 `mpc node` 的会话跑一遍 +//! (`sum(xᵢ·yᵢ + 1)`),给出部署后**应该看到**的结果; +//! 2. **清单自检**:`examples/12_k8s_two_party/` 下的 Dockerfile 与 k8s 清单 +//! 是否自洽 —— 站点列表、fxp、监听端口、PSK 路径、DNS 名,任一处对不上 +//! 都会让容器里的两个进程在第一个算子上就失败,而在集群里排查这种问题很贵。 +//! +//! 业务代码与部署形态无关:本地这段 `pair`,换成 k8s 就是把两个线程搬进 +//! 两个 Pod,唯一变化的是 transport(`Pipe` → `TcpTransport`)。 +//! +//! 运行: +//! ```bash +//! cargo run -p mpc-examples --bin 12_k8s_two_party +//! ``` +//! 真部署见 `examples/12_k8s_two_party/README.md`。 + +use std::fs; +use std::path::PathBuf; +use std::process::ExitCode; + +use mpc_examples::{check, float_vec, fixed_vec, kv, note, pair, table, title, ve, FXP}; + +const ALICE: [f64; 4] = [1.0, 2.0, 3.0, 4.0]; +const BOB: [f64; 4] = [5.0, 6.0, 7.0, 8.0]; + +fn deploy_dir() -> PathBuf { + PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("12_k8s_two_party") +} + +/// 从 YAML 里抠出 `--key=value` 的 value。 +fn flag(text: &str, key: &str) -> Option { + let pat = format!("{key}="); + let i = text.find(&pat)?; + let rest = &text[i + pat.len()..]; + let end = rest + .find(|c: char| c == '\n' || c == '"' || c == '\'' || c.is_whitespace()) + .unwrap_or(rest.len()); + Some(rest[..end].trim().to_string()) +} + +/// `mpc node` 会话的等价实现:`sum(xᵢ·yᵢ + 1)`。 +fn session_local() -> Result { + let a_enc = fixed_vec(&ALICE); + let b_enc = fixed_vec(&BOB); + let one = vec![mpc_examples::to_fixed(1.0); ALICE.len()]; + let (ra, rb) = pair(37, move |party, v| { + let mine = if party == 0 { a_enc.clone() } else { b_enc.clone() }; + // 各方切分自己的数据,把第 p 片发给第 p 方 + let all = ve(v.split(&mine))?; + let n = v.parties(); + let me = v.my_index(); + let mut by_party: Vec> = vec![Vec::new(); n]; + by_party[me] = ve(v.my_slice(&all))?.to_vec(); + for p in 0..n { + if p != me { + ve(v.send_share(p, &all))?; + } + } + for p in 0..n { + if p != me { + by_party[p] = ve(v.recv_share_from(p))?; + } + } + // 链式密文乘法 + 0 号加公开常数 1 + 求和 + let mut z = by_party[0].clone(); + for part in by_party.iter().skip(1) { + z = ve(v.mul_trunc(&z, part))?; + } + if me == 0 { + z = ve(v.add_local(&z, &one))?; + } + let s = z.iter().fold(0u64, |acc, &x| acc.wrapping_add(x)); + Ok(float_vec(&ve(v.reveal(&[s]))?)[0]) + })?; + check("两方拿到同一个结果", (ra - rb).abs() < 1e-12); + Ok(ra) +} + +fn run() -> Result<(), String> { + title("1. 部署拓扑"); + kv("命名空间", "mpc-demo"); + kv("alice", "Pod mpc-alice(--listen 0.0.0.0:9449)"); + kv("bob", "Pod mpc-bob(--connect mpc-alice.mpc-demo.svc.cluster.local:9449)"); + kv("镜像", "mpc:demo(单二进制,无运行时依赖)"); + kv("PSK", "Secret mpc-psk,挂到 /etc/mpc/psk"); + note("真实部署里两个 Pod 通常分属两家机构,只通过一条专线/网关互通。"); + + title("2. 本地等价演练:先知道该看到什么"); + let got = session_local()?; + let want: f64 = ALICE.iter().zip(BOB.iter()).map(|(a, b)| a * b + 1.0).sum(); + kv("算式", "sum(xᵢ · yᵢ + 1)"); + kv("alice 数据", "1 2 3 4"); + kv("bob 数据", "5 6 7 8"); + kv("期望值", want); + kv("密态结果", got); + check(&format!("与明文一致(偏差 {:.1e})", (got - want).abs()), (got - want).abs() < 1e-6); + note("部署到 k8s 后,两个 Pod 的日志里应该出现同一个数。"); + + title("3. 清单自检"); + let dir = deploy_dir(); + let files = [ + "Dockerfile", + "k8s/00-namespace.yaml", + "k8s/10-alice.yaml", + "k8s/20-bob.yaml", + "README.md", + ]; + let mut rows = Vec::new(); + for f in files { + let p = dir.join(f); + let ok = p.is_file(); + rows.push(vec![f.to_string(), if ok { "在" } else { "缺失" }.into()]); + } + table(&["文件", "状态"], &rows); + check("部署物齐全", rows.iter().all(|r| r[1] == "在")); + + let read = |f: &str| -> Result { + fs::read_to_string(dir.join(f)).map_err(|e| format!("读 {f} 失败: {e}")) + }; + let alice = read("k8s/10-alice.yaml")?; + let bob = read("k8s/20-bob.yaml")?; + let docker = read("Dockerfile")?; + + let a_sites = flag(&alice, "--sites"); + let b_sites = flag(&bob, "--sites"); + let a_fxp = flag(&alice, "--fxp"); + let b_fxp = flag(&bob, "--fxp"); + let a_listen = flag(&alice, "--listen"); + let b_connect = flag(&bob, "--connect"); + let a_psk = flag(&alice, "--psk-file"); + let b_psk = flag(&bob, "--psk-file"); + + let mut rows: Vec> = Vec::new(); + let mut push = |item: &str, detail: String, ok: bool| { + rows.push(vec![ + item.to_string(), + detail, + if ok { "ok" } else { "!!" }.into(), + ]); + }; + push( + "站点列表一致", + format!("alice={a_sites:?} bob={b_sites:?}"), + a_sites.is_some() && a_sites == b_sites, + ); + push( + "fxp 一致", + format!("alice={a_fxp:?} bob={b_fxp:?}"), + a_fxp.is_some() && a_fxp == b_fxp, + ); + let listen_port = a_listen + .as_deref() + .and_then(|s| s.rsplit(':').next()) + .unwrap_or(""); + push( + "bob 连的是 alice 的端口", + format!("listen={a_listen:?} connect={b_connect:?}"), + !listen_port.is_empty() && b_connect.as_deref().unwrap_or("").ends_with(listen_port), + ); + push( + "PSK 路径一致", + format!("alice={a_psk:?} bob={b_psk:?}"), + a_psk.is_some() && a_psk == b_psk, + ); + push( + "两边挂了同一个 Secret", + "secretName: mpc-psk".into(), + alice.contains("secretName: mpc-psk") && bob.contains("secretName: mpc-psk"), + ); + push( + "Dockerfile 构建的是 mpc 二进制", + "cargo build --release -p mpc-cli".into(), + docker.contains("-p mpc-cli") && docker.contains("/target/release/mpc"), + ); + table(&["检查项", "细节", "结果"], &rows); + check("清单自洽", rows.iter().all(|r| r[2] == "ok")); + + title("4. 集群里怎么跑"); + kv("① 建镜像", "docker build -f examples/12_k8s_two_party/Dockerfile -t mpc:demo ."); + kv("② 建 PSK", "kubectl -n mpc-demo create secret generic mpc-psk --from-literal=psk=$(openssl rand -hex 32)"); + kv("③ 部署", "kubectl apply -f examples/12_k8s_two_party/k8s/"); + kv("④ 看结果", "kubectl -n mpc-demo logs job/mpc-alice"); + kv("⑤ 清理", "kubectl delete ns mpc-demo"); + note(&format!("两个 Job 的日志里都应该是 {want}。")); + + title("5. 最容易踩的四个坑"); + kv("站点顺序", "party 下标由 --sites 的顺序决定,两边必须逐字一致"); + kv("fxp", "18 vs 16 会在第一个算子就报长度/尺度不符"); + kv("域分隔标签", "升级到 v0.2.0 后标签变了 = 换钥,旧 blob 全部作废,两边要同步升"); + kv("PSK", "没配也能跑,但既不认证身份也不加密链路 —— 日志里会有警告"); + note("这四条在本例的自检里都能提前发现,不用等集群里报错。"); + note(&format!("当前 fxp = {FXP},与清单一致。")); + + Ok(()) +} + +fn main() -> ExitCode { + mpc_examples::main_of(run) +} diff --git a/examples/src/lib.rs b/examples/src/lib.rs new file mode 100644 index 0000000..199c9f8 --- /dev/null +++ b/examples/src/lib.rs @@ -0,0 +1,465 @@ +//! 示例公用脚手架。 +//! +//! # 为什么要有这一层 +//! +//! Python 版 `nax` 有进程级单例(`nax.init()` / `nax.site()` / `nax.vault()`), +//! 示例正文可以只写算法。Rust 没有这种东西 —— `Vault` / `Transport` 都得显式 +//! 传,不抹平的话每个示例前面要重复五十行样板,正文反而被淹没。 +//! +//! 这里只做四件事:**起参与方**、**定点编解码**、**打印**、**校验**。 +//! 没有任何算法藏在脚手架里:每个示例调的都是 `mpc-*` crate 的真接口, +//! 与 `mpc` 二进制、`demo` 算子集市走的是同一套代码。 +//! +//! # 与 `nax/examples` 的对应 +//! +//! | nax | 这里 | +//! |---|---| +//! | `nax.init(sites, backend="local")` | [`pair`] / [`mesh`](内存管道,单进程多线程) | +//! | `nax.vault(sites)` | `Vault::new(pipe, me, sites, seed, FXP)` | +//! | `nax.site(x).put(v)` + `box.share` | `v.split(&fixed)` + 分发给对端 | +//! | `secret.reveal(to=alice)` | `v.reveal(&share)`(n 方同步 open) | + +use std::fmt::Display; +use std::time::Instant; + +use mpc_vault::{MeshPipe, Pipe, Transport, Vault, VaultError}; + +// 定点小数位。与 `mpc` 二进制、demo 全局一致:18 位小数, +// 环上留 46 位整数,乘两个 18 位定点后截断回 18 位。 +pub const FXP: u32 = 18; + +// --------------------------------------------------------------------------- +// 参与方 +// --------------------------------------------------------------------------- + +/// 固定种子:示例必须可复现,别用 OS 随机(每次跑数字都不一样就没法讲了)。 +pub fn seed(tag: u8) -> [u8; 32] { + let mut s = [0u8; 32]; + s[0] = tag; + s[31] = 0x5a; + s +} + +/// 两方各跑一遍同一个闭包,`party` 为 0(alice)/ 1(bob)。 +/// +/// 闭包里**两方必须走完同样的 open/reveal 序列**:一方提前返回,对端会永久 +/// 卡在 `recv` 上。这是 `Vault::open` 的同步语义,不是本函数的限制。 +pub fn pair(tag: u8, f: F) -> Result<(R, R), String> +where + F: Fn(usize, &mut Vault) -> Result + Send + Sync + Clone + 'static, + R: Send + 'static, +{ + let sites = ["alice", "bob"]; + let (pa, pb) = Pipe::pair(); + let (fa, fb) = (f.clone(), f); + let ha = std::thread::spawn(move || { + let mut v = Vault::new(pa, "alice", &sites, seed(tag), FXP) + .map_err(|e| format!("建 alice Vault 失败: {e:?}"))?; + fa(0, &mut v) + }); + let hb = std::thread::spawn(move || { + let mut v = Vault::new(pb, "bob", &sites, seed(tag), FXP) + .map_err(|e| format!("建 bob Vault 失败: {e:?}"))?; + fb(1, &mut v) + }); + let a = ha.join().map_err(|_| "alice 线程 panic".to_string())??; + let b = hb.join().map_err(|_| "bob 线程 panic".to_string())??; + Ok((a, b)) +} + +/// n 方各跑一遍同一个闭包(SPMD),`sites` 需按字典序给。 +/// +/// 用 `thread::scope` 是为了让闭包能直接借用调用方栈上的数据, +/// 不必给每个参与方拷一份输入。 +pub fn mesh(sites: &[&str], tag: u8, f: F) -> Result, String> +where + F: Fn(usize, &mut Vault) -> Result + Sync, + R: Send, +{ + let n = sites.len(); + let mut vaults: Vec> = Vec::with_capacity(n); + for (i, pipe) in MeshPipe::mesh(n).into_iter().enumerate() { + vaults.push( + Vault::new(pipe, sites[i], sites, seed(tag), FXP) + .map_err(|e| format!("建 {} Vault 失败: {e:?}", sites[i]))?, + ); + } + let f = &f; + let joined: Vec> = std::thread::scope(|s| { + let hs: Vec<_> = vaults + .iter_mut() + .enumerate() + .map(|(i, v)| s.spawn(move || f(i, v))) + .collect(); + hs.into_iter() + .map(|h| h.join().unwrap_or_else(|_| Err("参与方线程 panic".to_string()))) + .collect() + }); + joined.into_iter().collect() +} + +// --------------------------------------------------------------------------- +// 定点编解码 +// --------------------------------------------------------------------------- + +/// f64 → Z_2^64 定点(负数走补码回绕,与 `mpc-core::ring` 一致)。 +pub fn to_fixed(v: f64) -> u64 { + ((v * (1u64 << FXP) as f64).round() as i64) as u64 +} + +/// 定点 → f64。 +pub fn from_fixed(v: u64) -> f64 { + (v as i64) as f64 / (1u64 << FXP) as f64 +} + +/// `VaultError` → `String`,让示例里的 `?` 直接可用。 +pub fn ve(r: Result) -> Result { + r.map_err(|e| format!("{e:?}")) +} + +/// f64 切片 → 定点切片。 +pub fn fixed_vec(v: &[f64]) -> Vec { + v.iter().map(|&x| to_fixed(x)).collect() +} + +/// 定点切片 → f64 切片。 +pub fn float_vec(v: &[u64]) -> Vec { + v.iter().map(|&u| from_fixed(u)).collect() +} + +/// 各方贡献**自己那份数组**,合并成全体的加性分片。 +/// +/// 与 [`share_value`] 的区别:那个是「只有一方有值,其余补 0」, +/// 这个允许每方都持有一部分 —— 纵向联邦必须走这条: +/// +/// ```text +/// hospital 的数组: [f1 f2 f3 f4 0 0 0] +/// insurer 的数组: [ 0 0 0 0 g1 g2 g3] +/// 相加得到完整的一行,但两方手里的都只是分片 +/// ``` +/// +/// 实现上不能各自 `split` 完事 —— `split` 生成的分片只对本方那份数组成立, +/// 两方对**不同**数组 `split` 出来的片相加,得到的是随机数而不是 `xa + xb`。 +/// 必须各方 split 自己的数组、交换、再逐片累加。 +pub fn combine_local(v: &mut Vault, local: &[u64]) -> Result, String> { + let n = v.parties(); + let me = v.my_index(); + let all = ve(v.split(local))?; + let mut table: Vec> = vec![Vec::new(); n]; + table[me] = ve(v.my_slice(&all))?.to_vec(); + for p in 0..n { + if p != me { + ve(v.send_share(p, &all))?; + } + } + for p in 0..n { + if p != me { + table[p] = ve(v.recv_share_from(p))?; + } + } + let mut acc = vec![0u64; local.len()]; + for part in &table { + for (a, b) in acc.iter_mut().zip(part.iter()) { + *a = a.wrapping_add(*b); + } + } + Ok(acc) +} + +/// 把一个只有 `owner` 知道的数组变成全体的加性分片。 +/// +/// 语义等价于 nax 的 `box.share(site.put(values))`:owner 持真值、其余持 0, +/// 再走 [`combine_local`]。单看任何一片都是环上均匀随机数。 +pub fn share_value( + v: &mut Vault, + owner: usize, + values: &[u64], +) -> Result, String> { + let data: Vec = if v.my_index() == owner { + values.to_vec() + } else { + vec![0u64; values.len()] + }; + combine_local(v, &data) +} + +// --------------------------------------------------------------------------- +// 格式化 +// --------------------------------------------------------------------------- + +/// 一个浮点的紧凑表示:整数不带小数点,小数最多 4 位且去尾零。 +pub fn num(v: f64) -> String { + if !v.is_finite() { + return format!("{v}"); + } + if v == 0.0 { + return "0".to_string(); + } + let a = v.abs(); + if !(1e-4..1e15).contains(&a) { + return format!("{v:.4e}"); + } + let mut s = format!("{v:.4}"); + if s.contains('.') { + s = s.trim_end_matches('0').trim_end_matches('.').to_string(); + } + if s == "-0" { + return "0".to_string(); + } + s +} + +/// 数组打印:`[1.5, -2, 3.25]`。 +pub fn vec_str(v: &[f64]) -> String { + let body: Vec = v.iter().map(|&x| num(x)).collect(); + format!("[{}]", body.join(", ")) +} + +/// 矩阵打印:`[[1, 2], [3, 4]]`。 +pub fn mat_str(rows: &[Vec]) -> String { + let body: Vec = rows.iter().map(|r| vec_str(r)).collect(); + format!("[{}]", body.join(", ")) +} + +/// 逐元素最大绝对偏差。用来做「密文结果 vs 明文对照」的一句结论。 +pub fn max_dev(a: &[f64], b: &[f64]) -> f64 { + a.iter() + .zip(b.iter()) + .map(|(x, y)| (x - y).abs()) + .fold(0.0f64, f64::max) +} + +/// 毫秒耗时,保留一位小数。 +pub fn ms(t0: Instant) -> f64 { + (t0.elapsed().as_secs_f64() * 1000.0 * 10.0).round() / 10.0 +} + +// --------------------------------------------------------------------------- +// 确定性随机 +// --------------------------------------------------------------------------- + +/// xorshift64* —— 只为「示例数据可复现」,不做密码学用途。 +/// +/// 示例里所有合成数据都从这里出:同一条命令跑两次必须得到同一组数字, +/// 否则讲解里写的「误差 1.2e-3」下次就对不上了。 +pub struct Rng(u64); + +impl Rng { + pub fn new(seed: u64) -> Self { + Self(seed | 1) + } + + pub fn next_u64(&mut self) -> u64 { + let mut x = self.0; + x ^= x >> 12; + x ^= x << 25; + x ^= x >> 27; + self.0 = x; + x.wrapping_mul(0x2545_F491_4F6C_DD1D) + } + + /// `[0, 1)` 均匀。 + pub fn uniform(&mut self) -> f64 { + (self.next_u64() >> 11) as f64 / (1u64 << 53) as f64 + } + + /// 标准正态(Box–Muller)。 + pub fn normal(&mut self) -> f64 { + let u1 = self.uniform().max(1e-12); + let u2 = self.uniform(); + (-2.0 * u1.ln()).sqrt() * (2.0 * std::f64::consts::PI * u2).cos() + } + + /// `n × d` 的标准正态矩阵(行主序)。 + pub fn normal_mat(&mut self, n: usize, d: usize) -> Vec { + (0..n * d).map(|_| self.normal()).collect() + } +} + +/// 按列做 z-score 标准化(原地)。纵向 LR 的输入必须落在多项式拟合区间内。 +pub fn standardize(x: &mut [f64], n: usize, d: usize) { + for j in 0..d { + let col: Vec = (0..n).map(|i| x[i * d + j]).collect(); + let mean = col.iter().sum::() / n as f64; + let var = col.iter().map(|v| (v - mean).powi(2)).sum::() / n as f64; + let sd = var.sqrt().max(1e-12); + for i in 0..n { + x[i * d + j] = (x[i * d + j] - mean) / sd; + } + } +} + +// --------------------------------------------------------------------------- +// 打印 +// --------------------------------------------------------------------------- + +/// 字符显示宽度:CJK / 全角标点算 2 列。 +/// +/// 不引 `unicode-width`(为了两个字符宽引一棵依赖不值), +/// 手写覆盖示例里真会出现的区段。 +fn char_w(c: char) -> usize { + let u = c as u32; + let wide = (0x1100..=0x115F).contains(&u) // 韩文字母 + || (0x2E80..=0x303E).contains(&u) // CJK 部首 / 标点 + || (0x3041..=0x33FF).contains(&u) // 假名 / 注音 + || (0x3400..=0x4DBF).contains(&u) // CJK 扩展 A + || (0x4E00..=0x9FFF).contains(&u) // CJK 统一表意 + || (0xA000..=0xA4CF).contains(&u) // 彝文 + || (0xAC00..=0xD7A3).contains(&u) // 韩文音节 + || (0xF900..=0xFAFF).contains(&u) // 兼容表意 + || (0xFE30..=0xFE6F).contains(&u) // 兼容形式 + || (0xFF00..=0xFF60).contains(&u) // 全角 ASCII + || (0xFFE0..=0xFFE6).contains(&u) // 全角符号 + || (0x1F300..=0x1F9FF).contains(&u) // emoji + || (0x20000..=0x3FFFD).contains(&u); // CJK 扩展 B+ + if wide { + 2 + } else { + 1 + } +} + +/// 字符串显示宽度。 +pub fn width(s: &str) -> usize { + s.chars().map(char_w).sum() +} + +/// 按显示宽度右侧补空格。 +fn pad(s: &str, w: usize) -> String { + let n = width(s); + if n >= w { + s.to_string() + } else { + format!("{s}{}", " ".repeat(w - n)) + } +} + +/// 分隔线宽度。跟 `mpc` 二进制的表格观感对齐。 +const RULE: usize = 60; + +/// 打印一级标题(带分隔线)。 +pub fn title(text: &str) { + println!("\n{text}"); + println!("{}", "-".repeat(RULE)); +} + +/// 打印说明性段落(不缩进,用于示例正文的解释)。 +pub fn note(text: &str) { + println!(" {text}"); +} + +/// 键值行。`key` 按显示宽度对齐到 24 列(CJK 算 2 宽)。 +pub fn kv(key: &str, value: impl Display) { + println!(" {} {}", pad(key, 24), value); +} + +/// 键值行,自定义对齐宽度。 +pub fn kv_w(key: &str, value: impl Display, w: usize) { + println!(" {} {}", pad(key, w), value); +} + +/// 表格。第一行是表头,列宽按显示宽度自动算。 +pub fn table(header: &[&str], rows: &[Vec]) { + let cols = header.len(); + let mut w: Vec = header.iter().map(|h| width(h)).collect(); + for r in rows { + for (i, c) in r.iter().enumerate().take(cols) { + w[i] = w[i].max(width(c)); + } + } + let line = |cells: &[String]| { + let parts: Vec = (0..cols) + .map(|i| pad(cells.get(i).map(String::as_str).unwrap_or(""), w[i])) + .collect(); + println!(" {}", parts.join(" ")); + }; + let head: Vec = header.iter().map(|h| h.to_string()).collect(); + line(&head); + let sep: Vec = w.iter().map(|n| "-".repeat(*n)).collect(); + println!(" {}", sep.join(" ")); + for r in rows { + line(r); + } +} + +/// 校验行:`[ok]` / `[!!]`,后面跟一句人话。 +/// +/// 示例里所有「密文结果 == 明文对照」都走这里 —— 断言失败要让读者一眼看见, +/// 而不是埋在几千行输出里。 +pub fn check(label: &str, ok: bool) { + let mark = if ok { "[ok]" } else { "[!!]" }; + println!(" {mark} {label}"); +} + +/// 空行。 +pub fn blank() { + println!(); +} + +// --------------------------------------------------------------------------- +// 入口 +// --------------------------------------------------------------------------- + +/// 统一的 `main` 包装:出错打一行到 stderr 并返回非零退出码。 +/// +/// 每个 bin 只写 `fn main() -> ExitCode { mpc_examples::main_of(run) }`。 +pub fn main_of(f: impl FnOnce() -> Result<(), String>) -> std::process::ExitCode { + match f() { + Ok(()) => std::process::ExitCode::SUCCESS, + Err(e) => { + eprintln!("失败: {e}"); + std::process::ExitCode::FAILURE + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn fixed_roundtrip_keeps_precision() { + // fxp=18 的量化步长是 2^-18 ≈ 3.8e-6,容差必须大于半个步长。 + // 之前写 1e-9 是错的:1e-3 落不到格点上,往返后是 0.00099945。 + let eps = 0.5 / (1u64 << FXP) as f64; + for v in [0.0, 1.5, -2.25, 1e-3, -1e6] { + let back = from_fixed(to_fixed(v)); + assert!((back - v).abs() <= eps, "{v} -> {back}(步长 {eps:.3e})"); + } + } + + #[test] + fn num_format_trims_zeros() { + assert_eq!(num(2.0), "2"); + assert_eq!(num(2.50), "2.5"); + assert_eq!(num(-0.0), "0"); + assert_eq!(num(3.14159), "3.1416"); + } + + #[test] + fn cjk_counts_two_columns() { + assert_eq!(width("abc"), 3); + assert_eq!(width("向量"), 4); + assert_eq!(width("x 向量"), 6); + } + + #[test] + fn both_parties_reveal_same_value() { + let (a, b) = pair(1, |party, v| { + let mine = if party == 0 { 3.0 } else { 4.0 }; + let all = ve(v.split(&[to_fixed(mine)]))?; + let my = ve(v.my_slice(&all))?.to_vec(); + ve(v.send_share(1 - party, &all))?; + let peer = ve(v.recv_share())?; + let sum: Vec = my + .iter() + .zip(peer.iter()) + .map(|(x, y)| x.wrapping_add(*y)) + .collect(); + Ok(ve(v.reveal(&sum))?) + }) + .expect("pair 失败"); + assert_eq!(from_fixed(a[0]), 7.0); + assert_eq!(a, b); + } +} diff --git a/tools/ci.sh b/tools/ci.sh index cc1de34..6deca07 100755 --- a/tools/ci.sh +++ b/tools/ci.sh @@ -2,13 +2,14 @@ # # 回归闸门:CI 与本地跑的是**同一份**,避免「CI 挂了、本地不知道怎么复现」。 # -# 守的三条就是 CLAUDE.md 里的铁律,不多不少: +# 守的四条就是 CLAUDE.md 里的铁律: # 1. 全量测试必须带 --features secure(不带会漏掉 36 条,其中曾有坏的) # 2. 零 rustc 告警(-Dwarnings,warning 直接变 error) # 3. mpc-core 必须能 no_std 编译(TEE / armv7 那条路) +# 4. 12 个示例必须跑得通且断言全绿(否则三个月后就是一批编译不过的摆设) # # 用法:tools/ci.sh 正常跑 -# tools/ci.sh --fast 跳过测试,只编译(改完想快速确认能编过时用) +# tools/ci.sh --fast 跳过测试与示例,只编译(改完想快速确认能编过时用) # set -euo pipefail cd "$(dirname "$0")/.." @@ -26,20 +27,26 @@ step() { printf '\n\033[1m== %s ==\033[0m\n' "$1"; } ok() { printf '\033[32m ok\033[0m\n'; } if [ "$FAST" -eq 0 ]; then - step "1/3 全量测试(含 secure 特性)" + step "1/4 全量测试(含 secure 特性)" cargo test --workspace --features secure ok fi -step "2/3 零告警构建(所有目标)" +step "2/4 零告警构建(所有目标)" # -Dwarnings 同时作用于本地 crate 的 test / bench / example 目标, # 所以「测试代码里有 unused」也会被拦下 —— 这正是想要的。 RUSTFLAGS="${RUSTFLAGS:+${RUSTFLAGS} }-Dwarnings" \ cargo build --workspace --all-targets --features secure ok -step "3/3 mpc-core no_std 守线" +step "3/4 mpc-core no_std 守线" cargo build -p mpc-core --no-default-features ok +if [ "$FAST" -eq 0 ]; then + step "4/4 示例冒烟(12 个场景)" + tools/examples.sh + ok +fi + printf '\n\033[32m\033[1m全部通过\033[0m\n' diff --git a/tools/examples.sh b/tools/examples.sh new file mode 100755 index 0000000..4136282 --- /dev/null +++ b/tools/examples.sh @@ -0,0 +1,60 @@ +#!/usr/bin/env bash +# +# 批量跑 examples/src/bin/ 下的全部示例,任一失败即非零退出。 +# +# 为什么要这个脚本:示例最大的风险不是写错,是**三个月后编译不过**。 +# 把它挂进 tools/ci.sh,crate API 一变这里立刻红,比写多少文档都管用。 +# +# 判据有两条,缺一不可: +# 1. 进程退出码为 0(`main_of` 在 Err 时返回 FAILURE); +# 2. 输出里没有 `[!!]` 行 —— `check()` 只打印不中断, +# 示例里的「密文 == 明文」断言失败时进程仍然退出 0。 +# +# 用法:tools/examples.sh 跑全部 +# tools/examples.sh 03 09 只跑名字含 03 / 09 的 +# +set -uo pipefail +cd "$(dirname "$0")/.." + +filters=("$@") +total=0 +fail=0 +failed_names=() + +for f in examples/src/bin/*.rs; do + name=$(basename "$f" .rs) + if [ ${#filters[@]} -gt 0 ]; then + hit=0 + for pat in "${filters[@]}"; do + case "$name" in *"$pat"*) hit=1 ;; esac + done + [ "$hit" -eq 1 ] || continue + fi + + total=$((total + 1)) + out=$(cargo run -q -p mpc-examples --bin "$name" 2>&1) + rc=$? + bad=$(printf '%s\n' "$out" | grep -c '\[!!\]' || true) + + if [ "$rc" -ne 0 ] || [ "$bad" -ne 0 ]; then + fail=$((fail + 1)) + failed_names+=("$name") + printf ' \033[31mFAIL\033[0m %s\n' "$name" + printf '%s\n' "$out" | grep -E '\[!!\]|^失败' | sed 's/^/ /' || true + [ "$rc" -ne 0 ] && printf ' 退出码 %s\n' "$rc" + else + printf ' \033[32m ok \033[0m %s\n' "$name" + fi +done + +if [ "$total" -eq 0 ]; then + echo "没有匹配的示例:${filters[*]:-}" >&2 + exit 2 +fi + +printf '\n' +if [ "$fail" -ne 0 ]; then + printf '\033[31m%d/%d 个示例失败:%s\033[0m\n' "$fail" "$total" "${failed_names[*]}" + exit 1 +fi +printf '\033[32m%d 个示例全部通过\033[0m\n' "$total"