📚 FIBEMATE API 参考

更新于 2026-06-25 · 所有 API 均通过 window 全局对象暴露，无需 import · ← 返回首页

一、ML-KEM-768 (`window.MLKEM768`)

后量子密钥封装机制，FIPS 203 标准。ML-KEM-768 提供 NIST 安全等级 3（等效于 AES-192），抵抗 Shor 算法攻击。

常量

常量	值	说明
`MLKEM768.pkSize`	1184	公钥字节数
`MLKEM768.skSize`	2400	私钥字节数
`MLKEM768.ctSize`	1088	密文字节数
`MLKEM768.ssSize`	32	共享密钥字节数

keygen()

生成一对 ML-KEM-768 密钥对。

const { publicKey, secretKey } = await window.MLKEM768.keygen();

返回值	类型	长度	说明
`publicKey`	Uint8Array	1184 B	公钥，可公开发送
`secretKey`	Uint8Array	2400 B	私钥，绝不可泄露

encapsulate(publicKey)

使用对方公钥封装，生成一次性密文和共享密钥。

const { ciphertext, sharedSecret } = await window.MLKEM768.encapsulate(publicKey);

参数	类型	长度	说明
`publicKey`	Uint8Array	1184 B	接收方公钥

返回值	类型	长度	说明
`ciphertext`	Uint8Array	1088 B	密文，发送给接收方
`sharedSecret`	Uint8Array	32 B	共享密钥，直接用于 AES-256-GCM

安全保证：

密文可安全通过不可信信道传输
共享密钥为 32 B 随机值（密钥空间 2^256）
每次封装生成全新密钥（非确定性 KEM）

decapsulate(secretKey, ciphertext)

使用私钥解封装密文，恢复共享密钥。

const sharedSecret = await window.MLKEM768.decapsulate(secretKey, ciphertext);

参数	类型	长度	说明
`secretKey`	Uint8Array	2400 B	接收方私钥
`ciphertext`	Uint8Array	1088 B	发送方密文

返回值 Uint8Array（32 B）

成功解封装时与发送方 encapsulate() 返回的 sharedSecret 完全相同
输入无效时返回不匹配的 32 B 值（FO 变换隐式拒绝）

二、KeyStorage (`window.KeyStorage`)

基于 IndexedDB + WebCrypto 的密钥管理。支持长期身份密钥对的生成、存储、签名和密钥交换。

initDB()

await window.KeyStorage.initDB();

数据库名 FIBEMATE_Keys，对象存储 keys。所有其他方法内部自动调用 initDB()，可省略此步骤。

generateAndStoreKeyPair(keyId, userId)

const keyPair = await window.KeyStorage.generateAndStoreKeyPair('identity', 'alice@fibemate.link');

参数	类型	说明
`keyId`	string	密钥标识符（如 `'identity'`、`'rotation-2026'`）
`userId`	string	用户标识符，关联到密钥

storeKey(keyId, keyData)

await window.KeyStorage.storeKey('pre-key-1', {
  publicKey: 'hex_string...',
  privateKey: 'hex_string...',
  algorithm: 'ECDH-P256'
});

loadKey(keyId) / hasKey(keyId)

const keyData = await window.KeyStorage.loadKey('identity');
const exists = await window.KeyStorage.hasKey('identity'); // true | false

exportPublicKey(keyId)

const pubHex = await window.KeyStorage.exportPublicKey('identity');
// '04a3b1c2...' (130 字符, SEC1 未压缩格式)

sign(keyId, message) / deriveSharedKey(keyId, otherPublicKeyHex)

const signature = await window.KeyStorage.sign('identity', 'Hello World');
const sharedHex = await window.KeyStorage.deriveSharedKey('identity', otherPubHex);

rotateKey(keyId, userId) / deleteKey(keyId) / clearAllKeys()

const newKeyPair = await window.KeyStorage.rotateKey('identity', 'alice@fibemate.link');
await window.KeyStorage.deleteKey('old-session-key');
await window.KeyStorage.clearAllKeys();

migrateFromLocalStorage()

await window.KeyStorage.migrateFromLocalStorage();

三、MessageCrypto (`window.MessageCrypto`)

消息加解密引擎，组合 ML-KEM-768 + ECDH + Double Ratchet。

encryptMessage(text, recipientPublicKey, ratchetState)

const encrypted = await window.MessageCrypto.encryptMessage(
  'Hello Bob!',
  bobPublicKey,
  ratchetState
);
// encrypted 含 { ciphertext, iv, pqHeader }

decryptMessage(encryptedData, selfSecretKey, ratchetState)

const plaintext = await window.MessageCrypto.decryptMessage(
  encryptedData,
  selfSecretKey,
  ratchetState
);
// 'Hello Bob!'

四、Tauri 命令（Rust 后端）

前端通过 @tauri-apps/api 调用 Rust 命令。

