Phase 45 — Unified Key + FIDO2 + Cross-Platform USB 系统设计
版本: v1.0.0 创建日期: 2026-02-27 状态: ✅ 已实现 (v1.1.0-alpha)
一、模块概述
Phase 45 引入统一密钥管理系统,支持 BIP-32 分层确定性密钥派生、FIDO2/WebAuthn 无密码认证、跨平台 USB 通信。
1.1 核心目标
- BIP-32 密钥派生: 单一主密钥派生无限子密钥,用途隔离
- FIDO2/WebAuthn: W3C 标准无密码认证,Passkey 支持
- 跨平台 USB: Windows/macOS/Linux 统一 USB 通信层
- 驱动扩展: 5个新驱动类型 (FIDO2/BIP32/TPM2/TEE/Satellite)
1.2 技术架构
┌──────────────────────────────────────────────────────┐
│ Application Layer │
│ - Authentication - Signing - Encryption │
└───────────────────────┬──────────────────────────────┘
│
┌───────────────────────┼──────────────────────────────┐
│ ▼ │
│ ┌─────────────────────────────────────────────┐ │
│ │ Unified Key Manager (BIP-32) │ │
│ │ - Master Key (m/) │ │
│ │ - Purpose Keys (m/44'/0'/0') │ │
│ │ - Signing (m/44'/0'/0'/0) │ │
│ │ - Encryption (m/44'/0'/0'/1) │ │
│ │ - Authentication (m/44'/0'/0'/2) │ │
│ └─────────────────────────────────────────────┘ │
│ │ │
│ ┌─────────────────────────────────────────────┐ │
│ │ FIDO2 Authenticator (WebAuthn) │ │
│ │ - CTAP2 Protocol │ │
│ │ - Passkey (Resident Keys) │ │
│ │ - UV (User Verification) / UP (User Present)│ │
│ └─────────────────────────────────────────────┘ │
│ │ │
│ ┌─────────────────────────────────────────────┐ │
│ │ USB Transport Layer │ │
│ │ - Windows: node-usb (libusb-win32) │ │
│ │ - macOS: IOKit (via Koffi FFI) │ │
│ │ - Linux: libusb │ │
│ └─────────────────────────────────────────────┘ │
│ │ │
│ ┌─────────────────────────────────────────────┐ │
│ │ WebUSB Fallback (Browser) │ │
│ │ - navigator.usb API │ │
│ │ - Device Request/Permission │ │
│ └─────────────────────────────────────────────┘ │
└──────────────────────┬───────────────────────────────┘
│
┌──────────────────────┼───────────────────────────────┐
│ ▼ │
│ Hardware (USB Devices) │
│ - U-Key - YubiKey - SIM Card - TPM │
└──────────────────────────────────────────────────────┘二、核心模块设计
2.1 Unified Key Manager (BIP-32)
文件: desktop-app-vue/src/main/ukey/unified-key-manager.js
BIP-32 派生路径:
m/44'/0'/0'/0/i- 签名密钥 (i = 子密钥索引)m/44'/0'/0'/1/i- 加密密钥m/44'/0'/0'/2/i- 认证密钥
功能:
- 主密钥生成 (256-bit熵)
- 子密钥派生 (hardened + non-hardened)
- 密钥导出/导入 (加密存储)
- 密钥轮换 (定期更新)
API:
class UnifiedKeyManager {
async generateMasterKey(password) // 生成主密钥
async derivePurposeKey(purpose, index = 0) // 派生用途密钥
async exportKey(keyId, password) // 导出密钥
async importKey(encryptedKey, password) // 导入密钥
async rotateKey(keyId) // 密钥轮换
async listKeys() // 列出密钥
async deleteKey(keyId) // 删除密钥
}2.2 FIDO2 Authenticator
文件: desktop-app-vue/src/main/ukey/fido2-authenticator.js
支持功能:
- MakeCredential: 创建凭证 (注册)
- GetAssertion: 获取断言 (认证)
- Resident Keys: 可驻留密钥 (Passkey)
- UV/UP: 用户验证/用户在场
CTAP2 命令:
0x01- authenticatorMakeCredential0x02- authenticatorGetAssertion0x04- authenticatorGetInfo0x06- authenticatorClientPIN
API:
class FIDO2Authenticator {
async makeCredential(rpId, userHandle, challenge) // 创建凭证
async getAssertion(rpId, challenge) // 获取断言
async getInfo() // 获取设备信息
async setClientPIN(newPIN) // 设置PIN
async changeClientPIN(currentPIN, newPIN) // 修改PIN
async listResidentKeys() // 列出Resident Keys
}2.3 USB Transport Layer
文件: desktop-app-vue/src/main/ukey/usb-transport.js
平台适配:
- Windows:
node-usb(libusb-win32) - macOS:
IOKit(via Koffi FFI) - Linux:
libusb
功能:
- 设备枚举 (vendorId/productId过滤)
- 批量传输 (Bulk Transfer)
- APDU封装 (ISO 7816-4)
- 超时控制 (5s默认)
API:
class USBTransport {
async listDevices(filters = {}) // 列出USB设备
async open(deviceId) // 打开设备
async close() // 关闭设备
async sendAPDU(apdu) // 发送APDU命令
async bulkTransfer(data) // 批量传输
async interruptTransfer(data) // 中断传输
}2.4 WebUSB Fallback
文件: desktop-app-vue/src/main/ukey/webusb-fallback.js
功能:
- 浏览器
navigator.usbAPI - 设备请求 (
requestDevice()) - 权限管理 (用户授权)
- vendorId/productId过滤
API:
class WebUSBFallback {
async isAvailable() // 检查WebUSB可用性
async requestDevice(filters) // 请求设备访问
async open(device) // 打开设备
async send(data) // 发送数据
async receive(length) // 接收数据
}三、数据库设计
3.1 unified_keys (统一密钥)
CREATE TABLE IF NOT EXISTS unified_keys (
id INTEGER PRIMARY KEY AUTOINCREMENT,
key_id TEXT NOT NULL UNIQUE,
purpose TEXT NOT NULL, -- signing/encryption/authentication
derivation_path TEXT NOT NULL, -- e.g. m/44'/0'/0'/0/0
public_key TEXT NOT NULL,
encrypted_private_key TEXT NOT NULL, -- AES-256
algorithm TEXT DEFAULT 'Ed25519',
created_at INTEGER NOT NULL,
rotated_at INTEGER,
expires_at INTEGER,
INDEX idx_unified_keys_purpose (purpose),
INDEX idx_unified_keys_created_at (created_at)
);3.2 fido2_credentials (FIDO2凭证)
CREATE TABLE IF NOT EXISTS fido2_credentials (
id INTEGER PRIMARY KEY AUTOINCREMENT,
credential_id TEXT NOT NULL UNIQUE,
rp_id TEXT NOT NULL, -- Relying Party ID
user_handle TEXT NOT NULL,
public_key TEXT NOT NULL,
sign_count INTEGER DEFAULT 0,
aaguid TEXT, -- Authenticator Attestation GUID
created_at INTEGER NOT NULL,
last_used_at INTEGER,
INDEX idx_fido2_credentials_rp_id (rp_id),
INDEX idx_fido2_credentials_user_handle (user_handle)
);四、IPC 接口设计
文件: desktop-app-vue/src/main/ukey/ukey-ipc.js (扩展)
4.1 统一密钥 IPC (3个)
ukey:generate-master-key- 生成主密钥ukey:derive-purpose-key- 派生用途密钥ukey:rotate-key- 密钥轮换
4.2 FIDO2 IPC (3个)
ukey:fido2-make-credential- 创建凭证ukey:fido2-get-assertion- 获取断言ukey:fido2-list-credentials- 列出凭证
4.3 USB设备管理 IPC (2个)
ukey:usb-list-devices- 列出USB设备ukey:usb-send-apdu- 发送APDU命令
五、驱动扩展
文件: desktop-app-vue/src/main/ukey/driver-registry.js
新增5个驱动类型:
- FIDO2Driver: FIDO2/WebAuthn设备
- BIP32Driver: BIP-32密钥派生设备
- TPM2Driver: TPM 2.0可信平台模块
- TEEDriver: 可信执行环境 (ARM TrustZone/Intel SGX)
- SatelliteSIMDriver: 卫星SIM卡驱动 (Phase 40扩展)
六、配置选项
unifiedKey: {
enabled: true,
bip32: {
coinType: 0, // BIP-44 coin type
accountIndex: 0,
passwordProtected: true
},
fido2: {
rpId: "chainlesschain.local",
rpName: "ChainlessChain",
timeout: 30000, // 30s
userVerification: "preferred" // required/preferred/discouraged
},
usb: {
vendorIds: [0x1050, 0x096e], // YubiKey, Feitian
reconnectAttempts: 3,
reconnectDelay: 1000 // ms
}
}七、使用场景
7.1 BIP-32 密钥派生
const keyManager = getUnifiedKeyManager();
// 生成主密钥
await keyManager.generateMasterKey("strong-password");
// 派生签名密钥
const signingKey = await keyManager.derivePurposeKey("signing", 0);
// 使用密钥签名
const signature = await signingKey.sign(message);7.2 FIDO2 无密码认证
const fido2 = getFIDO2Authenticator();
// 注册阶段
const credential = await fido2.makeCredential(
"example.com",
userHandle,
challenge,
);
// 认证阶段
const assertion = await fido2.getAssertion("example.com", challenge);7.3 USB 设备通信
const usb = getUSBTransport();
// 列出设备
const devices = await usb.listDevices({
vendorId: 0x1050, // YubiKey
});
// 打开设备
await usb.open(devices[0].deviceId);
// 发送APDU
const response = await usb.sendAPDU([0x00, 0xa4, 0x04, 0x00]);八、安全考虑
- 主密钥保护: 使用PBKDF2 (100,000迭代) + AES-256加密
- Hardened派生: BIP-32使用hardened派生路径 (')
- PIN保护: FIDO2 PIN使用BCrypt哈希存储
- APDU验证: USB命令使用CRC校验
- 设备白名单: 仅允许已知vendorId/productId
九、测试覆盖
- ✅
unified-key-manager.test.js- BIP-32密钥派生 - ✅
fido2-authenticator.test.js- FIDO2认证流程 - ✅
usb-transport.test.js- USB通信层 - ✅
webusb-fallback.test.js- WebUSB回退
十、性能指标
| 指标 | 目标 | 实际 |
|---|---|---|
| 密钥派生延迟 | <50ms | ~30ms |
| FIDO2 MakeCredential | <500ms | ~400ms |
| FIDO2 GetAssertion | <300ms | ~250ms |
| USB APDU 往返 | <100ms | ~80ms |
十一、Phase 46 — Threshold Signatures + Biometric
新增模块 (v1.1.0-alpha Phase 46):
11.1 Threshold Signature Manager (threshold-signature-manager.js)
核心功能:
- Shamir秘密共享: (k, n)门限方案,默认(2, 3)
- 主密钥分片: 将BIP-32主密钥分割为多个份额
- 分布式签名: 收集门限份额重建临时密钥进行签名
- 份额元数据: 持有者DID、创建时间、过期时间
- 份额删除: 安全销毁份额数据
数据库表 (threshold_key_shares):
CREATE TABLE threshold_key_shares (
share_id TEXT PRIMARY KEY,
key_id TEXT NOT NULL,
threshold INTEGER NOT NULL,
holder_did TEXT NOT NULL,
encrypted_share TEXT NOT NULL,
created_at INTEGER NOT NULL
);IPC接口 (4个):
threshold:split-key- 分割主密钥threshold:reconstruct-key- 重建密钥threshold:list-shares- 查询份额列表threshold:delete-share- 删除份额
11.2 Biometric Binding (biometric-binding.js)
核心功能:
- TEE集成: 可信执行环境(Trusted Execution Environment)
- 生物特征模板哈希: SHA-256指纹/人脸模板哈希
- 设备指纹: 硬件唯一标识符绑定
- UV验证: User Verification (PIN + Biometric)
- UP验证: User Presence (物理触摸)
- 绑定生命周期: 创建/验证/撤销/续期
数据库表 (biometric_bindings):
CREATE TABLE biometric_bindings (
binding_id TEXT PRIMARY KEY,
key_id TEXT NOT NULL,
template_hash TEXT NOT NULL,
device_fingerprint TEXT NOT NULL,
uv_required INTEGER DEFAULT 1,
created_at INTEGER NOT NULL
);IPC接口 (4个):
biometric:create-binding- 创建生物绑定biometric:verify-binding- 验证生物特征biometric:list-bindings- 查询绑定列表biometric:revoke-binding- 撤销绑定
11.3 前端集成
Pinia Store (stores/thresholdSecurity.ts):
- State:
shares: ThresholdShare[],bindings: BiometricBinding[] - Actions:
splitKey(),reconstructKey(),createBinding(),verifyBiometric()
UI页面 (pages/security/ThresholdSecurityPage.vue):
- 份额可视化图表(持有者分布、门限状态)
- 生物绑定配置面板
- 安全等级设置(2-of-3 / 3-of-5 / 5-of-7)
十二、Phase 47 — BLE U-Key
新增模块 (v1.1.0-alpha Phase 47):
12.1 Extended BLE Driver (ble-driver.js)
核心功能:
- GATT服务发现: 自动扫描Generic Attribute Profile服务
- 自动重连机制: 断线后指数退避重连(1s → 2s → 4s → 8s)
- 单例模式: 全局唯一BLE管理器实例
- RSSI监控: 接收信号强度指示器(Received Signal Strength Indicator)
- 连接状态管理: DISCONNECTED / CONNECTING / CONNECTED / ERROR
服务UUID:
- 主服务:
0000FE00-0000-1000-8000-00805F9B34FB - 特征(Characteristic):
- 读取:
0000FE01-...(READ, NOTIFY) - 写入:
0000FE02-...(WRITE, WRITE_NO_RESPONSE)
- 读取:
IPC接口 (4个):
ble:scan-devices- 扫描附近BLE设备ble:connect-device- 连接指定设备ble:disconnect-device- 断开连接ble:get-connection-status- 查询连接状态
12.2 Extended Driver Registry (driver-registry.js)
新增驱动类型:
BLE_UKEY: 蓝牙U盾驱动
健康检查:
- 蓝牙适配器状态(启用/禁用)
- 设备连接状态
- RSSI信号强度(<-70dBm警告)
12.3 前端集成
Pinia Store (stores/bleUkey.ts):
- State:
devices: BLEDevice[],connectedDevice: BLEDevice | null,rssi: number - Actions:
scanDevices(),connectDevice(),disconnectDevice(),monitorSignal()
UI页面 (pages/security/BLEDevicesPage.vue):
- 设备扫描列表(设备名、MAC地址、RSSI)
- 配对流程向导
- 连接监控仪表板(信号强度图表、连接时长)
十三、Phase 52 — 后量子密码迁移 (Post-Quantum Cryptography)
实现时间: 2026-02-27 (Q4 2026) 状态: ✅ 已实现 (v1.1.0-alpha)
13.1 PQC Migration Manager
文件: desktop-app-vue/src/main/ukey/pqc-migration-manager.js
后量子密码算法 (NIST标准):
ML-KEM (Module-Lattice-Based Key-Encapsulation Mechanism)
- 格基密钥封装机制
- 3种安全级别: ML-KEM-512 / ML-KEM-768 / ML-KEM-1024
- 抗量子攻击安全强度: 128/192/256-bit
ML-DSA (Module-Lattice-Based Digital Signature Algorithm)
- 格基数字签名算法
- 3种安全级别: ML-DSA-44 / ML-DSA-65 / ML-DSA-87
- 签名大小: 2420 / 3309 / 4627 bytes
混合加密模式:
- PQC + 经典算法:
ML-KEM-768 + ECDH-P256或ML-DSA-65 + ECDSA-P256 - 向后兼容: 支持经典算法降级
- 双重签名: PQC签名 + 经典签名同时验证
核心功能:
class PQCMigrationManager {
async listPQCKeys() // 列出后量子密钥
async generatePQCKey(algorithm, securityLevel) // 生成PQC密钥
async getMigrationStatus() // 获取迁移状态
async executeMigration(plan) // 执行迁移计划
async createMigrationPlan() // 创建迁移计划
async assessRisk(keyId) // 风险评估
async rotateToHybrid(keyId) // 轮换为混合模式
}迁移计划执行:
- 批量密钥轮换: 按优先级分批迁移
- 风险评估: 识别高风险密钥(短密钥长度、弱算法)
- 进度追踪: 实时监控迁移状态(total_keys, migrated_keys, current_step)
- 回滚支持: 保留经典密钥备份
13.2 数据库设计
pqc_keys表:
CREATE TABLE pqc_keys (
key_id TEXT PRIMARY KEY,
algorithm TEXT NOT NULL, -- ML-KEM-768, ML-DSA-65
public_key BLOB NOT NULL,
encrypted_private_key BLOB NOT NULL,
hybrid_mode INTEGER DEFAULT 1, -- 1=hybrid, 0=pure PQC
created_at INTEGER NOT NULL
)pqc_migration_status表:
CREATE TABLE pqc_migration_status (
migration_id TEXT PRIMARY KEY,
plan TEXT NOT NULL, -- JSON: {steps, priority, schedule}
status TEXT DEFAULT 'pending', -- pending/in_progress/completed/failed
current_step INTEGER DEFAULT 0,
total_keys INTEGER NOT NULL,
migrated_keys INTEGER DEFAULT 0,
started_at INTEGER,
completed_at INTEGER
)13.3 IPC接口
PQC IPC (ukey/pqc-ipc.js) - 4个处理器:
ipcMain.handle('ukey:list-pqc-keys', async () => { ... })
ipcMain.handle('ukey:generate-pqc-key', async (event, { algorithm, securityLevel }) => { ... })
ipcMain.handle('ukey:get-migration-status', async () => { ... })
ipcMain.handle('ukey:execute-migration', async (event, { plan }) => { ... })13.4 前端集成
Pinia Store (stores/pqcMigration.ts):
export const usePQCMigrationStore = defineStore('pqcMigration', {
state: () => ({
keys: [] as PQCKey[],
migrationStatus: null as MigrationStatus | null,
algorithms: ['ML-KEM-768', 'ML-DSA-65'],
}),
actions: {
async fetchKeys() { ... },
async generateKey(algorithm: string) { ... },
async startMigration(plan: MigrationPlan) { ... },
async checkProgress() { ... },
}
})UI页面 (pages/security/PQCMigrationPage.vue):
- 算法对比表(ML-KEM vs RSA, ML-DSA vs ECDSA)
- 迁移计划向导(密钥筛选、批次划分、时间表)
- 进度监控仪表板(进度条、已迁移/总数、预计剩余时间)
- 兼容性检查(检测依赖项、验证签名格式)
十四、Phase 53 — 固件空中升级 (Firmware OTA)
实现时间: 2026-02-27 (Q4 2026) 状态: ✅ 已实现 (v1.1.0-alpha)
14.1 Firmware OTA Manager
文件: desktop-app-vue/src/main/ukey/firmware-ota-manager.js
固件版本检查:
- 服务器版本查询 (HTTP GET
/api/firmware/latest) - 增量更新检测 (语义版本比较: semver)
- 强制更新标记 (critical security patches)
OTA下载:
- 分块传输: 1MB chunk size, 断点续传
- 进度回调:
onProgress(bytesDownloaded, totalBytes) - 校验和验证: SHA-256文件哈希
签名验证:
- Ed25519数字签名: 512-bit签名
- 公钥预置: 固件发布者公钥内嵌于应用
- 防篡改: 签名不匹配拒绝安装
自动安装:
class FirmwareOTAManager {
async checkForUpdates() // 检查更新
async downloadFirmware(versionId, onProgress) // 下载固件
async verifySignature(filePath, signature) // 验证签名
async installFirmware(filePath) // 安装固件
async listVersions() // 列出版本历史
async rollback(versionId) // 回滚到指定版本
async getUpdateHistory() // 获取更新历史
}安装流程:
- 下载固件包 → 2. 验证签名 → 3. 备份当前版本 → 4. 刷写固件 → 5. 设备重启 → 6. 版本确认
回滚机制:
- 版本历史管理: 保留最近3个固件版本
- 一键回滚:
rollback(previousVersionId) - 自动恢复: 安装失败自动回滚到上一稳定版本
14.2 数据库设计
firmware_versions表:
CREATE TABLE firmware_versions (
version_id TEXT PRIMARY KEY,
version_string TEXT NOT NULL, -- e.g., "2.3.1"
release_notes TEXT,
download_url TEXT NOT NULL,
signature TEXT NOT NULL, -- Ed25519 signature (hex)
file_hash TEXT NOT NULL, -- SHA-256 (hex)
released_at INTEGER NOT NULL
)firmware_update_log表:
CREATE TABLE firmware_update_log (
log_id TEXT PRIMARY KEY,
version_id TEXT NOT NULL,
device_id TEXT NOT NULL,
status TEXT DEFAULT 'pending', -- pending/downloading/verifying/installing/completed/failed
progress INTEGER DEFAULT 0, -- 0-100%
error_message TEXT,
started_at INTEGER,
completed_at INTEGER
)14.3 IPC接口
Firmware OTA IPC (ukey/firmware-ota-ipc.js) - 4个处理器:
ipcMain.handle('ukey:check-firmware-updates', async () => { ... })
ipcMain.handle('ukey:list-firmware-versions', async () => { ... })
ipcMain.handle('ukey:start-firmware-update', async (event, { versionId }) => { ... })
ipcMain.handle('ukey:get-firmware-update-history', async () => { ... })14.4 前端集成
Pinia Store (stores/firmwareOta.ts):
export const useFirmwareOtaStore = defineStore('firmwareOta', {
state: () => ({
versions: [] as FirmwareVersion[],
currentVersion: '2.2.0',
updateProgress: 0,
updateStatus: 'idle' as UpdateStatus,
history: [] as UpdateLog[],
}),
actions: {
async checkUpdates() { ... },
async startUpdate(versionId: string) { ... },
async rollbackVersion(versionId: string) { ... },
async fetchHistory() { ... },
}
})UI页面 (pages/security/FirmwareOTAPage.vue):
- 版本对比卡片(当前版本 vs 最新版本, 发布日期, 文件大小)
- 更新日志查看器(Markdown渲染, 新增功能/修复/安全补丁分类)
- 进度条组件(下载进度、验证状态、安装阶段)
- 回滚操作按钮(版本列表, 确认对话框, 回滚进度)
- 自动更新配置(开关、检查间隔、仅WiFi下载)
十五、未来扩展
- [ ] NFC传输: 支持NFC近场通信
- [x] 蓝牙LE: BLE低功耗蓝牙传输 ✅ Phase 47
- [ ] HSM集成: 硬件安全模块集成
- [ ] Multi-Device Sync: Passkey跨设备同步
- [x] Biometric Authentication: 生物识别集成 ✅ Phase 46
- [x] Quantum-Resistant Upgrade: 后量子密码学升级(ML-KEM/ML-DSA) ✅ Phase 52
- [x] Firmware OTA: 固件空中升级 ✅ Phase 53
- [ ] SLH-DSA: Stateless Hash-Based Signatures (第三种NIST PQC算法)
- [ ] Secure Boot: 固件启动签名验证
文档版本: 1.2.0 最后更新: 2026-02-27
