Biometric Authentication

If the physical device supports biometric authentication it can be used to authenticate into a Device and to decide Operations

Biometric Cipher (Android only)

Minimum API Level

Biometric authentication requires Android 6.0 (API 23) or higher. Devices running API 21–22 do not have a standard biometric API and cannot use this feature.

On Android, biometric operations require a Cipher obtained from the SDK. This cipher is backed by a hardware-bound key that can only be used after the user authenticates via BiometricPrompt.

Important

These cipher methods are exposed because Android requires the app to manage BiometricPrompt and its CryptoObject directly — unlike iOS, where LAContext handles biometric authentication entirely within the SDK. The cipher must be passed to BiometricPrompt as a CryptoObject before being used in any SDK method. Using a cipher that was not authenticated through BiometricPrompt will result in a security exception.

The SDK's cipher is backed by its own internal KeyStore key and is completely independent from any other cipher your app may use for its own biometric logic. You can safely use both without any conflict.

isBiometricAuthenticationEnabled()

Returns whether biometric authentication was previously enabled on this device. Use this to check before attempting to show the BiometricPrompt.

boolean enabled = trustFactorClient.isBiometricAuthenticationEnabled();

getBiometricEncryptCipher()

Returns a Cipher for use when enabling biometric authentication. Pass this cipher as a CryptoObject to BiometricPrompt, then use the authenticated cipher from the callback in enableBiometricAuthentication.

Cipher cipher = trustFactorClient.getBiometricEncryptCipher();

getBiometricDecryptCipher()

Returns a Cipher for use when authenticating with biometrics or deciding operations. Pass this cipher as a CryptoObject to BiometricPrompt, then use the authenticated cipher from the callback in authenticate.

Cipher cipher = trustFactorClient.getBiometricDecryptCipher();

Enable Biometric authentication

iOS (Swift)

//context: must be previously authenticated
trustFactorClient.enableBiometricAuthentication(pin: <String>, context: <LAContext>) { result, correlationId in
  switch result {
    case .failure(let error):
        // handle error

    case .success(_):
        // handle success
  }
}

Android (Java)

The cipher parameter must be obtained from getBiometricEncryptCipher() and authenticated via BiometricPrompt's CryptoObject.

//context: must be previously authenticated
trustFactorClient.enableBiometricAuthentication(pin, cipher, (result) -> result.fold(
    (Boolean value, String correlationId) -> {
        // value is a boolean we can ignore
    },
    (Error error, String correlationId) -> {
        // handle errors
    }
));

Authenticate

iOS (Swift)

trustFactorClient.authenticate(context: <LAContext>) { result, correlationId in
  switch result {
    case .failure(let error):
        // handle error

    case .success(_):
        // handle success
  }
}

Android (Java)

The cipher parameter must be obtained from getBiometricDecryptCipher() and authenticated via BiometricPrompt's CryptoObject.

trustFactorClient.authenticate(cipher, (result) -> result.fold(
    (TFAuthenticationResponse value, String correlationId) -> {
        // handle success
    },
    (Error error, String correlationId) -> {
        // handle errors
    }
));

Disable

Disabling biometric authentication does not require the Device to be authenticated but it's important to update the device as soon as the user authenticates via PIN.

iOS (Swift)

try trustFactorClient.disableBiometricAuthentication()

Android (Java)

trustFactorClient.disableBiometricAuthentication((result) -> result.fold(
    (Boolean value, String correlationId) -> {
        // value is a boolean we can ignore
    },
    (Error error, String correlationId) -> {
        // handle errors
    }
));