feat(examples): 新增 mpc-examples,12 个场景对齐 nax/examples

- 新 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 轮
This commit is contained in:
admin committed 2026-11-05 20:55:07 +08:00
1 parent 4ec4147122
commit 49b421c23a
24 files changed
+3068 -6

No files matched your search

+218
View File
@@ -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<f64>,
z: Vec<f64>,
w: Vec<f64>,
prod: Vec<f64>,
sum_x: f64,
mean_m: f64,
/// (degree, 密文结果, 与真 sigmoid 的最大误差)
sig: Vec<(usize, Vec<f64>, 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<f64>> = 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<f64> = 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<MeshPipe>| -> Result<PartyOut, String> {
// ── 三个秘密入域: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::<f64>();
check(
&format!("三片累加 == alice 的原值 {}", vec_str(&a_val)),
(recon - a_val.iter().sum::<f64>()).abs() < 1e-9,
);
mpc_examples::note("三片之和才是原值 —— 需要三方同时凑齐才行。");
title("3. 在密文上做四则运算");
let z = &outs[0].z;
let w = &outs[0].w;
let z_plain: Vec<f64> = (0..a_val.len()).map(|i| a_val[i] * b_val[i] + 1.0).collect();
let w_plain: Vec<f64> = (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<f64> = (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::<f64>())),
(outs[0].sum_x - a_val.iter().sum::<f64>()).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)
}
+113
View File
@@ -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<String> = [1, 3, 5, 7, 9, 11, 13, 15]
.iter()
.map(|i| format!("u{i:03}"))
.collect();
let shop_ids: Vec<String> = [2, 3, 5, 8, 9, 13, 14, 20, 21]
.iter()
.map(|i| format!("u{i:03}"))
.collect();
let bank: Vec<Vec<u8>> = bank_ids.iter().map(|s| s.as_bytes().to_vec()).collect();
let shop: Vec<Vec<u8>> = 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<String> = hits.iter().map(|&i| bank_ids[i].clone()).collect();
kv("交集大小", common.len());
kv("交集", common.join(" "));
let expect: Vec<String> = 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)
}
+138
View File
@@ -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<f64> = 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)
}
+122
View File
@@ -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<f64> = vec![0.9, -0.6, 0.7, 0.3, -0.8, 0.5];
let mut data: HashMap<String, ClientData> = 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<Vec<f64>> = (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)
}
+141
View File
@@ -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<String>> = 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<String>> = 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<u64> = 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<Vec<String>> = 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<String> {
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)
}
+147
View File
@@ -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<f64> = vec![0.9, -0.6, 0.7, 0.3, -0.8, 0.5];
let mut data: HashMap<String, ClientData> = 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<Vec<f64>> = (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)
}
+219
View File
@@ -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<u64> {
(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<f64> = 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<Vec<f64>> = (0..N).map(|i| x[i * D..(i + 1) * D].to_vec()).collect();
let y_rows: Vec<Vec<f64>> = 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<f64> = 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<f64> = (0..D)
.flat_map(|k| (0..HIDDEN).map(move |j| w1[j][k]))
.collect();
let w2_t: Vec<f64> = (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)
}
+134
View File
@@ -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<Vec<String>> = (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<usize> = q.iter().map(|c| (c.bits() + 7) / 8).collect();
kv(
"每个密文的字节数",
format!("[{}]", vec_str(&bytes.iter().map(|&b| b as f64).collect::<Vec<_>>())),
);
// 极偶尔会少一个字节(密文高位为 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)
}
+323
View File
@@ -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<BankRow>, Vec<ShopRow>) {
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<String, (f64, f64, f64)> = 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<Vec<u8>> = bank.iter().map(|b| b.uid.as_bytes().to_vec()).collect();
let shop_ids: Vec<Vec<u8>> = 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<usize> = align_shop.into_iter().collect::<Result<_, _>>()?;
let n = align_bank.len();
let ages: Vec<f64> = align_bank.iter().map(|&i| bank[i].age).collect();
let cities: Vec<f64> = align_bank.iter().map(|&i| bank[i].city as f64).collect();
let spends: Vec<f64> = 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<Vec<Vec<f64>>, 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)
}
+232
View File
@@ -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<f64>> = 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<Vec<f64>> = 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::<Vec<_>>().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<usize> = 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<mpc_ml::binning::BinRow>, 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::<Vec<_>>()
.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)
}
+204
View File
@@ -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<usize>,
aggs: Vec<Agg>,
pred: Option<Pred>,
}
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)
}
+202
View File
@@ -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<String> {
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<f64, String> {
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<u64>> = 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<String, String> {
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<String>> = 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)
}
+465
View File
@@ -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<R, F>(tag: u8, f: F) -> Result<(R, R), String>
where
F: Fn(usize, &mut Vault<Pipe>) -> Result<R, String> + 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<R, F>(sites: &[&str], tag: u8, f: F) -> Result<Vec<R>, String>
where
F: Fn(usize, &mut Vault<MeshPipe>) -> Result<R, String> + Sync,
R: Send,
{
let n = sites.len();
let mut vaults: Vec<Vault<MeshPipe>> = 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<Result<R, String>> = 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<T>(r: Result<T, VaultError>) -> Result<T, String> {
r.map_err(|e| format!("{e:?}"))
}
/// f64 切片 → 定点切片。
pub fn fixed_vec(v: &[f64]) -> Vec<u64> {
v.iter().map(|&x| to_fixed(x)).collect()
}
/// 定点切片 → f64 切片。
pub fn float_vec(v: &[u64]) -> Vec<f64> {
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<T: Transport>(v: &mut Vault<T>, local: &[u64]) -> Result<Vec<u64>, String> {
let n = v.parties();
let me = v.my_index();
let all = ve(v.split(local))?;
let mut table: Vec<Vec<u64>> = 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<T: Transport>(
v: &mut Vault<T>,
owner: usize,
values: &[u64],
) -> Result<Vec<u64>, String> {
let data: Vec<u64> = 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<String> = v.iter().map(|&x| num(x)).collect();
format!("[{}]", body.join(", "))
}
/// 矩阵打印:`[[1, 2], [3, 4]]`。
pub fn mat_str(rows: &[Vec<f64>]) -> String {
let body: Vec<String> = 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<f64> {
(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<f64> = (0..n).map(|i| x[i * d + j]).collect();
let mean = col.iter().sum::<f64>() / n as f64;
let var = col.iter().map(|v| (v - mean).powi(2)).sum::<f64>() / 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<String>]) {
let cols = header.len();
let mut w: Vec<usize> = 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<String> = (0..cols)
.map(|i| pad(cells.get(i).map(String::as_str).unwrap_or(""), w[i]))
.collect();
println!(" {}", parts.join(" "));
};
let head: Vec<String> = header.iter().map(|h| h.to_string()).collect();
line(&head);
let sep: Vec<String> = 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<u64> = 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);
}
}