VirgilPrivateKeys 2.2.1

您想将以下类似于下面的代码添加到 Podfile 中

target 'MyApp' do
  pod 'VirgilPrivateKeys', '~> 2.2'
end

然后在终端内部或从 CocoaPods.app 运行 pod install

或者为了测试运行，运行以下命令

pod try VirgilPrivateKeys


依赖关系
VirgilFoundation	= 1.3.3
VirgilKit	>= 0

VirgilPrivateKeys 2.2.1

由
Pavlo Gorb

此库已弃用，建议您查看 VirgilSDK。

描述

VirgilPrivateKeysiOS 框架是 iOS 应用程序对 Virgil Private Keys 服务的包装。它允许用户更容易地与 Virgil Private Keys 服务进行交互。此框架负责构建正确的请求并将服务响应解析为可用的模型和数据类。

入门

VirgilPrivateKeysiOS 框架应通过 CocoaPods 安装。所以，如果您不熟悉它，现在是安装 CocoaPods 的时间。打开您的终端窗口并执行以下行

$ sudo gem install cocoapods

它将询问您的密码，然后安装 CocoaPods 的最新版本。CocoaPods 使用 Ruby 构建，它将使用默认的 Ruby 在 OS X 上安装。

如果在安装过程中遇到任何问题，请参阅 cocoapods.org 获取更多信息。

VirgilPrivateKeysiOS 框架有两个依赖项

VirgilCryptoiOS - 这是执行基本安全操作（如：创建密钥对、加密/解密某些数据以及签名/验证签名）的底层框架。
VirgilFrameworkiOS - 这是一个包含一些基本类的小框架，也用于其他 Virgil 库和应用程序。

您不需要手动安装任何内容。CocoaPods 将自动为您处理。

现在可以在特定应用程序中添加 VirgilPrivateKeysiOS。所以

打开 Xcode 并创建一个新的项目（在 Xcode 菜单中：文件-》新建-》项目），或者使用以下方法导航到现有的 Xcode 项目：

$ cd <Path to Xcode project folder>

在 Xcode 项目的文件夹中创建一个新文件，将其命名为 Podfile（带大写的 P，不带任何扩展名）。在 Podfile 中放入以下行并保存。

source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '8.0'
pod 'VirgilPrivateKeysiOS'

注意

您可能已经使用了 VirgilKeysiOS 框架为 Virgil Keys 服务。在这种情况下，您的 Podfile 内容应如下所示

source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '8.0'
pod 'VirgilKeysiOS'
pod 'VirgilPrivateKeysiOS'

回到您的终端窗口并执行以下行

$ pod install

关闭 Xcode 项目（如果它仍然打开）。对于任何进一步的开发工作，您应使用 CocoaPods 为您创建的 .xcworkspace 文件。

到此为止，您应该能够在代码中使用 VirgilPrivateKeys 功能。下面是常见任务的示例。如果在 CocoaPods 安装过程中遇到任何问题，请尝试在 cocoapods.org 上找到更多信息。

Swift 中间件

尽管 VirgilPrivateKeys 主要使用 Objective-C 作为其语言，但它可能很容易在 Swift 应用程序中使用。按照入门章节中描述的方法安装 VirgilPrivateKeys 后，需要执行以下步骤：

在 Swift 项目中创建一个新头文件。
将其命名为类似 BridgingHeader.h 。
在该文件中放置以下行

#import <VirgilPrivateKeysiOS/VirgilPrivateKeysiOS.h>

在 Xcode 的构建设置中找到名为 Objective-C 桥接头 的设置，并将路径设置为您的 BridgingHeader.h 文件。请注意，此路径是相对于您的 Xcode 项目文件夹的。添加桥接头设置后，您应该能够使用该框架。

您可以在此处找到有关在同一项目中使用 Objective-C 和 Swift 的更多信息。

Virgil 应用程序令牌

在进行任何调用到 Virgil Private Keys 服务之前，您需要获取一个应用程序令牌。请在此处注册这里或如果您已有账号，请登录。

登录后，点击“注册应用程序”按钮，填写所需字段。完成这些步骤后，您应该能够复制生成的应用程序令牌。此令牌对于向 Virgil Private Keys 服务进行任何调用都是必需的。

注意

您可能已经使用 VirgilKeysiOS 框架（用于 Virgil Keys 服务）或您的方案实现，并且已经生成了应用程序令牌。在这种情况下，您必须使用此现有令牌。

