Android-Goldfinger 三种模式怎么选authenticate、encrypt 与 decrypt 完全解析【免费下载链接】Android-GoldfingerAndroid library to simplify Biometric authentication implementation.项目地址: https://gitcode.com/gh_mirrors/an/Android-Goldfinger在 Android 开发中生物识别认证指纹、人脸已经是登录、支付等场景的标配能力。而Android-Goldfinger正是一个用来简化 Biometric 生物识别认证实现的轻量级开源库。很多新手第一次接触它时最容易困惑的问题就是authenticate、encrypt、decrypt三种模式到底有什么区别什么场景该用哪一种这篇文章就带你彻底搞清楚 Android-Goldfinger 的三种模式帮你快速做出正确的技术选型。一、为什么需要三种模式先看它们的本质区别Android-Goldfinger 内部用一个Mode枚举区分三种模式源码位于core/src/main/java/co/infinum/goldfinger/Mode.java模式内部枚举值是否需要加密对象核心用途纯认证AUTHENTICATION不需要只验证你是不是本人加密ENCRYPTION需要 Cipher验证身份 把数据加密保存解密DECRYPTION需要 Cipher验证身份 把加密数据还原一句话总结核心区别authenticate只回答你是谁而encrypt和decrypt在回答你是谁的同时还要完成数据的加密与解密。这也是 Android-Goldfinger 相比原生 BiometricPrompt 最省心的地方——它把 CryptoObject 的创建、Cipher 的初始化、IV 的存取全部封装好了。二、authenticate 模式最纯粹的指纹认证2.1 适用场景只需要确认身份authenticate是三种模式中最简单的一种适合只需要验证用户身份、不需要保存任何敏感数据的场景例如支付前确认是本人操作参考示例example/src/main/java/co/infinum/example/PaymentActivity.java解锁 App 内的某个功能区域确认操作权限它的调用非常简单只需要PromptParams弹窗参数和Callback回调goldfinger.authenticate(params, new Goldfinger.Callback() { onError(Exception e) { /* 严重错误 */ } onResult(Result result) { /* 认证结果 */ } });2.2 一个重要限制不能配合设备密码在 Android-Goldfinger 中如果使用DEVICE_CREDENTIAL允许用设备密码代替生物识别只支持authenticate方法。这在参数校验类ValidateUtils中有明确约束DeviceCredentials are allowed only for Goldfinger#authenticate method.也就是说加密/解密模式必须使用纯生物识别这一点在做方案设计时要提前想清楚。三、encrypt 模式指纹认证 数据加密保存3.1 适用场景保存密码、Token、PIN 码encrypt模式解决的是既验证身份又把明文数据安全落盘的问题。最典型的应用就是自动登录功能用户首次输入密码或 PIN 后用指纹加密保存下次直接指纹登录。示例中的设置页就是标准用法见example/src/main/java/co/infinum/example/SettingsActivity.java把用户设置的 PIN 加密保存goldfinger.encrypt(params, fp_pin, pin, callback);这里有两个额外参数需要理解key唯一键名用于在本地生成和索引加密密钥IVvalue要加密的明文数据3.2 它内部做了什么调用encrypt时Android-Goldfinger 会走这样的流程核心逻辑在GoldfingerImpl.java校验硬件、已录入指纹等前置条件通过CryptoObjectFactory创建带Cipher的 CryptoObject弹出生物识别认证弹窗认证成功后用CrypterProxy自动加密value通过Result.value()返回加密后的密文默认加密实现是AES/CBC/PKCS7见core/src/main/java/co/infinum/goldfinger/crypto/impl/AesCipherFactory.java密钥存放在 AndroidKeyStore 中IV 自动保存到 SharedPreferences。这也意味着即使别人拿到你的 SharedPreferences 文件没有你的指纹也解不开数据。四、decrypt 模式指纹认证 解密还原数据4.1 适用场景读取之前加密的数据decrypt和encrypt是成对出现的负责把加密数据还原成明文。典型场景是自动登录时读取之前保存的加密 PIN示例中的登录页就是这样做的见example/src/main/java/co/infinum/example/LoginActivity.javagoldfinger.decrypt(params, fp_pin, encryptedPin, callback);注意这里的key必须和encrypt时使用完全相同的 key因为解密时需要用它从 AndroidKeyStore 加载同一把密钥、从本地读取同一个 IV。4.2 解密失败最常见的原因decrypt模式有一个新手最容易踩的坑当用户重新录入指纹新增或删除指纹后之前加密的密钥会失效导致解密抛出KeyPermanentlyInvalidatedException之类的异常。Android-Goldfinger 会返回CryptoObjectInitException或认证失败。这是 AndroidKeyStore 的安全机制属于预期行为——处理方式是引导用户重新加密数据。五、三种模式怎么选一张决策图帮你快速判断不知道怎么选记住这条判断链路只想确认身份不涉及数据读写 →authenticate需要把敏感数据存到本地 →encrypt保存时用需要把本地加密数据读出来用 →decrypt读取时用需要存 读闭环 → encrypt 和 decrypt成对使用5.1 实战组合指纹自动登录的完整方案以最常见的指纹自动登录为例三种模式的组合是这样的阶段使用模式说明首次设置 PINencrypt加密 PIN 并保存密文下次启动decrypt指纹验证后解出 PIN 自动登录支付确认authenticate仅确认本人操作5.2 三种模式的参数差异参数authenticateencryptdecryptPromptParams✅ 必填✅ 必填✅ 必填key❌ 不需要✅ 必填✅ 必填value❌ 不需要✅ 必填明文✅ 必填密文如果encrypt/decrypt漏传 key 或 valueAndroid-Goldfinger 会在参数校验阶段直接抛出InvalidParametersException所以务必按上表传齐参数。六、三分钟快速上手从初始化到模式调用6.1 添加依赖并初始化在模块的build.gradle中添加依赖implementation com.infinum:goldfinger:2.2.0初始化只需要一行代码Goldfinger goldfinger new Goldfinger.Builder(context) .logEnabled(true) // 开启日志方便调试 .build();6.2 构建弹窗参数三种模式共用一个PromptParams用 Builder 模式构建对应Goldfinger.java中的PromptParams.BuilderGoldfinger.PromptParams params new Goldfinger.PromptParams.Builder(activity) .title(验证身份) .negativeButtonText(取消) .description(请按指纹以继续) .build();6.3 封装一个通用回调回调返回的Result包含typeSUCCESS / INFO / ERROR、reason失败原因、value加密/解密结果可以统一处理Goldfinger.Callback callback new Goldfinger.Callback() { Override public void onError(Exception e) { /* 处理严重错误 */ } Override public void onResult(Goldfinger.Result result) { if (result.type() Goldfinger.Type.SUCCESS) { String value result.value(); // encrypt/decrypt 的结果 } else if (result.type() Goldfinger.Type.ERROR) { // 根据 result.reason() 提示用户如取消、超时、锁定等 } } };6.4 如果项目用了 RxJavaAndroid-Goldfinger 还提供了 Rx 模块用响应式方式调用同样三种模式入口类为rx/src/main/java/co/infinum/goldfinger/rx/RxGoldfinger.javaimplementation com.infinum:goldfinger-rx:2.2.0RxGoldfinger goldfinger new RxGoldfinger.Builder(context).build(); goldfinger.authenticate(params).subscribe(observer);Rx 模块的方法名与回调版一一对应切换成本很低。七、容易踩的坑与实用建议encrypt/decrypt 必须成对使用同一 keykey 不同会导致解密失败。指纹变更后密文会失效新增/删除指纹会使密钥失效业务上要兜底处理。authenticate 是唯一支持设备密码的模式需要DEVICE_CREDENTIAL时只能用 authenticate。先检查前置条件调用前建议用goldfinger.canAuthenticate(authenticators)检查硬件和已录入指纹避免弹窗直接报错。Android 6.0 以下会自动降级库在低版本设备上返回GoldfingerMock不会真正弹窗需要自己处理降级逻辑。八、总结Android-Goldfinger 的三种模式本质上是一套认证 加密能力的组合authenticate纯生物识别认证用于支付确认、权限校验encrypt认证 加密保存用于首次保存密码、Token、PINdecrypt认证 解密读取用于自动登录、读取加密凭证。搞清楚了这三种模式的定位你就能在合适的场景快速选型。需要深入看实现细节时可以重点阅读GoldfingerImpl.java模式分发与认证流程、CryptoObjectFactory.javaCryptoObject 创建和AesCipherFactory.java默认 AES 加密实现。把这三个文件读懂Android-Goldfinger 的核心机制就尽在掌握了。【免费下载链接】Android-GoldfingerAndroid library to simplify Biometric authentication implementation.项目地址: https://gitcode.com/gh_mirrors/an/Android-Goldfinger创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考