1. 项目概述：为什么我们需要一个鸿蒙加解密工具箱？

在鸿蒙应用开发中，数据安全是一个绕不开的核心议题。无论是用户登录凭证的本地存储、敏感配置信息的保护，还是网络传输数据的防篡改，加解密都是保障应用安全基石的必备技术。然而，对于许多开发者，尤其是刚接触鸿蒙生态的伙伴来说，加解密功能的实现往往伴随着几个痛点：官方提供的加解密API（ @ohos.security.cryptoFramework ）功能强大但略显底层，直接使用需要处理密钥管理、算法模式、填充方式等一系列复杂参数；而网络上流传的JavaScript加解密库又未必能完美适配鸿蒙的ArkTS环境。

这正是“基于@ohos/crypto-js实现加解密工具箱”这个项目的价值所在。它瞄准的正是开发中的实际效率与安全需求。 @ohos/crypto-js 是OpenHarmony官方提供的一个密码学算法库，它封装了常见的对称加密（如AES）、非对称加密（如RSA）、散列算法（如SHA256）等，接口相对友好。本项目的目的，就是以此为基础，构建一个开箱即用、功能聚合、配置清晰的加解密工具集。它不是一个简单的API调用示例堆砌，而是一个经过实战检验的、包含完整密钥生命周期管理、多种算法场景适配以及详尽错误处理的解决方案。无论你是要快速实现一个“记住密码”功能，还是需要为应用间的数据交换提供安全通道，这个工具箱都能提供清晰的路径和可靠的代码片段，让你告别四处搜索和反复调试，把精力聚焦在业务逻辑本身。

2. 核心思路与架构设计

2.1 为什么选择 @ohos/crypto-js？

在鸿蒙生态中，进行加解密操作主要有两种官方途径：一是使用更底层的 @ohos.security.cryptoFramework ，它提供了完整的密钥生成、加密、解密流程，支持硬件级安全，但学习曲线陡峭；二是使用 @ohos/crypto-js 。后者可以看作是前者的一个轻量级、面向常见Web开发场景的封装。对于绝大多数应用层的数据保护需求——比如加密本地存储的token、计算文件的哈希值校验完整性、对API请求参数进行签名—— crypto-js 已经完全足够，且其API设计更接近前端开发者熟悉的 crypto-js 库，迁移和上手成本极低。

本工具箱选择 @ohos/crypto-js 作为基石，主要基于以下几点考量：

  1. 开发效率 ：它提供了诸如 CryptoJS.AES.encrypt(plainText, key, options) 这样高度封装的函数，一行代码即可完成加密，极大提升了开发速度。
  2. 功能覆盖 ：它涵盖了AES、DES、TripleDES、RC4、Rabbit等对称加密，以及MD5、SHA1、SHA256、SHA512等哈希算法，还有HMAC、PBKDF2等密钥派生函数，能满足90%以上的日常需求。
  3. 生态兼容 ：其数据格式（如Base64、Hex字符串）与后端及其他平台通用，便于数据交换。
  4. 官方维护 ：作为OpenHarmony官方库，其稳定性和与系统版本的兼容性有保障，避免了使用第三方库可能带来的潜在风险。

2.2 工具箱的整体架构设计

一个健壮的工具箱不应该只是几个孤立函数的集合。本项目的设计遵循“高内聚、低耦合”的原则，将功能模块化，并充分考虑实际应用场景。整体架构分为三层：

  1. 核心算法层 ：直接封装 @ohos/crypto-js 的原生API，提供最基础的加密、解密、哈希计算功能。这一层确保功能的纯粹性和正确性。
  2. 业务工具层 ：这是工具箱的主体。针对不同场景，提供更易用的工具函数。例如：
    • StorageCryptoUtil ：专门用于加密后存入 Preferences （轻量级存储）或 Database 的工具，自动处理序列化和反序列化。
    • NetworkCryptoUtil ：提供对URL参数、请求体进行对称加密，以及生成请求签名（HMAC）的工具。
    • FileHashUtil ：用于计算大型文件的哈希值，支持分块处理以避免内存溢出。
  3. 密钥管理层 ：这是安全的核心。设计一个统一的 KeyManager 类，负责密钥的生成、存储（使用系统安全的 keyStore 或加密后存 Preferences ）、轮换和销毁。绝对避免将硬编码的密钥写在代码中。

