Fingerprint generation

When fingerprints are generated that are protected by device biometric credentials this provides a more secure fingerprint which is based on the user's registered biometric profile. The Device Binding SDK provides several ways to generate the fingerprint, with parameters such as HARDWARE or ANDROID_ID.

For detailed information about how to generate fingerprints and a description of parameters, refer to the technical documentation and sample application provided in the product package. These include technical details for the following operations:

  • generate the fingerprint
  • bind the Android device using the fingerprint method
  • how to use a biometry-protected fingerprint

For fingerprint generation, we recommend using the HARDWARE parameter to leverage the hardware capabilities of Android devices.

The invalidateByBiometricEnrollment parameter in the biometry-protected fingerprint method determines whether a fingerprint should become invalid when a new biometric credential is added to the device. For any given salt, this parameter is enforced on the first call to this method. This behavior is set on the first call to the method and subsequent calls will not change the behavior, even if the value of the parameter is changed after that first call.

Extreme caution should be taken when setting the invalidateByBiometricEnrollment parameter to true on the first call to the biometry-protected fingerprint method. The encryption key used for fingerprint generation will be lost forever if there is any change to the biometry on the device such as adding or resetting a fingerprint. Evaluate whether this is the behavior you want to enforce because the fingerprint will no longer be generated for the given salt.

Serial and device ID availability

As of Android 10, the serial and device ID parameters are no longer available. Therefore, as of version 4.20.1 of the Device Binding SDK, the serial and device ID are encrypted with a key derived from the Android ID. Depending on the Android version on which the device is running, the SDK handles these derived values differently:

  • For devices running Android 9 or earlier: The values are stored in the OneSpan_DeviceBinding file in the internal storage of the application that integrates the SDK.
  • For devices running Android 10 or later: The values are read from the storage to ensure continued availability of these identifiers. The SDK must be upgraded to version 4.20.1 or later before updating to Android 10. As of this version, the context is always mandatory when using the fingerprint method.

Exceptions

When an error occurs, a DeviceBindingSDKException is thrown. This exception consists of an error code and, if the exception is an internal error, the cause of the exception.

The fingerprint is computed with a securely-generated 256-bit random value. This value is protected in the iOS Keychain with the kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly attribute and encrypted with elliptic-curve cryptography using keys generated with Secure Enclave.

By default, the fingerprint is unique to an app but it can be shared between different apps by the same provider. The fingerprint does not change after re-installation of the app. However, the fingerprint does change after a factory reset of the device.

The product package contains tutorials to help you correctly:

  • Integrate the Device Binding SDK for iOS

  • Obtain a fingerprint

  • Protect new fingerprints with a device passcode or biometric authentication

  • Share fingerprints between apps using different types of access groups

To locate the tutorial, open the MSSDeviceBinding.doccarchive file from the iOS/Documentation folder contained in the product package.

You must have Xcode 13.2.1 or later installed to open the documentation archive file.

Protecting new fingerprints

The Protection parameter protects new fingerprints by requiring a device passcode or biometry as authentication options. If you select the biometry authentication option, you can choose whether the fingerprint should remain authenticated after the current biometry set has been updated. Once the fingerprint is created, the protection method can not be changed, even if a different protection is passed through any subsequent API calls. The Protection parameter applies only to new fingerprints. Any fingerprints created before the addition of the Protection parameter will be noted as Protection.none and will be returned without any biometry or passcode prompts.

Before using biometry protection on a fingerprint, a Privacy - Face ID Usage Description string key must be added to the Info.plist file.

The Protection parameter is also available in the Secure Storage SDK. For a better user experience, be sure to enable this parameter in either the Device Binding SDK or the Secure Storage SDK. If the parameter is enabled in both SDKs, the user will be forced to authenticate two times.

Fingerprints saved with Protection.biometryCurrentSet will be locked if there are any changes to the currently-enrolled biometry set at the time of the fingerprint creation. These changes include adding, removing, or resetting a fingerprint or face ID. There is no guarantee from Apple that a major iOS update will not impact the Protection.currentBiometrySet.
For more information about the various protection methods, refer to the technical documentation and sample application provided in the product package.

Sharing generated fingerprints with Keychain sharing group

Generated fingerprints can either be kept private in the app, or they can be shared in the app and Keychain sharing groups. This is governed with the AccessGroup parameter.

If you update to the latest version of the Device Binding SDK from a version earlier than 4.32.0, we recommend that you use the AppPrivate group. This should be based on the teamId and bundleId that were used before you upgraded to the current version.

Access groups
Class type Access
AppPrivate Accessible only in the app.

AppGroup

Accessible in the app and shared through app group containers.
KeychainSharingGroup Accessible in the app and shared through Keychain sharing groups.

For information about how to use the access groups, refer to the technical documentation and sample application provided in the product package. A tutorial on access groups is also available there.

Backward compatibility

To ensure SDK functionality after upgrading to a current version make sure you follow our recommendations regarding backward compatibility.

Fingerprint generated with static salt

If your app uses a previous version of the Device Binding SDK in which the fingerprint was generated with a static salt, you may continue to use the same fingerprint. The method call using the static salt is currently deprecated and might be removed in future releases of the SDK.

To increase security, we strongly recommend migrating to the newer method described in the tutorials included in the product package.

On devices where a fingerprint has been generated with a static salt, a call to the non-deprecated API will NOT return the same fingerprint.

The iOS version of the OneSpanDevice Binding SDK provides a method to clear all device fingerprints, including the Keychain, and SecureEnclave. This operation cannot be undone and any new fingerprint generated after this call for the same salt will be unique.

Dynamic salt generation in versions before Mobile Security Suite 4.32.0 (without AccessGroup and Keychain Sharing Group)

In versions of the Device Binding SDK included in the Mobile Security Suite package earlier than 4.32.0, the best practice is to use the dynamic method to generate the salt for fingerprint creation. For detailed information on how to dynamically generate the salt, refer to the technical documentation and sample application provided in the product package

Migrating to Mobile Security Suite 4.32.0 and later

When migrating the Device Binding SDK to the version included in Mobile Security Suite 4.32.0 and later, you must also migrate to the method where an AppPrivate group is used that specifies the team and bundle identifiers used in the app in the SDK version from which you are migrating.

If an app was built originally with com.onespan.myappid in an SDK version of Mobile Security Suite earlier than 4.32.0, the teamId and bundleId should initialise the AppPrivate group in version 4.32.0 or later.

For more information about the AppPrivate group, refer to the technical documentation and sample application provided in the product package.

After migration from a previous to the current version, downgrading is not a supported scenario since it can lead to unexpected behavior!

Errors

When an error occurs, a DeviceBindingError object is thrown. Refer to the tutorials included in the product package for examples of error handling.

If the error is an internalError type, please provide OneSpan Technical Support with the following information:

  • The trace string provided with the error
  • The procedural steps that led to the error, with as much detail as possible
  • The devices and iOS versions that were affected
  • Any other relevant information which could help identify and replicate the issue