生物识别保险库

BiometricsVault 是一个适用于 iOS 和 macOS 的 Swift 6.0 包，它可以简化对生物识别登录的支持。

• 描述
• 要求
• 安装
• 用法
  • 不立即启用生物识别登录
  • 升级到生物识别
  • 登录并启用生物识别
• 状态图
• 许可协议

• BiometricsVault 是一个库，可以将凭据以两种特定方式存储到钥匙串中：不受保护或受生物识别（FaceID/TouchID）保护。
• 您可以使用它轻松实现可以支持生物识别的登录流程。
• 可以使用 BiometricsVault 轻松实现以下场景

• iOS 14.0+ / macOS 12.0+
• Xcode 16.0+

Swift Package Manager 是一种用于自动化 Swift 代码分发的工具，并已集成到 swift 编译器中。

设置好 Swift 包后，只需将其添加到 Package.swift 的 dependencies 值或 Xcode 中的 Package 列表中，即可轻松地将 BiometricsVault 添加为依赖项。

dependencies: [
    .package(url: "https://github.com/ariskox/BiometricsVault.git", .upToNextMajor(from: "1.0.0"))
]

将 BiometricsVault 作为依赖项添加到您的目标

.product(name: "BiometricsVault", package: "BiometricsVault")

• 假设用户刚刚登录到我们的应用程序并获得了一些凭据。

• 使用自定义 'key' 创建保险库的实例，该 'key' 将在钥匙串上保存凭据。 key 只是钥匙串中条目的名称。它不应该是什么特殊的东西或加密密钥

• 将凭据保存到钥匙串，没有任何特殊安全措施

let vault = BiometricsVault<Credentials>(key: "biometrics_credentials")
try vault.enableKeychainVault(saving: credentials)

• 在应用重启时，我们可以创建一个保险库实例并检查状态。如果状态为 'keychainSecured'，那么我们可以检索凭据

let vault = BiometricsVault<Credentials>(key: "biometrics_credentials")
switch vault.state {
case .keychainSecured(let credentials):
    // we can login the user, validate the token, or any other operation we'd like
default:
    break
}

• 注销时只需调用 reset

let vault = BiometricsVault<Credentials>(key: "biometrics_credentials")
vault.resetEverything()

• 用户登录后，我们可以使用变量 'biometricsAvailable' 来检查是否可以启用 FaceID/TouchID。 如果可以，则在您的设置页面中添加一个按钮。
• 按下启用按钮后，使用 'upgradeKeychainWithBiometrics' 函数使用生物识别验证来存储凭据

let vault = BiometricsVault<Credentials>(key: "biometrics_credentials")
try await vault.upgradeKeychainWithBiometrics()

• 现在状态将设置为 'biometricsSecured'，您需要在启动应用程序时检查此状态
• 您可以使用 'lock' 函数来锁定保险库。当保险库被锁定时，您不应再将凭据保存在内存中，并且您唯一允许向用户显示的屏幕是带有“登录”按钮的“使用生物识别登录页面”
• 当用户点击此“登录”按钮时，您应该调用“unlockWithBiometrics”，并且在成功验证后，您将获得凭据

let vault = BiometricsVault<Credentials>(key: "biometrics_credentials")
let savedCredentials = try await vault.unlockWithBiometrics()

• 当用户选择禁用 FaceID/TouchID（并且保险库未锁定）时，您有两种选择。
  • 要降级到简单的钥匙串安全 - > 调用 downgradeBiometricsToKeychain()
  • 要忘记凭据 - > 调用 disableBiometricsSecureVault

• 您想要使用函数 'enableSecureVaultWithBiometrics' 从 'ready' 状态过渡到 'biometricsSecured'

• 如果由于多次失败的重试而锁定 FaceID/TouchID，请调用 'reauthenticateOwner' 以显示 PIN 条目对话框并解锁 FaceID/TouchID 功能。
• 要了解是否必须这样做，请检查错误类型是否为 'LAError'，代码为 LAError.biometryLockout

switch error {
case let laError as LAError where laError.code == LAError.biometryLockout:
    let _ = try await vault.reauthenticateOwner()
default:
    break // do other stuff

有关更多信息，请查看目录 Example 中的示例应用程序

• 不可用
  • 设备或应用程序不支持使用生物识别进行身份验证。
• 准备就绪
  • Vault 已准备好使用生物识别锁或不受保护的方式将凭据存储到钥匙串中
  • 钥匙串中不存在凭据，因此用户已注销
• 生物识别安全
  • 凭据已存储到钥匙串中，并受到生物识别的保护。 它们对我们可用，因为用户已通过生物识别进行了身份验证。 🔓
  • 用户已登录并且凭据可用
• 已锁定
  • 凭据已存储到钥匙串中，并受到生物识别的保护，但除非用户首先通过生物识别进行身份验证，否则它们对我们不可用🔒
  • 用户会看到“使用生物识别登录”屏幕。 他/她可以按“登录”或“更改帐户”（重置）
• 钥匙串安全
  • 凭据已存储到钥匙串中，但它们不受生物识别保护
  • FaceID/TouchID 尚未启用。 用户已登录

从设置启用 FaceID/TouchID 选项的简单登录流程如下

stateDiagram-v2
    [*] --> Ready
    Ready --> KeychainSecured: enableKeychainVault
    KeychainSecured --> ΒiometricsSecured: upgradeKeychainWithBiometrics
    ΒiometricsSecured --> Locked: lock
    Locked --> ΒiometricsSecured: unlockWithBiometrics
    ΒiometricsSecured --> Ready: disableBiometricsSecureVault

stateDiagram-v2
    [*] --> Ready
    [*] --> Unavailable
    Ready --> ΒiometricsSecured: enableSecureVaultWithBiometrics
    ΒiometricsSecured --> Locked: lock
    Locked --> ΒiometricsSecured: unlockWithBiometrics
    Ready --> KeychainSecured: enableKeychainVault
    KeychainSecured --> Ready: resetEverything
    ΒiometricsSecured --> Ready: disableBiometricsSecureVault
    ΒiometricsSecured --> KeychainSecured: downgradeBiometricsToKeychain
    KeychainSecured --> ΒiometricsSecured: upgradeKeychainWithBiometrics
    Locked --> Ready: resetEverything

BiometricsVault 在 MIT 许可证下发布。 有关详细信息，请参阅 LICENSE。