扩展 Android-Goldfinger：通过 Builder 自定义 Factory 与 Crypter 的进阶指南

扩展 Android-Goldfinger：通过 Builder 自定义 Factory 与 Crypter 的进阶指南

【免费下载链接】Android-GoldfingerAndroid library to simplify Biometric authentication implementation.项目地址: https://gitcode.com/gh_mirrors/an/Android-Goldfinger

Android-Goldfinger 是一个专门用于简化 Android Biometric（指纹/人脸）认证集成的开源库，它用几行代码就能完成"认证 + 数据加解密"的整套流程。默认情况下，它内置了基于 AndroidKeyStore 的 AES 加密方案，但真实项目中往往需要自定义密钥算法、加密格式甚至双通道登录。本文将以实战视角，带你掌握通过Goldfinger.Builder自定义 Factory 与 Crypter 的完整方法，让生物识别能力真正贴合你的业务需求。

为什么需要自定义 Factory 与 Crypter？

在了解自定义之前，先看 Android-Goldfinger 的默认行为。当你直接调用Goldfinger.Builder(context).build()时，库会自动注入两个默认实现：

• 默认 Factory：AesCipherFactory（位于core/src/main/java/co/infinum/goldfinger/crypto/impl/），采用AES/CBC/PKCS7算法，密钥存放在 AndroidKeyStore 中，并且强制要求用户认证后才能使用。
• 默认 Crypter：Base64CipherCrypter，负责把加密后的字节流做 Base64 编码存储。

这套组合对大多数 App 已经够用，但如果你遇到以下场景，就必须自定义了：

• 😫 需要换成 RSA、HmacSHA256 等其他算法；
• 🔐 需要与后端约定的加密格式保持一致；
• 💡 希望在不弹出生物识别弹窗的情况下也能加解密数据（例如 PIN 码登录）。

自定义的入口，就在Goldfinger接口内部的Builder类中（源码见core/src/main/java/co/infinum/goldfinger/Goldfinger.java）。

Builder 提供的 6 个扩展点，快速上手

Goldfinger.Builder一共暴露了 6 个与加解密相关的配置方法，加上 1 个日志开关：

这几个接口的源码都在core/src/main/java/co/infinum/goldfinger/crypto/目录下，结构非常清晰：Factory 负责"造"加密对象，Crypter 负责"用"加密对象，两者必须搭配同一种类型使用。

自定义 CipherFactory 与 CipherCrypter 的完整步骤

下面以最常见的 Cipher 方案为例，手把手教你写一套自己的加解密实现。

第一步：实现 CipherFactory

继承 CipherFactory 接口（基类Factory源码见core/src/main/java/co/infinum/goldfinger/crypto/Factory.java），实现两个方法：createEncryptionCrypter(key)负责生成用于加密的 Cipher，createDecryptionCrypter(key)负责生成用于解密的 Cipher。注意key参数由调用方传入，通常用来区分不同的密钥条目。

第二步：实现 CipherCrypter

继承 CipherCrypter 接口（基类Crypter源码见core/src/main/java/co/infinum/goldfinger/crypto/Crypter.java），分别实现encrypt(cipher, value)和decrypt(cipher, value)。这里拿到的 Cipher 已经通过生物识别认证被"解锁"，你可以自由决定输出格式——Base64、Hex 甚至自定义拼接都可以。

第三步：在 Builder 中装配并 build

Goldfinger goldfinger = new Goldfinger.Builder(context) .cipherFactory(new MyCipherFactory(context)) .cipherCrypter(new MyCipherCrypter()) .build();

完成这三步，Android-Goldfinger 就会在认证成功后自动调用你的 Crypter 完成数据加解密。整个调度逻辑封装在 CrypterProxy 中：它会根据认证返回的 CryptoObject 类型（Cipher / Mac / Signature），自动路由到对应的 Crypter 实现。

进阶技巧：用 UnlockedAesCipherFactory 实现"指纹 + PIN 双通道"

这是 Android-Goldfinger 最有价值的一个自定义场景。项目里提供了一个现成的扩展类 UnlockedAesCipherFactory（源码位于core/src/main/java/co/infinum/goldfinger/crypto/impl/），它继承自AesCipherFactory，只做了一件事：把isUserAuthRequired()重写为false。

什么意思呢？默认的AesCipherFactory生成的密钥必须通过指纹/人脸认证才能使用；而UnlockedAesCipherFactory生成的密钥不需要认证即可加解密。这正好可以支撑经典的"指纹优先、PIN 兜底"登录流程：

1. 用户开启生物识别：用默认AesCipherFactory加密存储数据，认证后才能解密；
2. 用户拒绝/无法使用指纹：用UnlockedAesCipherFactory直接加密 PIN 码，输入 PIN 即可解密，完全跳过生物识别弹窗。

把两种 Factory 分别装配到不同的Goldfinger实例中，互不干扰，一套加密体系轻松打通两种登录方式。

踩坑指南：Mac 与 Signature 必须成对配置

自定义虽然灵活，但也有严格的约束，务必记住这两条规则：

• 成对出现：如果设置了macFactory却没有设置macCrypter（或反过来），构建时会直接抛出RuntimeException。Signature 同理。这个校验逻辑写在Goldfinger.Builder.ensureParamsValid()中，源码见core/src/main/java/co/infinum/goldfinger/Goldfinger.java。
• 优先级顺序：当同时配置了多种 Factory 时，CryptoObjectFactory（源码见core/src/main/java/co/infinum/goldfinger/CryptoObjectFactory.java）会按Cipher → Mac → Signature的顺序优先选用 Cipher，所以实际项目中保持单一类型最不容易出错。

另外提醒一点：自定义 Factory 时，创建 Cipher/Mac/Signature 失败要记得返回null，库内部会将此视为CryptoObjectInitException并回调onError，这是接口约定好的错误处理通道，不要抛出未捕获的异常。

总结

Android-Goldfinger 通过Builder把加解密逻辑做成了高度可插拔的架构：Factory 管生成、Crypter 管运算、CrypterProxy管路由，三者解耦清晰，源码量不大，非常适合作为学习 Android 生物识别与密钥管理的范本。掌握自定义 Factory 与 Crypter 之后，无论是更换加密算法、对接后端格式，还是实现"指纹 + PIN"双通道登录，你都能轻松驾驭。

如果你需要更复杂的认证流程，还可以关注项目的 Rx 模块（源码见rx/src/main/java/co/infinum/goldfinger/rx/RxGoldfinger.java），它以响应式风格封装了同样的能力。动手改造之前，记得先通读core/src/main/java/co/infinum/goldfinger/crypto/impl/下的三个默认实现，你的自定义方案会在它们的肩膀上走得更稳。

【免费下载链接】Android-GoldfingerAndroid library to simplify Biometric authentication implementation.项目地址: https://gitcode.com/gh_mirrors/an/Android-Goldfinger