import { invoke } from '@tauri-apps/api/core';

get_auth_status()

const status = await invoke('get_auth_status');
// { authenticated: boolean, user_id: string | null }

on_auth_success(token, user_id) / logout()

await invoke('on_auth_success', { token: 'jwt...', userId: 'alice@fibemate.link' });
await invoke('logout');

get_app_info()

const info = await invoke('get_app_info');
// { name: 'FIBEMATE', version: '1.0.0', ... }

navigate_to(page)

await invoke('navigate_to', { page: 'main' }); // page: 'main' | 'register' | 'login'

minimize_window() / toggle_maximize() / close_app()

await invoke('minimize_window');
await invoke('toggle_maximize');
await invoke('close_app');

五、SM2 国密桥接 (`window.MessageGM`)

SM2-SM4 混合加密，ECIES 密钥封装 + SM4-GCM 认证加密。

encryptWithSM2(plaintext, recipientPublicKeyHex)

const envelope = await window.MessageGM.encryptWithSM2(
  '你好世界 🌍',
  '04a3b1c2d3...'  // SM2 公钥 hex（130 字符）
);
// { version: 3, protocol: 'sm2-sm4-hybrid', ciphertext: '...', iv: '...', signature: '...' }

decryptWithSM2(envelope)

const plaintext = await window.MessageGM.decryptWithSM2(envelope);
// '你好世界 🌍'

安全特性：每次加密生成独立 SM4 密钥（32 B），随机 IV（12 B），ecdhKey = SM2 ECDH(pkRecipient, skSender)，AAD = c1[:32] 防篡改。

六、SLH-DSA WASM (`window.SlhDsa`)

SLH-DSA-SHA2-128s 后量子签名，FIPS 205 标准。Web Worker 异步加载，不阻塞 UI。

init() / keygen() / sign(message, secretKey) / verify(message, signature, publicKey)

await window.SlhDsa.init();
const { publicKey, secretKey } = await window.SlhDsa.keygen();
const signature = await window.SlhDsa.sign('data', secretKey);
const valid = await window.SlhDsa.verify('data', signature, publicKey); // true

七、PQC 混合握手 API（`/api/pqc-hybrid/*`）

路径 C（TLS Exporter 后握手混合密钥交换）。不改 Nginx/OpenSSL，基于 TLS Session ID + HKDF 绑定。

GET /api/pqc-hybrid/init

获取服务端 ML-KEM-768 公钥，开始混合握手。

const resp = await fetch('/api/pqc-hybrid/init');
const { pk, tlsSessionId } = await resp.json();
// pk: 1184B hex 编码的 ML-KEM-768 公钥
// tlsSessionId: 当前 TLS 会话 ID（Nginx proxy_set_header）

POST /api/pqc-hybrid/finalize

提交密文，完成共享密钥派生。

const ct = await MLKEM768.encapsulate(hexToBytes(pk));
const resp = await fetch('/api/pqc-hybrid/finalize', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ ct: bytesToHex(ct.ciphertext), tlsSessionId })
});
const { sessionKey } = await resp.json();
// sessionKey: 32B hex 编码（与浏览器端 HKDF 派生一致）

GET /api/pqc-hybrid/status

GET /api/pqc-hybrid/status → {
  "alive": true,
  "activeSessions": 0,
  "uptime": 12345
}

安全特性：

TLS Session ID 绑定防跨会话重放
HKDF(TLS_exported_secret || ss_pqc) 双源密钥，任一算法未破即安全
Session 5 分钟自动过期
ct=1088B · pk=1184B · sessionKey=32B

数据类型参考

类型	字节数	编码	说明
ML-KEM-768 公钥	1184	二进制	可转 hex/base64 传输
ML-KEM-768 私钥	2400	二进制	本地安全存储
ML-KEM-768 密文	1088	二进制	一次一密
共享密钥	32	二进制	AES-256-GCM 密钥
ECDH 公钥	65	hex (130 字符)	SEC1 未压缩
AES-GCM IV	12	二进制	每条消息随机
Auth Tag	16	二进制	GCM 认证标签
SLH-DSA 签名	7,856	二进制	SLH-DSA-SHA2-128s
SLH-DSA 公钥	32	二进制	SLH-DSA-SHA2-128s

安全注意事项

私钥不落盘：ML-KEM-768 私钥存在于内存，不使用 localStorage 明文存储
WebCrypto Non-Extractable：ECDH 私钥标记 extractable: false，无法导出原始密钥材料
恒定时间：所有密码学操作恒定时间，无时序侧信道
Forward Secrecy：Double Ratchet 每次消息更新密钥，历史消息不可回溯解密
后量子安全：ML-KEM-768 封装密钥在后量子计算机下保持安全
PQC 混合密钥交换：路径 C 已上线，TLS Exporter + ML-KEM-768 + HKDF

一、ML-KEM-768 (window.MLKEM768)

常量