Files
ssw-mpc/crates/mpc-core/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

102 lines
4.4 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.
//! MPC 算子核 —— 多方安全计算(Secure Multi-Party Computation)的密码学底座。
//!
//! # 设计约束(三条,不可妥协)
//!
//! 1. **`no_std`、零依赖**。这个 crate 的依赖树是空的,因此它能被原样编进
//! OP-TEE TA(armv7,`no_std`,无线程)、编进 WASM,或静态链进任何宿主。
//! 任何"顺手加个 crate"的冲动都要先问:TA 里编得进去吗?
//!
//! 2. **零分配**。所有算子的签名是 `(&[u64], &mut [u64])`,调用方负责分配。
//! TA 里没有通用分配器,宿主的分配策略也不该被算子核替它决定。
//!
//! 3. **与参考实现逐位一致**。`refs/nax`(Python/numpy)是行为基线,
//! 同样的输入必须产出同样的 `u64`。浮点定点编码尤其要小心:
//! `np.rint` 是**银行家舍入**(round-half-to-even),
//! 所以这里必须用 `f64::round_ties_even()`,而不是 `f64::round()`
//! —— 后者是 round-half-away-from-zero,在 `.5` 边界上会用不同结果。
//!
//! # 分层
//!
//! ```text
//! domain 协议域分隔常量(全框架唯一真相源;改一个字节 = 换钥)
//! ring Z_2^64 定点算术 + 矩阵乘(唯一碰裸 u64 的模块)
//! hash SHA-256(commitment / 种子派生 / attestation 摘要)
//! hmac HMAC-SHA256 + 定长比较 + 带标签派生(握手认证用)
//! aead ChaCha20-Poly1305(链路机密性 + 完整性,复用 prg 的 core)
//! prg ChaCha20 伪随机流(成对掩码 / 零和分享 / 离线物料)
//! share 加性分享、Beaver 三元组、定点截断、edaBit
//! compare BitLT 安全比较(符号位提取)
//! osrand OS 熵源(仅 std;no_std 下整模块不存在)
//! ```
//!
//! 上层(vault 算子、协议编排、调度)不在这里 —— 那是 `mpc-node` 的活儿。
#![cfg_attr(not(feature = "std"), no_std)]
#![deny(unsafe_op_in_unsafe_fn)]
#![warn(missing_docs)]
// `matmul_triple_into` 需要动态大小的临时缓冲(矩阵尺寸由调用方决定),
// 核心算子仍然零分配。alloc 在 no_std 下可用(只要宿主有全局分配器,
// OP-TEE TA 的 TEE_Malloc 就是)。
extern crate alloc;
pub mod aead;
pub mod compare;
pub mod domain;
pub mod hash;
pub mod hmac;
/// OS 熵源。**只在 `std` 下存在** —— TA 里没有 `/dev/urandom`,由宿主注入。
#[cfg(feature = "std")]
pub mod osrand;
pub mod prg;
pub mod ring;
pub mod share;
pub use ring::{DEFAULT_FXP, MODULUS_F, RING_BITS};
/// 算子核统一错误类型。
///
/// `no_std` 下不能带 `String`,所以错误只描述**类别**,
/// 具体上下文(哪个 shape 不符)由宿主层补。
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum MpcError {
/// 浮点数值超出定点可表示范围(`|x * 2^fxp| >= 2^62`)。
FixedPointOverflow,
/// 输入切片长度与声明的形状不符。
ShapeMismatch,
/// 输出缓冲区长度不足。
BufferTooSmall,
/// 参与方数量非法(加性分享至少 2 方)。
TooFewParties,
/// 定点小数位非法(必须 0..=62)。
BadFxp,
/// AEAD 标签校验失败 —— 密文被篡改,或密钥 / nonce / AAD 对不上。
///
/// 单独成一个变体,是因为它和上面几个性质完全不同:其余几个是**调用方写错**,
/// 这个是**有人在动链路**。上层要能据此告警而不是当参数错误处理。
TagMismatch,
/// ChaCha20 块计数器用尽(`u32` 回绕会重用密钥流,必须报错而非静默继续)。
CounterExhausted,
}
impl core::fmt::Display for MpcError {
fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
let s = match self {
Self::FixedPointOverflow => "数值超出定点表示范围",
Self::ShapeMismatch => "形状不匹配",
Self::BufferTooSmall => "输出缓冲区不足",
Self::TooFewParties => "秘密分享至少需要 2 个参与方",
Self::BadFxp => "定点小数位非法(合法范围 0..=62)",
Self::TagMismatch => "AEAD 标签校验失败(密文被篡改或密钥不符)",
Self::CounterExhausted => "ChaCha20 块计数器用尽",
};
f.write_str(s)
}
}
#[cfg(feature = "std")]
impl std::error::Error for MpcError {}
/// 便捷结果别名。
pub type Result<T> = core::result::Result<T, MpcError>;