对服务的请求是一个异步网络操作。VSSPrivateKeysClient 实例发送请求，并完成它时调用任何调用中作为最后一个参数给出的完成块。为了使这起作用，VSSPrivateKeysClient 实例应该在请求完成时存在。创建一个属性来存储 VSSPrivateKeysClient 实例是个好主意。

使用服务请求创建新的私钥容器

假设我们已生成了一个密钥对，并且公钥已通过 VirgilKeysiOS 框架推送到 Virgil Keys 服务。私钥容器可以是以下三种类型之一：简单、普通和偏执狂。容器的类型影响了 Virgil Private Keys 服务如何保存用户后来的私钥。Virgil Private Keys 服务仅识别和与 Easy 或普通类型工作。偏执狂容器类型仅用于本地操作，而不涉及 Virgil Private Keys 服务（基本上是用户只想在特定设备上本地保存其密钥）。关于更多详细信息，请参阅下面的 保存私钥 部分。

Objective-C

#import <VirgilFrameworkiOS/VirgilFrameworkiOS.h>
#import <VirgilPrivateKeysiOS/VirgilPrivateKeysiOS.h>

//...
@property (nonatomic, strong) VSSPrivateKeysClient *pKeysClient;
//...
//...

/// Create an user data instance for authentication. This user data should be already added to public key and confirmed with Virgil Keys Service.
VSSUserData *userData = [[VSSUserData alloc] initWithDataClass:UDCUserId dataType:UDTEmail value:<#Email address#>];
/// Create a credentials instance with user data and user password.
VSSCredentials *credentials = [[VSSCredentials alloc] initWithUserData:userData password:<#User password#>];
/// Create a new instance of Private Keys Client
self.pKeysClient = [[VSSPrivateKeysClient alloc] initWithApplicationToken:<#Virgil Application Token#> credentials:credentials];
/// Prepare container details necessary to create at Virgil Private Keys Service.
/// Easy or Normal container type should be used.
VSSContainer *container = [[VSSContainer alloc] initWithContainerType:<#CTEasy or CTNormal#>];
/// Pack the private key related information into VSSPrivateKey object for convenience.
VSSPrivateKey *privateKey = [[VSSPrivateKey alloc] initWithKey:<#Private key data#> password:<#Password which was used for creating key pair or nil#>];
/// Make actual request for initializing the container at the Virgil Private Keys Service. 
[self.pKeysClient initializeContainer:container publicKeyId:<#Public key's UUID#> privateKey:privateKey completionHandler:^(NSError *error) {
    if (error != nil) {
        NSLog(@"Error initializing the Private Keys Container: %@", [error localizedDescription]);
        return;
    }

    /// NSLog(@"Container has been created successfully!");
}];
//...

Swift

//...
private var pKeysClient: VSSPrivateKeysClient! = nil
//...

/// Create an user data instance for authentication. This user data should be already added to public key and confirmed with Virgil Keys Service.
let userData = VSSUserData(dataClass: .UDCUserId, dataType: .UDTEmail, value: <#Email address#>)
/// Create a credentials instance with user data and user password.
let credentials = VSSCredentials(userData: userData, password: <#User password#>)
/// Create a new instance of Private Keys Client
self.pKeysClient = VSSPrivateKeysClientStg(applicationToken: <#Virgil Application Token#>, credentials: credentials)
/// Prepare container details necessary to create at Virgil Private Keys Service.
/// Easy or Normal container type should be used.        
let container = VSSContainer(containerType: <#.CTEasy or .CTNormal#>)
/// Pack the private key related information into VSSPrivateKey object for convenience.
let privateKey = VSSPrivateKey(key: <#Private key's data#>, password: <#Password used for creating the key pair or nil#>)
/// Make actual request for initializing the container at the Virgil Private Keys Service.
self.pKeysClient.initializeContainer(container, publicKeyId: <#Public key's UUID#>, privateKey: privateKey) { error in
    if error != nil {
        print("Error creating the Private Keys Container: \(error!.localizedDescription)")
        return
    }

    //print("Private Keys Container has been created sucessfully!")
}
//...

保存私钥

Virgil Private Keys 服务最重要的功能之一是能够存储可以由键对的所有者轻松访问的私钥。私钥服务可以将私钥以基于密码加密的形式存储在两种方式：这实际上取决于用于初始化容器（简单或普通）的 Virgil Private Keys 容器类型。在两种情况下，私钥都将以密码加密的形式存储。

简单容器类型：在这种情况下，私钥将使用容器密码进行加密（与用于容器初始化和身份验证请求的同一密码）。这允许用户在忘记密码的情况下恢复密码本身及其对私钥的访问（可以通过使用VSSPrivateKeysClient实例和 -resetContainerPassword:completionHandler: 方法来完成）。当将新密码提供给Virgil私钥服务时，它将使用旧密码解密私钥，然后使用新密码进行重新加密。因此，用户可以轻松地进一步使用其密钥。
常规容器类型：在这种情况下，私钥将使用与容器初始化和身份验证期间提供的不同密码进行加密。此密码应作为参数传递给VSSPrivateKeysClient方法调用，因此VSSPrivateKeysClient将在将私钥发送到Virgil私钥服务之前对其进行加密。当使用常规容器类型时，无法重置密码，因为Virgil私钥服务无法解密存储的密钥。因此，在这种情况下，用户对访问其私钥及其密码负有责任。

Objective-C

#import <VirgilFrameworkiOS/VirgilFrameworkiOS.h>
#import <VirgilPrivateKeysiOS/VirgilPrivateKeysiOS.h>

//...
@property (nonatomic, strong) VSSPrivateKeysClient *pKeysClient;
//...
//...
/// Create a VSSPrivateKeys container
VSSPrivateKey *privateKey = [[VSSPrivateKey alloc] initWithKey:<#Private key data#> password:<#Password which was used for creating key pair or nil#>]; 
// Create a request
[self.pKeysClient pushPrivateKeyPublicKeyId:<#Public key's UUID#> privateKey:privateKey password:<#Password (for Normal container) or nil#> completionHandler:^(NSError *error) {
    if (error != nil) {
        NSLog(@"Error saving the Private Key in container: %@", [error localizedDescription]);
        return;
    }

    ///NSLog(@"Private key has been saved successfully.");
}];
//...

Swift

//...
private var pKeysClient: VSSPrivateKeysClient! = nil
//...

//...
/// Create VSSPrivateKey container
let privateKey = VSSPrivateKey(key: <#Private key's data#>, password: <#Password used for creating the key pair or nil#>)
/// Make a request
self.pKeysClient.pushPrivateKeyPublicKeyId(<#Public key UUID#>, privateKey: privateKey, password: <#Password which was used for creating key pair or nil#>) { error in
    if error != nil {
        print("Error saving the Private Key in container: \(error!.localizedDescription)")
        return
    }

    //print("Private Key has been saved sucessfully!")
}
//...

从服务获取私钥

当私钥存储在Virgil私钥服务中时，有必要能够访问它并获取它以进行安全相关活动。在使用常规容器类型的情况下，从Virgil私钥服务返回的私钥数据实际上将以某个密码进行加密（因为所有常规容器类型的私钥在保存到服务之前都会进行加密）。因此，应提供密码，VSSPrivateKeysClient将在从服务接收到私钥数据后对其进行解密。如果容器类型为简单，则预期密码参数将为'nil'，因此VSSPrivateKeysClient将使用其凭证中的密码。

Objective-C

#import <VirgilFrameworkiOS/VirgilFrameworkiOS.h>
#import <VirgilPrivateKeysiOS/VirgilPrivateKeysiOS.h>

//...
@property (nonatomic, strong) VSSPrivateKeysClient *pKeysClient;
//...
//...
// Create a request
[self.pKeysClient getPrivateKeyPublicKeyId:<#Public key's UUID#> password:<#Password (for Normal container) or nil#> completionHandler:^(NSData *keyData, NSError *error) {
    if (error != nil) {
        NSLog(@"Error getting the Private Key from the Service: %@", [error localizedDescription]);
        return;
    }

    /// At this point keyData will contain plain private key data which can be used for decryption and composing the signature.
    /// NSLog(@"Private key has been received successfully!");
}];
//...

Swift

//...
private var pKeysClient: VSSPrivateKeysClient! = nil
//...

//...
self.pKeysClient.getPrivateKeyPublicKeyId(<#Public key's UUID#>, password: <#Password used for creating the key pair or nil#>) { keyData, error in
    if error != nil {
        print("Error getting the Private Key from the Service: \(error!.localizedDescription)")
        return
    }

    /// At this point keyData will contain plain private key data which can be used for decryption and composing the signature.
    /// print("Private key has been received successfully!")
}
//...

需求

需要iOS 8.x 或更高版本。

许可

使用提供受 BSD 3-Clause 许可协议的约束。有关详细信息，请参阅LICENSE。