fix(android): Use CryptoObject to prevent UserNotAuthenticatedException

[grndcherokee]

Summary

Fix race condition between BiometricPrompt.onAuthenticationSucceeded and subsequent crypto operations that causes CryptoFailedException: User not authenticated on some Android devices (particularly Samsung S24/S25).

Problem

When setUserAuthenticationRequired(true) is set on a KeyStore key with a validity duration (e.g., 5 seconds), there's a timing window between:

1. BiometricPrompt.onAuthenticationSucceeded callback firing
2. The actual crypto operation (cipher.doFinal()) executing

On some devices, particularly Samsung Galaxy S24/S25 with fingerprint authentication, this window can expire before the crypto operation runs, causing UserNotAuthenticatedException wrapped in CryptoFailedException.

The root cause is that the current implementation calls prompt.authenticate(promptInfo) without a CryptoObject, then attempts crypto operations in the success callback. This decouples the authentication from the crypto operation, creating a race condition.

Solution

Use BiometricPrompt.CryptoObject to atomically bind the biometric authentication to the crypto operation, controlled via a new opt-in option:

1. Pre-initialize the Cipher before calling BiometricPrompt.authenticate()
2. Pass it as BiometricPrompt.CryptoObject(cipher) to authenticate()
3. Use the authenticated cipher from AuthenticationResult.cryptoObject in onAuthenticationSucceeded

This ensures the crypto operation is cryptographically bound to the biometric authentication, eliminating timing-related failures.

New Option: authenticateWithCryptoObject

A new optional parameter has been added to SetOptions and GetOptions:

await Keychain.setGenericPassword('username', 'password', {
  accessControl: Keychain.ACCESS_CONTROL.BIOMETRY_CURRENT_SET,
  authenticateWithCryptoObject: true, // Enable CryptoObject binding
});

await Keychain.getGenericPassword({
  authenticateWithCryptoObject: true, // Enable CryptoObject binding
});

When enabled (true):

• Biometric authentication is atomically bound to the crypto operation
• Prevents race conditions causing "User not authenticated" errors
• Only Class 3 (Strong) biometrics are allowed - typically fingerprint
• Face Unlock may not work on devices where it's classified as Class 2 (Weak)

When disabled (false, default):

• Standard authentication flow (current behavior)
• All biometric types supported including Face Unlock
• Maintains full backward compatibility

Changes

• types.ts: Add authenticateWithCryptoObject?: boolean to SetOptions and GetOptions
• KeychainModule.kt:
  • Add AUTHENTICATE_WITH_CRYPTO_OBJECT constant
  • Add getAuthenticateWithCryptoObject() helper
  • Pass option through decrypt/encrypt call chain
• ResultHandlerProvider.kt: Accept and pass authenticateWithCryptoObject parameter
• ResultHandlerInteractiveBiometric.kt:
  • Accept authenticateWithCryptoObject constructor parameter
  • Conditionally use CryptoObject in authenticateWithPrompt()
  • Use authenticated cipher from AuthenticationResult.cryptoObject in success callback
• ResultHandlerInteractiveBiometricManualRetry.kt: Pass through the parameter
• ResultHandler.kt: Add optional cipher field to CryptoContext
• CipherStorageKeystoreRsaEcb.kt: Initialize cipher before biometric prompt
• CipherStorageKeystoreAesGcm.kt: Initialize cipher before biometric prompt

Backwards Compatibility

• Fully backward compatible - default is false, preserving existing behavior
• No changes to key generation or storage format
• Existing credentials remain valid and accessible
• No changes required for existing applications
• Apps can opt-in to stronger security when needed

Testing

• Covered by existing E2E tests in accessControlTest.spec.js which test biometric save/load flows
• Falls back gracefully if cipher initialization fails
• Tested manually on Samsung S24/S25 devices where the issue was reported

Related Issues

Fixes timing-related UserNotAuthenticatedException errors reported on Samsung devices.

Migration Notes

For apps experiencing CryptoFailedException with "User not authenticated" on Samsung devices:

// Add the option to your keychain calls
await Keychain.getGenericPassword({
  authenticateWithCryptoObject: true,
});

Note: When enabling this option, Face Unlock may stop working on some devices. Only enable if you're experiencing the race condition issue and fingerprint authentication is acceptable for your use case.

[tiagomelilo]

Hi @grndcherokee. I'm using your version on my project. On my package.json i'm using "react-native-keychain": "git+https://github.com/grndcherokee/react-native-keychain.git#fix/crypto-object-binding", instead of "react-native-keychain": "10.0.0".

But, now, on my android device I'm only able to log in using fingerprint biometrics. The error message "authenticate to retrieve secret" appear and only fingerprint biometrics is acessible for log in.

[grndcherokee]

Hi! Thanks for trying out the fork and reporting this issue.

This is actually expected behavior when using CryptoObject binding - it enforces Class 3 (Strong) biometrics only, which typically means fingerprint. Face Unlock on most Android devices is classified as Class 2 (Weak) biometrics and won't work when CryptoObject is used.

Good news: I've just pushed an update that makes this behavior configurable via a new authenticateWithCryptoObject option.

To restore Face Unlock support, you can now explicitly set it to false (or simply omit it, as false is the default):

await Keychain.getGenericPassword({
  authenticateWithCryptoObject: false, // Allow all biometric types including Face Unlock
});

If you want the stronger security that prevents the "User not authenticated" race condition (but limits to fingerprint), use:

await Keychain.getGenericPassword({
  authenticateWithCryptoObject: true, // Class 3 biometrics only (fingerprint)
});

Please update to the latest commit on the fix/crypto-object-binding branch and let me know if this resolves your issue!

[DorianMazur]

Why do we need this and how do we know they are slow?

[DorianMazur]

Why in try catch? I don't think this function can throw.

[DorianMazur]

Please remove the lib files, clean up this PR.