Skip to content

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 核心目标

  1. BIP-32 密钥派生: 单一主密钥派生无限子密钥,用途隔离
  2. FIDO2/WebAuthn: W3C 标准无密码认证,Passkey 支持
  3. 跨平台 USB: Windows/macOS/Linux 统一 USB 通信层
  4. 驱动扩展: 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:

javascript
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 - authenticatorMakeCredential
  • 0x02 - authenticatorGetAssertion
  • 0x04 - authenticatorGetInfo
  • 0x06 - authenticatorClientPIN

API:

javascript
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:

javascript
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.usb API
  • 设备请求 (requestDevice())
  • 权限管理 (用户授权)
  • vendorId/productId过滤

API:

javascript
class WebUSBFallback {
  async isAvailable() // 检查WebUSB可用性
  async requestDevice(filters) // 请求设备访问
  async open(device) // 打开设备
  async send(data) // 发送数据
  async receive(length) // 接收数据
}

三、数据库设计

3.1 unified_keys (统一密钥)

sql
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凭证)

sql
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个驱动类型:

  1. FIDO2Driver: FIDO2/WebAuthn设备
  2. BIP32Driver: BIP-32密钥派生设备
  3. TPM2Driver: TPM 2.0可信平台模块
  4. TEEDriver: 可信执行环境 (ARM TrustZone/Intel SGX)
  5. SatelliteSIMDriver: 卫星SIM卡驱动 (Phase 40扩展)

六、配置选项

javascript
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 密钥派生

javascript
const keyManager = getUnifiedKeyManager();

// 生成主密钥
await keyManager.generateMasterKey("strong-password");

// 派生签名密钥
const signingKey = await keyManager.derivePurposeKey("signing", 0);

// 使用密钥签名
const signature = await signingKey.sign(message);

7.2 FIDO2 无密码认证

javascript
const fido2 = getFIDO2Authenticator();

// 注册阶段
const credential = await fido2.makeCredential(
  "example.com",
  userHandle,
  challenge,
);

// 认证阶段
const assertion = await fido2.getAssertion("example.com", challenge);

7.3 USB 设备通信

javascript
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]);

八、安全考虑

  1. 主密钥保护: 使用PBKDF2 (100,000迭代) + AES-256加密
  2. Hardened派生: BIP-32使用hardened派生路径 (')
  3. PIN保护: FIDO2 PIN使用BCrypt哈希存储
  4. APDU验证: USB命令使用CRC校验
  5. 设备白名单: 仅允许已知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):

sql
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个):

  1. threshold:split-key - 分割主密钥
  2. threshold:reconstruct-key - 重建密钥
  3. threshold:list-shares - 查询份额列表
  4. 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):

sql
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个):

  1. biometric:create-binding - 创建生物绑定
  2. biometric:verify-binding - 验证生物特征
  3. biometric:list-bindings - 查询绑定列表
  4. 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个):

  1. ble:scan-devices - 扫描附近BLE设备
  2. ble:connect-device - 连接指定设备
  3. ble:disconnect-device - 断开连接
  4. 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标准):

  1. ML-KEM (Module-Lattice-Based Key-Encapsulation Mechanism)

    • 格基密钥封装机制
    • 3种安全级别: ML-KEM-512 / ML-KEM-768 / ML-KEM-1024
    • 抗量子攻击安全强度: 128/192/256-bit
  2. 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-P256ML-DSA-65 + ECDSA-P256
  • 向后兼容: 支持经典算法降级
  • 双重签名: PQC签名 + 经典签名同时验证

核心功能:

javascript
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表:

sql
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表:

sql
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个处理器:

javascript
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):

typescript
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签名
  • 公钥预置: 固件发布者公钥内嵌于应用
  • 防篡改: 签名不匹配拒绝安装

自动安装:

javascript
class FirmwareOTAManager {
  async checkForUpdates() // 检查更新
  async downloadFirmware(versionId, onProgress) // 下载固件
  async verifySignature(filePath, signature) // 验证签名
  async installFirmware(filePath) // 安装固件
  async listVersions() // 列出版本历史
  async rollback(versionId) // 回滚到指定版本
  async getUpdateHistory() // 获取更新历史
}

安装流程:

  1. 下载固件包 → 2. 验证签名 → 3. 备份当前版本 → 4. 刷写固件 → 5. 设备重启 → 6. 版本确认

回滚机制:

  • 版本历史管理: 保留最近3个固件版本
  • 一键回滚: rollback(previousVersionId)
  • 自动恢复: 安装失败自动回滚到上一稳定版本

14.2 数据库设计

firmware_versions表:

sql
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表:

sql
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个处理器:

javascript
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):

typescript
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

ChainlessChain 系统设计文档 — 面向开发者