Valet

Valet 让您可以安全地将数据存储在 iOS、tvOS、watchOS 或 macOS 的钥匙串中，而无需了解钥匙串的工作原理。它很简单，我们保证。

入门

CocoaPods

通过在 Podfile 中添加以下内容来使用 CocoaPods 安装：

在 iOS 上：

platform :ios, '9.0'
use_frameworks!
pod 'Valet'

在 tvOS 上：

platform :tvos, '9.0'
use_frameworks!
pod 'Valet'

在 watchOS 上：

platform :watchos, '2.0'
use_frameworks!
pod 'Valet'

在 macOS 上：

platform :osx, '10.11'
use_frameworks!
pod 'Valet'

Carthage

通过在 Cartfile 中添加以下内容来使用 Carthage 安装：

github "Square/Valet"

运行 carthage 来构建框架，并将构建的 Valet.framework 拖入您的 Xcode 项目中。

Swift Package Manager

通过在 Package.swift 中添加以下内容来使用 Swift Package Manager 安装：

dependencies: [
    .package(url: "https://github.com/Square/Valet", from: "4.0.0"),
],

子模块

或者手动检出子模块，使用 git submodule add git@github.com:Square/Valet.git，将 Valet.xcodeproj 拖入您的项目中，并将 Valet 添加为构建依赖项。

使用

更喜欢通过观看视频学习？请查看这个视频教程。

基本初始化

let myValet = Valet.valet(with: Identifier(nonEmpty: "Druidia")!, accessibility: .whenUnlocked)

VALValet *const myValet = [VALValet valetWithIdentifier:@"Druidia" accessibility:VALAccessibilityWhenUnlocked];

要开始使用 Valet 安全地存储数据，您需要创建一个 Valet 实例，其中包含：

• 一个标识符 - 用于标识此 Valet 的非空字符串。Swift API 使用 Identifier 包装类来强制执行非空约束。
• 一个可访问性值 - 一个枚举（Accessibility），用于定义何时可以持久化和检索数据。

这个 myValet 实例可以用于在此设备上安全地存储和检索数据，但只有在设备解锁时才能使用。

选择最佳标识符

您为 Valet 选择的标识符用于为 Valet 写入钥匙串的数据创建一个沙盒。通过相同的初始化器、可访问性值和标识符创建的相同类型的两个 Valet 将能够读取和写入相同的键值对；具有不同标识符的 Valet 各自都有自己的沙盒。选择一个能描述 Valet 将保护的数据类型的标识符。您不需要在 Valet 的标识符中包含应用程序名称或包标识符。

在 macOS 上选择用户友好的标识符

let myValet = Valet.valet(withExplicitlySet: Identifier(nonEmpty: "Druidia")!, accessibility: .whenUnlocked)

VALValet *const myValet = [VALValet valetWithExplicitlySetIdentifier:@"Druidia" accessibility:VALAccessibilityWhenUnlocked];

使用开发者 ID 签名的 Mac 应用程序可能会看到其 Valet 的标识符显示给用户。⚠️⚠️ 虽然可以显式设置用户友好的标识符，但请注意，这样做会绕过本项目保证的一种 Valet 类型不会访问另一种类型的键值对的保证 ⚠️⚠️。为了维持这一保证，请确保每个 Valet 的标识符在全局范围内是唯一的。

选择最佳可访问性值

可访问性枚举用于确定何时可以访问您的秘密。使用允许您的应用程序正常运行的最严格的可访问性是个好主意。例如，如果您的应用程序不在后台运行，您会希望确保只有在手机解锁时才能读取秘密，使用 .whenUnlocked 或 .whenUnlockedThisDeviceOnly。

在持久化数据后更改可访问性值

