Files
ssw-mpc/crates/nax-proto/src/lib.rs
T
ssw c5b2cf69a5 feat: nax-rs P0/P1/P1.5 —— Rust 重写隐私计算框架
算子核(nax-core):零依赖 no_std
- Z_2^64 定点算术 + AVX2 矩阵乘,与 Python 参考实现 215 条逐位一致
- 加性分享 / Beaver 三元组 / 截断对 / edaBit,ChaCha20 PRG,SHA-256
- 自实现银行家舍入(f64::round_ties_even 是 std-only,no_std 编不过)

协议栈
- nax-proto:手写帧协议(12 字节头 + u64 payload),无 protobuf 依赖
- nax-vault:Beaver 乘 / 定点截断 / open / reveal
- nax-node:TCP 传输 + 密文会话 + PSI 会话
- nax-psi:X25519 ECDH-PSI(唯一外部依赖 dalek,因恒定时间约束)
- nax-tee:HAL trait(seal/unseal/attest/sign)+ Mock + TrustPlan 四级降级

验收
- 83 用例全绿;armv7 全 workspace 编译通过
- 两进程密文计算:(1·4+1)+(2·5+1)+(3·6+1) = 35
- 两进程 PSI:[1..5] ∩ [3..7] = {3,4,5}
- 单二进制 450 KB,零运行时依赖

文档
- docs/ARCHITECTURE.md:分层、Ray 定位、TEE 分工与降级梯度
- docs/ZYNQ.md:A9 性能预算(比 i5 慢 8-12x,非 50x)与部署形态
2026-10-29 11:10:54 +08:00

