8.7 版本发布—WinterCG 兼容性第一部分
了解更多

在 GitHub 上查看

@nativescript/biometrics

内容

简介

一个允许您使用生物识别信息(例如指纹、面部识别等)对用户进行身份验证的插件。

注意 此插件替换了 @nativescript/fingerprint-auth

安装

cli
npm install @nativescript/biometrics

注意 此插件替换了 @nativescript/fingerprint-auth

使用 @nativescript/biometrics 插件

检查设备是否支持生物识别身份验证

要检查设备是否支持生物识别身份验证,请在 BiometricAuth 实例上调用 available() 方法。

ts
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 密钥的值提供

xml
<key>NSFaceIDUsageDescription</key>
<string>For easy authentication with our app.</string>
  • 在模拟器上,要注册面部并测试面容 ID 身份验证,请使用 功能->面容 ID 菜单项。

验证用户生物识别信息

要验证用户生物识别信息,请调用 verifyBiometric() 方法并向其传递一个 VerifyBiometricOptions 对象。

注意:iOS > verifyBiometric() 在 IOS 模拟器上将失败,除非使用 pinfallBack 选项。

typescript
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,您可能需要在再次接受有效的指纹之前重新对用户进行身份验证。

typescript
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() 时设置 secretkeyName 选项。

如果您未将 pinFallbackkeyName 选项传递给 verifyBiometric() 方法,则插件将自动

  1. 创建安全密钥
  2. 提示用户进行面部/指纹身份验证
  3. 尝试使用密钥加密某些文本。

但是,这种自动密钥生成并非万无一失。

使用生物识别身份验证进行加密/解密

最佳实践是使用选项加密一些独立验证的密钥。

加密您的密钥

要加密一些敏感字符串,请将 secretkeyName 选项传递给 verifyBiometric() 方法。将敏感字符串设置为 secret 属性的值,并将访问该密钥的密钥名称设置为 keyName 属性的值。

typescript
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() 对用户进行登录时使用

解密您的密钥

typescript
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。请注意,此设置还会禁用加密。

typescript
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关闭面部/指纹提示。如果 pinFallBacktrue,则 close() 对 Android 无效。
deleteKey(keyName?: string)void删除指定的密钥。

BiometricIDAvailableResult 接口

名称类型描述
anyboolean如果 Android 上没有可用的生物识别身份验证,但设备设置了 PIN 码/图案/密码,则为 true
touchboolean可选仅限 iOS
faceboolean可选仅限 iOS
biometricsboolean可选:(仅限 Android) 指示是否可用面部/指纹。

VerifyBiometricOptions 接口

名称类型描述
titlestring可选:(仅限 Android) 指纹屏幕的标题。默认为设备的默认值。
subTitlestring可选:(仅限 Android) 指纹屏幕中的副标题。默认为 ''
messagestring可选:指纹屏幕的描述。在 iOS 上默认为 '扫描您的手指',在 Android 上可能是 '输入您的设备密码以继续'
confirmboolean可选:(仅限 Android) 在指纹屏幕中验证生物识别信息后的确认按钮。默认为 false
fallbackMessagestring可选:扫描指纹失败时的按钮标签。默认为 '输入密码'
在 Android 上
- 当 pinFallback= true 时,这将是 PIN 码对话框中显示的文本。
- 当 pinFallback = false 时,这将是生物识别提示上的否定按钮文本。
pinFallbackboolean可选:允许回退到 PIN 码 - 请注意,如果为 true,则不会发生任何加密操作,并且 Android 上不可用面容 ID。
keyNamestring可选:用于加密操作的密钥的名称。如果未提供,将创建它。如果 pinFallback = true,则不使用它。
androidAndroidOptions可选:Android 特定选项。
iosIOSOptions可选:iOS 特定选项。

IOSOptions 接口

名称类型描述
customFallbackboolean可选:指示是否允许从生物识别信息自定义回退。
fetchSecretboolean可选:指示是否尝试从指定的密钥获取密钥。

AndroidOptions 接口

名称类型描述
decryptTextstring如果设置且 pinFallbacktrue 以及 keyName 已设置,则此字符串将通过生物识别控制的密钥解密。
如果设置且 pinFallback 为 true,以及 keyName 已设置,则此字符串将通过生物识别控制的密钥解密。
ivstring可选:从加密结果中检索。
validityDurationnumber可选:密钥操作在不触发生物识别提示的情况下有效的时间段(以秒为单位)。

BiometricResult 接口

名称类型描述
codeERROR_CODES
messagestring
encryptedstring可选
decryptedstring可选
ivstring可选

ERROR_CODES 枚举

typescript
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 版

下一页
亮度