VirgilPrivateKeysiOS 2.2.0

您想将以下内容类似于以下添加到您的 Podfile 中：

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

然后在您的终端或 CocoaPods.app 中运行以下命令：

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

pod try VirgilPrivateKeysiOS


依赖
VirgilFoundation	>= 0
VirgilKit	>= 0

VirgilPrivateKeysiOS 2.2.0

由
Pavlo Gorb

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

描述

VirgilPrivateKeysiOS 框架是对 Virgil Private Keys 服务 iOS 应用的包装。它允许用户更轻松地与 Virgil Private Keys 服务交互。此框架会处理编撰正确的请求和解析服务的响应到可用的模型和数据类别。

入门

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

$ sudo gem install cocoapods

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

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

VirgilPrivateKeysiOS 框架有 2 个依赖项

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 的更多信息，请参阅此处 https://developer.apple.com/library/ios/documentation/Swift/Conceptual/BuildingCocoaApps/MixandMatch.html。

Virgil 应用程序令牌

在调用 Virgil 私钥服务之前，您需要获取一个应用程序令牌。请在 https://api.virgilsecurity.com/signin 注册或登录，如果您已经有账户。

登录后，点击 注册应用程序 按钮，填写所需字段。完成这些操作后，您应该能够复制生成的应用程序令牌。此令牌对于调用 Virgil 私钥服务是必需的。

注意

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

对服务的请求是一个异步网络操作。VSSPrivateKeysClient 实例发送请求，并在请求完成时调用作为任何调用最后一个参数给出的完成处理程序块。为了使其正常工作，VSSPrivateKeysClient 实例应在请求完成时存在。创建一个属性以保存 VSSPrivateKeysClient 实例是一个好主意。

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

假设我们已经生成了一对密钥，并且公钥已经通过 VirgilKeysiOS 框架推送到 Virgil Keys 服务。私钥容器可以是以下三种类型之一：简单、常规和偏执。容器的类型会影响 Virgil 私钥服务以后如何保存用户的私钥。Virgil 私钥服务只能识别和与简单或常规类型的容器一起工作。偏执容器类型仅适用于当地操作，不使用 Virgil 私钥服务（基本上意味着如果用户只想在特定设备上本地保存自己的密钥）。有关详细信息，请参阅文档下方的 保存私钥 部分。

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 私钥服务最重要的特性之一是能够存储私钥，稍后只有密钥对的所有者可以轻松访问。私钥服务可以以两种方式存储私钥，这实际上取决于初始化容器时使用的 Virgil 私钥容器类型（简单或常规）。在两种情况下，私钥将以基于密码的加密形式存储。

简易容器类型：在这种情况下，私钥将使用容器密码进行加密（与用于容器初始化和身份验证请求的相同密码）。这允许用户在忘记密码的情况下恢复密码和私钥访问（可以使用VSSPrivateKeysClient实例和重置容器密码-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以获取完整详情。