let myOldValet = Valet.valet(withExplicitlySet: Identifier(nonEmpty: "Druidia")!, accessibility: .whenUnlocked)
let myNewValet = Valet.valet(withExplicitlySet: Identifier(nonEmpty: "Druidia")!, accessibility: .afterFirstUnlock)
try? myNewValet.migrateObjects(from: myOldValet, removeOnCompletion: true)

VALValet *const myOldValet = [VALValet valetWithExplicitlySetIdentifier:@"Druidia" accessibility:VALAccessibilityWhenUnlocked];
VALValet *const myNewValet = [VALValet valetWithExplicitlySetIdentifier:@"Druidia" accessibility:VALAccessibilityAfterFirstUnlock];
[myNewValet migrateObjectsFrom:myOldValet removeOnCompletion:true error:nil];

用于创建 Valet 的 Valet 类型、标识符、可访问性值和初始化器被组合在一起，在钥匙串中创建一个沙盒。这种行为确保不同的 Valet 不能读取或写入彼此的键值对。如果在持久化键值对后更改 Valet 的可访问性，您必须将键值对从不再需要的可访问性的 Valet 迁移到所需可访问性的 Valet，以避免数据丢失。

读取和写入

let username = "Skroob"
try? myValet.setString("12345", forKey: username)
let myLuggageCombination = myValet.string(forKey: username)

NSString *const username = @"Skroob";
[myValet setString:@"12345" forKey:username error:nil];
NSString *const myLuggageCombination = [myValet stringForKey:username error:nil];

除了允许存储字符串外，Valet 还允许通过 setObject(_ object: Data, forKey key: Key) 和 object(forKey key: String) 存储 Data 对象。使用不同类型、通过不同初始化器创建或具有不同可访问性属性的 Valet 将无法读取或修改 myValet 中的值。

使用钥匙串共享授权在多个应用程序之间共享秘密

let mySharedValet = Valet.sharedGroupValet(with: SharedGroupIdentifier(appIDPrefix: "AppID12345", nonEmptyGroup: "Druidia")!, accessibility: .whenUnlocked)

VALValet *const mySharedValet = [VALValet sharedGroupValetWithAppIDPrefix:@"AppID12345" sharedGroupIdentifier:@"Druidia" accessibility:VALAccessibilityWhenUnlocked];

这个实例可以用于在由同一开发者编写的任何应用程序中安全地存储和检索数据，这些应用程序在其 Entitlements 中将 AppID12345.Druidia（或 $(AppIdentifierPrefix)Druidia）设置为 keychain-access-groups 键的值，其中 AppID12345 是应用程序的 App ID 前缀。这个 Valet 在设备解锁时可访问。请注意，myValet 和 mySharedValet 不能读取或修改彼此的值，因为这两个 Valet 是使用不同的初始化器创建的。所有 Valet 类型都可以通过使用 sharedGroupValet 初始化器在由同一开发者编写的应用程序之间共享秘密。

使用应用程序组授权在多个应用程序之间共享秘密

let mySharedValet = Valet.sharedGroupValet(with: SharedGroupIdentifier(groupPrefix: "group", nonEmptyGroup: "Druidia")!, accessibility: .whenUnlocked)

VALValet *const mySharedValet = [VALValet sharedGroupValetWithGroupPrefix:@"group" sharedGroupIdentifier:@"Druidia" accessibility:VALAccessibilityWhenUnlocked];

这个实例可以用于在由同一开发者编写的任何应用程序中安全地存储和检索数据，这些应用程序在其 Entitlements 中将 group.Druidia 设置为 com.apple.security.application-groups 键的值。这个 Valet 在设备解锁时可访问。请注意，myValet 和 mySharedValet 不能读取或修改彼此的值，因为这两个 Valet 是使用不同的初始化器创建的。所有 Valet 类型都可以通过使用 sharedGroupValet 初始化器在由同一开发者编写的应用程序之间共享秘密。请注意，在 macOS 上，groupPrefix 必须是 App ID 前缀。