这样的架构使得工具箱不仅能用，而且好用、安全。开发者可以根据需求，直接引入业务工具层进行快速开发，而无需关心底层算法细节和密钥管理的复杂性。

注意 ： @ohos/crypto-js 主要处理的是字符串和 ArrayBuffer 数据。对于非常敏感或大量的数据，仍需评估是否使用 cryptoFramework 以获得硬件级安全或更高性能。

3. 环境准备与基础封装

3.1 项目初始化与依赖安装

首先，你需要一个鸿蒙应用工程。如果你还没有，可以使用DevEco Studio创建一个空的 Stage 模型项目。本工具箱主要适用于API 9及以上版本。

在项目的 entry 模块下的 oh-package.json5 文件中，添加 @ohos/crypto-js 依赖。

// entry/oh-package.json5
{
  "dependencies": {
    "@ohos/crypto-js": "^1.0.0" // 请检查并填写最新的版本号
  }
}

然后在终端中，进入 entry 目录，执行 ohpm install 命令来安装依赖。

cd entry
ohpm install

安装完成后，你就可以在代码中引入 crypto-js 了。通常，我们会在一个独立的工具类中进行统一引入和封装。

3.2 核心算法类的初步封装

我们创建一个核心的加密工具类 CryptoCore.ts ，作为所有加解密操作的基座。这里先实现最常用的AES对称加密和解密。

// utils/CryptoCore.ts
import cryptoJs from '@ohos/crypto-js';

export class CryptoCore {
  // 密钥，在实际项目中应由KeyManager动态获取，此处仅为示例
  private static readonly DEFAULT_AES_KEY = 'Your32ByteLongSecretKey00000'; // AES-256需要32字节

  /**
   * AES加密 (默认使用CBC模式，PKCS7填充)
   * @param plainText 明文
   * @param key 密钥字符串，长度需为16/24/32字节（对应AES-128/192/256）
   * @param iv 初始化向量，16字节。不传则使用默认值（仅用于演示，生产环境必须使用随机IV）
   * @returns 返回Base64格式的密文
   */
  static aesEncrypt(plainText: string, key: string = this.DEFAULT_AES_KEY, iv?: string): string {
    if (!plainText) {
      throw new Error('Plain text cannot be empty.');
    }
    // 将字符串密钥和IV转换为crypto-js需要的WordArray格式
    const keyWordArray = cryptoJs.enc.Utf8.parse(key);
    const ivWordArray = iv ? cryptoJs.enc.Utf8.parse(iv) : cryptoJs.enc.Utf8.parse('1234567890123456'); // 默认IV，仅示例！

    // 执行加密
    const encrypted = cryptoJs.AES.encrypt(plainText, keyWordArray, {
      iv: ivWordArray,
      mode: cryptoJs.mode.CBC, // 密码分组链接模式
      padding: cryptoJs.pad.Pkcs7 // 填充方式
    });

    // 将加密结果转换为Base64字符串
    return encrypted.toString();
  }

  /**
   * AES解密
   * @param cipherText Base64格式的密文
   * @param key 密钥字符串，必须与加密时使用的密钥一致
   * @param iv 初始化向量，必须与加密时使用的IV一致
   * @returns 解密后的明文
   */
  static aesDecrypt(cipherText: string, key: string = this.DEFAULT_AES_KEY, iv?: string): string {
    if (!cipherText) {
      throw new Error('Cipher text cannot be empty.');
    }
    const keyWordArray = cryptoJs.enc.Utf8.parse(key);
    const ivWordArray = iv ? cryptoJs.enc.Utf8.parse(iv) : cryptoJs.enc.Utf8.parse('1234567890123456');

    // 执行解密
    const decrypted = cryptoJs.AES.decrypt(cipherText, keyWordArray, {
      iv: ivWordArray,
      mode: cryptoJs.mode.CBC,
      padding: cryptoJs.pad.Pkcs7
    });

    // 将解密结果（WordArray）转换为UTF-8字符串
    return decrypted.toString(cryptoJs.enc.Utf8);
  }

