@ getmaapp/ signal-wasm
为基于浏览器的 E2EE 消息编辑到 WebAssembly 的信号协议
特征
- 🔐 端到端加密 - 信号协议(PQXDH + 三重鼠标)
- 🛡️ 量子后准备 - Kyber1024(P-DH)支助
- 👥 分组消息 ——发件人密钥和私人团体(GV2)
- 🆔 灵活身份 - 任意字符串标识符(Firebase UID、用户名、UUID)
- 🔢 安全编号 - 身份核查指纹
- 💾 序列化 - 索引数据库持续进出口
- 🌐 浏览器- 第一 —— 随机性使用 Web Crypto API
安装
npm install @getmaapp/signal-wasm
快速启动
import init, {
PrivateKey,
IdentityKeyPair,
ProtocolAddress,
InMemIdentityKeyStore,
InMemSessionStore,
InMemPreKeyStore,
InMemSignedPreKeyStore,
InMemKyberPreKeyStore,
generateRegistrationId,
generatePreKeys,
generateSignedPreKey,
generateKyberPreKey,
processPreKeyBundle,
encryptMessage,
decryptMessage,
} from "@getmaapp/signal-wasm";
// 1. Initialise the WASM module
await init();
// 2. Generate an identity (no device ID required)
const privateKey = PrivateKey.generate();
const publicKey = privateKey.getPublicKey();
const identityKeyPair = new IdentityKeyPair(publicKey, privateKey);
const registrationId = generateRegistrationId();
// 3. Create stores
const identityStore = new InMemIdentityKeyStore(identityKeyPair, registrationId);
const sessionStore = new InMemSessionStore();
const prekeyStore = new InMemPreKeyStore();
const signedPrekeyStore = new InMemSignedPreKeyStore();
const kyberPrekeyStore = new InMemKyberPreKeyStore();
// 4. Generate keys for registration
const prekeys = await generatePreKeys(1, 100, prekeyStore);
const signedPreKey = await generateSignedPreKey(1, identityKeyPair, signedPrekeyStore);
const kyberPreKey = await generateKyberPreKey(1, identityKeyPair, kyberPrekeyStore);
// 5. Addressing (device ID is only used here)
const localAddress = new ProtocolAddress("alice-firebase-uid", 1);
const bobAddress = new ProtocolAddress("bob-firebase-uid", 1);
// 6. Establish a session (Alice processes Bob's PreKey bundle)
await processPreKeyBundle(
bobAddress,
localAddress,
bobRegistrationId,
bobIdentityKey,
bobSignedPreKey.id,
bobSignedPreKeyPublic,
bobSignedPreKey.signature,
bobPreKey.id,
bobPreKey.public_key,
bobKyberPreKey.id,
bobKyberPreKey.public_key,
bobKyberPreKey.signature,
sessionStore,
identityStore,
);
// 7. Encrypt a message
const plaintext = new TextEncoder().encode("Hello Bob! 🔒");
const ciphertext = await encryptMessage(
plaintext,
bobAddress,
localAddress,
sessionStore,
identityStore,
);
// 8. Decrypt a message
const result = await decryptMessage(
ciphertext.body,
ciphertext.message_type,
aliceAddress,
bobAddress,
sessionStore,
identityStore,
prekeyStore,
signedPrekeyStore,
kyberPrekeyStore,
);
const plaintext2 = result.plaintext;
// 9. Tombstone any one-time keys the decrypt consumed. All id fields
// are `undefined` when nothing was consumed (e.g. non-prekey messages).
if (result.kyberPreKeyId !== undefined) {
// delete kyber prekey result.kyberPreKeyId from your durable store
}
if (result.oneTimePreKeyId !== undefined) {
// delete X25519 prekey result.oneTimePreKeyId from your durable store
}
API 参考
加密初级
| 类 | 方法 |
|---|---|
PrivateKey | generate(), (中文(简体) ), getPublicKey(), (中文(简体) ), serialize(), (中文(简体) ), deserialize(data) |
PublicKey | serialize(), (中文(简体) ), deserialize(data) |
IdentityKeyPair | constructor(publicKey, privateKey), (中文(简体) ), serialize(), (中文(简体) ), deserialize(data) |
协议地址
| 类 | 说明 |
|---|---|
ProtocolAddress | constructor(name, deviceId) —— 说 name 可以是任意字符串(Firebase UID,UUID等) |
存储(内存)
所有商店都支持索引数据库的持续进出口.
| 存储 | 构造器 | 进出口方法 |
|---|---|---|
InMemIdentityKeyStore | new(identityKeyPair, registrationId) | —— 说 |
InMemSessionStore | new() | export_session(address), (中文(简体) ), import_session(address, bytes), (中文(简体) ), has_session(address), (中文(简体) ), archive_session(address), (中文(简体) ), delete_session(address) |
InMemPreKeyStore | new() | export_pre_key(id), (中文(简体) ), import_pre_key(id, bytes) |
InMemSignedPreKeyStore | new() | export_signed_pre_key(id), (中文(简体) ), import_signed_pre_key(id, bytes) |
InMemKyberPreKeyStore | new() | export_kyber_pre_key(id), (中文(简体) ), import_kyber_pre_key(id, bytes), (中文(简体) ), export_kyber_usage(), (中文(简体) ), import_kyber_usage(bytes) |
InMemSenderKeyStore | new() | export_sender_key(address, distributionId), (中文(简体) ), import_sender_key(address, distributionId, bytes), (中文(简体) ), remove_sender_key(address, distributionId) |
自0.4.0起: 每个
distributionId一定是被打来的 UUID 字符串 (例如:.crypto.randomUUID()) (中文(简体) ). 包装纸不再从 任意组合字符串.remove_sender_key(address, distributionId)删除 发送键记录(返回)boolean) 并且必须在 重新制作关于成员去除/妥协的分布图,否则为自定义 重新使用已存在的链条,被移除的成员继续解密.
自0.6.0起:
InMemKyberPreKeyStore也带着开膛手 反重放 内存 - 这套(kyberId, signedPreKeyId, senderBaseKey)三倍 引擎已经看到。 坚持下去export_kyber_usage()- 字节,import_kyber_usage(bytes)与kyber的记录. 没有它,每一次重新装入和重放的后卫 PreKeySignalMessage 对抗活的后遗症密钥再次被斩首. 这与Signal自己的客户端所坚持的一致(Signal-iOS的)KyberPreKeyUseRecord表,信号-德斯克托普kyberPreKey_triples) (中文(简体) ).
密钥生成
| 函数 | 回返 | 说明 |
|---|---|---|
generatePreKeys(startId, count, store) | Promise<WasmPreKey[]> | 批量遗传一次性预键 |
generateSignedPreKey(id, identityKeyPair, store) | Promise<WasmSignedPreKey> | 生成一个签名的 PreKey |
generateKyberPreKey(id, identityKeyPair, store) | Promise<WasmKyberPreKey> | 生成 Kyber PreKey (PQXDH) |
generateRegistrationId() | number | 生成无偏见的登记身份证(1-16383) |
礼宾业务
| 函数 | 回返 | 说明 |
|---|---|---|
processPreKeyBundle(...) | Promise<void> | 从 PreKey 捆绑建立会话 |
encryptMessage(plaintext, recipient, localAddress, sessionStore, identityStore) | Promise<WasmCiphertext> | 加密 1:1 个消息 |
decryptMessage(ciphertext, type, sender, localAddress, sessionStore, identityStore, prekeyStore, signedPrekeyStore, kyberPrekeyStore) | Promise<WasmDecryptResult> | 解密1:1个消息. 结果获取器 : plaintext (单位:千美元)Uint8Array),加 (中文(简体) ) kyberPreKeyId 编号 : oneTimePreKeyId 编号 : signedPreKeyId - 一次性预键标识,用于建立新的届会(undefined (没有) 墓碑在你的耐用店里消耗了身份证 |
createSenderKeyDistribution(localAddress, distributionId, senderKeyStore) | Promise<Uint8Array> | 创建发件人密钥分发信件( E)distributionId 必须是 UUID 字符串) |
processSenderKeyDistribution(senderAddress, distMessage, senderKeyStore) | Promise<void> | 处理发送者密钥分发消息( 从信件读取) |
encryptGroupMessage(localAddress, distributionId, plaintext, senderKeyStore) | Promise<Uint8Array> | 加密组信件( E)distributionId 必须是 UUID 字符串) |
decryptGroupMessage(senderAddress, ciphertext, senderKeyStore) | Promise<Uint8Array> | 解密一个组消息( 从密码文本读取 ) |
处理错误
每个被否决的诺言都会有真正的联署材料 Error 改为:
message—— 说"SignalError: <detail>"在调试构造中;平整为"SignalError: Operation failed"正在建立(未改变的行为).code——一个稳定的机器可读字符串,与 libsignal 错误相匹配 类型 因此,即使在释放时,它仍然保持具体:
code | 含义 |
|---|---|
NoSenderKeyState | 信件分发代号没有发件人键记录( 如 SKDM 尚未处理 —— 拉后重试) |
DuplicatedMessage | 已看到信件计数器( 重放/ 复制; 通常是良性) |
ReusedKyberBaseKey | Kyber 反重放拒绝: 此发件人基础密钥已被使用 (kyberId, signedPreKeyId) 配对 — 一个重放的 PreKey SignalMessage |
UntrustedIdentity | 无法信任地址的发件人身份密钥 |
InvalidKyberPreKeyId | 引用的 Kyber 预键id 无效/ 丢失 |
InvalidPreKeyId | 引用的预键 ID 无效/ 丢失 |
InvalidSignedPreKeyId | 已签名的引用预钥 ID 无效/ 丢失 |
FingerprintVersionMismatch | 扫描的 QR 指纹版本与我们的不同( 由 verifyScannableFingerprint(中文(简体) ) |
FingerprintParsingError | 扫描的 QR 指纹有效载荷无法解码或变形 |
Generic | 其他一切,包括包装侧验证失败 |
说明: String(err) 现在产量 "Error: SignalError: …" (标准) Error
字符串化),而不是空信,因为抛出值是一个
真实 Error 而不是绳子。 网站阅读 err.message 为:
不受影响.
安全编号
| 函数 | 回返 | 说明 |
|---|---|---|
generateSafetyNumber(localUuid, localIdentityKey, contactUuid, contactIdentityKey) | WasmSafetyNumber | 生成安全编号指纹( E)displayable 字符串 + scannable QR有效载荷) |
verifyScannableFingerprint(scanned, localUuid, localIdentityKey, contactUuid, contactIdentityKey) | boolean | 从0.5.0. Canonical 跨视角 QR 校验 (ScannableFingerprint::compare:检查他们的. local \"我们的.remote" 和他们的.remote \"我们的.local" 在恒定的时间。 掷出 FingerprintVersionMismatch 关于版本不匹配, FingerprintParsingError 在不可解码的有效载荷上 |
verifySafetyNumber(...) | boolean | 从0.5.0. 重新计算我们自己的指纹和字节比对——它永远无法验证一个跨视角扫描. 用于 API 兼容性; 使用 verifyScannableFingerprint |
身份证明
服务器可核实的对身份密钥的持有证明(例如授权 (原始内容存档于2018-03-26). Re-key). XEdDSA上方为X25519身份密钥,犬形的libsignal签名.
| 函数 | 回返 | 说明 |
|---|---|---|
signWithIdentityKey(identityPrivateKey, message) | Uint8Array | 签名 message 带有私钥的身份(64字节签名) |
verifyIdentitySignature(identityPublicKey, message, signature) | boolean | 经常核查; false 错误的密钥/消息或错误的签名 |
GV2(私人团体)
| 类 | 方法 |
|---|---|
WasmGroupMasterKey | generate(), (中文(简体) ), from_bytes(bytes), (中文(简体) ), derive_identifier(), (中文(简体) ), derive_secret_params() |
WasmGroupIdentifier | serialize |
WasmGroupSecretParams | serialize_master_key (自0. 5. 0; 返回 32 字节) 主密钥而不是完整的参数编码, get_identifier() |
数据结构
| 结构 | 属性 |
|---|---|
WasmPreKey | id, (中文(简体) ), public_key, (中文(简体) ), record |
WasmSignedPreKey | id, (中文(简体) ), public_key, (中文(简体) ), signature, (中文(简体) ), timestamp, (中文(简体) ), record |
WasmKyberPreKey | id, (中文(简体) ), public_key, (中文(简体) ), signature, (中文(简体) ), timestamp, (中文(简体) ), record |
WasmCiphertext | message_type, (中文(简体) ), body |
WasmSafetyNumber | displayable (弦声), scannable (Uint8箭头) |
工具函数
| 函数 | 说明 |
|---|---|
generate_random_bytes(length) | 生成 CSPRNG 随机字节( 最大 1 MiB) |
generate_uuid() | 生成一个 UUID v4( 返回 16 字节) |
uuid_to_string(bytes) | 将 16 字节转换为 UUID 字符串 |
uuid_from_string(str) | 将 UUID 字符串转换为 16 字节 |
message_type_signal() | 普通信号信息类型常数 |
message_type_pre_key() | PreKey 消息类型常数 |
message_type_sender_key() | 发送者密钥消息类型常数 |
虚拟配置
// vite.config.ts
import wasm from "vite-plugin-wasm";
import topLevelAwait from "vite-plugin-top-level-await";
export default defineConfig({
plugins: [wasm(), topLevelAwait()],
});
测试
我们用 wasm-bindgen-test 用于无头浏览器集成测试.
# Run tests in Headless Chrome
wasm-pack test --headless --chrome
# Run tests in Headless Firefox
wasm-pack test --headless --firefox
从源创建
# Prerequisites
rustup target add wasm32-unknown-unknown
cargo install wasm-pack
# Build
wasm-pack build --target web --scope getmaapp
警卫
- ✅
#![deny(unsafe_code)]- 没有不安全的玫瑰花 - QQ 对所有 WASM 绑定参数进行输入验证
- 固定拨款额
generate_random_bytes限于1个小米B) - PreKey 批量生成限500个键
- QQ 24 位 PreKey ID 包装( 匹配信号行为)
- 通过 Web Crypto API 创建 CSPRNG
- 生产中的一般错误信息构建
- * 秘密包装缓冲器在滴出时为零(
zeroize::Zeroizing)-见下文说明 - ✅
log_to_console调试帮助器编译出释放构建
内存安全和零化
- 包装器拥有的秘密缓冲器被包裹
zeroize::Zeroizing并带有零值的复写:序列化 PreKey/签名PreKey/KyberPreKey记录(每个记录包含私分), 和组合主键字节WasmGroupMasterKey编号 :WasmGroupSecretParams。 。 。 . - 限制. 长期身份密钥本身是一个自定义
PrivateKey- 上游地区Copy类型在一个以上[u8; 32]利比诺是 空投时不是零,所以包装器无法保证身份的去除 当它活在WASM线性记忆中时,会变平. 还有 任何字节导出到 Java 脚本 (通过)serialize()等)是JS记忆中的复制品 受浏览器垃圾收集器约束; 无法从中去除 生锈. 用极其小心的方式处理导出密钥 .
* Panics Brick the Entertainment * * 惊慌失措 *
释放构建使用 panic = "abort" (瓦斯姆河对岸没有风)
边界)。 因此,一个Rust恐慌 永久为 WASM 实例建砖 —— 说
之后的每一个呼叫陷阱, 和表面JS作为平地
SignalError: Operation failed 没有可收回的细节。 页面重载( 新实例) 是唯一
补救。 调试构建寄存器 console_error_panic_hook 如此惊慌
在开发过程中在控制台中可见.
许可证
AGPL-3.0 — 见 自由主义
此软件包基于 升号 v0.101.0 (承诺) b056faa6d)由信号技术基金会提供.
免责声明
此套件不隶属于信号技术基金会或得到其认可. 信号与信号协议是信号技术基金会的商标.