原生生物测量仪

在您的 Capacitor app 上添加 Face ID,触摸 ID 和指纹登录,并在 iOS 键链和 Android Keystore 中保存证书安全.

主要特点

• 生物测量检查数字 : isAvailable() 返回生物测量类型,带有可选设备证书倒置.
• 认证数字 : verifyIdentity() 显示本地生物识别提示.
• 全权证书数字 : setCredentials(), (中文(简体) ), getCredentials(), (中文(简体) ), getSecureCredentials() 财务报告和审定财务报表 deleteCredentials() 每个服务器.
• 安全数据数字 : setData(), (中文(简体) ), getData() 财务报告和审定财务报表 getSecureData() 存储任意字符串值.
• 改变事件页:1 biometryChange 当应用程序恢复时, 聆听器会运行, 这样您就可以检测在背景中所做的注册更改 .
• 平台: iOS,Android和Web. 互联网档案馆的存檔,存档日期2013-12-02. 网络为发展提供模拟.

为什么是原生生物?

A 类 免费, (中文(简体) ), 综合 具有安全证书存储的生物鉴别认证插件 :

• 所有生物鉴别类型 - 脸部身份、触摸身份、指纹、脸部认证、Iris和装置证书(PIN、图案、密码)
• 安全证书存储 - 键链(iOS)和键盘(Android)集成
• 弹性倒置 - 生物鉴别技术缺乏时可选密码回落
• 自定义 UI - 充分控制提示、标题、说明、按钮文本
• 详细错误代码 - 跨iOS和Android的统一错误处理
• 继续收听器 - 在应用程序从背景返回时检测生物计量可用性的变化
• 现代软件包管理 - 支持Swift软件包管理器(SPM)和CocoaPods(SPM-为Capacitor 8准备)

适合银行应用程序,密码管理器,认证流,以及任何需要安全用户验证的应用程序.

文档

这里有最完整的医生: https://capgo.app/docs/plugins/native-biometric/ 互联网档案馆的存檔,存档日期2013-12-21

安全考虑

重要: 验证身份( ) 可在根/ 断接设备上通过

这个 verifyIdentity() 方法 不应作为唯一的认证机制 用于敏感行动。 在扎根的Android设备或jailbroken iOS设备上,攻击者可以使用Frida,Xposed等工具或类似的框架来:

• 钩住 JavaScript 桥并强制 verifyIdentity() 以返回成功
• 拦截本地方法呼叫和绕过生物鉴别认证
• 修改应用程序的运行时行为以跳过认证检查

建议的安保做法

1. 使用根/ 断层检测:通过检测被损坏的设备来保护您的应用程序. 我们建议使用 @ capgo/ 电容- is- root 检测根/断裂设备的插件 :

import { IsRoot } from '@capgo/capacitor-is-root';

async function checkDeviceSecurity() {
  const { result } = await IsRoot.isRooted();
  
  if (result) {
    // Handle rooted device - show warning, restrict features, or block access
    console.warn('Device security compromised');
    return false;
  }
  return true;
}

2. 永不存储敏感数据客户端:不要依赖本地存储的证书进行关键认证. 使用 verifyIdentity() 作为方便的特征,而不是安全边界.

3. 服务器系统验证: 总是在后端服务器上验证认证. 生物计量认证应用于用户方便,真正的认证发生在服务器侧.

4. 执行额外的安全层数字 :

   • API 调用证书 pinning
   • 执行服务器侧会话管理
   • 使用生物鉴别认证后过期的短寿命符号
   • 添加防卫生检查

安全使用模式

import { NativeBiometric } from "@capgo/capacitor-native-biometric";
import { IsRoot } from '@capgo/capacitor-is-root';