  /**
   * 生成SHA256哈希
   * @param message 原始消息
   * @returns 十六进制字符串格式的哈希值
   */
  static sha256(message: string): string {
    return cryptoJs.SHA256(message).toString(cryptoJs.enc.Hex);
  }

  /**
   * 生成HMAC-SHA256签名
   * @param message 待签名的消息
   * @param secret 密钥
   * @returns 十六进制字符串格式的HMAC
   */
  static hmacSha256(message: string, secret: string): string {
    return cryptoJs.HmacSHA256(message, secret).toString(cryptoJs.enc.Hex);
  }
}

这个 CryptoCore 类提供了最基础的功能。但请注意，代码中将密钥和IV硬编码了，这在生产环境中是 绝对禁止的 。它只是为了演示API的用法。接下来，我们就要解决这个最关键的安全问题——密钥管理。

4. 密钥安全与管理策略

4.1 密钥管理的重要性与常见误区

密钥是加解密系统的“钥匙”，一旦泄露，所有加密数据形同虚设。在移动应用开发中，常见的错误做法包括：

  1. 硬编码在代码中 ：这是最危险的方式，应用一旦被反编译，密钥直接暴露。
  2. 存储在未加密的Preferences中 ：与硬编码无异。
  3. 从网络动态获取但不验证 ：可能遭受中间人攻击，获取到伪造的密钥。

在鸿蒙应用中，我们应利用系统提供的安全能力来保护密钥。

4.2 使用KeyStore管理密钥

对于需要最高安全级别的密钥（如用于加密用户核心数据的根密钥），推荐使用 @ohos.security.cryptoFramework 来生成并存入系统KeyStore。KeyStore是一个由系统保护的、用于存储密钥和证书的安全容器，其私钥部分通常难以被直接提取。

由于本工具箱主要基于 crypto-js ，而它本身不直接与KeyStore交互，我们可以设计一个混合方案：

  • 根密钥 (Root Key) ：使用 cryptoFramework 生成一个非对称密钥对（如RSA），私钥存入KeyStore。这个密钥 极少使用 ，仅用于加密/解密另一个密钥。
  • 数据加密密钥 (Data Key) ：使用 crypto-js 生成一个随机的AES密钥，用于实际的数据加解密。但这个AES密钥本身，会被上面的RSA公钥加密后，存储在应用的 Preferences 中。

每次应用启动时，用KeyStore中的RSA私钥解密出AES密钥，再交给 crypto-js 使用。这样，即使 Preferences 被窃取，没有KeyStore中的私钥也无法解密出AES密钥。

4.3 实现一个简单的混合密钥管理器

下面是一个简化版的 KeyManager 实现思路，它结合了 cryptoFramework 和 crypto-js ：

// utils/KeyManager.ts
import cryptoFramework from '@ohos.security.cryptoFramework';
import cryptoJs from '@ohos/crypto-js';
import preferences from '@ohos.data.preferences';

export class KeyManager {
  private static readonly RSA_KEY_ALIAS = 'my_app_rsa_key';
  private static readonly PREFS_KEY_ENCRYPTED_AES_KEY = 'encrypted_aes_key';
  private static preferences: preferences.Preferences | null = null;

  // 初始化，获取Preferences实例
  static async init(context: common.Context): Promise<void> {
    try {
      this.preferences = await preferences.getPreferences(context, 'crypto_toolbox');
    } catch (error) {
      console.error(`KeyManager init failed: ${JSON.stringify(error)}`);
    }
  }

  /**
   * 获取用于数据加密的AES密钥。
   * 策略：如果存在已加密存储的AES密钥，则用RSA私钥解密后返回。
   *       否则，生成新的AES密钥，用RSA公钥加密后存储，再返回。
   */
  static async getDataEncryptionKey(): Promise<string> {
    // 1. 尝试从Preferences读取已加密的AES密钥
    const encryptedAesKeyBase64 = await this.preferences?.get(this.PREFS_KEY_ENCRYPTED_AES_KEY, '');
    
    if (encryptedAesKeyBase64 && encryptedAesKeyBase64.length > 0) {
      // 2. 存在，则进行解密
      const rsaPrivateKey = await this.getRsaPrivateKey(); // 从KeyStore获取私钥
      const aesKey = await this.decryptWithRsaPrivateKey(encryptedAesKeyBase64, rsaPrivateKey);
      return aesKey;
    } else {
      // 3. 不存在，生成新的AES密钥（32字节，用于AES-256）
      const newAesKey = this.generateRandomAesKey();
      // 4. 获取RSA公钥并加密新生成的AES密钥
      const rsaPublicKey = await this.getRsaPublicKey();
      const encryptedAesKey = await this.encryptWithRsaPublicKey(newAesKey, rsaPublicKey);
      // 5. 存储加密后的AES密钥
      await this.preferences?.put(this.PREFS_KEY_ENCRYPTED_AES_KEY, encryptedAesKey);
      await this.preferences?.flush();
      return newAesKey;
    }
  }

