加密解密库：AES/RSA/MD5等算法的ArkTS封装（238）

在鸿蒙HarmonyOS原生应用开发中保障客户端与服务端的数据传输安全、防止敏感信息泄露是核心诉求。鸿蒙系统提供了强大的官方加解密算法框架服务Crypto Architecture Kit同时社区也涌现了进一步封装的便捷工具库。一、 官方核心框架Crypto Architecture Kit鸿蒙官方提供了cryptoFramework模块支持对称加密、非对称加密、消息摘要等多种算法是构建安全应用的底层基石。对称加密AES支持多种分组模式如 ECB、CBC、GCM、XTS 等提供同步和异步的加解密方法。其中 GCM 模式是官方推荐的认证加密模式可同时提供机密性、完整性和认证。非对称加密RSA支持生成密钥对、分段加解密解决长文本加密限制常用于安全传输对称密钥或数字签名。消息摘要Hash内置 MD5、SHA 系列SHA1/256/512等、SM3 等算法用于数据完整性校验和密码存储。编码转换Base64提供二进制数据与 ASCII 字符之间的安全转换确保数据在文本协议中传输不丢失。二、 社区便捷封装库security 等为了降低原生 API 的调用门槛社区开发者推出了如security这样的加密算法工具库。极简调用将复杂的cryptoFramework流程封装开发者仅需一行代码即可完成 MD5、Base64、SHA、SM3、AES、RSA 等算法的调用。多模式支持内部支持多种加密模式满足多场景的业务需求且经过严格测试保证了组件的稳定性。三、 工程级避坑与最佳实践首选认证加密模式在 AES 加密时强烈建议使用 AES-GCM 模式避免使用“AES-CBC 独立 HMAC”的分离实现以防止实现错误导致的安全漏洞。严禁 IV 复用每次加密操作必须生成唯一的初始化向量IV。GCM 模式下 IV 复用会导致灾难性的安全崩溃。主线程阻塞防范大数据量的加解密操作会消耗大量 CPU 资源。务必将加密逻辑放入TaskPool或Worker子线程中执行避免阻塞 UI 主线程。敏感数据内存擦除密钥等敏感数据在使用完毕后应立即置零引用或使用安全擦除函数如OPENSSL_cleanse清理内存防止内存转储泄露。四、 AES 对称加密CBC模式与随机IV生成场景在应用内对用户的敏感业务数据进行本地加密存储。使用 AES128 算法的 CBC 模式并在每次加密时动态生成 16 字节的随机初始化向量IV确保相同明文每次加密后的密文不同。import { cryptoFramework } from kit.CryptoArchitectureKit; import { buffer } from kit.ArkTS; // 1. 生成随机 IV 参数 function genIvParamsSpec(): cryptoFramework.IvParamsSpec { let rand cryptoFramework.createRandom(); let ivBlob rand.generateRandomSync(16); return { algName: IvParamsSpec, iv: ivBlob }; } // 2. 执行 AES-CBC 加密 async function encryptMessage(symKey: cryptoFramework.SymKey, plainText: string) { let cipher cryptoFramework.createCipher(AES128|CBC|PKCS7); let iv genIvParamsSpec(); await cipher.init(cryptoFramework.CryptoMode.ENCRYPT_MODE, symKey, iv); let dataBlob: cryptoFramework.DataBlob { data: new Uint8Array(buffer.from(plainText, utf-8).buffer) }; let cipherData await cipher.doFinal(dataBlob); return cipherData; }五、RSA 非对称加密长文本分段加解密场景RSA 算法对单次加密的数据长度有严格限制例如 1024 位密钥最多只能加密 112 字节数据。当需要加密超长文本或大文件时必须采用分段加解密策略。import { cryptoFramework } from kit.CryptoArchitectureKit; // 分段加密长文本 async function rsaEncryptBySegment(pubKey: cryptoFramework.PubKey, plainText: cryptoFramework.DataBlob) { let cipher cryptoFramework.createCipher(RSA1024|PKCS1); await cipher.init(cryptoFramework.CryptoMode.ENCRYPT_MODE, pubKey, null); let plainTextSplitLen 64; // 每次加密的明文长度 let cipherText new Uint8Array(); for (let i 0; i plainText.data.length; i plainTextSplitLen) { let updateMessage plainText.data.subarray(i, i plainTextSplitLen); let updateOutput await cipher.doFinal({ data: updateMessage }); // 拼接密文 let mergeText new Uint8Array(cipherText.length updateOutput.data.length); mergeText.set(cipherText); mergeText.set(updateOutput.data, cipherText.length); cipherText mergeText; } return { data: cipherText }; }六、MD5 摘要大文件流式读取与一致性校验场景在文件上传或下载完成后通过计算文件的 MD5 哈希值来校验文件在传输过程中是否发生损坏或被篡改。采用流式update方式避免将整个大文件加载到内存中。import { cryptoFramework } from kit.CryptoArchitectureKit; import { fileIo as fs } from kit.CoreFileKit; import { buffer } from kit.ArkTS; async function calFileMd5(fileUrl: string): Promisestring | undefined { let md cryptoFramework.createMd(MD5); let file fs.openSync(fileUrl, fs.OpenMode.READ_ONLY); let arrayBuffer new ArrayBuffer(2048); // 每次读取 2KB let len 0; do { len fs.readSync(file.fd, arrayBuffer); if (len 0) { let uint8Array new Uint8Array(arrayBuffer.slice(0, len)); await md.update({ data: uint8Array }); } } while (len 0); fs.closeSync(file); let mdOutput await md.digest(); return buffer.from(mdOutput.data).toString(hex); }七、 性能优化TaskPool 子线程异步加密场景在主线程UI 线程执行耗时的加解密操作会导致应用界面卡顿。利用鸿蒙的TaskPool将加密任务分发到子线程执行确保 UI 的绝对流畅。import { taskpool } from kit.ArkTS; import { cryptoFramework } from kit.CryptoArchitectureKit; // 1. 定义并发函数必须使用 Concurrent 装饰器 Concurrent function aesEncryptInWorker(src: Uint8Array): Uint8Array { let cipher cryptoFramework.createCipher(AES256|CBC|PKCS7); // 注意密钥和 IV 需要在子线程内部生成或作为 Sendable 传入 // 此处省略密钥生成细节假设 key 和 iv 已就绪 cipher.initSync(cryptoFramework.CryptoMode.ENCRYPT_MODE, key, iv); return cipher.doFinalSync({ data: src }).data; } // 2. 在主线程调用 TaskPool 分发任务 async function startEncryption() { let plainData new Uint8Array([0x01, 0x02, 0x03]); let task new taskpool.Task(aesEncryptInWorker, plainData); let encryptedData await taskpool.execute(task) as Uint8Array; console.info(子线程加密完成:, encryptedData.toString()); }