Troubleshooting Android SDK Keystore Errors

Overview

The Futurae Android SDK uses the Android Keystore system to securely manage cryptographic keys. On devices that support it, the SDK may leverage hardware-backed security modules, such as Android StrongBox, for additional protection.

On some Android devices — especially those with heavily customized OS layers like Samsung One UI or Huawei EMUI — the Android Keystore system may behave unpredictably. When hardware-backed security is involved, this can lead to corrupted key material, repeated initialization errors, forced account re-enrollment, or even application freezes (ANRs).

To handle these situations, the SDK provides four main options:

1. Skip hardware security:  configure the SDK with setSkipHardwareSecurity(true) to avoid hardware-backed storage (like StrongBox) and fall back to the standard software-based Keystore.

2. Switch SDK configuration:  after corruption or repeated errors, update an existing installation to use setSkipHardwareSecurity(true) without forcing user re-enrollment.

3. Account recovery: if initialization fails with corruption errors, attempt to recover SDK secrets using launchAccountRecovery(...), provided essential cryptographic material is still available.

4. Reset SDK: If recovery or reconfiguration is not possible, resetting the SDK and re-enrolling affected user’s account is the last resort. After resetting the SDK, it’s recommended to disable hardware security before initializing the SDK, as this might prevent further Keystore related errors.

Each option is described in detail below, with guidance on when to use it, how it works, and what to expect.

Skip Hardware Security

What is it?

When enabled, setSkipHardwareSecurity(true) instructs the SDK not to use StrongBox or other hardware-backed Keystore features, even if supported on the device.

• Enabled (true): cryptographic keys are stored in the software-based Android Keystore (no StrongBox).

• Disabled (false, default): the SDK will attempt to use StrongBox or another hardware-backed Keystore if available.

Hardware-backed Keystore modules like StrongBox are designed to provide additional protection by isolating keys in secure hardware. On most devices this works reliably. However, some manufacturers’ implementations are unstable and can cause errors. By setting setSkipHardwareSecurity(true), the SDK sets isStrongBoxBacked = false, preventing the use of StrongBox (SECURITY_LEVEL_STRONGBOX) while still allowing the Keystore to select the next highest available security level. Therefore, if the device supports hardware-backed security (TEE), the Keystore will still use that protection rather than falling back to a purely software-based implementation.

When to use it

Enable setSkipHardwareSecurity(true) if you encounter:

• FTKeystoreException or its subclasses (FTKeyNotFoundException, FTSignatureException)

• App freezes (ANRs) during SDK startup or cryptographic operations

• Users on devices known for unstable StrongBox implementations
   
• Repeated keystore-related crashes during account setup
   

How it works

We recommend initializing the SDK with setSkipHardwareSecurity(true) ideally on a background thread to reduce UI thread blocking and potential ANRs:

 SDKConfiguration config = new SDKConfiguration.Builder()
    .setSkipHardwareSecurity(true)
    // other config...
    .build();

What to expect

• Improves stability on affected devices

• Does not eliminate all keystore errors, but reduces their frequency significantly

See SDK Initialization Errors & Recovery for potential errors during SDK initialization.

Switch SDK Configuration

What is it?

The SDK provides a way to switch to a different SDK configuration post initialization. If errors keep recurring, you can change the SDK configuration such as changing setSkipHardwareSecurity(false) to setSkipHardwareSecurity(true) post-initialization using Switch SDK configuration. This lets you migrate from hardware-backed to software-backed security without data loss or user re-enrollment.

If the SDK cannot be recovered or reconfigured, the fallback is to reset() and re-enroll.

 

When to use it

• After corruption or repeated keystore errors
   
• When you need to move an existing installation to setSkipHardwareSecurity(true)
   

How it works

• Launch with the original configuration

• Update the configuration using switchToLockConfiguration(), setting setSkipHardwareSecurity(true)
   
• On the next and subsequent launches, initialize with the new config
   

What to expect

• Reconfiguration with skip hardware reduces the chance of repeated failures

• Existing keys and encrypted data remain intact, so users do not need to re-enroll

See Switch SDK configuration docs for implementation details.

