Android BiometricX库仅注册FaceID时创建密钥抛IllegalStateException问题

这个问题我之前做生物识别认证时也踩过坑，本质是Android密钥库默认只把指纹当作符合要求的生物识别认证方式，而FaceID（面部识别）需要你明确配置才能被系统认可为有效认证手段。

当你只注册了FaceID时，系统检查密钥生成的参数要求，发现没有允许面部识别作为认证方式，就会抛出IllegalStateException——它提示的“至少需要注册一种生物识别”，其实指的是它默认认可的生物识别类型（仅指纹）。

解决步骤 #

你需要修改KeyGenParameterSpec.Builder的配置，明确允许面部识别和指纹都作为用户认证的方式，具体分API级别处理：

1. 修改密钥生成代码
   在构建KeyGenParameterSpec时，添加指定允许的生物识别认证方法的代码：

try {
    KeyGenParameterSpec.Builder builder = new KeyGenParameterSpec.Builder(KEY_NAME, 
            KeyProperties.PURPOSE_ENCRYPT | KeyProperties.PURPOSE_DECRYPT)
            .setBlockModes(KeyProperties.BLOCK_MODE_CBC)
            .setEncryptionPaddings(KeyProperties.ENCRYPTION_PADDING_PKCS7)
            .setUserAuthenticationRequired(true);

    // 关键：添加这部分，允许面部识别和指纹作为认证方式
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
        // API 30+ 明确指定允许的认证方法
        builder.setUserAuthenticationParameters(-1, 
                KeyProperties.USER_AUTHENTICATION_METHOD_BIOMETRIC_STRONG,
                KeyProperties.USER_AUTHENTICATION_METHOD_BIOMETRIC_WEAK);
    } else if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.P) {
        // Android 9-10 用这个参数允许长期有效认证（包含面部识别）
        builder.setUserAuthenticationValidityDurationSeconds(-1);
    }

    mKeyGenerator.init(builder.build());
    secretKey = mKeyGenerator.generateKey();
} catch (NoSuchAlgorithmException | InvalidAlgorithmParameterException | CertificateException | IOException e) {
    Toast.makeText(this,"Create Key "+ e.getLocalizedMessage(), Toast.LENGTH_LONG).show();
}

2. 提前检查生物识别可用性
   建议在创建密钥前，先通过BiometricManager检查当前设备是否有可用的生物识别（包括面部和指纹），这样能提前给用户提示，避免异常：

BiometricManager biometricManager = BiometricManager.from(this);
// 检查是否有面部或指纹可用
int authResult = biometricManager.canAuthenticate(BiometricManager.Authenticators.BIOMETRIC_STRONG | BiometricManager.Authenticators.BIOMETRIC_WEAK);
if (authResult != BiometricManager.BIOMETRIC_SUCCESS) {
    Toast.makeText(this, "请先注册指纹或面部识别", Toast.LENGTH_LONG).show();
    return;
}

为什么这样能解决问题 #

• 在API 30及以上，setUserAuthenticationParameters方法可以明确指定允许的用户认证方式，其中BIOMETRIC_STRONG对应面部识别（比如FaceID），BIOMETRIC_WEAK对应指纹。
• 低于API 30的版本，setUserAuthenticationValidityDurationSeconds(-1)会让密钥的认证要求包含所有已注册的生物识别类型，而不仅仅是指纹。

这样修改后，系统就能识别到已注册的FaceID是符合要求的生物识别，不会再抛出异常了。

内容的提问来源于stack exchange，提问作者abhishek maharajpet