与 Valet 一样，共享的 iCloud Valet 可以使用额外的标识符创建，允许在同一共享组内存在多个独立沙盒的钥匙串。

使用 iCloud 在设备之间共享秘密

let myCloudValet = Valet.iCloudValet(with: Identifier(nonEmpty: "Druidia")!, accessibility: .whenUnlocked)

VALValet *const myCloudValet = [VALValet iCloudValetWithIdentifier:@"Druidia" accessibility:VALAccessibilityWhenUnlocked];

这个实例可以用于存储和检索数据，这些数据可以在启用了 iCloud 钥匙串的其他设备上登录相同 iCloud 账户的此应用程序中检索。如果此设备未启用 iCloud 钥匙串，仍然可以读取和写入秘密，但不会同步到其他设备。请注意，myCloudValet 不能读取或修改 myValet 或 mySharedValet 中的值，因为 myCloudValet 是使用不同的初始化器创建的。

可以使用额外的标识符创建共享的 iCloud Valet，允许在同一 iCloud 共享组内存在多个独立沙盒的钥匙串。

使用 Face ID、Touch ID 或设备密码保护秘密

let mySecureEnclaveValet = SecureEnclaveValet.valet(with: Identifier(nonEmpty: "Druidia")!, accessControl: .userPresence)

VALSecureEnclaveValet *const mySecureEnclaveValet = [VALSecureEnclaveValet valetWithIdentifier:@"Druidia" accessControl:VALAccessControlUserPresence];

这个实例可以用于在安全飞地中存储和检索数据。每次从这个 如果您的macOS应用程序支持macOS 10.14或更早版本，您必须在从Valet读取值之前运行myValet.migrateObjectsFromPreCatalina()。macOS Catalina引入了对macOS钥匙串的重大更改，要求使用kSecAttrAccessible或kSecAttrAccessGroup的macOS钥匙串项目在写入或访问这些项目时将kSecUseDataProtectionKeychain设置为true。Valet的migrateObjectsFromPreCatalina()将在较旧的macOS设备或其他操作系统上输入到钥匙串中的项目升级，以包含键值对kSecUseDataProtectionKeychain:true。请注意，使用iCloud在设备之间共享钥匙串项目的Valet不受此要求的限制。同样，SecureEnclaveValet和SinglePromptSecureEnclaveValet也不受此要求的限制。

调试

Valet保证只要写入的数据有效且canAccessKeychain()返回true，读写操作就会成功。只有少数几种情况会导致钥匙串无法访问：

1. 对您的用例使用了错误的Accessibility。不当使用的例子包括在设备上没有设置密码时使用.whenPasscodeSetThisDeviceOnly，或在后台运行时使用.whenUnlocked。
2. 使用共享访问组Valet初始化Valet时，共享访问组标识符不在您的授权文件中。
3. 在没有安全飞地的iOS设备上使用SecureEnclaveValet。安全飞地是随A7芯片引入的，首次出现在iPhone 5S、iPad Air和iPad Mini 2中。
4. 从Xcode以DEBUG模式运行您的应用。Xcode有时不能正确签名您的应用，这会导致由于授权问题而无法访问钥匙串。如果遇到此问题，只需在Xcode中再次点击运行。这个签名问题不会在正确签名的（非DEBUG）构建中出现。
5. 在设备上或模拟器中附加调试器运行应用也可能在读取或写入钥匙串时导致返回授权错误。要在设备上解决此问题，请在不附加调试器的情况下运行应用。在不附加调试器的情况下运行一次后，钥匙串通常会在附加调试器的情况下正常运行几次，然后需要重复此过程。
6. 在没有application-identifier授权的情况下运行应用或单元测试。Xcode 8引入了一项要求，即所有方案必须使用application-identifier授权签名才能访问钥匙串。为了在运行单元测试时满足此要求，您的单元测试必须在主机应用程序内运行。
7. 尝试写入大于4kb的数据。钥匙串旨在安全存储小型机密 - Apple的Security守护进程不支持写入大型blob。

