zyw-encrypt

安全的端到端加密管理库，提供密钥管理和数据安全存储功能。

功能特点

• 🔐 跨平台兼容的多种加密算法支持（RSA、AES-GCM、ECDH）
• 🛡️ 浏览器和服务器端专用实现
• 📝 端到端加密消息传输与数据保护
• 🔑 WebAuthn/Passkey高级身份验证集成
• 💾 多级缓存密钥安全存储
• 📱 完整的密钥生命周期管理

安装

npm install zyw-encrypt
# 或
yarn add zyw-encrypt
# 或
pnpm add zyw-encrypt

核心组件

ZYWEncrypt - 通用加密基类

import { ZYWEncrypt } from 'zyw-encrypt';

const encrypt = new ZYWEncrypt({ enabled: true });
await encrypt.initialize('user123');

主要功能:

• 提供RSA加密/解密、签名验证
• 提供AES-GCM加密/解密
• 支持ECDH密钥交换
• Base64编码/解码工具
• 基于用户ID的密钥派生
• 高级数据加密/解密工作流

主要方法:

• • initialize(userId?): 初始化加密服务
• • reset(): 重置加密服务状态
• • generateAESKey(): 生成随机AES密钥和初始化向量
• • aesEncrypt(data, key, iv): 使用AES-GCM加密数据
• • aesDecrypt(encryptedData, key, iv): 使用AES-GCM解密数据
• • importAESKey(keyBase64): 导入AES密钥
• • deriveKeyFromUserId(salt, keyLength): 从用户ID派生密钥
• • toBase64(buffer): 将ArrayBuffer转换为Base64字符串
• • fromBase64(base64): 将Base64字符串转换为Uint8Array
• • stringToArrayBuffer(str): 将字符串转换为ArrayBuffer
• • generateRSAKeyPair(modulusLength): 生成RSA密钥对
• • rsaEncrypt(data, publicKeyBase64): 使用RSA公钥加密数据
• • rsaDecrypt(encryptedData, privateKeyBase64): 使用RSA私钥解密数据
• • generateDHKeyPair(): 生成ECDH密钥对
• • signData(data, privateKeyBase64): 使用私钥对数据签名
• • verifySignature(data, signature, publicKeyBase64): 验证数据签名
• • encrypt(data, publicKey?, aesKey?): 高级加密方法
• • decrypt(encryptedResult, privateKey?, aesKey?): 高级解密方法
• • verify(data, signature, publicKey): 验证数据签名

ZYWEncryptClient - 客户端加密组件

import { ZYWEncryptClient } from 'zyw-encrypt';

const client = new ZYWEncryptClient();
await client.initialize('user123');
const keyPair = await client.generateDHKeyPair();

主要功能:

• 客户端RSA密钥对生成和管理
• ECDH密钥交换与共享密钥派生
• 安全密钥存储与检索
• PEM格式密钥支持
• 浏览器WebCrypto API集成

主要方法:

• • initialize(userId?): 初始化客户端加密服务
• • generateRSAKeyPair(): 生成客户端RSA密钥对，适配PEM格式
• • generateDHKeyPair(): 生成ECDH密钥对
• • deriveSharedSecret(otherPublicKeyBase64): 使用对方公钥和自己私钥生成共享密钥
• • loadKeysFromStorage(): 从存储中加载密钥
• • storeKeys(): 将密钥存储到安全存储
• • formatBase64(base64String): 格式化Base64字符串，添加换行符
• • importECDHPrivateKeyFromBase64(privateKeyBase64): 导入ECDH私钥
• • importECDHPublicKeyFromBase64(publicKeyBase64): 导入ECDH公钥
• • exportECDHPrivateKeyToBase64(privateKey): 导出ECDH私钥
• • saveKeysToStorage(): 保存密钥到存储

ZYWKeysStorage - 密钥安全存储

import { ZYWKeysStorage } from 'zyw-encrypt';

const storage = new ZYWKeysStorage('user123', true);
await storage.storeKey('appKey', secretValue, { encrypt: true });

主要功能:

• 密钥安全存储和检索
• 基于用户ID的密钥隔离
• AES-GCM加密保护存储的敏感密钥
• 多级缓存策略(内存+localStorage)
• 密钥元数据管理
• 密钥导入导出功能

主要方法:

• • constructor(userId, useEncryption): 构造函数
• • getEncryptionKey(): 获取用于加密其他密钥的派生密钥
• • getKeyMaterial(): 获取密钥材料
• • getFullKeyName(keyName): 生成完整的键名
• • storeKey(keyName, value, options): 存储密钥
• • getKey(keyName): 获取密钥
• • decryptKeyIfNeeded(storedKey): 如需要，解密存储的密钥
• • removeKey(keyName): 删除密钥
• • listKeys(): 列出所有存储的密钥名称
• • clearKeys(): 清除所有存储的密钥
• • setUserId(userId): 设置用户ID
• • exportKeys(includeEncrypted): 导出所有密钥
• • importKeys(exportedKeys): 导入密钥

ZYWEncryptServer - 服务器端加密组件

import { ZYWEncryptServer } from 'zyw-encrypt';

const server = new ZYWEncryptServer({
  enabled: true,
  keyStorage: myKeyStorageService
});
await server.initialize('user123');

主要功能:

• 服务器端RSA密钥对生成和管理
• 服务器端Diffie-Hellman密钥交换
• 密钥持久化存储（通过密钥存储服务接口）
• 数据签名和验证
• 用户特定密钥隔离

主要方法:

