插件
生物识别
@nativescript/biometrics
内容
简介
一个允许您使用生物识别信息(例如指纹、面部识别等)对用户进行身份验证的插件。
注意 此插件替换了 @nativescript/fingerprint-auth。
安装
npm install @nativescript/biometrics
注意 此插件替换了 @nativescript/fingerprint-auth。
使用 @nativescript/biometrics 插件
检查设备是否支持生物识别身份验证
要检查设备是否支持生物识别身份验证,请在 BiometricAuth
实例上调用 available()
方法。
import {
BiometricAuth,
BiometricIDAvailableResult,
} from '@nativescript/biometrics'
var biometricAuth = new BiometricAuth()
biometricAuth.available().then((result: BiometricIDAvailableResult) => {
console.log(`Biometric ID available? ${result.any}`)
console.log(`Touch? ${result.touch}`)
console.log(`Face? ${result.face}`)
console.log(`Biometrics? ${result.biometrics}`)
})
Android 上的生物识别身份验证支持
- 仅在
API 23+
上受支持。 - 在某些设备上,操作系统认为面部识别不够安全,因此您的应用无法将其用于生物识别身份验证。许多三星设备就是这种情况。例如,三星 Galaxy S10 具有。因此,如果设备启用了面部识别并保存了面部扫描,则
available()
返回{ any: true, biometrics: false }
。
iOS 上的面容 ID 身份验证支持
仅在 iOS 11+ 上受支持。
要在您的应用中允许面容 ID 支持,请将支持它的原因作为
app/App_Resources/ios/Info.plist
文件中NSFaceIDUsageDescription
密钥的值提供
<key>NSFaceIDUsageDescription</key>
<string>For easy authentication with our app.</string>
- 在模拟器上,要注册面部并测试面容 ID 身份验证,请使用
功能->面容 ID
菜单项。
验证用户生物识别信息
要验证用户生物识别信息,请调用 verifyBiometric()
方法并向其传递一个 VerifyBiometricOptions 对象。
注意:iOS >
verifyBiometric()
在 IOS 模拟器上将失败,除非使用pinfallBack
选项。
biometricAuth
.verifyBiometric({
title: 'Android title', // optional title (used only on Android)
message: 'Scan your finger', // optional (used on both platforms) - for FaceID on iOS see the notes about NSFaceIDUsageDescription
fallbackMessage: 'Enter your PIN', // this will be the text to show for the "fallback" button on the biometric prompt
pinFallback: true, // allow fall back to pin/password
})
.then((result?: BiometricResult) => {
if (result.code === ERROR_CODES.SUCCESS) {
console.log('Biometric ID OK')
}
})
.catch((err) => console.log(`Biometric ID NOT OK: ${JSON.stringify(err)}`))
检测已注册指纹的变化(iOS)
对于 iOS 9+,您可以检查自上次检查以来已注册的指纹是否发生了变化。建议您添加此检查以抵御针对您的应用的黑客攻击。有关更多详细信息,请参阅 本文。
要检查已注册的指纹是否发生了变化,请调用 didBiometricDatabaseChange()
方法。如果它返回 true
,您可能需要在再次接受有效的指纹之前重新对用户进行身份验证。
biometricAuth.available().then((avail) => {
if (!avail) {
return
}
biometricAuth.didBiometricDatabaseChange().then((changed) => {
if (changed) {
// re-auth the user by asking for his credentials before allowing a fingerprint scan again
} else {
// call the fingerprint scanner
}
})
})
生物识别和加密
要将生物识别身份验证与加密相结合,以实现更安全的数据保护,请在调用 verifyBiometric()
时设置 secret
和 keyName
选项。
如果您未将 pinFallback
或 keyName
选项传递给 verifyBiometric()
方法,则插件将自动
- 创建安全密钥
- 提示用户进行面部/指纹身份验证
- 尝试使用密钥加密某些文本。
但是,这种自动密钥生成并非万无一失。
使用生物识别身份验证进行加密/解密
最佳实践是使用选项加密一些独立验证的密钥。
加密您的密钥
要加密一些敏感字符串,请将 secret
和 keyName
选项传递给 verifyBiometric()
方法。将敏感字符串设置为 secret
属性的值,并将访问该密钥的密钥名称设置为 keyName
属性的值。
biometricAuth
.verifyBiometric({
title: 'Enter your password',
message: 'Scan your finger', // optional
pinFallback: false, // do not allow pinFallback to enable crypto operations
keyName: 'MySecretKeyName', // The name of the key that will be created/used
secret: 'The Secret I want encrypted',
})
.then((result) => {
const encryptedText = result.encrypted // The text encrypted with a key named "MySecretKeyName" (Android Only)
const IV = result.iv // the initialization vector used to encrypt (Android Only)
// For IOS the secret is stored in the keycain
})
.catch((err) =>
this.set('status', `Biometric ID NOT OK: " + ${JSON.stringify(err)}`)
)
对于 Android,加密的和初始化向量将存储在您的应用中,并在每次使用 verifyBiometric()
对用户进行登录时使用
解密您的密钥
biometricAuth
.verifyBiometric({
title: 'Enter your password',
message: 'Scan yer finger', // optional
keyName: 'MySecretKeyName', // The name of the key that will be created/used
pinFallback: false, // do not allow pinFallback to enable crypto operations
android: {
decryptText: 'The encrypted text retrieved previously',
iv: 'The IV retrieved previously',
},
ios: { fetchSecret: true }, // Tell IOS to fetch the secret
})
.then((result) => {
const decryptedText = result.decrypted // The unencrypted secret
verifyMySecret(decryptedText) // verify the secret by some means, e.g. a call to a back end server.
})
.catch((err) =>
this.set('status', `Biometric ID NOT OK: " + ${JSON.stringify(err)}`)
)
回退到 PIN 码
要允许生物识别身份验证回退到锁定屏幕凭据,请将 pinFallback
设置为 true
。请注意,此设置还会禁用加密。
biometricAuth
.verifyBiometric({
title: 'Enter your password',
message: 'Scan yer finger', // optional
fallbackMessage: 'Enter PIN', // optional
pinFallback: true,
ios: { customFallback: false }, // passing true here will show the fallback message and allow you to handle this in a custom manner.
})
.then((result) => {
console.log('Fingerprint/ PIN was OK')
})
.catch((err) =>
this.set('status', `Biometric ID NOT OK: " + ${JSON.stringify(err)}`)
)
API
BiometricAuth 类
名称 | 返回类型 | 描述 |
---|---|---|
available() | Promise<BiometricIDAvailableResult> | 检查设备上是否支持生物识别身份验证。有关更多详细信息,请参阅 BiometricIDAvailableResult。 |
didBiometricDatabaseChange(options?: VerifyBiometricOptions) | Promise<boolean> | 检查用户的生物识别信息是否发生了变化。 |
verifyBiometric(options: VerifyBiometricOptions) | Promise<BiometricResult> | 使用指定的 VerifyBiometricOptions 对象验证生物识别身份验证。 |
close() | void | 关闭面部/指纹提示。如果 pinFallBack 为 true ,则 close() 对 Android 无效。 |
deleteKey(keyName?: string) | void | 删除指定的密钥。 |
BiometricIDAvailableResult 接口
名称 | 类型 | 描述 |
---|---|---|
any | boolean | 如果 Android 上没有可用的生物识别身份验证,但设备设置了 PIN 码/图案/密码,则为 true 。 |
touch | boolean | 可选:仅限 iOS |
face | boolean | 可选:仅限 iOS |
biometrics | boolean | 可选:(仅限 Android ) 指示是否可用面部/指纹。 |
VerifyBiometricOptions 接口
名称 | 类型 | 描述 |
---|---|---|
title | string | 可选:(仅限 Android ) 指纹屏幕的标题。默认为设备的默认值。 |
subTitle | string | 可选:(仅限 Android ) 指纹屏幕中的副标题。默认为 '' |
message | string | 可选:指纹屏幕的描述。在 iOS 上默认为 '扫描您的手指' ,在 Android 上可能是 '输入您的设备密码以继续' 。 |
confirm | boolean | 可选:(仅限 Android ) 在指纹屏幕中验证生物识别信息后的确认按钮。默认为 false 。 |
fallbackMessage | string | 可选:扫描指纹失败时的按钮标签。默认为 '输入密码' 。在 Android 上 - 当 pinFallback = true 时,这将是 PIN 码对话框中显示的文本。- 当 pinFallback = false 时,这将是生物识别提示上的否定按钮文本。 |
pinFallback | boolean | 可选:允许回退到 PIN 码 - 请注意,如果为 true ,则不会发生任何加密操作,并且 Android 上不可用面容 ID。 |
keyName | string | 可选:用于加密操作的密钥的名称。如果未提供,将创建它。如果 pinFallback = true ,则不使用它。 |
android | AndroidOptions | 可选:Android 特定选项。 |
ios | IOSOptions | 可选:iOS 特定选项。 |
IOSOptions 接口
名称 | 类型 | 描述 |
---|---|---|
customFallback | boolean | 可选:指示是否允许从生物识别信息自定义回退。 |
fetchSecret | boolean | 可选:指示是否尝试从指定的密钥获取密钥。 |
AndroidOptions 接口
名称 | 类型 | 描述 |
---|---|---|
decryptText | string | 如果设置且 pinFallback 为 true 以及 keyName 已设置,则此字符串将通过生物识别控制的密钥解密。 |
如果设置且 pinFallback 为 true,以及 keyName 已设置,则此字符串将通过生物识别控制的密钥解密。 | ||
iv | string | 可选:从加密结果中检索。 |
validityDuration | number | 可选:密钥操作在不触发生物识别提示的情况下有效的时间段(以秒为单位)。 |
BiometricResult 接口
名称 | 类型 | 描述 |
---|---|---|
code | ERROR_CODES | |
message | string | |
encrypted | string | 可选 |
decrypted | string | 可选 |
iv | string | 可选 |
ERROR_CODES 枚举
enum ERROR_CODES {
PASSWORD_FALLBACK_SELECTED = -3, // historically this is what iOS uses, so using that as well
SUCCESS = 0,
DEVELOPER_ERROR = 10,
NOT_AVAILABLE = 20,
NOT_CONFIGURED = 30,
NOT_RECOGNIZED = 40,
RECOVERABLE_ERROR = 50,
USER_CANCELLED = 60,
UNEXPECTED_ERROR = 70,
}
许可证
Apache 许可证 2.0 版