  // --- 以下为内部辅助方法（简化示意，实际需处理完整异步流程和错误）---
  private static generateRandomAesKey(): string {
    // 使用crypto-js生成随机字节，并转换为Base64或Hex字符串
    const randomWordArray = cryptoJs.lib.WordArray.random(32); // 32字节
    return cryptoJs.enc.Base64.stringify(randomWordArray);
  }

  private static async getRsaKeyPair(): Promise<cryptoFramework.KeyPair> {
    // 使用cryptoFramework生成或获取RSA密钥对
    // 此处省略具体代码，涉及KeyStore的检查、生成、存取等复杂操作
    // 返回一个Promise<KeyPair>
  }

  private static async getRsaPublicKey(): Promise<cryptoFramework.PubKey> {
    const keyPair = await this.getRsaKeyPair();
    return keyPair.pubKey;
  }

  private static async getRsaPrivateKey(): Promise<cryptoFramework.PriKey> {
    const keyPair = await this.getRsaKeyPair();
    return keyPair.priKey;
  }

  private static async encryptWithRsaPublicKey(data: string, pubKey: cryptoFramework.PubKey): Promise<string> {
    // 使用cryptoFramework的RSA进行加密，返回Base64字符串
    // 省略具体代码
    return 'encrypted_base64_string';
  }

  private static async decryptWithRsaPrivateKey(encryptedDataBase64: string, priKey: cryptoFramework.PriKey): Promise<string> {
    // 使用cryptoFramework的RSA进行解密，返回原始字符串
    // 省略具体代码
    return 'decrypted_string';
  }
}

这个 KeyManager 提供了一个安全获取AES密钥的入口。在实际的 CryptoCore.aesEncrypt/Decrypt 中，密钥参数不应再硬编码，而是调用 KeyManager.getDataEncryptionKey() 来获取。

实操心得 ：密钥管理是安全中最复杂的一环。上述混合方案是一个较好的折中，平衡了安全性和开发复杂度。对于绝大多数应用，这已足够。如果你的应用处理金融、生物识别等极高敏感数据，请务必深入研究 cryptoFramework 并考虑使用安全芯片（如果设备支持）进行密钥存储和运算。

5. 业务工具层实现详解

有了安全的密钥来源，我们就可以构建面向具体业务场景的工具了。这里实现两个最常用的工具类。

5.1 安全存储工具 (StorageCryptoUtil)

这个工具用于加密后保存数据到 Preferences ，防止明文存储敏感信息。

// utils/StorageCryptoUtil.ts
import preferences from '@ohos.data.preferences';
import { CryptoCore } from './CryptoCore';
import { KeyManager } from './KeyManager';

export class StorageCryptoUtil {
  private preferences: preferences.Preferences | null = null;
  private context: common.Context;

  constructor(context: common.Context) {
    this.context = context;
  }

  async init(): Promise<void> {
    this.preferences = await preferences.getPreferences(this.context, 'secure_storage');
  }

