UICKeyChainStore 技术文档

本文档将详细介绍如何安装、使用以及API调用UICKeyChainStore项目，帮助用户更好地理解和应用该项目。

1. 安装指南

UICKeyChainStore 支持多种安装方式，以下是常用的安装方法：

使用 CocoaPods 安装

在 Podfile 中添加以下代码：

pod 'UICKeyChainStore

然后执行 pod install 命令。

使用 Carthage 安装

在 Cartfile 中添加以下代码：

github "kishikawakatsumi/UICKeyChainStore"

然后执行 carthage update 命令。

手动安装

从 GitHub 下载 UICKeyChainStore 的源代码，将其添加到你的项目，并确保链接正确的库。

2. 项目使用说明

UICKeyChainStore 是一个简单的 Keychain 包装器，使得使用 Keychain API 和使用 NSUserDefaults 一样简单。

基础使用

保存应用密码

UICKeyChainStore *keychain = [UICKeyChainStore keyChainStoreWithService:@"com.example.github-token"];
keychain[@"kishikawakatsumi"] = @"01234567-89ab-cdef-0123-456789abcdef";

保存互联网密码

UICKeyChainStore *keychain = [UICKeyChainStore keyChainStoreWithServer:[NSURL URLWithString:@"https://github.com"]
                                                          protocolType:UICKeyChainStoreProtocolTypeHTTPS];
keychain[@"kishikawakatsumi"] = @"01234567-89ab-cdef-0123-456789abcdef";

3. 项目API使用文档

以下是 UICKeyChainStore 的一些主要 API 使用方法。

实例化

创建应用密码的 Keychain

UICKeyChainStore *keychain = [UICKeyChainStore keyChainStoreWithService:@"com.example.github-token"];

创建互联网密码的 Keychain

UICKeyChainStore *keychain = [UICKeyChainStore keyChainStoreWithServer:[NSURL URLWithString:@"https://github.com"]
                                                          protocolType:UICKeyChainStoreProtocolTypeHTTPS];

添加项目

下标操作

keychain[@"kishikawakatsumi"] = @"01234567-89ab-cdef-0123-456789abcdef";

set 方法

[keychain setString:@"01234567-89ab-cdef-0123-456789abcdef" forKey:@"kishikawakatsumi"];

错误处理

if (![keychain setString:@"01234567-89ab-cdef-0123-456789abcdef" forKey:@"kishikawakatsumi"]) {
    // 发生错误
}

获取项目

下标操作（自动转换为字符串）

NSString *token = keychain[@"kishikawakatsumi"];

获取方法

作为字符串

NSString *token = [keychain stringForKey:@"kishikawakatsumi"];

作为数据

NSData *data = [keychain dataForKey:@"kishikawakatsumi"];

错误处理

首先，获取 failable（值或错误）对象

NSError *error;
NSString *token = [keychain stringForKey:@"" error:&error];
if (error) {
    NSLog(@"%@", error.localizedDescription);
}

删除项目

下标操作

keychain[@"kishikawakatsumi"] = nil;

删除方法

[keychain removeItemForKey:@"kishikawakatsumi"];

错误处理

if (![keychain removeItemForKey:@"kishikawakatsumi"]) {
    // 发生错误
}

配置（可访问性、共享、iCloud 同步）

可访问性

默认的可访问性匹配后台应用程序（= kSecAttrAccessibleAfterFirstUnlock）

UICKeyChainStore *keychain = [UICKeyChainStore keyChainStoreWithService:@"com.example.github-token"];

共享 Keychain 项目

UICKeyChainStore *keychain = [UICKeyChainStore keyChainStoreWithService:@"kishikawakatsumi.git"
                                                            accessGroup:@"12ABCD3E4F.shared"];

与 iCloud 同步 Keychain 项目

创建实例

UICKeyChainStore *keychain = [UICKeyChainStore keyChainStoreWithService:@"com.example.github-token"];
keychain.synchronizable = YES;

keychain[@"kishikawakatsumi"] = @"01234567-89ab-cdef-0123-456789abcdef"

Touch ID 集成

任何需要认证的操作必须在后台线程中运行。
如果在主线程中运行，UI 线程将锁定，系统尝试显示认证对话框。

添加 Touch ID 保护的项

如果你想存储 Touch ID 保护的 Keychain 项，请指定 accessibility 和 authenticationPolicy 属性。

UICKeyChainStore *keychain = [UICKeyChainStore keyChainStoreWithService:@"com.example.github-token"];

dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_BACKGROUND, 0), ^{
    [keychain setAccessibility:UICKeyChainStoreAccessibilityWhenPasscodeSetThisDeviceOnly
          authenticationPolicy:UICKeyChainStoreAuthenticationPolicyUserPresence];

    keychain[@"kishikawakatsumi"] = @"01234567-89ab-cdef-0123-456789abcdef"
});

更新 Touch ID 保护的项

更新方法与添加时相同。
如果有可能该项已存在且受保护，请不要在主线程中运行，因为更新受保护的项需要认证。

获取 Touch ID 保护的项

获取方法与获取普通项相同。如果尝试获取的项受保护，将自动显示 Touch ID 或密码认证。
如果需要显示自定义认证提示信息，请指定 authenticationPrompt 属性。

删除 Touch ID 保护的项

删除方法与删除普通项相同。没有显示 Touch ID 或密码认证的方式来删除 Keychain。

4. 项目安装方式

请参考上述“安装指南”部分，选择适合您项目的安装方法。