要求

• Xcode 13.0或更高版本。
• iOS 9或更高版本。
• tvOS 9或更高版本。
• watchOS 2或更高版本。
• macOS 10.11或更高版本。

从先前的Valet版本迁移

好消息是：大多数Valet配置在从旧版本的Valet升级时不需要迁移钥匙串数据。所有Valet对象都与先前版本的对应物向后兼容。我们有详尽的单元测试来证明这一点（搜索test_backwardsCompatibility）。已被Apple弃用的Valet配置将需要迁移存储的数据。

坏消息是：与先前版本相比，有多个源代码破坏性API更改。

以下两个指南都解释了升级到Valet 4所需的更改。

从Valet 2迁移

1. Swift和Objective-C中的初始化器都已更改 - 现在两种语言都使用类方法，这在语义上更诚实（很多时候您不是在实例化新的Valet，而是在重新访问已经创建的Valet）。请参阅上面的基本用法示例。
2. VALSynchronizableValet（允许将钥匙串同步到iCloud）已被Valet.iCloudValet(with:accessibility:)（在Objective-C中为+[VALValet iCloudValetWithIdentifier:accessibility:]）取代。请参阅上面的示例。
3. VALAccessControl已重命名为SecureEnclaveAccessControl（在Objective-C中为VALSecureEnclaveAccessControl）。由于Face ID的引入，此枚举不再引用TouchID；相反，它现在指的是使用biometric解锁。
4. Valet、SecureEnclaveValet和SinglePromptSecureEnclaveValet不再在同一继承树中。现在它们都直接继承自NSObject，并使用组合来共享代码。如果您之前依赖于子类层次结构，1) 这可能是一种代码异味 2) 考虑为您期望的共享行为声明一个协议，以使您迁移到Valet 3更容易。

您还需要继续阅读下面的从Valet 3迁移部分。

从Valet 3迁移

1. 已从Valet中移除了always和alwaysThisDeviceOnly可访问性值，因为Apple已弃用了它们的对应项（参见kSecAttrAccessibleAlways和kSecAttrAccessibleAlwaysThisDeviceOnly的文档）。要迁移使用always可访问性存储的值，请在具有您新首选可访问性的Valet上使用migrateObjectsFromAlwaysAccessibleValet(removeOnCompletion:)方法。要迁移使用alwaysThisDeviceOnly可访问性存储的值，请在具有您新首选可访问性的Valet上使用migrateObjectsFromAlwaysAccessibleThisDeviceOnlyValet(removeOnCompletion:)方法。
2. 大多数返回可选值或Bool值的API已迁移为返回非可选值，并在遇到错误时抛出异常。忽略每个API可能抛出的错误将保持您的代码流与之前的行为相同。举一个例子：在Swift中，let secret: String? = myValet.string(forKey: myKey)变为let secret: String? = try? myValet.string(forKey: myKey)。在Objective-C中，NSString *const secret = [myValet stringForKey:myKey];变为NSString *const secret = [myValet stringForKey:myKey error:nil];。如果您对未返回数据的原因感兴趣，请在Swift中使用do-catch语句，或在Objective-C中向每个API调用传递一个NSError并检查输出。每个方法都清楚地记录了它可能throw的Error类型。请参阅上面的示例。
3. 用于创建可以在使用钥匙串共享访问组的应用程序之间共享秘密的Valet的类方法已更改。为了防止在罕见情况下错误检测App ID前缀，现在必须明确地将App ID前缀传递给这些方法。要创建共享访问组Valet，您需要创建一个SharedGroupIdentifier(appIDPrefix:nonEmptyGroup:)。请参阅上面的示例。

贡献

我们很高兴您对Valet感兴趣，我们很想看看您会如何发展它。请在提交Pull Request之前阅读我们的贡献指南。

谢谢，请务必好好体验一下！