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

515 lines
20 KiB
Rust
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
//! ECDH-PSI 算法内核 —— 隐私求交。
//!
//! # 为什么这个 crate 允许引入外部依赖
//!
//! `mpc-core` 的铁律是**零依赖、`no_std`、手写**。这个 crate 是唯一的例外,
//! 而且只有一条依赖:`curve25519-dalek`。
//!
//! 理由不是"省事",是**手写 X25519 做不到恒定时间**。
//! Montgomery ladder 的每一步都要在"交换/不交换"之间选择,如果按比特
//! 分支(参考实现的 Python 版就是这么写的,它自己也在注释里承认非常数时间),
//! 攻击者用缓存时序或分支预测就能把私钥一位一位读出来。
//!
//! dalek 是经过广泛审计的恒定时间实现。在这种地方"自己造"不是节约,
//! 是给自己埋一个永远不会在测试里暴露的洞。
//!
//! 代价:编译期多 ~10 个 crate(proc-macro 链),运行期实质 5 个。
//! 二进制增量约 100 KB。这个代价换"私钥不会被时序读走",值得。
//!
//! # 协议(两方,结果双方都可见)
//!
//! ```text
//! alice bob
//! ─────────────────────────────────────────────────────
//! ka ← 随机标量 kb ← 随机标量
//! PA = shuffle(ka·H(ID_a)) ──────▶
//! ◀────── PB = shuffle(kb·H(ID_b))
//! AB = ka·PB BA = kb·PA
//! AB ──────▶
//! ◀────── BA
//! 交集 = {i : BA[i] ∈ AB} 交集 = {j : AB[j] ∈ BA}
//! ```
//!
//! 安全性来自 `ka·(kb·H(x)) == kb·(ka·H(x))`:只有 ID 相同时双盲结果才相同。
//! 对方拿到的全是曲线上的点,反推 ID 等价于解 X25519 上的离散对数。
//!
//! **洗牌是必须的**:不洗牌的话,对方能通过点的位置反推你原始数据的排列
//! ("第 3 条记录在交集里"本身就是信息)。
//!
//! # 与参考实现的一处差异
//!
//! `hash_to_point` 用的是 **SHA-256**,参考实现用 SHA-512。
//! 影响仅限"两套实现不能混跑同一场 PSI",交集语义完全一致
//! (双方用同一个映射,`x ∈ Y` 的判定结果不变)。
//! 换成 SHA-256 是为了不引入第二个哈希函数 —— `mpc-core` 里已有它。
use mpc_core::hash::Sha256;
use mpc_core::prg::Stream;
use curve25519_dalek::montgomery::MontgomeryPoint;
pub mod cache;
pub mod strict;
/// 默认 domain 分隔串,统一定义在 `mpc_core::domain::PSI_DOMAIN`。
///
/// 参考实现的 `hash_to_point` 用 SHA-512、这里用 SHA-256,两边曲线点本就不同;
/// 这个 domain 只约束**本框架各参与方**必须用同一个映射。
pub const DOMAIN: &[u8] = mpc_core::domain::PSI_DOMAIN;
/// 把一个 ID(任意字节)映射到曲线上的 u 坐标。
///
/// curve25519 及其扭曲线都是 twist-secure 的,所以可以直接把哈希值
/// 当作 u 坐标用,不需要完整的 hash-to-curve(Elligator 之类)。
/// 这是一个**依赖曲线性质**的简化,换别的曲线就不成立了。
pub fn hash_to_point(data: &[u8], domain: &[u8]) -> [u8; 32] {
let mut h = Sha256::new();
h.update(domain);
h.update(b"|");
h.update(data);
h.finalize()
}
/// X25519 标量乘:`k · u`。
///
/// `mul_clamped` 会自动做 RFC 7748 的 clamp(清低位、设高位),
/// 所以传进来的 `k` 不需要预处理。
pub fn scalar_mult(k: &[u8; 32], u: &[u8; 32]) -> [u8; 32] {
MontgomeryPoint(*u).mul_clamped(*k).to_bytes()
}
/// 从 PRG 流生成一个标量。
///
/// 用会话的 ChaCha20 流而不是操作系统的熵源,是为了让整场 PSI
/// 可以按种子复现 —— 调试与对照测试都靠这个。
pub fn random_scalar(s: &mut Stream) -> [u8; 32] {
let mut k = [0u8; 32];
s.fill_bytes(&mut k);
k
}
/// 一次盲化:`shuffle(k · H(item))`。
///
/// 返回 `(points, perm)`,`points[i]` 对应原始下标 `perm[i]`。
/// 调用方在最后要用 `perm` 把交集的**位置**换回**原始下标**。
pub fn blind(items: &[Vec<u8>], key: &[u8; 32], s: &mut Stream) -> (Vec<[u8; 32]>, Vec<usize>) {
blind_with_domain(items, key, DOMAIN, s)
}
/// 同 [`blind`],但用调用方给的 domain。
///
/// # 什么时候需要它
///
/// 默认 `DOMAIN` 是常量,所以同一个 ID 在任何一场 PSI 里都映射到同一个点。
/// 这让**离线预计算表**成为可能:攻击者先为一批候选 ID 算好点,之后抓到
/// 线上流量直接查表。传入会话相关的 domain(见 [`strict::session_domain`])
/// 可以打断这条路径 —— 每场会话的点空间不同,表不能复用。
///
/// 代价:双方必须算出**同一个** domain,否则交集恒为空。
/// 这个失败不报错,只是结果为空 —— 所以 domain 一律由共享主种子派生。
pub fn blind_with_domain(
items: &[Vec<u8>],
key: &[u8; 32],
domain: &[u8],
s: &mut Stream,
) -> (Vec<[u8; 32]>, Vec<usize>) {
let perm = shuffle_perm(items.len(), s);
// 先按**原始顺序**算点、再按 `perm` 取,与「按 perm 顺序逐项算」逐位相同 ——
// 但这样 [`blind_points`] 也能被缓存路径直接复用(缓存按元素索引,与顺序无关)。
let raw = blind_points(items, key, domain);
let points = perm.iter().map(|&i| raw[i]).collect();
(points, perm)
}
/// 只算盲化点,不打乱:`out[i] = k · H(items[i], domain)`。
///
/// 与 [`blind_with_domain`] 的关系:那个多一步洗牌。拆开是因为**缓存路径**
/// 需要按元素查、与顺序无关(见 [`cache::BlindCache`]),而洗牌只在协议层需要。
pub fn blind_points(items: &[Vec<u8>], key: &[u8; 32], domain: &[u8]) -> Vec<[u8; 32]> {
items
.iter()
.map(|it| scalar_mult(key, &hash_to_point(it, domain)))
.collect()
}
/// 生成 `0..n` 的随机排列(Fisher–Yates,会话 PRG 驱动)。
///
/// 单独暴露是为了让调用方能在「算点」之前就把顺序定下来 —— 协议层要的是
/// `points[i]` 对应 `items[perm[i]]`,而算点本身与顺序无关。
pub fn shuffle_perm(n: usize, s: &mut Stream) -> Vec<usize> {
let mut perm: Vec<usize> = (0..n).collect();
shuffle(&mut perm, s);
perm
}
/// 二次盲化:`k · P`,顺序保持不变(对端要按位置回溯)。
pub fn reblind(points: &[[u8; 32]], key: &[u8; 32]) -> Vec<[u8; 32]> {
points.iter().map(|p| scalar_mult(key, p)).collect()
}
/// 求 `mine` 中落在交集里的**位置**(打乱后的下标)。
///
/// 朴素 O(n·m) 比对在大集合上不可接受(1 万 × 1 万 = 1 亿次)。
/// 这里把对端建成排序数组 + 二分,复杂度 O(m log m + n log m)。
///
/// 用排序而不是 `HashSet`,是因为 `[u8; 32]` 做哈希要额外依赖,
/// 而排序比对在 32 字节固定宽度上本来就快(一次 memcmp 定胜负)。
pub fn match_points(mine: &[[u8; 32]], peer: &[[u8; 32]]) -> Vec<usize> {
let mut sorted: Vec<[u8; 32]> = peer.to_vec();
sorted.sort_unstable();
let mut out = Vec::new();
for (i, p) in mine.iter().enumerate() {
if sorted.binary_search(p).is_ok() {
out.push(i);
}
}
out
}
/// n 方求交:返回 `mine` 中**同时出现在每一个** `others` 里的位置。
///
/// # 为什么不能"两两求交再交起来"
///
/// 两两求交只回答"我和他有没有公共元素",不回答"这个元素是不是各方都有"。
/// 反例:A={1,2}、B={2,3}、C={3,1}。两两交集都非空({2}/{3}/{1}),
/// 但三方交集是空集。拿两两结果去拼,会把三个元素全部误判成交集成员。
///
/// 判据必须是**同一个元素在每一个集合里都出现**,也就是逐个 `match_points`
/// 再取 AND —— 这正是本函数做的事。
///
/// # 复杂度
///
/// `O(n · m log m)`,与方数线性。集合按大小升序处理(小集合先淘汰候选),
/// 候选清零后立即短路,实际开销随交集收敛而下降。
pub fn match_across(mine: &[[u8; 32]], others: &[&[[u8; 32]]]) -> Vec<usize> {
if others.is_empty() {
return (0..mine.len()).collect();
}
let mut peers: Vec<Vec<[u8; 32]>> = others.iter().map(|p| p.to_vec()).collect();
for set in peers.iter_mut() {
set.sort_unstable();
}
peers.sort_by_key(|s| s.len());
let mut alive = vec![true; mine.len()];
let mut left = mine.len();
for peer in &peers {
if left == 0 {
break;
}
for (i, p) in mine.iter().enumerate() {
if alive[i] && peer.binary_search(p).is_err() {
alive[i] = false;
left -= 1;
}
}
}
alive
.iter()
.enumerate()
.filter_map(|(i, &a)| if a { Some(i) } else { None })
.collect()
}
/// 把打乱后的位置换回原始下标,并按原始顺序排序。
pub fn resolve(perm: &[usize], positions: &[usize]) -> Vec<usize> {
let mut out: Vec<usize> = positions
.iter()
.filter_map(|&p| perm.get(p).copied())
.collect();
out.sort_unstable();
out
}
/// 把「本方落在交集里的行」按**共享规范键**排序,返回按对齐行序排列的行下标。
///
/// # 为什么必须排序
///
/// [`resolve`] 返回的是**本地行序**升序的下标 —— 两方拿到的序列互不相同,
/// 也不含共享顺序。下游的纵向拼接(同一个人在两方各有一行,拼成一行特征)
/// 要求「两方第 i 行是同一个人」,所以两边必须按同一个**全序**重排。
/// 这里用键的字节序:任何两方一致的全序都行,关键是别用本地行序。
///
/// 副作用(已知且接受):排序暴露了本方键相对对端键的秩,与 PSI 本身
/// 泄露交集是同一量级的元信息;不排序则结果直接错 —— 不崩、不报错,就是数不对。
///
/// # 三种失败
///
/// - **交集为空**:两方没有公共样本。继续往下跑会拿空列去 open,在此明确失败。
/// - **下标越界**:协议错乱的信号,不能当成正常情况处理。
/// - **本方键重复**:对应一对多 join,纵向对齐(一人一行)表达不了笛卡尔展开,
/// 必须在切分片**之前**拒绝,而不是按行号静默错拼。
pub fn align_by_key(keys: &[Vec<u8>], hits: &[usize]) -> Result<Vec<usize>, String> {
if hits.is_empty() {
return Err("交集为空:两方没有可对齐的行".into());
}
if let Some(&bad) = hits.iter().find(|&&i| i >= keys.len()) {
return Err(format!("PSI 交集中出现越界下标 {bad}"));
}
let mut order = hits.to_vec();
order.sort_by(|&x, &y| keys[x].cmp(&keys[y]));
if let Some(w) = order.windows(2).find(|w| keys[w[0]] == keys[w[1]]) {
return Err(format!(
"join 键在本方重复(第 {} 与第 {} 行),一对多 join 不支持",
w[0], w[1]
));
}
Ok(order)
}
/// Fisher–Yates 洗牌,随机源用会话 PRG。
fn shuffle(v: &mut [usize], s: &mut Stream) {
let n = v.len();
if n < 2 {
return;
}
// 从后往前,每次在 [0, i] 里取一个位置交换
let mut buf = [0u8; 8];
for i in (1..n).rev() {
s.fill_bytes(&mut buf);
let r = (u64::from_le_bytes(buf) % (i as u64 + 1)) as usize;
v.swap(i, r);
}
}
/// 把 ID 规范化成字节(与参考实现的 `_to_bytes` 语义对齐)。
///
/// 整数按十进制字符串、浮点整数值也按十进制整数 —— 这样 Python 侧
/// 的 `user_42` 与 Rust 侧的 `42` 不会因为表示不同而算成两个不同 ID。
pub fn id_from_u64(v: u64) -> Vec<u8> {
let mut buf = Vec::with_capacity(20);
write_u64(&mut buf, v);
buf
}
fn write_u64(out: &mut Vec<u8>, mut v: u64) {
if v == 0 {
out.push(b'0');
return;
}
let mut tmp = [0u8; 20];
let mut i = tmp.len();
while v > 0 {
i -= 1;
tmp[i] = b'0' + (v % 10) as u8;
v /= 10;
}
out.extend_from_slice(&tmp[i..]);
}
#[cfg(test)]
mod tests {
use super::*;
fn stream(seed: u8) -> Stream {
Stream::new(&[seed; 32])
}
/// X25519 的 RFC 7748 §6.1 测试向量(验证 dalek 用法正确)
#[test]
fn rfc7748_vector_1() {
let k: [u8; 32] = [
0xa5, 0x46, 0xe3, 0x6b, 0xf0, 0x52, 0x7c, 0x9d, 0x3b, 0x16, 0x15, 0x4b, 0x82, 0x46,
0x5e, 0xdd, 0x62, 0x14, 0x4c, 0x0a, 0xc1, 0xfc, 0x5a, 0x18, 0x50, 0x6a, 0x22, 0x44,
0xba, 0x44, 0x9a, 0xc4,
];
let u: [u8; 32] = [
0xe6, 0xdb, 0x68, 0x67, 0x58, 0x30, 0x30, 0xdb, 0x35, 0x94, 0xc1, 0xa4, 0x24, 0xb1,
0x5f, 0x7c, 0x72, 0x66, 0x24, 0xec, 0x26, 0xb3, 0x35, 0x3b, 0x10, 0xa9, 0x03, 0xa6,
0xd0, 0xab, 0x1c, 0x4c,
];
let want: [u8; 32] = [
0xc3, 0xda, 0x55, 0x37, 0x9d, 0xe9, 0xc6, 0x90, 0x8e, 0x94, 0xea, 0x4d, 0xf2, 0x8d,
0x08, 0x4f, 0x32, 0xec, 0xcf, 0x03, 0x49, 0x1c, 0x71, 0xf7, 0x54, 0xb4, 0x07, 0x55,
0x77, 0xa2, 0x85, 0x52,
];
assert_eq!(scalar_mult(&k, &u), want);
}
/// ECDH 的交换律 —— PSI 正确性的全部数学基础
#[test]
fn ecdh_is_commutative() {
let mut s = stream(1);
let ka = random_scalar(&mut s);
let kb = random_scalar(&mut s);
let base: [u8; 32] = {
let mut b = [0u8; 32];
b[0] = 9; // X25519 base point u=9
b
};
let a_then_b = scalar_mult(&kb, &scalar_mult(&ka, &base));
let b_then_a = scalar_mult(&ka, &scalar_mult(&kb, &base));
assert_eq!(a_then_b, b_then_a, "a·b·P 必须等于 b·a·P");
}
#[test]
fn hash_to_point_is_deterministic() {
let a = hash_to_point(b"user_1", DOMAIN);
let b = hash_to_point(b"user_1", DOMAIN);
assert_eq!(a, b);
assert_ne!(a, hash_to_point(b"user_2", DOMAIN));
// domain 必须参与哈希,否则跨协议会撞
assert_ne!(a, hash_to_point(b"user_1", b"other"));
}
#[test]
fn blind_preserves_perm_invertibility() {
let items: Vec<Vec<u8>> = (0..10).map(|i| format!("u{i}").into_bytes()).collect();
let mut s = stream(3);
let key = random_scalar(&mut s);
let (points, perm) = blind(&items, &key, &mut s);
assert_eq!(points.len(), 10);
assert_eq!(perm.len(), 10);
// perm 必须是 0..n 的排列
let mut sorted = perm.clone();
sorted.sort_unstable();
assert_eq!(sorted, (0..10).collect::<Vec<_>>());
// 洗牌真的生效了(10 个元素全同序的概率是 1/10!)
assert_ne!(perm, (0..10).collect::<Vec<_>>());
// 每个点必须能由对应原始项重算出来
for (i, &orig) in perm.iter().enumerate() {
let want = scalar_mult(&key, &hash_to_point(&items[orig], DOMAIN));
assert_eq!(points[i], want);
}
}
#[test]
fn full_psi_finds_intersection() {
// alice 有 0..20,bob 有 10..30,交集应是 10..20
let a_items: Vec<Vec<u8>> = (0..20u64).map(id_from_u64).collect();
let b_items: Vec<Vec<u8>> = (10..30u64).map(id_from_u64).collect();
let mut sa = stream(7);
let mut sb = stream(11);
let ka = random_scalar(&mut sa);
let kb = random_scalar(&mut sb);
let (pa, perm_a) = blind(&a_items, &ka, &mut sa);
let (pb, _perm_b) = blind(&b_items, &kb, &mut sb);
// 交叉双盲
let ab = reblind(&pb, &ka); // alice 看 bob 的
let ba = reblind(&pa, &kb); // bob 看 alice 的
// alice 求自己的交集
let idx_a = resolve(&perm_a, &match_points(&ba, &ab));
// 期望 10..20 这 10 个下标(原始下标升序)
let want: Vec<usize> = (10..20).collect();
assert_eq!(idx_a, want, "交集下标错");
}
#[test]
fn disjoint_sets_give_empty() {
let a: Vec<Vec<u8>> = (0..5u64).map(id_from_u64).collect();
let b: Vec<Vec<u8>> = (100..105u64).map(id_from_u64).collect();
let mut s = stream(13);
let ka = random_scalar(&mut s);
let kb = random_scalar(&mut s);
let (pa, perm) = blind(&a, &ka, &mut s);
let (pb, _) = blind(&b, &kb, &mut s);
let ab = reblind(&pb, &ka);
let ba = reblind(&pa, &kb);
assert!(resolve(&perm, &match_points(&ba, &ab)).is_empty());
}
#[test]
fn identical_sets_give_all() {
let a: Vec<Vec<u8>> = (0..8u64).map(id_from_u64).collect();
let b = a.clone();
let mut s = stream(17);
let ka = random_scalar(&mut s);
let kb = random_scalar(&mut s);
let (pa, perm) = blind(&a, &ka, &mut s);
let (pb, _) = blind(&b, &kb, &mut s);
let ab = reblind(&pb, &ka);
let ba = reblind(&pa, &kb);
assert_eq!(resolve(&perm, &match_points(&ba, &ab)), (0..8).collect::<Vec<_>>());
}
/// 对方拿到的点不能泄露"哪些 ID 在交集里"以外的信息:
/// 同一个 ID 在两次不同的会话里,盲化结果必须不同。
#[test]
fn blinding_is_session_random() {
let items = vec![b"same-id".to_vec()];
let mut s1 = stream(21);
let mut s2 = stream(22);
let k1 = random_scalar(&mut s1);
let k2 = random_scalar(&mut s2);
let (p1, _) = blind(&items, &k1, &mut s1);
let (p2, _) = blind(&items, &k2, &mut s2);
assert_ne!(p1[0], p2[0], "换会话换密钥后盲化结果必须不同");
}
#[test]
fn id_encoding_matches_reference() { // 参考实现的 _to_bytes 对整数用十进制字符串
assert_eq!(id_from_u64(0), b"0".to_vec());
assert_eq!(id_from_u64(42), b"42".to_vec());
assert_eq!(id_from_u64(1234567890), b"1234567890".to_vec());
assert_eq!(id_from_u64(u64::MAX), b"18446744073709551615".to_vec());
}
/// n 方求交**不等于**两两求交的交
///
/// A={1,2} B={2,3} C={3,1}:两两交集分别是 {2}{3}{1},全都非空,
/// 但没有任何一个元素同时出现在三方里。这条测试钉住的正是
/// "把 n 方 PSI 当成两两 PSI 拼起来"这个错误做法。
#[test]
fn n_way_intersection_is_not_pairwise() {
let p = |v: u64| hash_to_point(&id_from_u64(v), DOMAIN);
let a = vec![p(1), p(2)];
let b = vec![p(2), p(3)];
let c = vec![p(3), p(1)];
// 两两都有交集
assert_eq!(match_points(&a, &b), vec![1], "a∩b 只该命中 a 里的 2(位置 1)");
assert_eq!(match_points(&b, &c), vec![1], "b∩c 只该命中 b 里的 3(位置 1)");
assert_eq!(match_points(&a, &c), vec![0], "a∩c 只该命中 a 里的 1(位置 0)");
// 三方的交集必须是空的
assert!(
match_across(&a, &[&b, &c]).is_empty(),
"三方无公共元素时不得返回任何命中"
);
}
#[test]
fn n_way_intersection_finds_common_core() {
let p = |v: u64| hash_to_point(&id_from_u64(v), DOMAIN);
// A={0..10} B={5..15} C={7..20} → 三方交集 {7,8,9}
let a: Vec<[u8; 32]> = (0..10u64).map(p).collect();
let b: Vec<[u8; 32]> = (5..15u64).map(p).collect();
let c: Vec<[u8; 32]> = (7..20u64).map(p).collect();
// a 里的顺序是 0..10,命中位置应是 7,8,9
assert_eq!(match_across(&a, &[&b, &c]), vec![7, 8, 9]);
}
#[test]
fn n_way_intersection_handles_empty_peer() {
let p = |v: u64| hash_to_point(&id_from_u64(v), DOMAIN);
let a: Vec<[u8; 32]> = (0..5u64).map(p).collect();
let empty: Vec<[u8; 32]> = Vec::new();
assert!(match_across(&a, &[&empty]).is_empty(), "任一方为空则交集为空");
// 没有对端时,"本方全部"是数学上正确的退化
assert_eq!(match_across(&a, &[]), (0..5).collect::<Vec<_>>());
}
/// 大集合的求交必须走二分而不是双重循环
#[test]
fn match_handles_ten_thousand() {
let a: Vec<[u8; 32]> = (0..10_000u64)
.map(|i| hash_to_point(&id_from_u64(i), DOMAIN))
.collect();
let b: Vec<[u8; 32]> = (5_000..15_000u64)
.map(|i| hash_to_point(&id_from_u64(i), DOMAIN))
.collect();
let hits = match_points(&a, &b);
assert_eq!(hits.len(), 5_000);
assert_eq!(hits[0], 5_000);
assert_eq!(*hits.last().unwrap(), 9_999);
}
}