Luminous-Dynamics/xenia-wire

# xenia-wire [](https://crates.io/crates/xenia-wire) [](https://docs.rs/xenia-wire) [](https://github.com/Luminous-Dynamics/xenia-wire/actions/workflows/ci.yml) [](#license) [](Cargo.toml) 用于远程控制流的 AEAD 密封二进制通信协议，专为处理由上层握手层提供的、支持 ML-KEM 的会话密钥而设计。 ``` ╔═══════════════════════════════════════════════════════════╗ ║ PRE-ALPHA — DO NOT USE IN PRODUCTION ║ ║ ║ ║ The wire format is not yet frozen. Breaking changes may ║ ║ land between alpha releases. Peer authentication and key ║ ║ establishment are now available in this crate (feature ║ ║ `handshake`, off by default) as well as natively in ║ ║ product layers such as `xenia-handshake` -- pick one, not ║ ║ both, per identity you're establishing. ║ ║ ║ ║ This crate is an early research artifact. It will be ║ ║ ready for production use only after the specification is ║ ║ independently reviewed and the test-vector suite is ║ ║ cross-validated against another implementation. ║ ╚═══════════════════════════════════════════════════════════╝ ``` **Xenia** (ξενία) —— 古希腊语中客人与主人之间的契约。技术 人员是客户机器中的*客人*；客户提供有界的 款待；协议则以加密方式将这些条款明文码化。 ## 它是什么 `xenia-wire` 是 Xenia 协议的*字节级*层：获取 一系列应用 payload，将每个 payload 密封到有界的信封中， 防止重放和篡改，在不丢失传输中 消息的情况下轮换密钥。它对传输层（TCP、WebSocket、 QUIC、UDP 均可）没有限制，对帧策略没有限制（这是 调用者的责任），对握手也没有限制。这些均由上层处理。 ### 你能得到什么 - **ChaCha20-Poly1305 AEAD**，采用基于会话的随机 `source_id` + `epoch` 以及 nonce 中的单调序列 —— 按 payload 类型进行域分离，以便 相同的密钥可以密封多个并发流，而不会发生 nonce 碰撞。 - **64 位滑动重放窗口**，以 `(source_id, payload_type)` 为键， 匹配 IPsec/DTLS 重放保护语义。 - **旧密钥宽限期** —— 重置密钥而不会丢失传输中的帧。 - **可选的 LZ4-before-seal 压缩**（在 `lz4` feature 之后）—— 这是压缩 AEAD 密封流的唯一安全位置。 - **通用的 `Sealable` trait** —— 自带你的帧类型，或者使用 参考的 `Frame` / `Input` 类型进行快速原型设计。 - **在 drop 时执行 Zeroize** 的密钥材料。 ### 它*不*是什么 - 它不是传输层。你的调用者负责发送密封的字节；`xenia-wire` 不会 打开 socket。 - 它不是 TLS 的替代品 —— 没有证书链，没有 ALPN，没有主机名绑定。 - 它不是通用的 AEAD 库 —— `xenia-wire` 固定了一种特定的 nonce 布局， 适用于受重放保护的流。 上方的 AEAD 密封层（`Session`/`seal`/`open`）与传输和 握手无关 —— 可从任何地方引入任何 32 字节的密钥。话虽如此，这个 crate 现在*也*自带了它的握手（feature 为 `handshake`，默认关闭）： `handshake`（ML-KEM-768 + Ed25519 + ML-DSA-65，仅限观察者角色 —— 主机角色的标准套件对应项原生存在于 `xenia-peer` 产品中）和 `handshake_highsec`（ML-KEM-1024 + Ed25519 + ML-DSA-87，包含 主机和观察者双重角色，自包含）。两者都会派生出一个可以直接安装到 `Session` 中的 [`handshake::SessionKeySchedule`]。 已经有握手层（`xenia-handshake` 或其他）的调用者 可以忽略所有这些，只需在 `default-features = false` 的情况下使用密封层即可。 ## 安装 因为它是一个预发布版本，所以需要使用 `@` 形式添加它 —— `cargo add --version ...` 会拒绝预发布说明符。请使用 [crates.io](https://crates.io/crates/xenia-wire) 上最新的 `0.2.0-alpha.N` （目前是 `alpha.8`）： ``` $ cargo add 'xenia-wire@0.2.0-alpha.8' ``` 一旦稳定的 `0.2.0` 版本发布，`cargo add xenia-wire` 就可以直接使用了。 早期的 `0.1.x` alpha 版本仍然保留在 crates.io 上，但在 签名同意正文本层上存在传输不兼容性（有关草案 矩阵，请参阅 SPEC 附录 B）；新的集成应该从 `0.2.x` 开始。 ## 快速开始 ``` use xenia_wire::{Session, seal_frame, open_frame, Frame}; // Both sides install the same 32-byte key (in production, this comes // from a handshake such as ML-KEM-768; here we use a shared fixture). let key = [0xAB; 32]; let mut sender = Session::new(); let mut receiver = Session::new(); sender.install_key(key); receiver.install_key(key); // Seal a frame on the sender side. let frame = Frame { frame_id: 1, timestamp_ms: 1_700_000_000_000, payload: b"hello, xenia".to_vec(), }; let sealed: Vec = seal_frame(&frame, &mut sender) .expect("seal succeeds with a valid key"); // Ship `sealed` over any transport you like (TCP, WS, QUIC, UDP). // Receiver opens the envelope. let opened: Frame = open_frame(&sealed, &mut receiver) .expect("open succeeds, replay window advances"); assert_eq!(opened.payload, b"hello, xenia"); // Replaying the same bytes fails — replay window catches it. assert!(open_frame(&sealed, &mut receiver).is_err()); ``` 运行它： ``` $ cargo run --example hello_xenia ``` ## 功能 | Feature | 默认 | 功能 | |------------------|---------|-------------------------------------------------------| | `reference-frame`| 是 | 提供 `Frame` + `Input` 实现 `Sealable` 的参考类型。如果你只使用自定义的 payload 类型，可以去掉它。 | | `lz4` | 否 | 添加 `seal_frame_lz4` / `open_frame_lz4` 用于 LZ4-before-AEAD 压缩。在实际的 Pixel 8 Pro 捕获中测量值为 2.12 倍。 | | `handshake` | 否 | ML-KEM-768 + Ed25519 + ML-DSA-65 握手（`handshake` 模块，观察者角色）以及自包含的 ML-KEM-1024 + Ed25519 + ML-DSA-87 高安全性套件（`handshake_highsec`，双重角色）。每次握手都会生成一个用于该会话的新 KEM 密钥对（针对后来的长期密钥泄露具备前向安全性），并派生出一个准备好 `install_key` 到 `Session` 中的 [`handshake::SessionKeySchedule`]。 | | `operator-rekey` | 否 | 针对单密钥应用通道的前向密钥重置控制消息（`operator_rekey` 模块）—— 在已建立的会话上进行定期的原地密钥轮换。独立于 `handshake`：只需要 `blake3`+`bincode`+`serde`。 | ## 自定义 payload 为你自己的类型实现 `Sealable`： ``` use xenia_wire::{Sealable, WireError}; #[derive(serde::Serialize, serde::Deserialize)] struct MyPayload { data: Vec } impl Sealable for MyPayload { fn to_bin(&self) -> Result, WireError> { bincode::serialize(self).map_err(WireError::encode) } fn from_bin(bytes: &[u8]) -> Result { bincode::deserialize(bytes).map_err(WireError::decode) } } ``` 然后泛型地调用 `seal` / `open`： ``` use xenia_wire::{seal, open, Session}; let mut session = Session::new(); session.install_key([0; 32]); let payload = MyPayload { data: vec![1, 2, 3] }; let sealed = seal(&payload, &mut session, 0x30)?; # Ok::<(), xenia_wire::WireError>(()) ``` Payload 类型字节 `0x00..=0x0F` 和 `0x10..=0x2F` 是保留的；请参阅 `payload_types.rs`。请在你的应用中使用 `0x30..=0xFF`。 ## 经验来源 该通信协议格式是从一个生产级研究技术栈（Holon-Soma， Symthaea 意识 runtime 的一部分）中提取出来的。在真实硬件上的经验测量： - **JSON 基准 → bincode 密封**：带宽减少 3.27–3.52 倍（Pixel 8 Pro，Phase I.A）。 - **LZ4-before-seal**：整体额外减少 2.12 倍，在 稳态 Delta 帧上减少 2.20 倍（Pixel 8 Pro，Phase II.A，2026-04-17）。 - **队头阻塞比较 (WS vs QUIC)**：在 1% 丢包率下，WS 的尾延迟 会膨胀 4.7 倍；而 QUIC 保持在 ≤ 2 倍（Phase I.C，loopback netem harness）。这是传输层的结果 —— `xenia-wire` 并不关心 你选择哪种传输方式。 完整的方法论将在即将发布的 Xenia 协议论文中进行详述。 ## 论文 [`papers/xenia-paper.md`](papers/xenia-paper.md) —— 该协议的学术 说明，包含设计原理、经验 评估（带宽、HoL 阻塞、LZ4 测量），以及 与商业和开源替代方案的 设计空间比较。**Pre-alpha 草案**，正在积极征求 密码学家和 MSP 从业者的审查。论文是 说明；[`SPEC.md`](SPEC.md) 是规范参考。 ## 规范 阅读 [`SPEC.md`](SPEC.md)（**draft-03**，当前版本）应该足以 让你用任何语言编写一个可互操作的实现。没必要阅读 这个 crate 的源码。如果你在 规范中发现了漏洞，请提交 issue —— 规范是权威参考， 而不是 Rust 源码。 - [`SPEC.md`](SPEC.md) —— 完整的通信协议格式规范，包含 11 个章节 + 3 个附录，涵盖 nonce 布局、重放窗口语义、 密钥生命周期、LZ4-before-AEAD 规则、错误分类法以及安全性 属性。 - [`CHANGELOG.md`](CHANGELOG.md) —— 版本历史。 - [`test-vectors/`](test-vectors/README.md) —— 12 个确定性的十六进制 测试夹具，用于跨实现验证。无论用 Go、Swift、Python 还是任何其他语言编写的实现，都可以从发布的夹具中重现每一个 信封字节。 ## License 根据以下任一协议授权： - Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) 或 ) - MIT license ([LICENSE-MIT](LICENSE-MIT) 或 ) 由你选择。 ## 贡献 除非你明确声明，否则根据 Apache-2.0 协议的定义，你出于包含在此作品中的目的而有意提交的任何贡献， 均应按上述方式进行双重授权，不附加任何额外条款 或条件。 ## 相关内容 - [Luminous Dynamics](https://luminousdynamics.io) —— 发布此 crate 的研究机构。 - [Holon-Soma 路线图](https://github.com/Luminous-Dynamics/symthaea) （私有）—— 提取此通信协议格式的上游研究路线图。

标签：Rust, 内核驱动, 可视化界面, 密码学, 手动系统调用, 抗量子密码学, 网络协议, 网络流量审计, 远程控制, 通知系统