• • initialize(userId?): 初始化服务器加密服务
• • loadOrGenerateRSAKeys(): 加载或生成RSA密钥对
• • loadOrGenerateAESKey(): 加载或生成AES密钥
• • generateDHKeyPair(): 生成DH密钥对
• • getServerDHKeyPair(): 获取服务器完整DH密钥对(含素数和生成器)
• • computeDHSharedKey(myKeyPair, otherPublicKey): 计算DH共享密钥
• • getPublicKey(): 获取服务器公钥
• • decryptWithServerKey(encryptedData): 使用服务器私钥解密数据
• • signWithServerKey(data): 使用服务器私钥签名数据

ZYWClientControl - 客户端密钥控制器

import { ZYWClientControl } from 'zyw-encrypt';

const control = new ZYWClientControl({
  enablePasskey: true,
  appName: '我的应用'
});
await control.initialize('user123');

主要功能:

• WebAuthn/Passkey集成
• 敏感数据的端到端加密
• 密钥哈希派生和管理
• 多级密钥存储策略
• 客户端状态管理

主要方法:

• • initialize(userId): 初始化客户端控制器
• • hasPasskey(): 检查是否已注册Passkey
• • registerPasskey(username?): 注册新的Passkey
• • verifyPasskey(): 验证并获取Passkey
• • encryptSensitiveData(data): 加密敏感数据
• • decryptSensitiveData(encryptedData): 解密敏感数据
• • getStatus(): 获取客户端加密状态
• • hasValidKey(): 检查是否有有效的用户密钥
• • deriveKeyHashFromPasskey(response): 从Passkey响应派生密钥哈希
• • deriveKeyHashFromPasskeyAssertion(response): 从Passkey验证响应派生密钥哈希
• • generateRandomKeyHash(): 生成随机密钥哈希
• • generateChallenge(): 生成随机挑战
• • getEncryptClient(): 获取加密客户端实例
• • getKeysStorage(): 获取密钥存储实例

应用场景示例

客户端-服务器安全通信

// 客户端
const client = new ZYWEncryptClient();
await client.initialize('alice');
const clientKeyPair = await client.generateDHKeyPair();

// 将公钥发送到服务器
await sendToServer('/api/keys/exchange', { publicKey: clientKeyPair.publicKey });

// 收到服务器公钥后，派生共享密钥
const serverPublicKey = await fetchFromServer('/api/keys/public');
const sharedSecret = await client.deriveSharedSecret(serverPublicKey);

// 使用共享密钥加密敏感数据
const encryptedData = await client.encrypt(
  { message: '这是机密信息' },
  undefined,
  sharedSecret
);

// 发送加密数据到服务器
await sendToServer('/api/messages/secure', encryptedData);

// 服务器
const server = new ZYWEncryptServer({ keyStorage: dbKeyStorage });
await server.initialize('alice');

// 处理密钥交换请求
app.post('/api/keys/exchange', async (req, res) => {
  const { publicKey: clientPublicKey } = req.body;
  const serverKeyPair = await server.getServerDHKeyPair();
  
  // 存储客户端公钥
  await dbKeyStorage.storeKey('client_public', req.user.id, clientPublicKey);
  
  // 返回服务器公钥
  res.json({ publicKey: serverKeyPair.publicKey });
});

// 处理加密消息
app.post('/api/messages/secure', async (req, res) => {
  const encryptedData = req.body;
  const clientPublicKey = await dbKeyStorage.getKey('client_public', req.user.id);
  const serverKeyPair = await server.getServerDHKeyPair();
  
  // 计算共享密钥
  const sharedSecret = await server.computeDHSharedKey(
    serverKeyPair,
    clientPublicKey
  );
  
  // 解密数据
  const decryptedData = await server.decrypt(encryptedData, undefined, sharedSecret);
  
  // 处理解密后的数据
  console.log('收到安全消息:', decryptedData.message);
  res.json({ status: 'success' });
});

使用Passkey保护敏感数据

import { ZYWClientControl } from 'zyw-encrypt';

// 初始化控制器
const control = new ZYWClientControl({ 
  enablePasskey: true,
  appName: '保密文档应用'
});

// 登录后初始化
await control.initialize('user123');

// 检查是否需要注册Passkey
if (!(await control.hasPasskey())) {
  const registered = await control.registerPasskey('张三');
  if (registered) {
    showNotification('生物识别已设置，数据将受到更高级别保护');
  }
}

// 加密敏感文档
async function saveDocument(document) {
  try {
    // 加密文档内容
    const encrypted = await control.encryptSensitiveData(document);
    
    // 存储加密内容
    localStorage.setItem(`doc_${document.id}`, encrypted);
    
    return true;
  } catch (error) {
    console.error('保存文档失败:', error);
    return false;
  }
}

// 解密查看文档
async function openDocument(docId) {
  try {
    // 获取加密内容
    const encrypted = localStorage.getItem(`doc_${docId}`);
    if (!encrypted) return null;
    
    // 提示用户验证身份
    await showBiometricPrompt('请验证身份以查看文档');
    
    // 验证Passkey并解密
    if (await control.verifyPasskey()) {
      const document = await control.decryptSensitiveData(encrypted);
      return document;
    }
  } catch (error) {
    console.error('打开文档失败:', error);
    return null;
  }
}

安全最佳实践

• 在服务器端实现中，使用持久化密钥存储服务以保存用户密钥
• WebAuthn/Passkey应配置适当的userVerification策略以提高安全性
• 密钥存储应优先考虑更安全的选项，如安全飞地或HSM
• 实现密钥轮换机制以定期更新长期使用的密钥
• 敏感数据加密应使用混合加密方案，如RSA+AES
• 确保在传输加密密钥时使用安全信道

许可证

MIT