  /**
   * 加密并存储字符串
   * @param key 存储的键
   * @param value 需要加密存储的明文值
   * @param useAppLevelKey 是否使用应用级密钥（true）或用户级密钥（false）。用户级密钥需要与用户绑定，更安全。
   */
  async putEncryptedString(key: string, value: string, useAppLevelKey: boolean = true): Promise<void> {
    if (!this.preferences) {
      throw new Error('StorageCryptoUtil not initialized. Call init() first.');
    }
    if (!value) {
      await this.preferences.delete(key); // 如果值为空，则删除该键
      await this.preferences.flush();
      return;
    }

    // 获取加密密钥。这里简化处理，实际应根据useAppLevelKey选择不同的密钥派生方式。
    const encryptionKey = await KeyManager.getDataEncryptionKey();
    
    // 使用CryptoCore进行加密。注意，为了确保相同明文每次加密结果不同（语义安全），必须使用随机IV。
    const randomIv = this.generateRandomIv(); // 生成16字节随机IV
    const encryptedValue = CryptoCore.aesEncrypt(value, encryptionKey, randomIv);
    
    // 我们需要同时存储密文和IV，解密时需要用到同一个IV。
    const dataToStore = {
      iv: randomIv, // 将IV和密文一起存储，IV无需保密，但必须不可预测。
      cipher: encryptedValue
    };
    
    await this.preferences.putString(key, JSON.stringify(dataToStore));
    await this.preferences.flush();
  }

  /**
   * 读取并解密字符串
   * @param key 存储的键
   * @param defaultValue 解密失败或键不存在时返回的默认值
   */
  async getDecryptedString(key: string, defaultValue: string = ''): Promise<string> {
    if (!this.preferences) {
      throw new Error('StorageCryptoUtil not initialized.');
    }
    const storedJson = await this.preferences.getString(key, '');
    if (!storedJson) {
      return defaultValue;
    }

    try {
      const storedData: { iv: string; cipher: string } = JSON.parse(storedJson);
      const encryptionKey = await KeyManager.getDataEncryptionKey();
      const decryptedValue = CryptoCore.aesDecrypt(storedData.cipher, encryptionKey, storedData.iv);
      return decryptedValue;
    } catch (error) {
      console.error(`Failed to decrypt value for key '${key}':`, error);
      // 解密失败可能由于密钥变更、数据损坏等。可以选择删除损坏的数据。
      // await this.preferences.delete(key);
      // await this.preferences.flush();
      return defaultValue;
    }
  }

  private generateRandomIv(): string {
    // 生成16字节随机字符串作为IV
    const randomWordArray = cryptoJs.lib.WordArray.random(16);
    return cryptoJs.enc.Base64.stringify(randomWordArray);
  }
}

使用示例 ：

// 在EntryAbility的onCreate中初始化
const storageUtil = new StorageCryptoUtil(this.context);
await storageUtil.init();

// 存储用户token
await storageUtil.putEncryptedString('user_access_token', 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...');

// 读取用户token
const token = await storageUtil.getDecryptedString('user_access_token');
if (token) {
  // 使用token...
}

5.2 网络通信安全工具 (NetworkCryptoUtil)

这个工具主要用于两方面：1) 对请求参数进行简单混淆或加密（注意，HTTPS本身已提供传输层加密，这里通常用于额外保护或满足特定协议）；2) 生成请求签名，防止请求被篡改。

// utils/NetworkCryptoUtil.ts
import { CryptoCore } from './CryptoCore';
import { KeyManager } from './KeyManager';

export class NetworkCryptoUtil {
  private static appSecret: string = 'Your_App_Secret_From_Server'; // 应从安全渠道获取，不可硬编码

  /**
   * 生成API请求签名（常用HMAC-SHA256）
   * @param params 请求参数字典，需要按特定规则排序（如按key字母序）
   * @param timestamp 时间戳，用于防止重放攻击
   * @param nonce 随机数
   * @returns 签名字符串
   */
  static generateRequestSignature(params: Record<string, string>, timestamp: number, nonce: string): string {
    // 1. 参数排序并拼接成字符串
    const sortedKeys = Object.keys(params).sort();
    const paramString = sortedKeys.map(key => `${key}=${params[key]}`).join('&');
    
    // 2. 将timestamp, nonce, paramString按约定规则拼接
    const stringToSign = `timestamp=${timestamp}&nonce=${nonce}&${paramString}`;
    
    // 3. 使用HMAC-SHA256计算签名
    const signature = CryptoCore.hmacSha256(stringToSign, this.appSecret);
    
    return signature;
  }