556 lines
18 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.
//! nax 帧协议 —— 节点之间唯一的通信格式。
//!
//! # 为什么不引 protobuf / serde
//!
//! 两个理由:
//!
//! 1. **二进制体积**。prost + tonic 会拉进 axum/hyper/tower/h2 上百个 crate,
//! 编出来是十几 MB;这个协议的全部需求就是"几个整数 + 一段 u64 数组",
//! 手写编解码不到 300 行。
//! 2. **payload 就是 `&[u64]`**。MPC 的消息体是**均匀随机的环元素**,
//! 没有嵌套结构、没有可选字段、不需要版本演进。给它套一层 IDL
//! 只会增加拷贝次数 —— 而现在是从 `Vec<u64>` 直接逐元素写进帧尾。
//!
//! # 帧格式
//!
//! ```text
//! 0 2 3 4 8 12
//! +----+----+----+--------+------------+------------------+
//! | NX |ver | op | seq | payload_len| payload |
//! +----+----+----+--------+------------+------------------+
//! magic ver op u32 LE u32 LE 变长
//! ```
//!
//! `seq` 用于把 `Open` 请求和 `OpenValue` 响应配对 —— 一个会话里可能同时
//! 有多个 in-flight 的 open(流水线),没有 seq 就只能串行,延迟翻倍。
//!
//! payload 内的整数一律 **little-endian**。这不是随便选的:`u64` 数组
//! 在 little-endian 机器上可以零拷贝直读,而 MPC 的部署目标
//! (x86_64 / armv7 / aarch64)全是 little-endian。
use std::fmt;
/// 协议版本。改动帧布局时必须 +1,让旧节点明确拒绝而不是解析出垃圾。
pub const VERSION: u8 = 1;
/// 帧头长度(字节)。
pub const HEADER_LEN: usize = 12;
/// 单个 payload 的上限:64 MiB。
///
/// 这不是随便定的:一次 `Shares` 消息最多传 `n × len × 8` 字节,
/// 64 MiB 对应 4M 个 u64 分片(2 方),足够单批矩阵乘。
/// 超过这个量级应该分块流水,而不是发一个巨型帧 —— 否则一个
/// 恶意对端就能用 4GB 的 len 字段把内存打爆。
pub const MAX_PAYLOAD: usize = 64 * 1024 * 1024;
/// 帧类型。
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[repr(u8)]
pub enum Op {
/// 打招呼,携带 site 名。
Hello = 0x01,
/// 回应打招呼,携带对端 site 名。
HelloAck = 0x02,
/// 把明文落到本方节点(本地语义占位,不入网络)。
Put = 0x10,
/// 送分片。payload = `party_count:u32 | len:u32 | u64×party_count*len`。
Shares = 0x11,
/// 请求公开一个带掩码的值。payload = `len:u32 | u64×len`。
Open = 0x20,
/// 公开值。payload = `len:u32 | u64×len`,`seq` 与请求配对。
OpenValue = 0x21,
/// 请求把结果还原给某一方。payload = `target:utf8`。
Reveal = 0x30,
/// 还原结果。payload = `len:u32 | u64×len`。
Revealed = 0x31,
/// PSI 盲化点。payload = `len:u32 | 32字节点 × len`。
///
/// 与 `Open` 的关键区别:这里送出去的是**曲线上的点**,
/// 不是环元素 —— 对端反推 ID 等价于解离散对数。
PsiPoints = 0x40,
/// 协议错误。payload = `code:u32 | message:utf8`。
Error = 0x7F,
}
impl Op {
/// 从字节解析。
pub fn from_u8(v: u8) -> Option<Self> {
Some(match v {
0x01 => Self::Hello,
0x02 => Self::HelloAck,
0x10 => Self::Put,
0x11 => Self::Shares,
0x20 => Self::Open,
0x21 => Self::OpenValue,
0x30 => Self::Reveal,
0x31 => Self::Revealed,
0x40 => Self::PsiPoints,
0x7F => Self::Error,
_ => return None,
})
}
}
/// 一个协议帧。
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Frame {
/// 帧类型。
pub op: Op,
/// 序号,用于配对请求与响应。
pub seq: u32,
/// 负载。
pub payload: Vec<u8>,
}
impl Frame {
/// 构造空负载帧。
pub fn new(op: Op, seq: u32) -> Self {
Self { op, seq, payload: Vec::new() }
}
/// 编码到字节缓冲(含帧头)。
pub fn encode(&self) -> Result<Vec<u8>, ProtoError> {
if self.payload.len() > MAX_PAYLOAD {
return Err(ProtoError::PayloadTooLarge(self.payload.len()));
}
let mut out = Vec::with_capacity(HEADER_LEN + self.payload.len());
out.extend_from_slice(b"NX");
out.push(VERSION);
out.push(self.op as u8);
out.extend_from_slice(&self.seq.to_le_bytes());
out.extend_from_slice(&(self.payload.len() as u32).to_le_bytes());
out.extend_from_slice(&self.payload);
Ok(out)
}
/// 从字节缓冲解析,返回帧与消耗的字节数。
///
/// 只解析**一个完整帧**;缓冲可能包含多个帧(流水线),
/// 由调用方按 `consumed` 推进。
pub fn decode(buf: &[u8]) -> Result<(Self, usize), ProtoError> {
if buf.len() < HEADER_LEN {
return Err(ProtoError::Incomplete);
}
if &buf[0..2] != b"NX" {
return Err(ProtoError::BadMagic);
}
if buf[2] != VERSION {
return Err(ProtoError::VersionMismatch { got: buf[2], want: VERSION });
}
let op = Op::from_u8(buf[3]).ok_or(ProtoError::UnknownOp(buf[3]))?;
let seq = u32::from_le_bytes([buf[4], buf[5], buf[6], buf[7]]);
let len = u32::from_le_bytes([buf[8], buf[9], buf[10], buf[11]]) as usize;
// 先校验长度再分配 —— 否则一个 4GB 的 len 字段就能打爆内存
if len > MAX_PAYLOAD {
return Err(ProtoError::PayloadTooLarge(len));
}
if buf.len() < HEADER_LEN + len {
return Err(ProtoError::Incomplete);
}
Ok((
Self {
op,
seq,
payload: buf[HEADER_LEN..HEADER_LEN + len].to_vec(),
},
HEADER_LEN + len,
))
}
}
// ---------------------------------------------------------------------------
// payload 构造 / 解析
// ---------------------------------------------------------------------------
/// 顺序写 payload。
#[derive(Default)]
pub struct Writer {
buf: Vec<u8>,
}
impl Writer {
/// 新建。
pub fn new() -> Self {
Self::default()
}
/// 写 u32(LE)。
pub fn u32(&mut self, v: u32) -> &mut Self {
self.buf.extend_from_slice(&v.to_le_bytes());
self
}
/// 写 u64 数组(LE,紧密排列)。
pub fn u64s(&mut self, v: &[u64]) -> &mut Self {
self.buf.reserve(v.len() * 8);
for x in v {
self.buf.extend_from_slice(&x.to_le_bytes());
}
self
}
/// 写带长度前缀的字节串。
pub fn bytes(&mut self, v: &[u8]) -> &mut Self {
self.buf.extend_from_slice(&(v.len() as u32).to_le_bytes());
self.buf.extend_from_slice(v);
self
}
/// 写带长度前缀的字符串。
pub fn str(&mut self, v: &str) -> &mut Self {
self.bytes(v.as_bytes());
self
}
/// 取出底层缓冲。
pub fn finish(self) -> Vec<u8> {
self.buf
}
}
/// 顺序读 payload。
pub struct Reader<'a> {
buf: &'a [u8],
pos: usize,
}
impl<'a> Reader<'a> {
/// 新建。
pub fn new(buf: &'a [u8]) -> Self {
Self { buf, pos: 0 }
}
/// 剩余字节数。
pub fn remaining(&self) -> usize {
self.buf.len().saturating_sub(self.pos)
}
fn need(&self, n: usize) -> Result<(), ProtoError> {
if self.remaining() < n {
return Err(ProtoError::TruncatedPayload { need: n, got: self.remaining() });
}
Ok(())
}
/// 读 u32。
pub fn u32(&mut self) -> Result<u32, ProtoError> {
self.need(4)?;
let v = u32::from_le_bytes([
self.buf[self.pos],
self.buf[self.pos + 1],
self.buf[self.pos + 2],
self.buf[self.pos + 3],
]);
self.pos += 4;
Ok(v)
}
/// 读 u64 数组,长度由调用方给出。
pub fn u64s(&mut self, n: usize) -> Result<Vec<u64>, ProtoError> {
self.need(n * 8)?;
let mut out = Vec::with_capacity(n);
for i in 0..n {
let b = &self.buf[self.pos + i * 8..self.pos + i * 8 + 8];
out.push(u64::from_le_bytes([b[0], b[1], b[2], b[3], b[4], b[5], b[6], b[7]]));
}
self.pos += n * 8;
Ok(out)
}
/// 直接取走 `n` 字节的切片(零拷贝)。
pub fn take(&mut self, n: usize) -> Result<&'a [u8], ProtoError> {
self.need(n)?;
let sl = &self.buf[self.pos..self.pos + n];
self.pos += n;
Ok(sl)
}
/// 读带长度前缀的字节串。
pub fn bytes(&mut self) -> Result<Vec<u8>, ProtoError> {
let n = self.u32()? as usize;
self.need(n)?;
let v = self.buf[self.pos..self.pos + n].to_vec();
self.pos += n;
Ok(v)
}
/// 读带长度前缀的字符串。
pub fn str(&mut self) -> Result<String, ProtoError> {
let b = self.bytes()?;
String::from_utf8(b).map_err(|_| ProtoError::BadUtf8)
}
}
// ---------------------------------------------------------------------------
// 错误
// ---------------------------------------------------------------------------
/// 协议错误。
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ProtoError {
/// 缓冲不足一个完整帧。
Incomplete,
/// 魔数不对(不是 nax 流量)。
BadMagic,
/// 版本不匹配。
VersionMismatch {
/// 对端版本。
got: u8,
/// 本端版本。
want: u8,
},
/// 未知帧类型。
UnknownOp(u8),
/// payload 超限。
PayloadTooLarge(usize),
/// payload 被截断。
TruncatedPayload {
/// 需要的字节数。
need: usize,
/// 实际剩余。
got: usize,
},
/// 字符串不是合法 UTF-8。
BadUtf8,
/// 语义错误。
Semantic(String),
}
impl fmt::Display for ProtoError {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::Incomplete => f.write_str("帧不完整"),
Self::BadMagic => f.write_str("魔数不是 'NX',不是 nax 流量"),
Self::VersionMismatch { got, want } => {
write!(f, "协议版本不匹配: 对端 {got},本端 {want}")
}
Self::UnknownOp(op) => write!(f, "未知帧类型: {op:#04x}"),
Self::PayloadTooLarge(n) => write!(f, "payload 过大: {n} 字节"),
Self::TruncatedPayload { need, got } => {
write!(f, "payload 被截断: 需要 {need},剩 {got}")
}
Self::BadUtf8 => f.write_str("字符串不是合法 UTF-8"),
Self::Semantic(m) => write!(f, "语义错误: {m}"),
}
}
}
impl std::error::Error for ProtoError {}
// ---------------------------------------------------------------------------
// 便捷构造
// ---------------------------------------------------------------------------
impl Frame {
/// `Hello`:`[site]`。
pub fn hello(seq: u32, site: &str) -> Self {
let mut w = Writer::new();
w.str(site);
Self { op: Op::Hello, seq, payload: w.finish() }
}
/// `HelloAck`:`[site]`。
pub fn hello_ack(seq: u32, site: &str) -> Self {
let mut w = Writer::new();
w.str(site);
Self { op: Op::HelloAck, seq, payload: w.finish() }
}
/// `Open`:`[len][u64×len]`。
pub fn open(seq: u32, values: &[u64]) -> Self {
let mut w = Writer::new();
w.u32(values.len() as u32).u64s(values);
Self { op: Op::Open, seq, payload: w.finish() }
}
/// `OpenValue`:`[len][u64×len]`。
pub fn open_value(seq: u32, values: &[u64]) -> Self {
let mut w = Writer::new();
w.u32(values.len() as u32).u64s(values);
Self { op: Op::OpenValue, seq, payload: w.finish() }
}
/// `Revealed`:`[len][u64×len]`。
pub fn revealed(seq: u32, values: &[u64]) -> Self {
let mut w = Writer::new();
w.u32(values.len() as u32).u64s(values);
Self { op: Op::Revealed, seq, payload: w.finish() }
}
/// 解析 `Open` / `OpenValue` / `Revealed` 的负载。
pub fn read_values(&self) -> Result<Vec<u64>, ProtoError> {
let mut r = Reader::new(&self.payload);
let n = r.u32()? as usize;
r.u64s(n)
}
/// `PsiPoints`:`[len][32字节点×len]`。
pub fn psi_points(seq: u32, points: &[[u8; 32]]) -> Self {
let mut buf = Vec::with_capacity(4 + points.len() * 32);
buf.extend_from_slice(&(points.len() as u32).to_le_bytes());
for p in points {
buf.extend_from_slice(p);
}
Self { op: Op::PsiPoints, seq, payload: buf }
}
/// 解析 `PsiPoints` 的负载。
pub fn read_points(&self) -> Result<Vec<[u8; 32]>, ProtoError> {
let mut r = Reader::new(&self.payload);
let n = r.u32()? as usize;
// 防御:n*32 的整数溢出(32 位平台上 usize 可能只有 32 位)
let need = n.checked_mul(32).ok_or(ProtoError::PayloadTooLarge(n))?;
if r.remaining() < need {
return Err(ProtoError::TruncatedPayload { need, got: r.remaining() });
}
let mut out = Vec::with_capacity(n);
for _ in 0..n {
let mut pt = [0u8; 32];
pt.copy_from_slice(r.take(32)?);
out.push(pt);
}
Ok(out)
}
/// 解析 `Hello` / `HelloAck` 的 site 名。
pub fn read_site(&self) -> Result<String, ProtoError> {
Reader::new(&self.payload).str()
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn frame_roundtrip() {
for op in [Op::Hello, Op::Shares, Op::OpenValue, Op::Error] {
let f = Frame { op, seq: 42, payload: vec![1, 2, 3, 4, 5] };
let bytes = f.encode().unwrap();
assert_eq!(bytes.len(), HEADER_LEN + 5);
let (back, used) = Frame::decode(&bytes).unwrap();
assert_eq!(back, f);
assert_eq!(used, bytes.len());
}
}
#[test]
fn decode_pipelined_frames() {
let mut buf = Vec::new();
buf.extend_from_slice(&Frame::hello(1, "alice").encode().unwrap());
buf.extend_from_slice(&Frame::open(2, &[7, 8, 9]).encode().unwrap());
buf.extend_from_slice(&Frame::hello_ack(3, "bob").encode().unwrap());
let mut off = 0;
let mut ops = Vec::new();
while off < buf.len() {
let (f, used) = Frame::decode(&buf[off..]).unwrap();
ops.push(f.op);
off += used;
}
assert_eq!(ops, vec![Op::Hello, Op::Open, Op::HelloAck]);
assert_eq!(off, buf.len());
}
#[test]
fn decode_incomplete_returns_incomplete() {
let bytes = Frame::open(1, &[1, 2, 3]).encode().unwrap();
for cut in 0..bytes.len() {
assert_eq!(Frame::decode(&bytes[..cut]), Err(ProtoError::Incomplete));
}
}
#[test]
fn reject_bad_magic() {
let mut bytes = Frame::hello(1, "x").encode().unwrap();
bytes[0] = b'X';
assert_eq!(Frame::decode(&bytes), Err(ProtoError::BadMagic));
}
#[test]
fn reject_wrong_version() {
let mut bytes = Frame::hello(1, "x").encode().unwrap();
bytes[2] = VERSION + 1;
assert!(matches!(Frame::decode(&bytes), Err(ProtoError::VersionMismatch { .. })));
}
#[test]
fn reject_unknown_op() {
let mut bytes = Frame::hello(1, "x").encode().unwrap();
bytes[3] = 0xEE;
assert_eq!(Frame::decode(&bytes), Err(ProtoError::UnknownOp(0xEE)));
}
#[test]
fn reject_huge_len_without_allocating() {
// 恶意对端声明 4GB payload:必须在分配内存之前就拒绝
let mut bytes = Frame::hello(1, "x").encode().unwrap();
bytes[8..12].copy_from_slice(&0xFFFF_FFFFu32.to_le_bytes());
assert!(matches!(Frame::decode(&bytes), Err(ProtoError::PayloadTooLarge(_))));
}
#[test]
fn values_roundtrip() {
let vals: Vec<u64> = (0..1000).map(|i| (i as u64).wrapping_mul(0x9E37_79B9)).collect();
let f = Frame::open_value(7, &vals);
assert_eq!(f.seq, 7);
assert_eq!(f.read_values().unwrap(), vals);
}
#[test]
fn psi_points_roundtrip() {
let pts: Vec<[u8; 32]> = (0..64u8).map(|i| [i; 32]).collect();
let f = Frame::psi_points(9, &pts);
assert_eq!(f.op, Op::PsiPoints);
assert_eq!(f.read_points().unwrap(), pts);
}
#[test]
fn psi_points_rejects_truncated() {
let mut f = Frame::psi_points(1, &[[7u8; 32]; 4]);
f.payload.truncate(f.payload.len() - 1);
assert!(matches!(f.read_points(), Err(ProtoError::TruncatedPayload { .. })));
}
#[test]
fn psi_points_rejects_overflowing_count() {
// 声明 2^28 个点 = 8 GB,必须在分配前拒绝
let mut f = Frame::psi_points(1, &[]);
f.payload = 0x1000_0000u32.to_le_bytes().to_vec();
assert!(matches!(f.read_points(), Err(ProtoError::TruncatedPayload { .. })));
}
#[test]
fn site_roundtrip() {
let f = Frame::hello(1, "alice.example");
assert_eq!(f.read_site().unwrap(), "alice.example");
}
#[test]
fn writer_reader_mixed() {
let mut w = Writer::new();
w.u32(3).str("bob").u64s(&[10, 20, 30]);
let p = w.finish();
let mut r = Reader::new(&p);
assert_eq!(r.u32().unwrap(), 3);
assert_eq!(r.str().unwrap(), "bob");
assert_eq!(r.u64s(3).unwrap(), vec![10, 20, 30]);
assert_eq!(r.remaining(), 0);
}
#[test]
fn reader_detects_truncation() {
let mut r = Reader::new(&[1, 0, 0, 0, 5]);
assert_eq!(r.u32().unwrap(), 1);
assert!(matches!(r.u64s(1), Err(ProtoError::TruncatedPayload { .. })));
}
}