async function secureAuthentication() {
  // 1. Check device security first
  const { result } = await IsRoot.isRooted();
  if (result) {
    // Handle rooted device appropriately
    // Example: showSecurityWarning() could display an alert to the user
    showSecurityWarning();
    // Optionally: disable biometric login, require re-authentication, etc.
  }

  // 2. Perform biometric authentication
  try {
    await NativeBiometric.verifyIdentity({
      reason: "Authenticate to access your account",
      title: "Biometric Login",
    });
  } catch (error) {
    console.error("Biometric authentication failed");
    return false;
  }

  // 3. Get stored credentials (if needed for convenience)
  const credentials = await NativeBiometric.getCredentials({
    server: "www.example.com",
  });

  // 4. CRITICAL: Validate credentials with your backend server
  // Example: validateWithServer() should send credentials to your API
  // and verify them server-side before granting access
  const isValid = await validateWithServer(credentials.username, credentials.password);
  
  return isValid;
}

此插件提供了什么

此插件提供 :

• 方便的本地生物鉴别认证
• 使用 Keychain (iOS) 和 Keystore (Android) 安全证书存储
• * 防止临时擅自进入

此插件不提供 :

• * 保护在受损装置上免遭有决心的攻击者
• 服务器端认证或验证
• * 根/断裂探测(使用) @ capgo/ 电容- is- root(中文(简体) )

最近的安全改进(v8.2.0+)

Android 加密增强:Android的应用现在使用适当的随机化初始化矢量(IVs)对所储存的证书进行AES-GCM加密. 以前版本使用的是固定的IV,这是一种加密脆弱性.

自动迁移: 插件会用旧方法自动处理加密的证书 :

• 在读取证书时,它首先尝试新的安全格式,然后在必要时回到遗留格式
• 保存证书时, 总是使用新的安全格式进行加密
• 不需要用户采取行动 - 更新后在第一次证书保存时透明地进行迁移

建议:在被更新到v8.2.0+后,用户应重新保存其证书,以确保使用改进后的格式加密. 这在用户再次认证和保存证书时会自动发生.

兼容性

说明: 此插件的主要版本沿用了Capacitor的主要版本. 使用匹配您的 Capacitor 安装的版本( 如 Capacitor 8 的插件 v8) 。 只有最新的主要版本得到积极维护.

安装( 仅支持 Capacitor 7)

您可以使用我们的 AI 辅助设置安装插件 。 使用以下命令将 Capgo 技能添加到您的 AI 工具 :

npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins

