引言在现代应用开发中数据安全是一个不可回避的话题。无论是用户密码的存储、敏感数据的传输还是接口参数的签名验证都离不开密码学算法的支撑。HarmonyOS NEXT 通过ohos.security.cryptoFramework模块为开发者提供了一套完整的密码学能力涵盖消息摘要Hash、对称加密AES、消息认证码HMAC、非对称加密RSA、数字签名等全方位的安全功能。本文将以一个密码学工具箱的实战 Demo 为线索深入讲解 cryptoFramework 的核心 API 和使用模式。与上一篇文章介绍的 zlib 压缩引擎类似cryptoFramework 也遵循创建实例 → 初始化 → 更新数据 → 获取结果的管道式操作模式但它在算法丰富度和安全场景覆盖面上要广阔得多。读完本文你将掌握消息摘要MD5/SHA的计算方法及7种算法对比AES 对称加密的加密/解密流程及5种模式切换HMAC 消息认证码的生成与验证DataBlob 数据容器在密码学 API 中的核心作用同步 vs 异步 API的选择策略环境与权限cryptoFramework 属于CryptoArchitectureKit工具包自 API 9 开始提供API 11 起支持跨平台API 12 起支持原子化服务。本文基于API 24 (HarmonyOS NEXT)编写使用同步 APIxxxSync系列方法。cryptoFramework不需要申请任何权限直接导入即可使用importcryptoFrameworkfromohos.security.cryptoFramework;这是密码学 API 相比传感器、蓝牙等功能模块的一大优势——零权限门槛开箱即用。核心数据结构DataBlob在深入各个算法之前必须先理解 cryptoFramework 的通用数据容器——DataBlob。它是整个密码学框架的数据交换基础所有输入输出都通过它来传递。interfaceDataBlob{data:Uint8Array;}DataBlob 本质上是Uint8Array的包装。字符串与 DataBlob 之间的转换是所有操作的第一步。我们使用kit.ArkTS中的util.TextEncoder/util.TextDecoder来完成import{util}fromkit.ArkTS;// 字符串 → Uint8Array → DataBlobfunctionstringToUint8(str:string):Uint8Array{letencodernewutil.TextEncoder();returnencoder.encodeInto(str);}// DataBlob → Uint8Array → 字符串functionuint8ToString(buf:Uint8Array):string{letdecodernewutil.TextDecoder();returndecoder.decodeToString(buf);}实际使用时只需将Uint8Array放入对象字面量即可创建 DataBlobletdataBlob:cryptoFramework.DataBlob{data:this.stringToUint8(Hello HarmonyOS)};一、消息摘要HashMD5、SHA 系列与 SM3消息摘要算法又称哈希算法将任意长度的数据映射为固定长度的指纹。cryptoFramework 支持 7 种摘要算法算法摘要长度安全性典型用途MD5128 bit (16 B)已破解不推荐安全场景文件完整性校验、非安全去重SHA-1160 bit (20 B)已弱化遗留系统兼容SHA-224224 bit (28 B)中等资源受限场景SHA-256256 bit (32 B)高区块链、证书、签名SHA-384384 bit (48 B)很高高安全场景SHA-512512 bit (64 B)最高高安全场景、HMACSM3256 bit (32 B)高国密标准政务金融同步 Hash 计算三步走cryptoFramework 的 Hash 流程遵循统一的创建 → 更新 → 摘要三步模式// 步骤1创建消息摘要实例letmd:cryptoFramework.MdcryptoFramework.createMd(SHA256);// 步骤2更新数据可多次调用处理大块数据md.updateSync({data:this.stringToUint8(Hello HarmonyOS!)});// 步骤3获取摘要结果letresult:cryptoFramework.DataBlobmd.digestSync();// result.data 是 Uint8Array转为十六进制字符串展示lethexStringthis.bufToHex(result.data);// 输出32字节的SHA-256摘要Uint8Array → 十六进制字符串摘要结果是一段二进制数据展示时通常转为十六进制bufToHex(buf:Uint8Array):string{letsb;for(leti0;ibuf.length;i){leth(buf[i]0xFF).toString(16);if(h.length1)sb0;sbh;}returnsb;}批量对比7种算法一键测试Demo 中提供了批量对比功能对同一段文本依次运行 7 种算法同时记录每种算法的输出长度和计算耗时让开发者直观感受不同算法的特点batchHash():void{letinputDatathis.stringToUint8(this.textInput);for(leta0;athis.algos.length;a){letalgothis.algos[a];letmd:cryptoFramework.MdcryptoFramework.createMd(algo);letstartDate.now();md.updateSync({data:inputData});letresult:cryptoFramework.DataBlobmd.digestSync();letelapsedDate.now()-start;// 记录算法名、耗时、摘要长度...}}Md 接口完整方法列表interfaceMd{update(input:DataBlob,callback:AsyncCallbackvoid):void;// 异步更新update(input:DataBlob):Promisevoid;// Promise更新updateSync(input:DataBlob):void;// 同步更新推荐digest(callback:AsyncCallbackDataBlob):void;// 异步摘要digest():PromiseDataBlob;// Promise摘要digestSync():DataBlob;// 同步摘要推荐getMdLength():number;// 获取摘要长度}对于 Demo 场景同步 API 代码更简洁。生产环境中处理大文件如几百MB的视频建议使用异步 Promise 版以避免阻塞主线程。二、AES 对称加密5种模式的加密/解密往返cryptoFramework 的 Cipher密码器模块提供完整的对称加密能力。支持的对称算法包括AES128、AES192、AES256以及国密SM4。本文 Demo 聚焦最常用的 AES提供 5 种配置模式模式transformation 参数密钥长度填充方式AES128-ECBAES128|ECB|PKCS716 BPKCS7AES128-CBCAES128|CBC|PKCS716 BPKCS7AES128-CTRAES128|CTR|NoPadding16 B无填充流式AES192-ECBAES192|ECB|PKCS724 BPKCS7AES256-ECBAES256|ECB|PKCS732 BPKCS7transformation 参数的格式为算法|模式|填充方式三个部分用|连接。加密/解密六步流程完整的 AES 加解密往返包含 6 个核心步骤aesEncryptDecrypt():void{lettransformationAES128|ECB|PKCS7;// 算法|模式|填充letkeyStrthis.keyInput;// 1. 准备密钥将字符串填充/截断到算法需要的长度letkeyBufthis.stringToUint8(keyStr);letpaddedKeynewUint8Array(16);// AES128 16 bytesfor(leti0;i16;i){paddedKey[i]keyBuf[i%keyBuf.length];}// 2. 创建对称密钥生成器letsymKeyGen:cryptoFramework.SymKeyGeneratorcryptoFramework.createSymKeyGenerator(AES128);// 3. 从字节数据转换为 SymKey 对象letsymKey:cryptoFramework.SymKeysymKeyGen.convertKeySync({data:paddedKey});// 4. 创建 Cipher 并初始化为加密模式letcipher:cryptoFramework.CiphercryptoFramework.createCipher(transformation);letiv:cryptoFramework.IvParamsSpec{algName:IvParamsSpec,iv:{data:paddedKey}// ECB模式不需要IV为统一接口仍传入};cipher.initSync(cryptoFramework.CryptoMode.ENCRYPT_MODE,symKey,iv);// 5. 执行加密doFinal 完成并输出letcipherResult:cryptoFramework.DataBlobcipher.doFinalSync({data:this.stringToUint8(this.textInput)});// 6. 重新初始化并解密验证往返正确性letdecipher:cryptoFramework.CiphercryptoFramework.createCipher(transformation);decipher.initSync(cryptoFramework.CryptoMode.DECRYPT_MODE,symKey,iv);letplainResult:cryptoFramework.DataBlobdecipher.doFinalSync({data:cipherResult.data});letroundtrip(this.uint8ToString(plainResult.data)this.textInput);// roundtrip true 说明加解密往返正确}关键要点1) CryptoMode 枚举enumCryptoMode{ENCRYPT_MODE,// 加密模式DECRYPT_MODE// 解密模式}同一个 Cipher 实例在doFinal之后不可重复使用。如果需要解密必须创建新的 Cipher 实例并以DECRYPT_MODE重新 init。2) IV初始化向量参数CBC/CTR 等模式使用 IV 增加随机性保证同一明文每次产生不同密文。ECB 模式不使用 IV但initSync的第三个参数params在 ECB 模式下可传入null。Demo 中为统一接口风格对 ECB 也传入了一个占位 IV。3) 密钥长度与算法的对应AES128→ 16 bytes (128 bits)AES192→ 24 bytes (192 bits)AES256→ 32 bytes (256 bits)Demo 中自动从transformation字符串中提取密钥长度要求并用取模循环方式填充用户输入的任意长度密钥letkeyAlgtransformation.split(|)[0];// AES128letkeyBytesNeededparseInt(keyAlg.substring(3))/8;// 128/8 16letpaddedKeynewUint8Array(keyBytesNeeded);for(leti0;ikeyBytesNeeded;i){paddedKey[i]keyBuf[i%keyBuf.length];}三、HMAC 消息认证码带密钥的哈希HMACHash-based Message Authentication Code在哈希算法的基础上引入密钥同时验证数据的完整性和真实性。接收方只有持相同密钥才能生成一致的 HMAC 值有效防止中间人篡改。cryptoFramework 为 HMAC 提供了与 Md 完全一致的三步式 APIcomputeHmac():void{// 1. 准备对称密钥HMAC需要共享密钥letkeyBufthis.stringToUint8(this.keyInput);letpaddednewUint8Array(16);for(leti0;i16;i){padded[i]keyBuf[i%keyBuf.length];}letsymKeyGen:cryptoFramework.SymKeyGeneratorcryptoFramework.createSymKeyGenerator(AES128);letsymKey:cryptoFramework.SymKeysymKeyGen.convertKeySync({data:padded});// 2. 创建Mac实例并初始化letmac:cryptoFramework.MaccryptoFramework.createMac(HMAC|SHA256);mac.initSync(symKey);// 3. 更新数据并获取结果mac.updateSync({data:this.stringToUint8(this.textInput)});letmacResult:cryptoFramework.DataBlobmac.doFinalSync();this.hmacOutputthis.bufToHex(macResult.data);}HMAC 的算法名称格式为HMAC|摘要算法例如HMAC|SHA1HMAC|SHA256HMAC|SHA384HMAC|SHA512四、API 全景概览cryptoFramework 的模块结构层次分明下图展示了核心类与创建函数的关系cryptoFramework (namespace) ├── createMd(algName) ──────────────→ Md ──→ updateSync() digestSync() ├── createMac(algName) ─────────────→ Mac ─→ initSync() updateSync() doFinalSync() ├── createCipher(transformation) ───→ Cipher → initSync() doFinalSync() ├── createSymKeyGenerator(algName) ─→ SymKeyGenerator ─→ generateSymKeySync() convertKeySync() ├── createRandom() ─────────────────→ Random ─→ generateRandomSync() ├── createSign(algName) ────────────→ Sign ──→ initSync() signSync() ├── createVerify(algName) ──────────→ Verify → initSync() verifySync() ├── createKeyAgreement(algName) ────→ KeyAgreement ─→ generateSecretSync() └── createAsyKeyGenerator(algName) ─→ AsyKeyGenerator ─→ generateKeyPairSync()本文 Demo 聚焦最常用的前 4 个模块Md、Cipher、Mac、SymKeyGenerator它们已经覆盖了日常开发 90% 的密码学需求。五、实战 Demo密码学工具箱页面结构Demo 页面CryptoFrameworkPage.ets采用输入区 三大功能面板 历史记录的卡片式布局密码学工具箱 ├── 状态栏 — 实时反馈当前操作结果 ├── 输入区 │ ├── 文本输入框3000字上限 │ └── AES密钥输入框自动填充至所需长度 ├── 消息摘要 (Hash) 面板 │ ├── 7种算法横向选择MD5/SHA1/SHA224/SHA256/SHA384/SHA512/SM3 │ ├── 计算Hash 按钮 — 对输入文本执行选中算法 │ ├── 批量对比 按钮 — 对同一输入执行全部7种算法 │ └── 结果展示区 — 十六进制摘要 耗时 ├── AES 对称加密面板 │ ├── 5种模式选择AES128-ECB/CBC/CTR, AES192-ECB, AES256-ECB │ ├── 加密并解密 按钮 — 执行完整的加密→解密往返 │ ├── 密文展示hex格式前40字符预览 │ └── 解密验证结果对比原文显示通过/失败 ├── HMAC 消息认证码面板 │ ├── 计算 HMAC-SHA256 按钮 │ └── MAC值展示hex格式 ├── 摘要/认证记录 — 最近8次Hash和HMAC操作 ├── 加解密记录 — 最近8次AES操作及往返验证状态 └── 核心API参考 — 12个关键API速查表4 个交互点算法选择与单次Hash— 点击7种算法标签切换输入文本后计算Hash实时显示摘要和耗时批量算法对比— 一键对同一文本执行全部7种算法记录在历史面板中直观对比摘要长度和速度AES加解密往返— 选择5种模式之一点击加密自动执行解密并验证往返正确性对比原文HMAC认证码生成— 用密钥对输入文本生成MAC展示键控哈希与普通哈希的区别核心代码位置完整代码在dev/entry/src/main/ets/pages/CryptoFrameworkPage.ets约 380 行路由已注册为pages/CryptoFrameworkPage。六、同步 vs 异步 API 的选择cryptoFramework 为每个操作提供了 3 种调用方式Callback 异步、Promise 异步、同步Sync。以 Md.digest 为例// 方式1Callback 异步md.digest((err,result){if(err){console.error(digest failed);return;}lethexbufToHex(result.data);});// 方式2Promise 异步md.digest().then((result){lethexbufToHex(result.data);}).catch((err){console.error(digest failed);});// 方式3同步Demo 推荐letresult:cryptoFramework.DataBlobmd.digestSync();lethexbufToHex(result.data);选择策略场景推荐方式原因小数据 1 KB同步 Sync代码简洁阻塞时间可忽略中等数据1 KB - 1 MBPromise 异步避免UI卡顿保持响应大数据 1 MBPromise 异步 update 分块利用 update 逐块处理内存友好Worker 线程同步 SyncWorker 不阻塞主线程Sync 更简单七、常见问题与排查1. “algName is invalid” 错误算法名称字符串区分大小写且不能有额外空格。标准算法名称为正确: SHA256, AES128|ECB|PKCS7, HMAC|SHA256 错误: sha256, AES128|ECB|PKCS7 尾部有空格2. doFinalSync 只能调用一次每个 Md/Cipher/Mac 实例的doFinalSync/digestSync只能调用一次。如果需要重复计算必须创建新实例// 错误 —— 重复使用同一个MdletmdcryptoFramework.createMd(SHA256);md.digestSync();md.digestSync();// 抛出异常// 正确 —— 每次创建新实例letmd1cryptoFramework.createMd(SHA256);md1.updateSync({data:data1});letresult1md1.digestSync();letmd2cryptoFramework.createMd(SHA256);md2.updateSync({data:data2});letresult2md2.digestSync();3. AES 加解密往返验证失败如果解密后的明文与原文本不一致检查以下几点加密和解密使用的transformation参数是否完全一致加密和解密的 IV 是否一致密钥是否一致是否被意外截断或补零密文在传输过程中是否被修改如错误的反序列化4. cipher.init: params is nullECB/CTR 等不需要 IV 的模式initSync的第三个参数params可传入null。但对于 CBC 模式必须提供IvParamsSpec。八、安全最佳实践1. 密码存储绝不用 MD5MD5 和 SHA-1 已被证明存在碰撞漏洞。存储用户密码时应使用SHA-256 随机盐值或专门的密钥派生函数。// 不安全的密码存储lethashcryptoFramework.createMd(MD5);hash.updateSync({data:passwordData});letresulthash.digestSync();// MD5 易碰撞// 更好的做法简化示意lethashcryptoFramework.createMd(SHA256);letsaltcryptoFramework.createRandom().generateRandomSync(16);// 随机盐letcombinednewUint8Array(salt.data.lengthpasswordData.data.length);combined.set(salt.data,0);combined.set(passwordData.data,salt.data.length);hash.updateSync({data:combined});letresulthash.digestSync();// 存储 salt result2. IV 必须随机且不重复CBC 模式下每次加密都应使用新的随机 IV。重复使用相同 IV 会泄露明文模式letrandomcryptoFramework.createRandom();letivrandom.generateRandomSync(16);// 16字节随机IV3. ECB 模式的局限性ECB 模式下相同的明文块产生相同的密文块可能泄露数据模式。对于包含重复结构的数据如 JSON、XML应优先使用 CBC 或 CTR 模式。4. 密钥管理Demo 中的密钥输入仅供演示。生产环境中密钥应使用cryptoFramework.createRandom().generateRandomSync()生成存储在系统安全区域如 HUKS 密钥管理服务绝不明文硬编码在代码中使用后及时从内存清除九、与其它平台对比如果你有 Android 或 iOS 开发经验以下对照表可帮助理解功能HarmonyOS cryptoFrameworkAndroid javax.cryptoiOS CryptoKit消息摘要createMd(SHA256).digestSync()MessageDigest.getInstance(SHA-256).digest()SHA256.hash(data:)AES加密createCipher(AES128|CBC|PKCS7)Cipher.getInstance(AES/CBC/PKCS5Padding)AES.GCM.seal()HMACcreateMac(HMAC|SHA256)Mac.getInstance(HmacSHA256)HMACSHA256.authenticationCode()对称密钥生成createSymKeyGenerator(AES256).generateSymKeySync()KeyGenerator.getInstance(AES).generateKey()SymmetricKey(size:)可以看到HarmonyOS 的 API 设计融合了 Android 的灵活性字符串参数指定算法和 iOS 的类型安全性强类型接口同时加入了国密算法SM3、SM4的原生支持这是其它平台不具备的独特优势。十、总结cryptoFramework 是 HarmonyOS NEXT 密码学能力的核心入口它提供了7种摘要算法— MD5、SHA-1/224/256/384/512、SM3覆盖国际标准和国密AES对称加密— AES128/192/256 × ECB/CBC/CTR 多种组合HMAC认证码— 基于SHA-256的键控哈希验证完整性和真实性统一的管道式API— 所有模块遵循创建→初始化→更新→完成四步模式同步/异步双轨支持— 小数据用 Sync大文件用 Promise灵活切换零权限门槛— 无需申请任何系统权限即可使用与 zlib 压缩引擎一样cryptoFramework 也体现了 HarmonyOS API 设计的统一哲学用createXxx()创建实例用xxxSync()完成同步操作用DataBlob传递二进制数据。掌握这一个模式就能触类旁通地驾驭整个框架。下一篇文章我们将继续探索 HarmonyOS NEXT 的其它新特性敬请期待。
