Matrix-JS-SDK 中 E2EE 重置后跨设备签名初始化问题分析

在基于 Matrix-JS-SDK 开发端到端加密应用时，开发者可能会遇到一个特定场景下的加密初始化问题：当用户通过 Element Web 执行完整的端到端加密重置操作（"Reset all"）并生成新的恢复密钥后，在自定义客户端应用中尝试通过 bootstrapCrossSigning() 初始化跨设备签名时，SDK 会抛出 App returned unknown key from getSecretStorageKey! 错误。

问题本质

这个问题的核心在于密钥回调函数的返回值格式不符合 SDK 预期。当 Matrix 客户端需要访问密钥存储（Secret Storage）时，会调用开发者提供的 getSecretStorageKey 回调函数。在跨设备签名初始化过程中，SDK 期望获取的不仅是对应的加密密钥，还包括该密钥的元数据标识。

技术细节解析

1. 密钥存储机制： Matrix 使用分层加密存储系统（SSSS）来保护用户的加密密钥。重置操作会生成全新的存储密钥和恢复密钥，这些密钥通过 PBKDF2 算法派生，并采用 AES-HMAC-SHA2 加密方案。

2. 回调函数要求： 正确的回调实现应该返回一个包含两个元素的数组：

   • 第一个元素是实际的密钥数据（Uint8Array 格式）
   • 第二个元素是密钥标识符对象（包含算法等元数据）

3. 常见错误模式： 开发者容易犯的错误包括：

   • 仅返回密钥数据而缺少元数据
   • 返回 Map 对象而非数组
   • 对 Base64 解码处理不当

解决方案

正确的回调实现应遵循以下模式：

async function getSecretStorageKey(keyId) {
  // 获取用户输入的恢复密钥
  const userInput = await promptForRecoveryKey();
  
  // 处理密钥格式（移除空格等）
  const processedKey = processKeyInput(userInput);
  
  // Base64 解码
  const keyData = decodeBase64ToUint8Array(processedKey);
  
  // 返回包含密钥数据和元数据的数组
  return [
    keyData,
    {
      name: 'm.secret_storage.v1.aes-hmac-sha2',
      algorithm: 'm.secret_storage.v1.aes-hmac-sha2'
    }
  ];
}

最佳实践建议

1. 密钥处理：

   • 确保正确处理用户输入中的空格和格式
   • 使用标准 Base64 解码方法
   • 验证解码后的密钥长度是否符合预期

2. 错误处理：

   • 添加对用户输入格式的验证
   • 捕获并处理解码过程中的异常
   • 提供清晰的用户提示信息

3. 调试技巧：

   • 在开发阶段记录完整的回调参数
   • 验证返回值的结构和类型
   • 比较 Element Web 的行为作为参考

总结

这个问题典型地展示了 Matrix 加密系统中密钥管理的重要性。开发者需要严格遵循 SDK 的接口规范，特别是在处理加密相关操作时。理解 Matrix 的分层密钥存储架构和跨设备签名机制，有助于构建更健壮的加密应用。当遇到类似问题时，仔细检查回调函数的返回值格式通常是解决问题的第一步。

对于更复杂的场景，建议深入研究 Matrix 的加密白皮书，全面理解其密钥派生、存储和使用的完整流程，这将有助于预防和解决各类加密相关的问题。