  /**
   * 加密请求体（适用于对敏感请求体进行额外加密的场景）
   * @param requestBody 请求体对象
   * @returns 加密后的Base64字符串和使用的IV
   */
  static async encryptRequestBody(requestBody: object): Promise<{ encryptedData: string; iv: string }> {
    const plainText = JSON.stringify(requestBody);
    const encryptionKey = await KeyManager.getDataEncryptionKey();
    const randomIv = this.generateRandomIv();
    const encryptedData = CryptoCore.aesEncrypt(plainText, encryptionKey, randomIv);
    
    return {
      encryptedData: encryptedData,
      iv: randomIv
    };
  }

  /**
   * 解密响应体（对应encryptRequestBody）
   * @param encryptedData 加密的响应数据
   * @param iv 初始化向量
   */
  static async decryptResponseBody(encryptedData: string, iv: string): Promise<any> {
    const encryptionKey = await KeyManager.getDataEncryptionKey();
    const decryptedText = CryptoCore.aesDecrypt(encryptedData, encryptionKey, iv);
    try {
      return JSON.parse(decryptedText);
    } catch (e) {
      throw new Error('Failed to parse decrypted response body.');
    }
  }

  private static generateRandomIv(): string {
    const randomWordArray = cryptoJs.lib.WordArray.random(16);
    return cryptoJs.enc.Base64.stringify(randomWordArray);
  }
}

使用示例（在请求拦截器中） ：

import http from '@ohos.net.http';

// 假设有一个全局的请求方法
async function securePost(url: string, body: object) {
  const timestamp = Date.now();
  const nonce = Math.random().toString(36).substring(2);
  
  // 1. 生成签名（假设签名包含body摘要）
  const bodyString = JSON.stringify(body);
  const paramsForSign = {
    url,
    timestamp: timestamp.toString(),
    nonce,
    bodyHash: CryptoCore.sha256(bodyString) // 对请求体取哈希，防止篡改
  };
  const signature = NetworkCryptoUtil.generateRequestSignature(paramsForSign, timestamp, nonce);
  
  // 2. （可选）加密请求体
  const { encryptedData, iv } = await NetworkCryptoUtil.encryptRequestBody(body);
  
  // 3. 发起请求
  let httpRequest = http.createHttp();
  let options = {
    method: http.RequestMethod.POST,
    header: {
      'Content-Type': 'application/json',
      'X-Timestamp': timestamp.toString(),
      'X-Nonce': nonce,
      'X-Signature': signature,
      'X-IV': iv // 如果需要，将IV传给服务端
    },
    extraData: encryptedData // 使用加密后的数据作为请求体
  };
  
  // ... 发送请求并处理响应
  // 如果响应也是加密的，则用 NetworkCryptoUtil.decryptResponseBody 解密
}

6. 高级功能与性能优化

6.1 大文件哈希计算

直接使用 CryptoCore.sha256(文件全部内容) 对于大文件会导致内存溢出。我们需要流式或分块处理。

// utils/FileHashUtil.ts
import fs from '@ohos.file.fs';
import cryptoJs from '@ohos/crypto-js';

export class FileHashUtil {
  /**
   * 计算大文件的SHA256哈希值（分块处理）
   * @param filePath 文件路径
   * @param chunkSize 分块大小，默认1MB
   * @returns 文件的十六进制哈希值
   */
  static async computeFileSha256(filePath: string, chunkSize: number = 1024 * 1024): Promise<string> {
    let file;
    try {
      file = fs.openSync(filePath, fs.OpenMode.READ_ONLY);
      const stat = fs.statSync(filePath);
      const totalSize = stat.size;
      let hash = cryptoJs.algo.SHA256.create(); // 创建一个SHA256哈希计算实例
      let bytesRead = 0;
      const buffer = new ArrayBuffer(chunkSize);

      while (bytesRead < totalSize) {
        const readSize = Math.min(chunkSize, totalSize - bytesRead);
        const readResult = fs.readSync(file.fd, buffer, { offset: bytesRead, length: readSize });
        // 将ArrayBuffer转换为crypto-js可处理的WordArray
        const wordArray = this.arrayBufferToWordArray(buffer.slice(0, readSize));
        hash.update(wordArray); // 更新哈希计算
        bytesRead += readSize;
      }

      const finalHash = hash.finalize();
      return finalHash.toString(cryptoJs.enc.Hex);
    } catch (error) {
      console.error(`Compute file hash failed: ${JSON.stringify(error)}`);
      throw error;
    } finally {
      if (file) {
        fs.closeSync(file);
      }
    }
  }

