获取设备指纹 —— OneSpan 设备绑定 SDK 集成指南（5.5.0） 原文标题：Obtain the device fingerprint
内容概要总结
本文是 OneSpan 设备绑定 SDK（Device Binding SDK）关于「获取设备指纹」的官方集成指南（对应 5.5.0 版）。Android 侧介绍指纹生成：推荐使用 HARDWARE 参数以利用硬件能力，并说明生物识别保护方法中 invalidateByBiometricEnrollment 参数的行为——该参数在首次调用时确定，若设备生物识别发生变化，用于生成指纹的加密密钥将永久丢失。由于 Android 10 起序列号和设备 ID 不再可用，自 SDK 4.20.1 起二者改为用派生自 Android ID 的密钥加密，并按系统版本（Android 9 及更早 / Android 10 及更新）采用不同的存储与读取方式。iOS 侧指纹由安全生成的 256 位随机值计算，存于 Keychain（kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly），经 Secure Enclave 密钥的椭圆曲线加密保护；默认对单应用唯一，可经 AppPrivate 组、应用组容器或 Keychain 共享组在同一提供商的不同应用间共享，重装不变、恢复出厂设置则改变。文中还详述 Protection 保护参数、静态/动态 salt 及向 Mobile Security Suite 4.32.0 迁移的兼容性要点。
翻译内容
原文内容（English）
文档索引
获取完整文档索引，请访问：https://docs.onespan.com/llms.txt
在进一步浏览之前，使用该文件发现所有可用页面。
获取设备指纹
发布于 2025 年 10 月 28 日
Android
指纹生成
当生成的指纹受设备生物识别凭证保护时，会提供一个更安全的指纹，它基于用户已注册的生物识别档案。设备绑定 SDK（Device Binding SDK）提供多种生成指纹的方式，参数例如 HARDWARE 或 ANDROID_ID。
关于如何生成指纹以及参数说明的详细信息，请参阅产品包中提供的技术文档和示例应用。这些内容包括以下操作的技术细节：
- 使用指纹方法绑定 Android 设备
- 如何使用受生物识别保护的指纹
对于指纹生成，我们建议使用 HARDWARE 参数，以利用 Android 设备的硬件能力。
生物识别保护指纹方法中的 invalidateByBiometricEnrollment 参数决定：当设备上新增一个生物识别凭证时，指纹是否应失效。对于任意给定的 salt，该参数在首次调用该方法时被强制执行。此行为在首次调用该方法时设定，之后的调用不会改变该行为，即使在该首次调用之后更改了参数值也是如此。
在首次调用生物识别保护指纹方法时将 invalidateByBiometricEnrollment 参数设为 true 时，必须格外谨慎。如果设备上的生物识别发生任何变化（例如新增或重置指纹），用于生成指纹的加密密钥将永久丢失。请评估这是否是你想要强制执行的行为，因为该指纹将不再为给定的 salt 生成。
序列号与设备 ID 的可用性
自 Android 10 起，序列号（serial）和设备 ID（device ID）参数不再可用。因此，自设备绑定 SDK 4.20.1 版本起，序列号和设备 ID 会用一个派生自 Android ID 的密钥进行加密。根据设备所运行的 Android 版本，SDK 对这些派生值的处理方式有所不同：
- 对于运行 Android 9 或更早版本的设备：这些值存储在集成该 SDK 的应用内部存储中的 OneSpan_DeviceBinding 文件里。
- 对于运行 Android 10 或更高版本的设备：这些值从存储中读取，以确保这些标识符的持续可用性。必须在升级到 Android 10 之前先将 SDK 升级到 4.20.1 或更高版本。自该版本起，使用指纹方法时 context 始终是必需的。
异常
当发生错误时，会抛出 DeviceBindingSDKException。该异常由一个错误码构成；如果该异常是内部错误，还包含该异常的原因（cause）。
iOS
指纹通过一个安全生成的 256 位随机值计算得出。该值在 iOS Keychain 中以 kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly 属性加以保护，并使用通过 Secure Enclave 生成的密钥、以椭圆曲线加密进行加密。
默认情况下，指纹对单个应用是唯一的，但可以由同一提供商在不同应用之间共享。重新安装应用后指纹不会改变。但是，设备恢复出厂设置后指纹会改变。
产品包中包含教程，帮助你正确地完成：
- 为 iOS 集成设备绑定 SDK
- 用设备密码或生物识别认证保护新指纹
- 使用不同类型的访问组（access group）在应用之间共享指纹
要找到该教程，请打开产品包中 iOS/Documentation 文件夹下的 MSSDeviceBinding.doccarchive 文件。
你必须安装 Xcode 13.2.1 或更高版本才能打开该文档归档文件。
保护新指纹
Protection 参数通过要求设备密码或生物识别作为认证选项来保护新指纹。如果你选择生物识别认证选项，你可以选择在当前生物识别集合更新之后指纹是否仍保持认证。指纹一旦创建，保护方式便无法更改，即使后续通过任何 API 调用传入不同的保护方式也是如此。Protection 参数仅适用于新指纹。在 Protection 参数加入之前创建的任何指纹将被记为 Protection.none，并在返回时不进行任何生物识别或密码提示。
在对指纹使用生物识别保护之前，必须向 Info.plist 文件添加 Privacy - Face ID Usage Description 字符串键。
Protection 参数在 Secure Storage SDK 中也可用。为了获得更好的用户体验，请确保在设备绑定 SDK 或 Secure Storage SDK 之一中启用该参数。如果两个 SDK 中都启用了该参数，用户将被强制认证两次。
使用 Protection.biometryCurrentSet 保存的指纹，如果在指纹创建时当前已登记的生物识别集合发生任何变化，将被锁定。这些变化包括新增、移除或重置指纹或 Face ID。Apple 不保证一次重大的 iOS 更新不会影响 Protection.currentBiometrySet。
关于各种保护方法的更多信息，请参阅产品包中提供的技术文档和示例应用。
使用 Keychain 共享组共享生成的指纹
生成的指纹既可以保持在应用内私密，也可以在应用内及 Keychain 共享组（Keychain sharing groups）中共享。这由 AccessGroup 参数控制。
如果你从低于 4.32.0 的版本升级到最新版本的设备绑定 SDK，我们建议你使用 AppPrivate 组。这应基于你在升级到当前版本之前所使用的 teamId 和 bundleId。
- 仅在应用内可访问。
- 在应用内可访问，并通过应用组容器（app group containers）共享。
- 在应用内可访问，并通过 Keychain 共享组共享。
关于如何使用访问组的信息，请参阅产品包中提供的技术文档和示例应用。那里还提供一份关于访问组的教程。
向后兼容性
为确保升级到当前版本后 SDK 功能正常，请务必遵循我们关于向后兼容性的建议。
使用静态 salt 生成的指纹
如果你的应用使用旧版本的设备绑定 SDK，其中指纹是用静态 salt 生成的，你可以继续使用相同的指纹。使用静态 salt 的方法调用目前已被弃用，并可能在 SDK 的未来版本中移除。
为提高安全性，我们强烈建议迁移到产品包中所含教程里描述的新方法。
在已用静态 salt 生成指纹的设备上，调用非弃用的 API 将不会返回相同的指纹。
iOS 版本的 OneSpan 设备绑定 SDK 提供一种清除所有设备指纹的方法，包括 Keychain 和 SecureEnclave。此操作无法撤销，在此调用之后为同一 salt 生成的任何新指纹都将是唯一的。
Mobile Security Suite 4.32.0 之前版本中的动态 salt 生成（不含 AccessGroup 和 Keychain 共享组）
在早于 4.32.0 的 Mobile Security Suite 包中所包含的设备绑定 SDK 版本中，最佳实践是使用动态方法生成用于创建指纹的 salt。关于如何动态生成 salt 的详细信息，请参阅产品包中提供的技术文档和示例应用。
迁移到 Mobile Security Suite 4.32.0 及更高版本
将设备绑定 SDK 迁移到 Mobile Security Suite 4.32.0 及更高版本中所包含的版本时，你还必须迁移到使用 AppPrivate 组的方法，该组需指定你正在迁移的那个 SDK 版本中应用所使用的 team 和 bundle 标识符。
如果一个应用最初是在早于 4.32.0 的 Mobile Security Suite SDK 版本中用 com.onespan.myappid 构建的，那么 teamId 和 bundleId 应在 4.32.0 或更高版本中初始化 AppPrivate 组。
关于 AppPrivate 组的更多信息，请参阅产品包中提供的技术文档和示例应用。
从旧版本迁移到当前版本之后，不支持降级，因为降级可能导致意外行为！
错误
当发生错误时，会抛出一个 DeviceBindingError 对象。有关错误处理的示例，请参阅产品包中包含的教程。
如果错误类型为 internalError，请向 OneSpan 技术支持提供以下信息：
- 随错误提供的 trace 字符串
- 导致该错误的操作步骤，尽可能详细
- 受影响的设备和 iOS 版本
- 任何其他有助于识别和复现该问题的相关信息
这篇文章有帮助吗？
Documentation Index
Fetch the complete documentation index at: https://docs.onespan.com/llms.txt
Use this file to discover all available pages before exploring further.
Obtain the device fingerprint
- Published on Oct 28, 2025
Android
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:
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.
iOS
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
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.
Accessible only in the app.
Accessible in the app and shared through app group containers.
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
Was this article helpful?