封装两设备 MLS 客户端引擎与状态恢复

This commit is contained in:
xhgit committed 2026-11-13 18:31:29 +08:00
1 parent 0b17dd07c5
commit 1e05d7a3af
7 files changed
+448

No files matched your search

+2
View File
@@ -2081,6 +2081,8 @@ dependencies = [
"openmls",
"openmls_basic_credential",
"openmls_rust_crypto",
"serde",
"serde_json",
"tls_codec",
"wasm-bindgen",
"wasm-bindgen-test",
+2
View File
@@ -12,6 +12,8 @@ openmls = { version = "=0.9.2", features = ["js"] }
openmls_basic_credential = "=0.6.0"
openmls_rust_crypto = "=0.6.0"
tls_codec = "=0.5.0"
serde = { version = "1", features = ["derive"] }
serde_json = "1"
[target.'cfg(target_arch = "wasm32")'.dependencies]
getrandom = { version = "0.2", features = ["js"] }
+9
View File
@@ -5,3 +5,12 @@
在本目录使用 Rust 1.95 运行 `cargo test --locked` 执行原生验证。浏览器验证需安装 Rust 的 `wasm32-unknown-unknown` 目标、wasm-bindgen-cli 0.2.130 和与本机 Chrome 匹配的 ChromeDriver。将 ChromeDriver 放入 PATH 或设置 CHROMEDRIVER,再执行 `cargo test --locked --target wasm32-unknown-unknown`。
用例用独立的三个客户端加入同一 MLS 群,使用 TLS 编码传输 Welcome、应用消息和移除 Commit。验证接收者能解密,重复消息被拒绝,且被移除的客户端无法解密新世代消息。
WASM 导出 `DeviceMls`,负责生成密钥包、创建和加入两设备会话、绑定应用关联数据,以及处理消息。调用方需先独立验证设备公钥。MLS 快照包含私钥和会话秘密,调用方须在本机加密保存。每次操作从已保存快照恢复,成功后原子提交新快照和待发封包或接收游标。失败时丢弃该实例。
使用下列命令生成浏览器绑定。构建输出存放于 `target`。
```sh
cargo build --locked --release --target wasm32-unknown-unknown
wasm-bindgen --target web --out-dir target/web target/wasm32-unknown-unknown/release/xhchat_mls_check.wasm
```
+307
View File
@@ -0,0 +1,307 @@
use ::tls_codec::{Deserialize as _, Serialize as _};
use openmls::prelude::*;
use openmls_basic_credential::SignatureKeyPair;
use openmls_rust_crypto::OpenMlsRustCrypto;
use serde::{Deserialize, Serialize};
use std::collections::HashMap;
const SUITE: Ciphersuite = Ciphersuite::MLS_128_DHKEMX25519_AES128GCM_SHA256_Ed25519;
const MAX_SNAPSHOT: usize = 16 * 1024 * 1024;
type EngineResult<T> = Result<T, &'static str>;
#[derive(Serialize, Deserialize)]
struct Snapshot {
version: u8,
device: String,
public_key: Vec<u8>,
storage: Vec<(Vec<u8>, Vec<u8>)>,
}
pub struct Engine {
provider: OpenMlsRustCrypto,
device: String,
public_key: Vec<u8>,
}
impl Engine {
pub fn new(device: &str) -> EngineResult<Self> {
if !valid_device(device) {
return Err("invalid device id");
}
let provider = OpenMlsRustCrypto::default();
let signer = SignatureKeyPair::new(SUITE.signature_algorithm())
.map_err(|_| "signer generation failed")?;
signer
.store(provider.storage())
.map_err(|_| "signer storage failed")?;
Ok(Self {
provider,
device: device.to_owned(),
public_key: signer.to_public_vec(),
})
}
pub fn restore(bytes: &[u8]) -> EngineResult<Self> {
if bytes.len() > MAX_SNAPSHOT {
return Err("state too large");
}
let snapshot: Snapshot = serde_json::from_slice(bytes).map_err(|_| "invalid MLS state")?;
if snapshot.version != 1
|| !valid_device(&snapshot.device)
|| snapshot.public_key.len() != 32
{
return Err("invalid MLS state");
}
let provider = OpenMlsRustCrypto::default();
let count = snapshot.storage.len();
let storage: HashMap<_, _> = snapshot.storage.into_iter().collect();
if storage.len() != count {
return Err("invalid MLS state");
}
*provider
.storage()
.values
.write()
.map_err(|_| "state unavailable")? = storage;
let result = Self {
provider,
device: snapshot.device,
public_key: snapshot.public_key,
};
result.signer()?;
Ok(result)
}
pub fn snapshot(&self) -> EngineResult<Vec<u8>> {
let storage = self
.provider
.storage()
.values
.read()
.map_err(|_| "state unavailable")?;
let snapshot = Snapshot {
version: 1,
device: self.device.clone(),
public_key: self.public_key.clone(),
storage: storage
.iter()
.map(|(key, value)| (key.clone(), value.clone()))
.collect(),
};
let encoded = serde_json::to_vec(&snapshot).map_err(|_| "state encoding failed")?;
if encoded.len() > MAX_SNAPSHOT {
return Err("state too large");
}
Ok(encoded)
}
pub fn public_key(&self) -> &[u8] {
&self.public_key
}
pub fn device(&self) -> &str {
&self.device
}
pub fn key_package(&self) -> EngineResult<Vec<u8>> {
let package = KeyPackage::builder()
.build(SUITE, &self.provider, &self.signer()?, self.credential())
.map_err(|_| "key package creation failed")?;
MlsMessageOut::from(package.key_package().clone())
.tls_serialize_detached()
.map_err(|_| "key package encoding failed")
}
pub fn start(
&self,
group_id: &[u8],
peer: &str,
expected_key: &[u8],
wire: &[u8],
) -> EngineResult<Vec<u8>> {
let id = group_id_from(group_id)?;
if self.load_group(&id)?.is_some() {
return Err("conversation already exists");
}
let message =
MlsMessageIn::tls_deserialize_exact(wire).map_err(|_| "invalid key package")?;
let MlsMessageBodyIn::KeyPackage(package) = message.extract() else {
return Err("invalid key package");
};
let package = package
.validate(self.provider.crypto(), ProtocolVersion::Mls10)
.map_err(|_| "invalid key package")?;
let leaf = package.leaf_node();
if peer == self.device
|| package.ciphersuite() != SUITE
|| expected_key.len() != 32
|| !matches_device(leaf.credential(), peer)
|| leaf.signature_key().as_slice() != expected_key
{
return Err("unexpected peer identity");
}
let config = MlsGroupCreateConfig::builder()
.ciphersuite(SUITE)
.use_ratchet_tree_extension(true)
.build();
let signer = self.signer()?;
let mut group =
MlsGroup::new_with_group_id(&self.provider, &signer, &config, id, self.credential())
.map_err(|_| "conversation creation failed")?;
let (_, welcome, _) = group
.add_members(&self.provider, &signer, &[package])
.map_err(|_| "peer enrollment failed")?;
group
.merge_pending_commit(&self.provider)
.map_err(|_| "conversation commit failed")?;
welcome
.tls_serialize_detached()
.map_err(|_| "welcome encoding failed")
}
pub fn join(&self, peer: &str, expected_key: &[u8], wire: &[u8]) -> EngineResult<Vec<u8>> {
let message = MlsMessageIn::tls_deserialize_exact(wire).map_err(|_| "invalid welcome")?;
let MlsMessageBodyIn::Welcome(welcome) = message.extract() else {
return Err("invalid welcome");
};
if welcome.ciphersuite() != SUITE {
return Err("unsupported MLS ciphersuite");
}
let config = MlsGroupJoinConfig::builder()
.use_ratchet_tree_extension(true)
.build();
let staged = StagedWelcome::new_from_welcome(&self.provider, &config, welcome, None)
.map_err(|_| "welcome rejected")?;
let sender = staged
.welcome_sender()
.map_err(|_| "unknown welcome sender")?;
if peer == self.device
|| expected_key.len() != 32
|| !matches_device(sender.credential(), peer)
|| sender.signature_key().as_slice() != expected_key
{
return Err("unexpected peer identity");
}
let own = staged.own_leaf_node().ok_or("missing local device")?;
if !matches_device(own.credential(), &self.device)
|| own.signature_key().as_slice() != self.public_key
|| staged.members().count() != 2
{
return Err("unexpected conversation membership");
}
let id = staged.group_context().group_id();
group_id_from(id.as_slice())?;
if self.load_group(id)?.is_some() {
return Err("conversation already exists");
}
let group = staged
.into_group(&self.provider)
.map_err(|_| "welcome rejected")?;
Ok(group.group_id().as_slice().to_vec())
}
pub fn encrypt(
&self,
id: &[u8],
associated_data: &[u8],
plaintext: &[u8],
) -> EngineResult<Vec<u8>> {
let mut group = self
.load_group(&group_id_from(id)?)?
.ok_or("unknown conversation")?;
group.set_aad(associated_data.to_vec());
group
.create_message(&self.provider, &self.signer()?, plaintext)
.map_err(|_| "encryption failed")?
.tls_serialize_detached()
.map_err(|_| "ciphertext encoding failed")
}
pub fn decrypt(
&self,
peer: &str,
expected_key: &[u8],
associated_data: &[u8],
wire: &[u8],
) -> EngineResult<Vec<u8>> {
let protocol = MlsMessageIn::tls_deserialize_exact(wire)
.map_err(|_| "invalid ciphertext")?
.try_into_protocol_message()
.map_err(|_| "invalid ciphertext")?;
let mut group = self
.load_group(protocol.group_id())?
.ok_or("unknown conversation")?;
if !group.members().any(|member| {
matches_device(&member.credential, peer) && member.signature_key == expected_key
}) {
return Err("unexpected peer identity");
}
let processed = group
.process_message(&self.provider, protocol)
.map_err(|_| "ciphertext rejected")?;
let Sender::Member(index) = processed.sender() else {
return Err("unexpected message sender");
};
let member = group
.members()
.find(|member| &member.index == index)
.ok_or("unknown sender")?;
if peer == self.device
|| expected_key.len() != 32
|| !matches_device(processed.credential(), peer)
|| member.signature_key != expected_key
|| processed.aad() != associated_data
{
return Err("unexpected message identity");
}
let ProcessedMessageContent::ApplicationMessage(application) = processed.into_content()
else {
return Err("unexpected MLS content");
};
Ok(application.into_bytes())
}
fn signer(&self) -> EngineResult<SignatureKeyPair> {
SignatureKeyPair::read(
self.provider.storage(),
&self.public_key,
SUITE.signature_algorithm(),
)
.ok_or("missing signing key")
}
fn credential(&self) -> CredentialWithKey {
CredentialWithKey {
credential: BasicCredential::new(self.device.as_bytes().to_vec()).into(),
signature_key: self.public_key.clone().into(),
}
}
fn load_group(&self, id: &GroupId) -> EngineResult<Option<MlsGroup>> {
MlsGroup::load(self.provider.storage(), id).map_err(|_| "conversation state unavailable")
}
}
fn valid_device(id: &str) -> bool {
id.len() == 36
&& id.bytes().enumerate().all(|(i, b)| {
if [8, 13, 18, 23].contains(&i) {
b == b'-'
} else {
b.is_ascii_digit() || (b'a'..=b'f').contains(&b)
}
})
}
fn group_id_from(bytes: &[u8]) -> EngineResult<GroupId> {
if bytes.len() != 32 {
return Err("invalid conversation id");
}
Ok(GroupId::from_slice(bytes))
}
fn matches_device(credential: &Credential, device: &str) -> bool {
credential.credential_type() == CredentialType::Basic
&& credential.serialized_content() == device.as_bytes()
}
+63
View File
@@ -1,3 +1,9 @@
#[cfg(any(test, target_arch = "wasm32"))]
mod engine;
#[cfg(target_arch = "wasm32")]
mod wasm;
#[cfg(test)]
mod tests {
use ::tls_codec::{Deserialize as _, Serialize as _};
@@ -12,6 +18,63 @@ mod tests {
const SUITE: Ciphersuite = Ciphersuite::MLS_128_DHKEMX25519_AES128GCM_SHA256_Ed25519;
#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test)]
#[cfg_attr(not(target_arch = "wasm32"), test)]
fn device_conversation_survives_restore() {
use crate::engine::Engine;
let alice_id = "c82d961b-aa65-4d44-9de8-1967d32ee8d3";
let bob_id = "346c8638-f422-471a-827d-d07a1bcf8ae8";
let alice = Engine::new(alice_id).unwrap();
let bob = Engine::new(bob_id).unwrap();
let group = [5; 32];
let package = bob.key_package().unwrap();
assert!(alice.start(&group, bob_id, &[0; 32], &package).is_err());
let welcome = alice
.start(&group, bob_id, bob.public_key(), &package)
.unwrap();
assert!(
alice
.start(&group, bob_id, bob.public_key(), &package)
.is_err()
);
let bob_backup = bob.snapshot().unwrap();
let wrong_key = Engine::restore(&bob_backup).unwrap();
assert!(wrong_key.join(alice_id, &[0; 32], &welcome).is_err());
let bob = Engine::restore(&bob_backup).unwrap();
assert_eq!(bob.device(), bob_id);
assert_eq!(
bob.join(alice_id, alice.public_key(), &welcome).unwrap(),
group
);
let alice = Engine::restore(&alice.snapshot().unwrap()).unwrap();
let message = alice.encrypt(&group, b"message-1", b"hello").unwrap();
let bob_backup = bob.snapshot().unwrap();
let wrong_aad = Engine::restore(&bob_backup).unwrap();
assert!(
wrong_aad
.decrypt(alice_id, alice.public_key(), b"message-2", &message)
.is_err()
);
let bob = Engine::restore(&bob_backup).unwrap();
assert_eq!(
bob.decrypt(alice_id, alice.public_key(), b"message-1", &message)
.unwrap(),
b"hello"
);
let bob = Engine::restore(&bob.snapshot().unwrap()).unwrap();
assert!(
bob.decrypt(alice_id, alice.public_key(), b"message-1", &message)
.is_err()
);
let reply = bob.encrypt(&group, b"reply", b"hello back").unwrap();
assert_eq!(
alice
.decrypt(bob_id, bob.public_key(), b"reply", &reply)
.unwrap(),
b"hello back"
);
}
fn identity(id: &[u8]) -> (SignatureKeyPair, CredentialWithKey) {
let signer = SignatureKeyPair::new(SUITE.signature_algorithm()).unwrap();
let credential = CredentialWithKey {
+61
View File
@@ -0,0 +1,61 @@
use crate::engine::Engine;
use wasm_bindgen::prelude::*;
#[wasm_bindgen]
pub struct DeviceMls(Engine);
#[wasm_bindgen]
impl DeviceMls {
#[wasm_bindgen(constructor)]
pub fn new(device: &str) -> Result<DeviceMls, JsError> {
Ok(Self(Engine::new(device).map_err(JsError::new)?))
}
pub fn restore(state: &[u8]) -> Result<DeviceMls, JsError> {
Ok(Self(Engine::restore(state).map_err(JsError::new)?))
}
pub fn snapshot(&self) -> Result<Vec<u8>, JsError> {
self.0.snapshot().map_err(JsError::new)
}
pub fn device(&self) -> String {
self.0.device().to_owned()
}
pub fn public_key(&self) -> Vec<u8> {
self.0.public_key().to_vec()
}
pub fn key_package(&self) -> Result<Vec<u8>, JsError> {
self.0.key_package().map_err(JsError::new)
}
pub fn start(
&self,
id: &[u8],
peer: &str,
key: &[u8],
wire: &[u8],
) -> Result<Vec<u8>, JsError> {
self.0.start(id, peer, key, wire).map_err(JsError::new)
}
pub fn join(&self, peer: &str, key: &[u8], wire: &[u8]) -> Result<Vec<u8>, JsError> {
self.0.join(peer, key, wire).map_err(JsError::new)
}
pub fn encrypt(&self, id: &[u8], aad: &[u8], plaintext: &[u8]) -> Result<Vec<u8>, JsError> {
self.0.encrypt(id, aad, plaintext).map_err(JsError::new)
}
pub fn decrypt(
&self,
peer: &str,
key: &[u8],
aad: &[u8],
wire: &[u8],
) -> Result<Vec<u8>, JsError> {
self.0.decrypt(peer, key, aad, wire).map_err(JsError::new)
}
}
+4
View File
@@ -40,3 +40,7 @@ Web 和 Electron 共用 Vue 客户端,独立接入同一 Go API。真实 Postg
## 设备目录与密钥包
服务端已实现联系人设备目录、设备签名校验和一次性 MLS KeyPackage 领取。Compose 集成测试验证陌生人隔离、错误签名拒绝、并发只能领取一次、重复上传不会重新开放领取和撤销后目录隐藏。接下来需在双端接入可信公钥验证及 MLS 会话持久化。
## 两设备 MLS 引擎
OpenMLS WASM 提供两设备会话创建、加入、消息加解密和端侧状态快照。原生 Rust 和 Windows Chrome WebAssembly 各通过两项测试,覆盖错误公钥、错误消息关联数据、恢复后的正常收发和重放拒绝。界面、设备身份验证、快照加密保存和发送队列仍在接入。