  private static arrayBufferToWordArray(arrayBuffer: ArrayBuffer): any {
    // 这是一个辅助函数，将ArrayBuffer转换为crypto-js内部的WordArray格式
    const u8 = new Uint8Array(arrayBuffer);
    const len = u8.length;
    const words: number[] = [];
    for (let i = 0; i < len; i++) {
      words[i >>> 2] |= (u8[i] & 0xff) << (24 - (i % 4) * 8);
    }
    return (cryptoJs as any).lib.WordArray.create(words, len);
  }
}

6.2 性能考量与算法选型建议

不同的加解密算法和操作对性能影响很大。

  • 哈希算法 ：MD5 > SHA1 > SHA256 > SHA512 (速度递减，安全性递增)。对于密码存储，应使用 PBKDF2 、 bcrypt 或 Argon2 这类慢哈希函数（ crypto-js 支持 PBKDF2），以增加暴力破解难度。
  • 对称加密 ：AES是主流选择。在鸿蒙设备上，AES-256-GCM（支持认证加密）是兼顾安全与性能的好选择，但 crypto-js 默认可能未包含GCM模式，需要确认或使用其他库。CBC模式需要IV，且需防范填充预言攻击。
  • 非对称加密 ：RSA加密速度慢，通常只用于加密小数据（如对称密钥）。ECC（椭圆曲线加密）在相同安全强度下比RSA密钥更短、速度更快，但 crypto-js 可能不支持，需使用 cryptoFramework 。

性能优化建议 ：

  1. 避免在主线程进行大量加解密运算 ：对于大文件或频繁操作，使用 Worker 线程。
  2. 缓存密钥 ： KeyManager.getDataEncryptionKey() 的结果应在内存中缓存（注意生命周期），避免频繁的异步IO和加解密操作。
  3. 选择合适的算法和模式 ：根据数据敏感性和性能要求权衡。例如，本地缓存的数据可能用AES-128-CBC就够了，而传输支付信息则必须用AES-256-GCM。

7. 常见问题、调试技巧与避坑指南

在实际开发中，你肯定会遇到各种问题。下面是我踩过的一些坑和解决方案。

7.1 常见问题速查表