Account Recovery: Recovering from Keystore Errors

What is it?

Account Recovery is a built-in SDK mechanism that attempts to repair a corrupted state without requiring the user to re-enroll. When cryptographic material or encrypted storage is damaged (FTCorruptedStateException, including its subclass FTEncryptedStorageCorruptedException), you can call launchAccountRecovery(...) to try to restore functionality.

This exception contains three critical pieces of information:

• isRecoverable (Boolean): Indicates if the SDK installation can be recovered via Account Recovery.
• message (String): Details regarding the corruption.
• cause (Throwable): The underlying error that triggered the state.

When to use it

You should trigger the recovery flow when you catch an FTCorruptedStateException during FuturaeSDK.launch(...)or within an onError callback, provided that isRecoverable is true.

How it works

Before attempting recovery, you must check the state of the exception. The logic follows this pattern:

1. Inspect the isRecoverable attribute.
2. If true, call launchAccountRecovery(...)  using the appropriate user-presence mode (Biometrics, Device Credentials, or SDK PIN).
3. If false, the cryptographic material is irrecoverable. You must call FuturaeSDK.reset() and inform the user that re-enrollment is required.

For code samples covering each lock configuration type, see the SDK documentation on recovery.

For a clean implementation, refer to the SDKRecoveryFlow pattern in the Futurae Sample App, which is the main composable informing the user about the corrupted state and the result (success or failure) of the recovery attempt.

What to expect

• Success: The SDK repairs the internal state and resumes normal operation.
• Failure: If recovery fails or the 5-attempt limit is reached, you must proceed to reset.
• Irrecoverable State: If isRecoverable is false, launchAccountRecovery(...) cannot be used to restore the account. In this scenario performing, a SDK reset and re-enrolling the user is the only path forward.

See SDK Initialization Errors & Recovery for details and implementation example.

Reset for Non-Recoverable Errors

What is it?

Reset completely clears the SDK state. All keys, secrets, and enrollments are removed. Users must re-enroll their accounts.

When to use it

• If launchAccountRecovery(...) fails or you have exceeded the 5 recovery attempt limit

• If reconfiguration is not possible (SDK is stuck in corrupted state)
   
• As the last resort to restore a clean state
   

How it works

• Reset the SDK (FuturaeSDK.reset())

• Re-enroll the user

• Re-launch the SDK using setSkipHardwareSecurity(true) to reduce the chance of future problems
   

What to expect

• Complete data wipe

• Users will need to re-enroll

• Ensures a clean slate, but with the cost of user disruption

Case Study: Recovering Biometrics via SDK PIN Fallback

In some instances, hardware-backed Keystore corruption doesn't cause a total SDK crash, but specifically "breaks" the biometric authentication path. Below is a real-world scenario observed on certain devices and how to resolve it without data loss.

Observed Behaviour

1. Successful Start: The user launches the app (FuturaeSDK.launch succeeds).
2. Initial Enrollment: The user enrolls an account and successfully enables biometrics.
3. Biometric Failure: At a later point, biometric unlock consistently fails or stops responding, with the unlock() method throwing an FTKeystoreOperationException.

Resolution Path

If your application uses Lock Type SDK PIN with Biometrics Optional, you can recover the biometric functionality by following these steps:

1. Fallback to PIN: Prompt the user to authenticate using their SDK PIN instead of biometrics. 
2. Switch Configuration: Once the user is authenticated via PIN, trigger the switch SDK configuration:
   • switchToLockConfiguration().
   • Set setSkipHardwareSecurity(true).
3. Restore Biometrics: After the configuration has switched to software-based security, the biometric authentication path should be re-initialized. Because the SDK is no longer struggling with the unstable hardware-backed StrongBox, biometric authentication should function normally again.

⚠️ This specific recovery flow is only applicable if the SDK is configured with Lock Configuration Type through the method setLockConfigurationType() to SDK_PIN_WITH_BIOMETRICS_OPTIONAL. If biometrics are the exclusive lock type and the keys are corrupted, you must proceed to Account Recovery or Reset.

Need help?

For any technical support, do not hesitate to contact support@futurae.com.