然后使用下列提示:

Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-native-biometric` plugin in my project.

如果您更喜欢手动设置,请通过运行以下命令来安装插件,并遵循下面的平台特定指令:

• npm i @capgo/capacitor-native-biometric

使用量

⚠️ 重要:在实施生物鉴别认证之前,审查 安全考虑 理解安全执行的局限性和最佳做法.

import { NativeBiometric, BiometryType } from "@capgo/capacitor-native-biometric";

async performBiometricVerification(){
  const result = await NativeBiometric.isAvailable();

  if(!result.isAvailable) return;

  // Check the biometry type for display purposes
  // IMPORTANT: Always use isAvailable for logic decisions, not biometryType
  const isFaceID = result.biometryType == BiometryType.FACE_ID;

  // Check if device has PIN/pattern/password set
  console.log('Device is secure:', result.deviceIsSecure);

  // Check if strong biometry (Face ID, Touch ID, fingerprint) is available
  console.log('Strong biometry available:', result.strongBiometryIsAvailable);

  const verified = await NativeBiometric.verifyIdentity({
    reason: "For easy log in",
    title: "Log in",
    subtitle: "Maybe add subtitle here?",
    description: "Maybe a description too?",
  })
    .then(() => true)
    .catch(() => false);

  if(!verified) return;

  const credentials = await NativeBiometric.getCredentials({
    server: "www.example.com",
  });
  
  // IMPORTANT: Always validate credentials with your backend server
  // Do not trust client-side verification alone
}

// Save user's credentials
NativeBiometric.setCredentials({
  username: "username",
  password: "password",
  server: "www.example.com",
}).then();

// Check if credentials are already saved
const isSaved = await NativeBiometric.isCredentialsSaved({
  server: "www.example.com",
});
console.log('Credentials saved:', isSaved.isSaved);

// Delete user's credentials
NativeBiometric.deleteCredentials({
  server: "www.example.com",
}).then();

// Listen for biometry availability changes when app resumes from background
const handle = await NativeBiometric.addListener('biometryChange', (result) => {
  console.log('Biometry availability changed:', result.isAvailable);
  console.log('Biometry type:', result.biometryType);
});

// To remove the listener when no longer needed:
// await handle.remove();

完成登录流程示例

此示例显示如何使用 isCredentialsSaved() 在显示“ 保存证书” 弹出前检查是否保存了证书 :

// After successful login
async handleLoginSuccess(username: string, password: string) {
  // Check if biometric authentication is available
  const result = await NativeBiometric.isAvailable({ useFallback: true });
  
  if (!result.isAvailable) {
    // Biometrics not available - go to home page directly
    this.navigateToHome();
    return;
  }
  
  // Check if credentials are already saved
  const checkCredentials = await NativeBiometric.isCredentialsSaved({
    server: "www.example.com"
  });
  
  if (checkCredentials.isSaved) {
    // Credentials already saved - go to home page
    this.navigateToHome();
  } else {
    // No credentials saved - show save credentials popup
    this.showSaveCredentialsPopup(username, password);
  }
}

// Save credentials when user confirms
async saveCredentials(username: string, password: string) {
  await NativeBiometric.setCredentials({
    username: username,
    password: password,
    server: "www.example.com",
  });
  this.navigateToHome();
}

生物鉴别错误

这是可丢入错误代码的插件特定列表 verifyIdentity() 失败, 设置为 isAvailable(),或从 getSecureCredentials() 财务报告和审定财务报表 getSecureData() 当请求的服务器或密钥没有生物鉴别保护项时。 它将Android和iOS特定认证错误代码合并为一个综合错误列表.

代码 21 (getSecureCredentials, (中文(简体) ), getSecureData(中文(简体) ),稳定,在没有生物特征保护的证书或数据时预计被拒绝(例如删除后,新安装,或因生物特征识别入学变化而失效的项目)。 平台信息略有不同:

• getSecureCredentials()
  • 机器人: No protected credentials found
  • iOS: (英语) No protected credentials found for server
• getSecureData()
  • 机器人: No protected data found
  • iOS: (英语) No protected data found for key

isCredentialsSaved() 财务报告和审定财务报表 isDataSaved() 当服务器或密钥存在任何证书或数据(受保护或无保护)时返回真实性,所以它们不保证 getSecureCredentials() 或者说 getSecureData() 将会成功 处理代码 21 或只用存储器拨打 accessControl (原始内容存档于2017-09-26). BIOMETRY CARRENT SET BIOMETRY Any. 见 getSecureCredentials() 财务报告和审定财务报表 getSecureData() 详细情况.

• isAvailable(...)
• addListener('biometryChange', ...)
• verifyIdentity(...)
• getCredentials(...)
• setCredentials(...)
• deleteCredentials(...)
• getSecureCredentials(...)
• isCredentialsSaved(...)
• setData(...)
• getData(...)
• getSecureData(...)
• deleteData(...)
• isDataSaved(...)
• getPluginVersion()
• 接口
• 类型异名
• 数字

可扩展(...)

isAvailable(options?: IsAvailableOptions | undefined) => Promise<AvailableResult>

检查是否存在生物鉴别认证硬件.

回返情况: Promise<AvailableResult>

自: 1.0.0 (单位:千美元)

添加倾听器( “ 生物测量变化 ” ,...)

addListener(eventName: 'biometryChange', listener: BiometryChangeListener) => Promise<PluginListenerHandle>

添加一个当应用程序从背景恢复时调用的听众 . 这有助于检测生物测量可用性是否在变化的同时 应用程序的背景(如用户注册/未注册生物鉴别).

回返情况: Promise<PluginListenerHandle>

自: 7.6.0 (简体中文)

验证身份(...)

verifyIdentity(options?: BiometricOptions | undefined) => Promise<void>

促使用户使用生物鉴别技术进行认证.

自: 1.0.0 (单位:千美元)

获取证书(...)

getCredentials(options: GetCredentialOptions) => Promise<Credentials>

获取给定服务器的存储证书 .

回返情况: Promise<Credentials>

自: 1.0.0 (单位:千美元)

证书(...)

setCredentials(options: SetCredentialOptions) => Promise<void>

存储给定服务器的证书 .

自: 1.0.0 (单位:千美元)

删除证书(...)

deleteCredentials(options: DeleteCredentialOptions) => Promise<void>

删除给定服务器所存储的证书.

自: 1.0.0 (单位:千美元)

获取证书(...)

getSecureCredentials(options: GetSecureCredentialsOptions) => Promise<Credentials>

获取给定服务器的存储证书, 需要生物鉴别认证 . 证书必须保存在 BIOMETRY CURRENT SET 或 BIOMETRY ANY 的访问控制装置中.

在iOS上,系统在访问被保护的Keychain项目时自动显示生物鉴别提示. 在Android上,BiometricPrompt用一个Crypto对象绑定在证书解密密钥上显示.

如果服务器没有受保护的证书, 承诺会用代码拒绝 21 (单位:千美元)BiometricAuthError.NO_PROTECTED_CREDENTIALS_FOUND) (中文(简体) ). 这是稳定的,预期 行为——例如当证书从未保存有生物鉴别保护时, 被删除,或者在生物鉴别学注册变更后作废. isCredentialsSaved() 当存在任何证书(受保护或无保护)时,返回为真实, 因此,它不能保证存在生物特征保护条目——处理码 21 内 您的捕获块或仅存储后拨打 accessControl 图片类型( C) 或BIOMETRY ANY。 。 . 平台信息: Android No protected credentials found,iOS系统 No protected credentials found for server。 。 。 .

回返情况: Promise<Credentials>

自: 8.4.0 (单位:百万美元)

证书保存(...)

isCredentialsSaved(options: IsCredentialsSavedOptions) => Promise<IsCredentialsSavedResult>

检查是否已经为给定服务器保存了证书 .

回返情况: Promise<IsCredentialsSavedResult>

自: 7.3.0 (单位:千美元)

设置数据 (...)

setData(options: SetDataOptions) => Promise<void>

在给定的密钥下存储任意字符串值. 在休息时使用平台安全存储后端加密值 (Android Keystore + 共享优先,iOS keychain).

生物特征保护储存装置 accessControl 获取值 与 getSecureData()在用户名/密码流中仍然可以使用证书助手.

自: 8.6.0 (简体中文)

获取数据(...)

getData(options: GetDataOptions) => Promise<StoredData>

为给定的密钥获取先前存储的值. 仅返回没有生物鉴别的存储值 accessControl。 。 。 .

回返情况: Promise<StoredData>

自: 8.6.0 (简体中文)

获取SecureData (...)

getSecureData(options: GetSecureDataOptions) => Promise<StoredData>

为给定的密钥获得生物鉴别保护值. 该值必须是用 accessControl 设置为 BIOMETRY CURRENT SET或BIOMETRY ANY.

回返情况: Promise<StoredData>

自: 8.6.0 (简体中文)

删除数据(...)

deleteData(options: DeleteDataOptions) => Promise<void>

删除所给密钥的存储值(受保护和无保护).

自: 8.6.0 (简体中文)

已保存数据(...)

isDataSaved(options: IsDataSavedOptions) => Promise<IsDataSavedResult>

检查是否已为给定的密钥保存一个值 .

回返情况: Promise<IsDataSavedResult>

自: 8.6.0 (简体中文)

获取 PluginVersion ()

getPluginVersion() => Promise<{ version: string; }>

获取本地 Capacitor 插件版本 .

回返情况: Promise<{ version: string; }>

自: 1.0.0 (单位:千美元)

接口

可用结果

由表明生物鉴别认证可用性的Available()方法所产生.

可用选项

插件听筒

生物计量选项

全权证书

获取证书选项

设置关键选项

删除证书选项

获取证书选项

证书保存结果

证书保存选项

设置数据选项

存储数据

获取数据选项

获取安全数据选项

删除数据选项

IsData 保存结果

IsData 保存选项

类型异名

生物计量变异听器

生物计量变化的回调类型

(result: AvailableResult): void

数字

认证 强度

生物测量主题

生物计量法错误