问题现象 可能原因 排查步骤与解决方案
加密/解密结果与预期不符 1. 密钥不一致。
2. IV不一致或未传递。
3. 算法模式或填充方式不匹配。
4. 密文格式问题（如Base64解码错误）。		 1. 核对密钥 ：确保加密和解密使用的密钥字符串完全一致（包括长度和内容）。
2. 核对IV ：CBC模式必须使用相同的IV。确保加密生成的随机IV被正确存储并在解密时传入。
3. 核对算法参数 ：检查 mode (如CBC, ECB) 和 padding (如Pkcs7) 在加密解密时是否完全一致。
4. 检查数据格式 ： crypto-js 的 encrypt 默认返回一个包含盐、IV、密文的特殊格式对象，直接 toString() 得到的是OpenSSL兼容格式。如果与其他系统交互，需确认格式。使用 ciphertext.toString(cryptoJs.enc.Base64) 可以只输出密文。
解密时抛出 Malformed UTF-8 data 错误 1. 密钥错误，导致解密出的二进制数据无法转换为有效UTF-8字符串。
2. 密文在传输或存储过程中被损坏或篡改。		 1. 首先确认密钥是否正确。可以尝试用错误密钥解密，如果也报类似错误，则问题可能不在密钥。
2. 检查密文的完整性。如果是网络传输，确保没有进行额外的URL编码/解码。如果是存储，检查读写过程是否有编码问题。可以尝试将密文用Hex或Base64编码后传输/存储，避免特殊字符问题。
@ohos/crypto-js 模块找不到或方法未定义 1. ohpm依赖未正确安装。
2. 导入路径或方式错误。
3. 系统版本不支持。		 1. 检查 oh-package.json5 和 oh_modules 目录，确认依赖已安装。尝试删除 oh_modules 和 oh-package-lock.json 后重新 ohpm install 。
2. 确认导入语句： import cryptoJs from '@ohos/crypto-js'; 。
3. 查阅官方文档，确认当前鸿蒙API版本是否支持该库。
密钥管理相关错误（KeyStore） 1. 密钥别名冲突或不存在。
2. 密钥用途不匹配（如用签名密钥去加密）。
3. 用户认证（如生物识别）未通过。		 1. 使用 cryptoFramework 的 keyManager 接口检查密钥是否存在。
2. 生成密钥时，务必在 KeyProperties 中正确设置 purposes （如 `cryptoFramework.KeyPurpose.ENCRYPT
性能问题，界面卡顿 在主线程执行了大量或复杂的加解密操作。 1. 将耗时的加解密操作（如大文件哈希、大量数据加密）放入 Worker 线程。
2. 对于频繁操作的小数据，考虑使用更轻量的算法（如ChaCha20，如果可用）或是否真的需要实时加密。

7.2 调试技巧

  1. 日志输出关键中间值 ：在加密和解密函数中，临时打印出密钥（可打印部分）、IV、输入明文/密文的长度和前缀。这能帮你快速定位是哪一步的数据出了问题。 
    console.debug(`[Crypto] Encrypting. Key length: ${key.length}, IV: ${iv?.substring(0,8)}..., PlainText length: ${plainText.length}`);
  2. 使用已知向量测试 ：在调试阶段，使用固定的密钥和IV进行测试，确保算法本身工作正常。可以与在线加解密工具（如一些AES工具网站）的结果进行比对。
  3. 隔离测试 ：单独写一个测试页面，只测试加解密功能，排除业务逻辑干扰。
  4. 查看官方示例 ：OpenHarmony的Gitee仓库中通常有 crypto-js 和 cryptoFramework 的示例代码，是很好的参考。

7.3 安全避坑指南

  1. 绝对不要硬编码密钥 ：这是重复但最重要的警告。使用上文所述的密钥管理策略。
  2. CBC模式必须使用随机且不可预测的IV ：重复使用IV会严重削弱CBC模式的安全性。每次加密都应生成新的随机IV，并随密文一起存储/传输。
  3. 考虑加密算法的过时风险 ：避免使用已知不安全的算法，如DES、RC4、MD5（仅用于校验和，不可用于密码哈希）。优先使用AES（256位）、SHA-256/512、HMAC。
  4. 正确处理错误 ：加解密操作可能因各种原因失败（密钥错误、数据损坏、内存不足）。你的代码必须有健壮的错误处理，避免因异常导致应用崩溃或敏感信息泄露（如通过错误信息提示密钥错误）。
  5. 理解“加密”不等于“安全” ：加密只是安全的一环。还需要考虑安全的数据传输（HTTPS）、安全的存储（KeyStore）、防止代码反编译（混淆）、合理的权限控制等。

构建这个加解密工具箱的过程，本质上是一次对鸿蒙应用安全机制的深度实践。从选择 crypto-js 作为切入点，到设计分层的密钥管理架构，再到封装面向业务的工具类，每一步都需要在易用性、安全性和性能之间做出权衡。我个人的体会是，前期在密钥管理和架构设计上多花一点时间，能为后续的业务开发避免无数的坑。这个工具箱的代码并非一成不变，你可以根据自己项目的具体需求，轻松地扩展更多的算法（如SM国密算法，如果 crypto-js 未来支持或你找到兼容库）、优化性能或者集成更高级的安全特性。希望这份详细的拆解和实

# 鸿蒙应用开发
Logo
HarmonyOS开发者社区

讨论HarmonyOS开发技术，专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐

盘古大模型接入：调用云端大模型API（279）

在鸿蒙（HarmonyOS）应用中接入盘古大模型云端 API，通常可以通过华为云 ModelArts Studio (MaaS) 平台来实现。

avatar HarmonyOS开发者社区

端侧小模型部署：在手机上运行轻量化模型（280）

在鸿蒙（HarmonyOS）设备上部署端侧小模型，核心目标是利用本地算力实现低延迟、高隐私的 AI 推理。

avatar HarmonyOS开发者社区

SQLite集成：原生数据库库的封装（275）

在鸿蒙（HarmonyOS）开发中，集成并封装 SQLite 数据库主要有两种主流路径：一是直接使用官方提供的（关系型数据库）API；二是通过 NAPI 机制在 C++ 层调用原生的sqlite3库。

avatar HarmonyOS开发者社区