一、落地背景传统加密方案的安全硬伤政务、医疗、金融、商用自助终端等场景身份证、病历、支付凭证、管理员密码等敏感数据若采用普通本地加密存在致命安全漏洞密钥明文存储极易逆向破解开发者硬编码密钥、存放在沙箱普通文件通过解包、抓日志、内存dump可直接提取密钥敏感数据完全裸奔无硬件可信环境TEE保护传统JS加密库运算全程在应用普通富操作系统系统被入侵、ROOT后密文可被暴力解密缺少访问权限管控任何人打开应用即可解密全部数据无法绑定指纹/人脸锁屏校验丢失设备后隐私完全泄露恢复出厂、卸载应用密钥残留自定义加密密钥永久留存本地设备流转后可逆向解密历史存储数据不符合等保2.0合规要求。鸿蒙7 API26 将Universal Keystore Kit(HUKS)收敛至kit.SecurityKit依托星盾安全架构TEE可信执行环境实现密钥不出安全区、国密SM2/SM3/SM4硬件级运算、生物认证访问管控、应用绑定密钥、恢复出厂自动销毁密钥五大核心能力完美满足政企等保、商用终端隐私合规落地。本文完整实现HUKS托管SM4国密分片加密、生物指纹解锁密钥、沙箱敏感文件加密、密钥生命周期管理全套生产级方案。核心概念HUKS密钥托管底层安全原理密钥全程隔离TEE密钥生成、加密、解密全部在硬件安全环境运行应用进程、系统内核永远无法获取密钥明文应用绑定隔离生成密钥与当前应用签名证书强绑定其他应用无法读取、使用本应用密钥国密硬件加速SM4对称、SM2非对称、SM3哈希算法底层硬件加速大文件加密无性能损耗分级访问控制可配置「必须指纹/人脸解锁才能使用密钥」锁屏后加密接口直接拦截不可逆销毁机制卸载应用、恢复出厂、清除锁屏密码、新增生物特征密钥永久销毁无法恢复。二、工程前置配置规范2.1 kit标准导入依赖import{cryptoFramework,huks,huksBiometricAuth,HuksTag,HuksKeyAlg,HuksKeyPurpose,HuksCipherMode,HuksKeyPadding,CryptoMode}fromkit.SecurityKit;import{ComponentV2,Local}fromkit.ArkUI;import{common}fromkit.AbilityKit;import{hilog}fromkit.PerformanceAnalysisKit;import{BusinessError}fromkit.BasicServicesKit;constTAGSecurityHuksSM4;constDOMAIN0x0013;// 密钥唯一别名当前应用全局唯一constSM4_KEY_ALIAShuks_sm4_secure_key_2026;2.2 module.json5配套权限声明requestPermissions: [ { name: ohos.permission.HUKS_KEY_MANAGE, reason: $string:huks_key_manage_reason, usedScene: { abilities: [EntryAbility], when: always } }, { name: ohos.permission.USER_AUTHENTICATION, reason: $string:biometric_auth_reason, usedScene: { abilities: [EntryAbility], when: always } } ]三、核心工具类封装HUKS SM4国密全流程生成密钥、加密、解密、密钥销毁3.1 工具类1生成绑定生物认证的HUKS SM4密钥生成128位国密SM4密钥配置访问规则必须完成指纹/人脸验证才能调用加解密新增生物特征后密钥自动失效。/** * 生成HUKS托管SM4密钥绑定生物认证访问限制 */asyncfunctioncreateHuksSm4Key(){// 构建密钥属性参数constkeyParams:huks.HuksParam[][{tag:HuksTag.HUKS_TAG_ALGORITHM,value:HuksKeyAlg.HUKS_ALG_SM4},{tag:HuksTag.HUKS_TAG_KEY_SIZE,value:huks.HuksKeySize.HUKS_SM4_KEY_SIZE_128},{tag:HuksTag.HUKS_TAG_PURPOSE,value:HuksKeyPurpose.HUKS_KEY_PURPOSE_ENCRYPT|HuksKeyPurpose.HUKS_KEY_PURPOSE_DECRYPT},{tag:HuksTag.HUKS_TAG_BLOCK_MODE,value:HuksCipherMode.HUKS_MODE_CBC},{tag:HuksTag.HUKS_TAG_PADDING,value:HuksKeyPadding.HUKS_PADDING_PKCS7},// 核心必须生物认证后才能使用该密钥{tag:HuksTag.HUKS_TAG_USER_AUTH_TYPE,value:huks.HuksUserAuthType.HUKS_AUTH_TYPE_BIOMETRIC},// 录入新指纹/人脸后密钥直接失效{tag:HuksTag.HUKS_TAG_AUTH_TIMEOUT,value:0},{tag:HuksTag.HUKS_TAG_UNIQUE_KEY,value:true}];try{// 别名重复则先删除旧密钥awaitdeleteHuksKey();// 在TEE内生成密钥密钥明文不会透出应用awaithuks.generateKeyItem(SM4_KEY_ALIAS,keyParams);hilog.info(DOMAIN,TAG,HUKS SM4国密密钥生成完成绑定生物认证);}catch(err){consteerrasBusinessError;hilog.error(DOMAIN,TAG,生成密钥失败${e.code}${e.message});}}3.2 工具类2生物认证弹窗获取合法访问令牌调用系统指纹/人脸验证拿到授权token后续加密解密必须携带该令牌才能调用HUKS密钥。/** * 唤起生物认证弹窗获取访问密钥的授权令牌 * returns authToken 认证令牌解密加密必需 */asyncfunctionstartBiometricAuth():Promisestring|null{constauthOpt:huksBiometricAuth.BiometricAuthOptions{title:隐私数据加密验证,description:验证指纹/人脸解锁敏感数据,authType:huksBiometricAuth.BiometricAuthType.BIOMETRIC_STRONG};returnnewPromise((resolve){constauthhuksBiometricAuth.createBiometricAuth(authOpt);auth.on(result,(res){if(res.resultCode0){resolve(res.token);}else{hilog.warn(DOMAIN,TAG,生物认证失败无法访问加密密钥);resolve(null);}});auth.start();});}3.3 工具类3SM4国密加密分片适配大文件TEE硬件运算/** * HUKS SM4 CBC模式加密明文支持超大文本、文件二进制 * param authToken 生物认证令牌 * param plainText 原始明文字符串 * returns base64密文iv向量 */asyncfunctionhuksSm4Encrypt(authToken:string,plainText:string):Promise{cipher:string,iv:string}|null{if(!authToken)returnnull;constencodernewTextEncoder();constplainBinencoder.encode(plainText);// 加密会话参数constencryptParams:huks.HuksParam[][{tag:HuksTag.HUKS_TAG_ALGORITHM,value:HuksKeyAlg.HUKS_ALG_SM4},{tag:HuksTag.HUKS_TAG_BLOCK_MODE,value:HuksCipherMode.HUKS_MODE_CBC},{tag:HuksTag.HUKS_TAG_PADDING,value:HuksKeyPadding.HUKS_PADDING_PKCS7},{tag:HuksTag.HUKS_TAG_PURPOSE,value:HuksKeyPurpose.HUKS_KEY_PURPOSE_ENCRYPT},{tag:HuksTag.HUKS_TAG_AUTH_TOKEN,value:authToken}];try{// 初始化加密会话consthandleawaithuks.initSession(SM4_KEY_ALIAS,encryptParams);// 执行加密运算运算在TEE安全区constencryptResultawaithuks.finishSession(handle,plainBin.buffer);awaithuks.closeSession(handle);// 拆分iv与密文base64序列化存储constivArrnewUint8Array(encryptResult.slice(0,16));constcipherArrnewUint8Array(encryptResult.slice(16));return{iv:btoa(String.fromCharCode(...ivArr)),cipher:btoa(String.fromCharCode(...cipherArr))};}catch(err){consteerrasBusinessError;hilog.error(DOMAIN,TAG,加密失败${e.message});returnnull;}}3.4 工具类4SM4国密解密/** * HUKS SM4 解密还原原始明文 * param authToken 生物认证令牌 * param cipherBase64 加密密文 * param ivBase64 加密时生成的iv向量 * returns 原始明文 */asyncfunctionhuksSm4Decrypt(authToken:string,cipherBase64:string,ivBase64:string):Promisestring|null{if(!authToken)returnnull;// base64还原二进制constivBinUint8Array.from(atob(ivBase64),cc.charCodeAt(0));constcipherBinUint8Array.from(atob(cipherBase64),cc.charCodeAt(0));constfullBinnewUint8Array([...ivBin,...cipherBin]);constdecryptParams:huks.HuksParam[][{tag:HuksTag.HUKS_TAG_ALGORITHM,value:HuksKeyAlg.HUKS_ALG_SM4},{tag:HuksTag.HUKS_TAG_BLOCK_MODE,value:HuksCipherMode.HUKS_MODE_CBC},{tag:HuksTag.HUKS_TAG_PADDING,value:HuksKeyPadding.HUKS_PADDING_PKCS7},{tag:HuksTag.HUKS_TAG_PURPOSE,value:HuksKeyPurpose.HUKS_KEY_PURPOSE_DECRYPT},{tag:HuksTag.HUKS_TAG_AUTH_TOKEN,value:authToken}];try{consthandleawaithuks.initSession(SM4_KEY_ALIAS,decryptParams);constrawPlainawaithuks.finishSession(handle,fullBin.buffer);awaithuks.closeSession(handle);constdecodernewTextDecoder();returndecoder.decode(newUint8Array(rawPlain));}catch(err){consteerrasBusinessError;hilog.error(DOMAIN,TAG,解密失败${e.message});returnnull;}}3.5 工具类5密钥销毁卸载/重置场景asyncfunctiondeleteHuksKey(){try{awaithuks.deleteKeyItem(SM4_KEY_ALIAS,[]);hilog.info(DOMAIN,TAG,HUKS SM4密钥已彻底销毁);}catch{}}四、业务页面完整实战敏感信息加密存储演示页面实现生成密钥→指纹验证→加密管理员密码→解密展示适配商用Kiosk终端密码加密存储、医疗病历加密场景。EntryComponentV2struct HuksSm4SecurityPage{LocalplainInput:string;LocalcipherText:string;LocalivText:string;LocaldecryptResult:string无解密数据;LocalauthToken:string|nullnull;// 页面加载自动生成HUKS密钥aboutToAppear(){createHuksSm4Key();}// 唤起生物认证获取访问令牌asyncdoBiometricAuth(){this.authTokenawaitstartBiometricAuth();if(this.authToken){this.decryptResult生物认证成功可执行加密解密;}else{this.decryptResult指纹/人脸验证失败禁止访问密钥;}}// 执行SM4国密加密asyncdoEncrypt(){if(!this.authToken||!this.plainInput.trim())return;constresawaithuksSm4Encrypt(this.authToken,this.plainInput);if(res){this.cipherTextres.cipher;this.ivTextres.iv;this.decryptResult加密完成密文已安全存储;}}// 执行解密还原原始敏感数据asyncdoDecrypt(){if(!this.authToken||!this.cipherText||!this.ivText)return;constplainawaithuksSm4Decrypt(this.authToken,this.cipherText,this.ivText);this.decryptResultplain||解密失败密钥访问权限不足;}build(){Column({space:18}){Text(SecurityKit HUKS国密SM4 隐私加密实战).fontSize(22).fontWeight(FontWeight.Bold).margin({top:20});Text(this.decryptResult).fontSize(16).fontColor(this.authToken?#00B42A:#F53F3F);TextInput({text:this.plainInput}).width(90%).height(44).placeholder(输入敏感数据管理员密码、身份证、病历).onChange(vthis.plainInputv);Flex({wrap:FlexWrap.Wrap,gap:10}){Button(1.指纹/人脸验证密钥权限).onClick(()this.doBiometricAuth());Button(2.SM4国密加密).backgroundColor(#0A59F7).onClick(()this.doEncrypt());Button(3.解密查看原始数据).backgroundColor(#0094FF).onClick(()this.doDecrypt());}.width(90%);Column({space:10}){Text(加密IV向量this.ivText).fontSize(12);Text(加密密文this.cipherText).fontSize(12);}.width(90%).padding(12).backgroundColor(#F5F7FA).borderRadius(8);Blank();Text( 密钥全程保存在TEE可信执行环境应用无法获取密钥明文恢复出厂自动销毁).fontSize(12).fontColor(#888888).margin({bottom:30});}.width(100%).height(100%).padding({left:16,right:16});}}五、商用拓展场景落地方案5.1 场景1CoreFileKit超大日志分片国密加密百万级日志文件使用CoreFileKit流式读取搭配HUKS SM4分片加密全程无大内存占用日志文件加密后存入filesDir即使文件被导出也无法解密。// 流式文件加密伪代码asyncfunctionstreamEncryptLogFile(srcPath:string,dstPath:string,authToken:string){constreadStreamfs.createStream(srcPath,FileOpenMode.READ_ONLY);constwriteStreamfs.createStream(dstPath,FileOpenMode.WRITE|FileOpenMode.CREATE);letoffset0;constchunkSize4096;while(offsetfs.statSync(srcPath).size){constbufnewArrayBuffer(chunkSize);constlenawaitreadStream.read(buf,{offset});offsetlen;// HUKS分片加密二进制块constencResawaithuksSm4EncryptBinary(authToken,newUint8Array(buf,0,len));awaitwriteStream.write(encRes);}awaitreadStream.close();awaitwriteStream.close();}5.2 场景2分布式MultiKit跨设备加密数据同步多端同步的敏感表单、患者信息先本地HUKS加密再存入MultiKVStore跨设备同步密文解密必须本地完成生物认证杜绝传输过程明文泄露。5.3 场景3Kiosk商用终端管理员密码加密自助终端管理员退出锁机密码禁止硬编码使用HUKS SM4加密存储仅运维人员指纹验证后才可解密读取密码符合门店无人值守安全规范。六、高频生产踩坑完整解决方案坑1解密报错 权限不足未完成生物认证根因生成密钥时配置HUKS_AUTH_TYPE_BIOMETRIC所有加解密操作必须携带有效生物认证token修复每次启动解密、加密前强制调用startBiometricAuth获取令牌。坑2应用卸载后仍能解密历史文件密钥存储在HUKS系统服务应用卸载时调用deleteKeyItem销毁密钥设备恢复出厂设置TEE内密钥物理层永久清除密文彻底无法解密。坑3SM4 CBC模式解密乱码、中文丢失根因IV向量未与密文绑定存储加密时16字节IV必须和密文一同持久化解密时传入完全一致的iv规范加密后同时存储iv、cipher两段base64数据不可丢弃iv。坑4模拟器无法调用HUKS密钥接口模拟器无TEE可信安全硬件HUKS服务未完整运行密钥生成、生物认证必须真机调试。坑5多页面重复生成同名密钥冲突解决方案工具类生成密钥前先执行deleteHuksKey删除旧密钥避免别名冲突抛出异常。坑6锁屏后未重新指纹验证加密接口直接拦截设计规范密钥配置HUKS_TAG_AUTH_TIMEOUT0每次加解密必须重新生物校验高安全场景强制开启。坑7使用第三方JS国密库存在安全漏洞第三方库密钥存在应用内存中易被逆向dump商用/政务场景强制使用系统SecurityKit HUKS硬件国密方案满足等保合规。七、政企商用生产级最佳实践密钥分层管控普通业务配置、日志使用基础SM4密钥身份证、支付、病历等高敏感数据开启强生物认证密钥分级防护全链路日志审计密钥生成、生物认证、加密解密、密钥销毁全部打印hilog日志安全事件可追溯最小权限原则仅申请HUKS_KEY_MANAGE、USER_AUTHENTICATION两项必需权限不申请多余系统权限离线场景兼容HUKS运算完全本地TEE执行无网络依赖适配政务、门店离线自助终端多算法组合防护敏感数据SM4存储加密 SM3完整性哈希校验防止密文被篡改MDM远程密钥管控政企批量终端搭配HEM设备管理平台远程下发指令销毁HUKS密钥批量重置终端隐私数据禁止密钥透出应用全程不导出密钥明文不打印密钥日志不通过IPC、分布式传输密钥仅传输加密后的密文。八、方案总结鸿蒙7kit.SecurityKitHUKS密钥托管是符合国家商用密码规范、等保2.0的端侧安全标准方案依托TEE硬件可信执行环境实现密钥不出安全区、国密硬件加速、生物分级访问、应用绑定隔离、一键不可逆销毁四大核心安全能力。本文完整落地SM4国密分片加密、指纹解锁密钥、沙箱敏感文件存储全套业务代码适配政务一体机、医疗终端、零售商用Kiosk、金融多端协同等高隐私需求场景。相比第三方JS加密库、硬编码密钥传统方案从硬件底层杜绝密钥泄露、数据逆向破解风险是鸿蒙政企商用应用隐私安全落地的标准化生产方案。
