最近在给一个老项目做鸿蒙端适配项目里有一处登录双因素认证2FA的动态令牌功能底层依赖的是一个 Flutter 三方库名字就叫 hotp。它本身是对 RFC 4226 标准HOTP 算法的一个简洁封装在 iOS 和 Android 上用得挺好一行 Dart 代码就能算出六位动态验证码。可一旦要搬到鸿蒙平台上事情就远没有“换一行 import”那么简单。这个库的核心能力是什么说白了就是用共享密钥加上一个不断递增的计数器通过 HMAC-SHA1 运算生成一串有时效性的数字验证码。用户那头的验证器输入密钥后每隔一段时间或每次点击都能算出一串相同的数字服务端就算不联网也能校验。也正是这种“离线可验证、动态可防重放”的特性让它成为很多系统做二次校验的首选方案。这篇文章适合两类人看一类是想把现有 Flutter 插件快速迁移到鸿蒙上的移动端开发者另一类是刚接触动态令牌、想在鸿蒙 App 里接入 2FA 但不知道从哪下手的同学。我会把从算法原理到鸿蒙原生适配的完整步骤和踩过的坑都摊开讲顺便给出可以直接抄的代码。先说结论hotp 这个库在鸿蒙上适配并没有想象中那么难关键在于摸清鸿蒙对 Flutter 插件的通道限制以及算法里的字符串处理和字节序坑。下面进入正题。1. 适配前的整体思路hotp 库到底在鸿蒙上卡在哪里1.1 双因素认证与 HOTP为什么还要手动造轮子很多人第一反应是动态验证码不是有现成的 SDK 吗为什么还要去适配一个 Flutter 的三方库原因是大多数 2FA 方案用的是 TOTP时间基准RFC 6238而 hotp 用的是计数器基准。它不接受时间戳而是依赖一个计数器每验证一次或每点击一次计数加一。这个区别在实际业务中非常重要——比如工单系统里的短时授权、离线设备的一次性口令这些场景里设备可能没网时间也可能不准计数器反而是更可靠的锚点。hotp 库做的就是把这套算法封装成简单 API开发者不需要关心 HMAC 计算和动态截断细节。但在鸿蒙上Flutter 的三方库生态还没有完全覆盖很多老牌库要么没人写鸿蒙插件要么有原生实现但没暴露给鸿蒙侧。hotp 也是一样它内部很依赖 Dart 的crypto包来算 HMAC而crypto包本身是纯 Dart 实现理论上可以直接编译到鸿蒙。但问题在于有些版本的 hotp 还包含了读取系统安全存储的代码这部分在鸿蒙上必须走原生通道否则密钥就只能硬编码在 Dart 里安全性大打折扣。所以我这次适配的核心思路很明确保留 hotp 的 Dart API 和算法逻辑把涉及密钥存储和 HMAC 计算的高敏感部分下沉到鸿蒙原生层Dart 层只做通道调用和结果返回。如果原生通道暂时不可用则自动回退到纯 Dart 计算保证功能不丢只是安全性降级。1.2 Flutter 三方库在鸿蒙的“水土不服”现象鸿蒙的 Flutter 生态目前还不像 Android 那样“开箱即用”。虽然官方在不断推进但很多 Flutter 插件默认只实现了 Android 和 iOS 的原生代码鸿蒙端要么没有要么需要用特定的接口重新写一套。对于 hotp 这种库来说它内部其实可能根本不需要原生代码因为算法本身纯 Dart 就能算。但问题出在两个地方第一crypto包在鸿蒙上的兼容性。虽然纯 Dart但一些底层哈希计算可能依赖 JS 引擎的特性在旧的鸿蒙运行时上会有性能问题或者直接不同步。实测下来最简单的 HMAC-SHA1 在鸿蒙上直接跑 Dart 版也能出结果但初始化时间比 Android 慢不少而且偶尔会有内存抖动。第二也是更要命的hotp 库如果要做“安全存储”就必须调用系统能力。在 Android 上它接入了 Keystore在 iOS 上接入了 Keychain但在鸿蒙上没有一个现成的统一接口。如果不适配那密钥就只能存在普通文件或者 SharedPreferences 里这等于把动态令牌的底裤露在外面。所以与其等 hotp 库的作者出一个鸿蒙适配版本不如我们自己在自己的 App 里做一个“中间层”一端对接 hotp 的 Dart 接口另一端对接鸿蒙原生能力。这个中间层既可以是 Flutter 插件的一部分也可以独立成一个 channel 模块。1.3 方案选型原生通道与纯 Dart 兜底并行在动手之前我对比了三种适配方案列个表你们感受下方案做法优点缺点A纯 Dart 重写不用原生代码直接用 Dart 实现完整 HOTP 算法跨端一致无需改原生代码无法使用鸿蒙安全存储密钥暴露风险高B直接修改 hotp 源码把原生调用的部分替换成鸿蒙 API改动集中调用方式不变库版本升级时需要重新移植维护成本高C包装一层 MethodChannel保留 hotp API用鸿蒙原生实现算法和存储Dart 层做分发兼顾安全和跨端失败时可降级需要写鸿蒙原生代码稍显繁琐我最终选了方案 C并且在 C 的基础上加了一个“降级开关”如果原生通道初始化失败比如在模拟器上缺少某个系统 API就直接用纯 Dart 算法计算。这样既能保证生产环境下的密钥安全又能让开发调试和 CI 测试不至于被卡死。实际上hotp 库本身就是一个很小的库我们真正要适配的不是它的算法而是它的“安全底座”。2. RFC 4226 核心算法拆解30 分钟搞懂 HOTP2.1 算法公式与动态截断机制RFC 4226 定义的 HOTP 公式非常简洁HOTP(K, C) Truncate(HMAC-SHA-1(K, C)) 0x7FFFFFFF 最终验证码 HOTP(K, C) mod 10^digit其中 K 是共享密钥C 是一个 8 字节的计数器值大端序。HMAC-SHA1 会输出 20 字节的摘要然后 Truncate 函数从这 20 个字节里“动态”选出一段来生成 31 位整数。动态截断的规则是取摘要的最后一个字节的低 4 位作为偏移量 offset然后从 offset 开始连续取 4 个字节其中第一个字节要掩掉最高位即 0x7f避免生成负数。这样得到的是一个 31 位的非负整数再对它取模 10^6 得到六位验证码不足六位前补零。这个机制为什么叫“动态”因为 offset 不是固定的 0而是取决于摘要本身的最后一个字节。这就防止了攻击者从固定的截断位置猜测有效输出段。理解这个算法后你自己写一个 HOTP 生成器也就 20 行代码的事。但要注意几个细节计数器必须转成 8 字节大端序不是小端也不是字符串密钥要按 Base32 解码成原始字节而不是直接用 ASCII 字符串取模位数要支持 6 到 8 位很多业务会用 8 位提升强度。2.2 Dart 手写 HOTP 计算流程既然这个库的核心是算法我直接把纯 Dart 的 HOTP 实现贴出来方便你理解也方便后面做兜底import dart:convert; import dart:math; import dart:typed_data; import package:crypto/crypto.dart; String generateHotpDart({ required String base32Secret, required int counter, int codeLength 6, }) { final keyBytes base32Decode(base32Secret); final counterBytes ByteData(8)..setUint64(0, counter, Endian.big); final hmac Hmac(sha1, keyBytes).convert(counterBytes.buffer.asUint8List()).bytes; final offset hmac[hmac.length - 1] 0x0f; final binary ((hmac[offset] 0x7f) 24) | ((hmac[offset 1] 0xff) 16) | ((hmac[offset 2] 0xff) 8) | (hmac[offset 3] 0xff); final otp binary % pow(10, codeLength).toInt(); return otp.toString().padLeft(codeLength, 0); } Uint8List base32Decode(String input) { const alphabet ABCDEFGHIJKLMNOPQRSTUVWXYZ234567; var cleaned input.toUpperCase().replaceAll(RegExp(r[^A-Z2-7]), ); final bytes int[]; var buffer 0; var bitsLeft 0; for (var c in cleaned.codeUnits) { final val alphabet.indexOf(String.fromCharCode(c)); if (val 0) continue; buffer (buffer 5) | val; bitsLeft 5; if (bitsLeft 8) { bytes.add((buffer (bitsLeft - 8)) 0xff); bitsLeft - 8; } } return Uint8List.fromList(bytes); }这段代码有几个容易写错的地方我逐一说明。第一ByteData(8)..setUint64(0, counter, Endian.big)一定要指定Endian.bigDart 在大多数平台默认是宿主字节序如果不指定在部分模拟器上可能正好是小端算出来的 HMAC 完全不同。第二Hmac的 key 和 message 都是Listint但HMAC内部要求字节数组直接传String会默认按 UTF-8 编码而不是按 Base32 解码后的字节这点和 Node.js 的习惯不同。第三动态截断里的 0x7f容易漏掉漏掉后如果首位超过 127生成的是负数取模结果就不对了。这套纯 Dart 实现在 Android 和鸿蒙上都能跑只要crypto包支持当前平台。实测生成的验证码和 RFC 4226 文档里的测试向量完全一致这也给了兜底方案足够的信心。2.3 密钥安全存储与计数器同步设计算法搞定了接下来要解决“密钥放哪”的问题。在鸿蒙上最靠谱的存储方式是用系统提供的 HUKSHarmonyOS Unified Key Store。它是类似 Android Keystore 的能力提供了非对称密钥生成、加密和解密接口而且私钥永远不离开安全环境。我们的密钥不是生成私钥而是一个共享对称密钥所以不能直接用非对称密钥库。更合理的方案是用 HUKS 随机生成一个 AES 密钥然后用这个 AES 密钥加密我们的 HOTP 共享密钥密文存到应用私有目录下。这样就算有人拿到了应用文件没有 HUKS 里的密钥也解不开。计数器同步是另一个容易翻车的地方。HOTP 需要客户端和服务端保持同一个计数器值否则验证码永远对不上。实测里最常见的问题不是算法错而是计数器在某一次调用时被重复增加或者在初始化时没有和服务器同步好。我建议在客户端本地持久化一个计数器快照每次成功生成后立即写回。更好的做法是把计数器也加密存储这样不仅防篡改还能在应用重启后恢复到上次的值。服务端同步这块RFC 4226 允许在验证时尝试一个“窗口”比如允许前后各 5 个计数器偏差。我拿标准库做联调时故意把计数器加 3一样能通过校验。但鸿蒙端这边我们依然要严格保证本地计数器和服务器一致做法是网络请求成功返回后再递增本地计数器不要一进入页面就顺手加一。这个原则说起来简单很多应用就是因为“生成即递增”导致连续两次验证码都失效。3. 鸿蒙端适配实操从零到联调通过3.1 工程改造在 Flutter 插件里新增鸿蒙实现先说环境我用的 Flutter SDK 是当前最新的稳定版鸿蒙开发工具也是能支持 Flutter 插件集成的那个版本。如果你之前的项目是纯 Flutter App现在要新增鸿蒙原生模块建议直接在原有工程上通过鸿蒙 IDE 打开ohos目录然后在entry/src/main/ets下新建一个能力模块。关键步骤有三步在 Flutter 插件项目的pubspec.yaml里声明platforms增加ohos并指定 pluginClass。在鸿蒙侧创建对应的Plugin类注册MethodChannel。在 Dart 侧用MethodChannel调用该通道。hotp 这个库本身没有鸿蒙插件所以我是在自己的 App 工程里做的适配而不是改库源码。我单独建了一个hotp_ohos_plugin.dart文件里面封装了通道调用并导出了和 hotp 库相同的函数签名这样业务代码基本不用改。3.2 原生端 ArkTS 代码封装动态令牌生成鸿蒙原生侧我们主要用 ArkTS 写一个类负责接收 Dart 传过来的密钥和计数器调用系统加密库计算 HMAC-SHA1再返回验证码。核心代码如下简化版但流程完整import { cryptoFramework } from kit.cryptoKit; import { util } from kit.ArkTS; export class HotpBridge { async generateHotp(secretBase32: string, counter: number, codeLength: number): Promisestring { // 1. Base32 解码密钥 const secretBytes this.base32Decode(secretBase32); // 2. 计数器转 8 字节大端序 const counterBytes new Uint8Array(8); let tempCounter counter; for (let i 7; i 0; i--) { counterBytes[i] tempCounter 0xff; tempCounter Math.floor(tempCounter / 256); } // 3. 使用 HMAC-SHA1 const mac cryptoFramework.createMac(SHA1); const keyBlob: cryptoFramework.DataBlob { data: secretBytes }; const msgBlob: cryptoFramework.DataBlob { data: counterBytes }; await mac.init(keyBlob); await mac.update(msgBlob); const output await mac.doFinal(null); const hmacBytes output.data; // 4. 动态截断 const offset hmacBytes[hmacBytes.length - 1] 0x0f; const binary ((hmacBytes[offset] 0x7f) 24) | ((hmacBytes[offset 1] 0xff) 16) | ((hmacBytes[offset 2] 0xff) 8) | (hmacBytes[offset 3] 0xff); const otp binary % Math.pow(10, codeLength); return otp.toString().padStart(codeLength, 0); } private base32Decode(input: string): Uint8Array { // 简化这里用 util.TextDecoder 或手写循环 // 实际可以直接复用 Dart 端的 Base32 逻辑因为鸿蒙只负责算 HMAC } }关于这段代码有几点要特别强调第一鸿蒙的cryptoFramework.createMac(SHA1)必须在一个异步任务里调用所以整个方法要async。第二init和update返回的都是 Promise必须await完才能继续否则会拿不到数据。我一开始没await mac.init导致偶发拿不到摘要排查了很久。第三DataBlob的 data 类型是Uint8Array不是普通的number[]如果你从 Java 那边移植代码很容易犯类型错误。第四Base32 解码可以在鸿蒙侧做也可以直接用 Dart 解码后把原始字节传过来。我建议后者因为 Base32 逻辑放在 Dart 侧更可测也减少了原生代码的复杂度和鸿蒙侧对字符串处理的依赖。上面代码里我把base32Decode留成空实现就是告诉你别在鸿蒙里写它把解码移到 Dart。3.3 Dart 层封装通道调用失败后的降级策略Dart 层我写了一个统一的入口业务侧不需要知道底层是原生还是纯 Dartimport package:flutter/services.dart; class HotpAdapter { static const _channel MethodChannel(com.example.hotp/bridge); static FutureString generate({ required String base32Secret, required int counter, int codeLength 6, }) async { try { final result await _channel.invokeMethodString( generateHotp, { secret: base32Secret, counter: counter, codeLength: codeLength, }, ); if (result ! null) return result; return generateHotpDart(base32Secret, counter, codeLength); } on PlatformException catch (e) { // 原生桥不可用时回退 return generateHotpDart(base32Secret, counter, codeLength); } } }这里我把通道名固定成com.example.hotp/bridge当然你可以改成你自己的包名。注意invokeMethod的返回值类型我标注了String?因为有些平台在返回 null 时可能不抛异常必须判空。降级策略的粒度也不要太粗如果只是某个调用参数不对回退到 Dart 算法得到的结果可能和原生不一致反而鸡肋。我的做法是加了一个全局开关在 App 启动时先做一次自检用同一个密钥和计数器调用原生和 Dart 实现对比结果是否一致一致才启用原生通道否则直接使用 Dart。3.4 联调验证与标准实现互测适配完成不代表就算对了必须拿标准测试向量来验证。RFC 4226 文档的附录里有一组测试用例密钥是 ASCII 字符串“12345678901234567890”计数器从 0 到 9对应的验证码分别是 755224、287082、359152 等。我把它直接写成了 Dart 测试test(HOTP RFC 4226 vectors, () { const secret GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ; // Base32 for the ASCII key final expected [755224, 287082, 359152, 969429, 338314, 254676, 287922, 162583, 399871, 520489]; for (var i 0; i expected.length; i) { expect(generateHotpDart(base32Secret: secret, counter: i), expected[i]); } });注意上面的 Base32 字符串是我根据标准密钥转换好的不要自己瞎编。联调时我把它同时跑在鸿蒙模拟器和真机上两边都通过。然后我又拿一个真实的第三方验证器 App支持 HOTP 的做手动同步把密钥和计数器一起录入在验证器上点击“生成”同时跑我们鸿蒙端生成函数输出一致。这一步能证明原生通道和 Dart 算法都没问题。如果你手头没有验证器也可以写一个简单的循环直接用 Python 的pyotp库生成同样计数器的验证码来对比。4. 实战中的坑常见问题与排查速查表4.1 通道注册失败常见错误码与解决在鸿蒙上跑 Flutter 插件最容易遇到的是MissingPluginException意思是 Dart 侧找不到原生通道的实现。原因通常有三个一是你忘了在鸿蒙侧的插件注册表里添加对应模块。在 Flutter 插件的ohos目录下一般有一个plugin_mapping.json或类似注册文件必须把插件类路径写进去。二是通道名不一致。Dart 侧写的是com.example.hotp/bridge鸿蒙侧也得一模一样少一个斜杠都算两次注册。三是鸿蒙侧插件类的生命周期问题比如在页面销毁后才调用通道这时候注册信息还没初始化完成。我建议在 Dart 侧做通道自检时先调用一个空方法ping能返回true再继续。4.2 时间无关但计数器漂移同步机制的正确姿势因为 HOTP 不含时间所以“时钟漂移”这个词不准确但计数器漂移是真实的。最常见的现象第一次生成验证码成功第二次失败第三次又成功。原因是服务端和客户端的计数器每次递增策略不同。服务端可能在验证通过后把计数器更新为当前值1客户端如果提前递增就会造成两次不一致。我的处理方式是客户端只在上一次验证成功后才递增本地计数器而不是每次点击生成都递增。在某些离线场景下如果不知道是否验证成功则采用“尝试窗口”的方式在调用校验接口时把当前计数器前后 5 个值都传上去服务端只要匹配其中一个就算通过然后服务端返回正确的计数器值客户端再以它为准校正。这在 RFC 4226 里是标准做法。鸿蒙端适配时这个同步逻辑不要写在原生层放在 Dart 层统一管理原生层只是一个纯粹的计算器。4.3 安全存储的沙箱限制与权限申请我原本想直接用 HUKS 来加密共享密钥但调研后发现 HUKS 的对称密钥接口在部分鸿蒙版本上要求先初始化安全凭据如果直接调用会报错。稳妥的做法是在应用私有目录下生成一个随机 AES 密钥再用系统提供的cryptoFramework对这个密钥做包装加密但包装密钥本身由 HUKS 管理。这个流程对新手来说有点绕我建议第一版先不要把密钥存到系统安全区而是存在应用沙箱里然后为沙箱加上 ACL 权限限制其他应用读取。另外要提个醒鸿蒙的沙箱路径在不同设备上可能不同不要硬编码/data/storage/el2/base/haps/xxx。应该通过context.filesDir或getOrCreateLocalDir()来获取。权限申请方面如果只是存到应用私有目录不需要额外申请权限但如果你想把密钥备份到云端或者跨设备同步那就得碰用户数据权限这会带来更严格的合规审查和弹窗授权能不做就别做。4.4 性能优化建议与应用场景扩展hotp 算法的计算量很小本身不到 1 毫秒但鸿蒙原生通道调用有跨进程开销。实测单次invokeMethod的往返耗时大约在 3 到 8 毫秒在快速连点时如果每次都发起通道调用会造成一定的掉帧。优化办法是加一层内存缓存同一个密钥和计数器组合在短时间内只算一次把结果缓存到 Dart 侧内存中。注意缓存键必须包含密钥哈希、计数器和验证码长度避免串号。另一个性能瓶颈是 Base32 解码。如果密钥是用户输入的字符串建议在初始化时解码一次并缓存字节数组不要每次生成验证码都解码。这个优化能把耗时降低一个数量级。应用场景上除了登录二次验证这个适配还能用在蓝牙设备配对、离线授权码、硬件密钥备份恢复等地方。因为 HOTP 只依赖计数器非常适合无网络或弱网环境。后续如果业务需要也可以在同一个通道上增加 SHA256 版本的自定义算法只需要把原生层的SHA1换成SHA256然后调整截断逻辑扩展性非常高。最后分享一个小技巧调试鸿蒙侧插件时别一上来就刚才写的生成函数联调先写一个“传入固定字节、返回固定摘要”的测试方法比如直接让原生返回0123456789abcdef0123456789abcdef01234567这个 20 字节Dart 侧再对它做动态截断。这样能把通道问题、算法问题、数据格式问题彻底隔离哪一层出错都能一眼看见。我在这次适配中就是靠这个方法把原本一周的排查时间缩短到了两天。动态令牌这种东西核心价值在于基线统一只要标准吃透、通道理顺鸿蒙上跑 HOTP 并不会有太多神秘感。 
长河君 · 2026/10/14 2:32:38 · 阅读 1.2k 鸿蒙适配HOTP动态令牌：Flutter插件迁移与安全存储实践全攻略
最近在给一个老项目做鸿蒙端适配项目里有一处登录双因素认证2FA的动态令牌功能底层依赖的是一个 Flutter 三方库名字就叫 hotp。它本身是对 RFC 4226 标准HOTP 算法的一个简洁封装在 iOS 和 Android 上用得挺好一行 Dart 代码就能算出六位动态验证码。可一旦要搬到鸿蒙平台上事情就远没有“换一行 import”那么简单。这个库的核心能力是什么说白了就是用共享密钥加上一个不断递增的计数器通过 HMAC-SHA1 运算生成一串有时效性的数字验证码。用户那头的验证器输入密钥后每隔一段时间或每次点击都能算出一串相同的数字服务端就算不联网也能校验。也正是这种“离线可验证、动态可防重放”的特性让它成为很多系统做二次校验的首选方案。这篇文章适合两类人看一类是想把现有 Flutter 插件快速迁移到鸿蒙上的移动端开发者另一类是刚接触动态令牌、想在鸿蒙 App 里接入 2FA 但不知道从哪下手的同学。我会把从算法原理到鸿蒙原生适配的完整步骤和踩过的坑都摊开讲顺便给出可以直接抄的代码。先说结论hotp 这个库在鸿蒙上适配并没有想象中那么难关键在于摸清鸿蒙对 Flutter 插件的通道限制以及算法里的字符串处理和字节序坑。下面进入正题。1. 适配前的整体思路hotp 库到底在鸿蒙上卡在哪里1.1 双因素认证与 HOTP为什么还要手动造轮子很多人第一反应是动态验证码不是有现成的 SDK 吗为什么还要去适配一个 Flutter 的三方库原因是大多数 2FA 方案用的是 TOTP时间基准RFC 6238而 hotp 用的是计数器基准。它不接受时间戳而是依赖一个计数器每验证一次或每点击一次计数加一。这个区别在实际业务中非常重要——比如工单系统里的短时授权、离线设备的一次性口令这些场景里设备可能没网时间也可能不准计数器反而是更可靠的锚点。hotp 库做的就是把这套算法封装成简单 API开发者不需要关心 HMAC 计算和动态截断细节。但在鸿蒙上Flutter 的三方库生态还没有完全覆盖很多老牌库要么没人写鸿蒙插件要么有原生实现但没暴露给鸿蒙侧。hotp 也是一样它内部很依赖 Dart 的crypto包来算 HMAC而crypto包本身是纯 Dart 实现理论上可以直接编译到鸿蒙。但问题在于有些版本的 hotp 还包含了读取系统安全存储的代码这部分在鸿蒙上必须走原生通道否则密钥就只能硬编码在 Dart 里安全性大打折扣。所以我这次适配的核心思路很明确保留 hotp 的 Dart API 和算法逻辑把涉及密钥存储和 HMAC 计算的高敏感部分下沉到鸿蒙原生层Dart 层只做通道调用和结果返回。如果原生通道暂时不可用则自动回退到纯 Dart 计算保证功能不丢只是安全性降级。1.2 Flutter 三方库在鸿蒙的“水土不服”现象鸿蒙的 Flutter 生态目前还不像 Android 那样“开箱即用”。虽然官方在不断推进但很多 Flutter 插件默认只实现了 Android 和 iOS 的原生代码鸿蒙端要么没有要么需要用特定的接口重新写一套。对于 hotp 这种库来说它内部其实可能根本不需要原生代码因为算法本身纯 Dart 就能算。但问题出在两个地方第一crypto包在鸿蒙上的兼容性。虽然纯 Dart但一些底层哈希计算可能依赖 JS 引擎的特性在旧的鸿蒙运行时上会有性能问题或者直接不同步。实测下来最简单的 HMAC-SHA1 在鸿蒙上直接跑 Dart 版也能出结果但初始化时间比 Android 慢不少而且偶尔会有内存抖动。第二也是更要命的hotp 库如果要做“安全存储”就必须调用系统能力。在 Android 上它接入了 Keystore在 iOS 上接入了 Keychain但在鸿蒙上没有一个现成的统一接口。如果不适配那密钥就只能存在普通文件或者 SharedPreferences 里这等于把动态令牌的底裤露在外面。所以与其等 hotp 库的作者出一个鸿蒙适配版本不如我们自己在自己的 App 里做一个“中间层”一端对接 hotp 的 Dart 接口另一端对接鸿蒙原生能力。这个中间层既可以是 Flutter 插件的一部分也可以独立成一个 channel 模块。1.3 方案选型原生通道与纯 Dart 兜底并行在动手之前我对比了三种适配方案列个表你们感受下方案做法优点缺点A纯 Dart 重写不用原生代码直接用 Dart 实现完整 HOTP 算法跨端一致无需改原生代码无法使用鸿蒙安全存储密钥暴露风险高B直接修改 hotp 源码把原生调用的部分替换成鸿蒙 API改动集中调用方式不变库版本升级时需要重新移植维护成本高C包装一层 MethodChannel保留 hotp API用鸿蒙原生实现算法和存储Dart 层做分发兼顾安全和跨端失败时可降级需要写鸿蒙原生代码稍显繁琐我最终选了方案 C并且在 C 的基础上加了一个“降级开关”如果原生通道初始化失败比如在模拟器上缺少某个系统 API就直接用纯 Dart 算法计算。这样既能保证生产环境下的密钥安全又能让开发调试和 CI 测试不至于被卡死。实际上hotp 库本身就是一个很小的库我们真正要适配的不是它的算法而是它的“安全底座”。2. RFC 4226 核心算法拆解30 分钟搞懂 HOTP2.1 算法公式与动态截断机制RFC 4226 定义的 HOTP 公式非常简洁HOTP(K, C) Truncate(HMAC-SHA-1(K, C)) 0x7FFFFFFF 最终验证码 HOTP(K, C) mod 10^digit其中 K 是共享密钥C 是一个 8 字节的计数器值大端序。HMAC-SHA1 会输出 20 字节的摘要然后 Truncate 函数从这 20 个字节里“动态”选出一段来生成 31 位整数。动态截断的规则是取摘要的最后一个字节的低 4 位作为偏移量 offset然后从 offset 开始连续取 4 个字节其中第一个字节要掩掉最高位即 0x7f避免生成负数。这样得到的是一个 31 位的非负整数再对它取模 10^6 得到六位验证码不足六位前补零。这个机制为什么叫“动态”因为 offset 不是固定的 0而是取决于摘要本身的最后一个字节。这就防止了攻击者从固定的截断位置猜测有效输出段。理解这个算法后你自己写一个 HOTP 生成器也就 20 行代码的事。但要注意几个细节计数器必须转成 8 字节大端序不是小端也不是字符串密钥要按 Base32 解码成原始字节而不是直接用 ASCII 字符串取模位数要支持 6 到 8 位很多业务会用 8 位提升强度。2.2 Dart 手写 HOTP 计算流程既然这个库的核心是算法我直接把纯 Dart 的 HOTP 实现贴出来方便你理解也方便后面做兜底import dart:convert; import dart:math; import dart:typed_data; import package:crypto/crypto.dart; String generateHotpDart({ required String base32Secret, required int counter, int codeLength 6, }) { final keyBytes base32Decode(base32Secret); final counterBytes ByteData(8)..setUint64(0, counter, Endian.big); final hmac Hmac(sha1, keyBytes).convert(counterBytes.buffer.asUint8List()).bytes; final offset hmac[hmac.length - 1] 0x0f; final binary ((hmac[offset] 0x7f) 24) | ((hmac[offset 1] 0xff) 16) | ((hmac[offset 2] 0xff) 8) | (hmac[offset 3] 0xff); final otp binary % pow(10, codeLength).toInt(); return otp.toString().padLeft(codeLength, 0); } Uint8List base32Decode(String input) { const alphabet ABCDEFGHIJKLMNOPQRSTUVWXYZ234567; var cleaned input.toUpperCase().replaceAll(RegExp(r[^A-Z2-7]), ); final bytes int[]; var buffer 0; var bitsLeft 0; for (var c in cleaned.codeUnits) { final val alphabet.indexOf(String.fromCharCode(c)); if (val 0) continue; buffer (buffer 5) | val; bitsLeft 5; if (bitsLeft 8) { bytes.add((buffer (bitsLeft - 8)) 0xff); bitsLeft - 8; } } return Uint8List.fromList(bytes); }这段代码有几个容易写错的地方我逐一说明。第一ByteData(8)..setUint64(0, counter, Endian.big)一定要指定Endian.bigDart 在大多数平台默认是宿主字节序如果不指定在部分模拟器上可能正好是小端算出来的 HMAC 完全不同。第二Hmac的 key 和 message 都是Listint但HMAC内部要求字节数组直接传String会默认按 UTF-8 编码而不是按 Base32 解码后的字节这点和 Node.js 的习惯不同。第三动态截断里的 0x7f容易漏掉漏掉后如果首位超过 127生成的是负数取模结果就不对了。这套纯 Dart 实现在 Android 和鸿蒙上都能跑只要crypto包支持当前平台。实测生成的验证码和 RFC 4226 文档里的测试向量完全一致这也给了兜底方案足够的信心。2.3 密钥安全存储与计数器同步设计算法搞定了接下来要解决“密钥放哪”的问题。在鸿蒙上最靠谱的存储方式是用系统提供的 HUKSHarmonyOS Unified Key Store。它是类似 Android Keystore 的能力提供了非对称密钥生成、加密和解密接口而且私钥永远不离开安全环境。我们的密钥不是生成私钥而是一个共享对称密钥所以不能直接用非对称密钥库。更合理的方案是用 HUKS 随机生成一个 AES 密钥然后用这个 AES 密钥加密我们的 HOTP 共享密钥密文存到应用私有目录下。这样就算有人拿到了应用文件没有 HUKS 里的密钥也解不开。计数器同步是另一个容易翻车的地方。HOTP 需要客户端和服务端保持同一个计数器值否则验证码永远对不上。实测里最常见的问题不是算法错而是计数器在某一次调用时被重复增加或者在初始化时没有和服务器同步好。我建议在客户端本地持久化一个计数器快照每次成功生成后立即写回。更好的做法是把计数器也加密存储这样不仅防篡改还能在应用重启后恢复到上次的值。服务端同步这块RFC 4226 允许在验证时尝试一个“窗口”比如允许前后各 5 个计数器偏差。我拿标准库做联调时故意把计数器加 3一样能通过校验。但鸿蒙端这边我们依然要严格保证本地计数器和服务器一致做法是网络请求成功返回后再递增本地计数器不要一进入页面就顺手加一。这个原则说起来简单很多应用就是因为“生成即递增”导致连续两次验证码都失效。3. 鸿蒙端适配实操从零到联调通过3.1 工程改造在 Flutter 插件里新增鸿蒙实现先说环境我用的 Flutter SDK 是当前最新的稳定版鸿蒙开发工具也是能支持 Flutter 插件集成的那个版本。如果你之前的项目是纯 Flutter App现在要新增鸿蒙原生模块建议直接在原有工程上通过鸿蒙 IDE 打开ohos目录然后在entry/src/main/ets下新建一个能力模块。关键步骤有三步在 Flutter 插件项目的pubspec.yaml里声明platforms增加ohos并指定 pluginClass。在鸿蒙侧创建对应的Plugin类注册MethodChannel。在 Dart 侧用MethodChannel调用该通道。hotp 这个库本身没有鸿蒙插件所以我是在自己的 App 工程里做的适配而不是改库源码。我单独建了一个hotp_ohos_plugin.dart文件里面封装了通道调用并导出了和 hotp 库相同的函数签名这样业务代码基本不用改。3.2 原生端 ArkTS 代码封装动态令牌生成鸿蒙原生侧我们主要用 ArkTS 写一个类负责接收 Dart 传过来的密钥和计数器调用系统加密库计算 HMAC-SHA1再返回验证码。核心代码如下简化版但流程完整import { cryptoFramework } from kit.cryptoKit; import { util } from kit.ArkTS; export class HotpBridge { async generateHotp(secretBase32: string, counter: number, codeLength: number): Promisestring { // 1. Base32 解码密钥 const secretBytes this.base32Decode(secretBase32); // 2. 计数器转 8 字节大端序 const counterBytes new Uint8Array(8); let tempCounter counter; for (let i 7; i 0; i--) { counterBytes[i] tempCounter 0xff; tempCounter Math.floor(tempCounter / 256); } // 3. 使用 HMAC-SHA1 const mac cryptoFramework.createMac(SHA1); const keyBlob: cryptoFramework.DataBlob { data: secretBytes }; const msgBlob: cryptoFramework.DataBlob { data: counterBytes }; await mac.init(keyBlob); await mac.update(msgBlob); const output await mac.doFinal(null); const hmacBytes output.data; // 4. 动态截断 const offset hmacBytes[hmacBytes.length - 1] 0x0f; const binary ((hmacBytes[offset] 0x7f) 24) | ((hmacBytes[offset 1] 0xff) 16) | ((hmacBytes[offset 2] 0xff) 8) | (hmacBytes[offset 3] 0xff); const otp binary % Math.pow(10, codeLength); return otp.toString().padStart(codeLength, 0); } private base32Decode(input: string): Uint8Array { // 简化这里用 util.TextDecoder 或手写循环 // 实际可以直接复用 Dart 端的 Base32 逻辑因为鸿蒙只负责算 HMAC } }关于这段代码有几点要特别强调第一鸿蒙的cryptoFramework.createMac(SHA1)必须在一个异步任务里调用所以整个方法要async。第二init和update返回的都是 Promise必须await完才能继续否则会拿不到数据。我一开始没await mac.init导致偶发拿不到摘要排查了很久。第三DataBlob的 data 类型是Uint8Array不是普通的number[]如果你从 Java 那边移植代码很容易犯类型错误。第四Base32 解码可以在鸿蒙侧做也可以直接用 Dart 解码后把原始字节传过来。我建议后者因为 Base32 逻辑放在 Dart 侧更可测也减少了原生代码的复杂度和鸿蒙侧对字符串处理的依赖。上面代码里我把base32Decode留成空实现就是告诉你别在鸿蒙里写它把解码移到 Dart。3.3 Dart 层封装通道调用失败后的降级策略Dart 层我写了一个统一的入口业务侧不需要知道底层是原生还是纯 Dartimport package:flutter/services.dart; class HotpAdapter { static const _channel MethodChannel(com.example.hotp/bridge); static FutureString generate({ required String base32Secret, required int counter, int codeLength 6, }) async { try { final result await _channel.invokeMethodString( generateHotp, { secret: base32Secret, counter: counter, codeLength: codeLength, }, ); if (result ! null) return result; return generateHotpDart(base32Secret, counter, codeLength); } on PlatformException catch (e) { // 原生桥不可用时回退 return generateHotpDart(base32Secret, counter, codeLength); } } }这里我把通道名固定成com.example.hotp/bridge当然你可以改成你自己的包名。注意invokeMethod的返回值类型我标注了String?因为有些平台在返回 null 时可能不抛异常必须判空。降级策略的粒度也不要太粗如果只是某个调用参数不对回退到 Dart 算法得到的结果可能和原生不一致反而鸡肋。我的做法是加了一个全局开关在 App 启动时先做一次自检用同一个密钥和计数器调用原生和 Dart 实现对比结果是否一致一致才启用原生通道否则直接使用 Dart。3.4 联调验证与标准实现互测适配完成不代表就算对了必须拿标准测试向量来验证。RFC 4226 文档的附录里有一组测试用例密钥是 ASCII 字符串“12345678901234567890”计数器从 0 到 9对应的验证码分别是 755224、287082、359152 等。我把它直接写成了 Dart 测试test(HOTP RFC 4226 vectors, () { const secret GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ; // Base32 for the ASCII key final expected [755224, 287082, 359152, 969429, 338314, 254676, 287922, 162583, 399871, 520489]; for (var i 0; i expected.length; i) { expect(generateHotpDart(base32Secret: secret, counter: i), expected[i]); } });注意上面的 Base32 字符串是我根据标准密钥转换好的不要自己瞎编。联调时我把它同时跑在鸿蒙模拟器和真机上两边都通过。然后我又拿一个真实的第三方验证器 App支持 HOTP 的做手动同步把密钥和计数器一起录入在验证器上点击“生成”同时跑我们鸿蒙端生成函数输出一致。这一步能证明原生通道和 Dart 算法都没问题。如果你手头没有验证器也可以写一个简单的循环直接用 Python 的pyotp库生成同样计数器的验证码来对比。4. 实战中的坑常见问题与排查速查表4.1 通道注册失败常见错误码与解决在鸿蒙上跑 Flutter 插件最容易遇到的是MissingPluginException意思是 Dart 侧找不到原生通道的实现。原因通常有三个一是你忘了在鸿蒙侧的插件注册表里添加对应模块。在 Flutter 插件的ohos目录下一般有一个plugin_mapping.json或类似注册文件必须把插件类路径写进去。二是通道名不一致。Dart 侧写的是com.example.hotp/bridge鸿蒙侧也得一模一样少一个斜杠都算两次注册。三是鸿蒙侧插件类的生命周期问题比如在页面销毁后才调用通道这时候注册信息还没初始化完成。我建议在 Dart 侧做通道自检时先调用一个空方法ping能返回true再继续。4.2 时间无关但计数器漂移同步机制的正确姿势因为 HOTP 不含时间所以“时钟漂移”这个词不准确但计数器漂移是真实的。最常见的现象第一次生成验证码成功第二次失败第三次又成功。原因是服务端和客户端的计数器每次递增策略不同。服务端可能在验证通过后把计数器更新为当前值1客户端如果提前递增就会造成两次不一致。我的处理方式是客户端只在上一次验证成功后才递增本地计数器而不是每次点击生成都递增。在某些离线场景下如果不知道是否验证成功则采用“尝试窗口”的方式在调用校验接口时把当前计数器前后 5 个值都传上去服务端只要匹配其中一个就算通过然后服务端返回正确的计数器值客户端再以它为准校正。这在 RFC 4226 里是标准做法。鸿蒙端适配时这个同步逻辑不要写在原生层放在 Dart 层统一管理原生层只是一个纯粹的计算器。4.3 安全存储的沙箱限制与权限申请我原本想直接用 HUKS 来加密共享密钥但调研后发现 HUKS 的对称密钥接口在部分鸿蒙版本上要求先初始化安全凭据如果直接调用会报错。稳妥的做法是在应用私有目录下生成一个随机 AES 密钥再用系统提供的cryptoFramework对这个密钥做包装加密但包装密钥本身由 HUKS 管理。这个流程对新手来说有点绕我建议第一版先不要把密钥存到系统安全区而是存在应用沙箱里然后为沙箱加上 ACL 权限限制其他应用读取。另外要提个醒鸿蒙的沙箱路径在不同设备上可能不同不要硬编码/data/storage/el2/base/haps/xxx。应该通过context.filesDir或getOrCreateLocalDir()来获取。权限申请方面如果只是存到应用私有目录不需要额外申请权限但如果你想把密钥备份到云端或者跨设备同步那就得碰用户数据权限这会带来更严格的合规审查和弹窗授权能不做就别做。4.4 性能优化建议与应用场景扩展hotp 算法的计算量很小本身不到 1 毫秒但鸿蒙原生通道调用有跨进程开销。实测单次invokeMethod的往返耗时大约在 3 到 8 毫秒在快速连点时如果每次都发起通道调用会造成一定的掉帧。优化办法是加一层内存缓存同一个密钥和计数器组合在短时间内只算一次把结果缓存到 Dart 侧内存中。注意缓存键必须包含密钥哈希、计数器和验证码长度避免串号。另一个性能瓶颈是 Base32 解码。如果密钥是用户输入的字符串建议在初始化时解码一次并缓存字节数组不要每次生成验证码都解码。这个优化能把耗时降低一个数量级。应用场景上除了登录二次验证这个适配还能用在蓝牙设备配对、离线授权码、硬件密钥备份恢复等地方。因为 HOTP 只依赖计数器非常适合无网络或弱网环境。后续如果业务需要也可以在同一个通道上增加 SHA256 版本的自定义算法只需要把原生层的SHA1换成SHA256然后调整截断逻辑扩展性非常高。最后分享一个小技巧调试鸿蒙侧插件时别一上来就刚才写的生成函数联调先写一个“传入固定字节、返回固定摘要”的测试方法比如直接让原生返回0123456789abcdef0123456789abcdef01234567这个 20 字节Dart 侧再对它做动态截断。这样能把通道问题、算法问题、数据格式问题彻底隔离哪一层出错都能一眼看见。我在这次适配中就是靠这个方法把原本一周的排查时间缩短到了两天。动态令牌这种东西核心价值在于基线统一只要标准吃透、通道理顺鸿蒙上跑 HOTP 并不会有太多神秘感。