Description

VirgilPrivateKeysiOS framework is a wrapper over the Virgil Private Keys service for iOS applications. It allows user to interact with Virgil Private Keys Service much easier. This framework takes care about composing correct requests and parsing the service's responds into usable model and data classes.

Getting started

VirgilPrivateKeysiOS framework is supposed to be installed via CocoaPods. So, if you are not familiar with it it is time to install CocoaPods. Open your terminal window and execute the following line:

$ sudo gem install cocoapods

It will ask you about the password and then will install latest release version of CocoaPods. CocoaPods is built with Ruby and it will be installable with the default Ruby available on OS X.

If you encountered any issues during this installation, please take a look at cocoapods.org for more information.

VirgilPrivateKeysiOS framework has 2 dependencies:

• VirgilCryptoiOS - this is low-level framework for performing basic security operations such as: creating key pairs, encrypting/decrypting some data and signing/verifying signs.
• VirgilFrameworkiOS - this is a small framework with some base classes which is also used for other Virgil libraries and applications.

You don't need to install any of them manually. CocoaPods will handle it for you automatically.

Now it is possible to add VirgilPrivateKeysiOS to the particular application. So:

• Open Xcode and create a new project (in the Xcode menu: File->New->Project), or navigate to existing Xcode project using:

$ cd <Path to Xcode project folder>

• In the Xcode project's folder create a new file, give it a name Podfile (with a capital P and without any extension). Put the following lines in the Podfile and save it.

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

Note:

It is possible that you already use VirgilKeysiOS framework for Virgil Keys Service. In this situation your Podfile content should look like this:

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

• Get back to your terminal window and execute the following line:

$ pod install

• Close Xcode project (if it is still opened). For any further development purposes you should use Xcode .xcworkspace file created for you by CocoaPods.

At this point you should be able to use VirgilPrivateKeys functionality in your code. See examples for most common tasks below. If you encountered any issues with CocoaPods installations try to find more information at cocoapods.org.

Swift note

Although VirgilPrivateKeys is using Objective-C as its primary language it might be quite easily used in a Swift application. After VirgilPrivateKeys is installed as described in the Getting started section it is necessary to perform the following:

• Create a new header file in the Swift project.

• Name it something like BridgingHeader.h

• Put there the following line:

#import <VirgilPrivateKeysiOS/VirgilPrivateKeysiOS.h>

• In the Xcode build settings find the setting called Objective-C Bridging Header and set the path to your BridgingHeader.h file. Be aware that this path is relative to your Xcode project's folder. After adding bridging header setting you should be able to use the framework.

You can find more information about using Objective-C and Swift in the same project here.

Virgil Application token

Before you make any calls to the Virgil Private Keys Service you need to obtain an application token. Please, register here or sign in if you already have an account.

After signing in press Register an application button and fill required fields. When it is done you should be able to copy a generated application token. This token is necessary for making any calls to the Virgil Private Keys Service.

Note:

It is possible that you already use VirgilKeysiOS framework for Virgil Keys Service (or you use your own implementation) and you already have the application token generated. In this case you must use this exisiting token.

Requests to the service is an asynchronous network operation. VSSPrivateKeysClient instance send the request and when it is done it calls completion handler block given as last parameter in any call. To get this work VSSPrivateKeysClient instance should exist when the request is done. It is a good idea to make a property which will hold the VSSPrivateKeysClient instance.

Creating a new private keys container with service request

Assuming that we have a key pair generated and public key is already pushed to the Virgil Keys Service (via VirgilKeysiOS framework). The Private Keys Container can be one of three types: Easy, Normal and Paranoid. The type of the container affects the way how the Virgil Private Keys Service will save the private keys of the users later. The Virgil Private Keys Service recognizes and works only with either Easy or Normal type. Paranoid container type is intended only for local operations without the Virgil Private Keys Service (basically if user wants to save his/her keys only locally on the particular device). See Save a private key section of this document below for more details.

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!")
}
//...

Save a private key

One of the most important features of the Virgil Private Keys Service is the ability to store the private keys which later can be accessed easily only by the owner of the key pair. The Private Keys Service can store the private keys in two ways which actually depend on the Virgil Private Keys Container type used for initializing the contaier (Easy or Normal). In both cases private keys will be stored in password-based encrypted form.

• Easy container type: in this case the private keys will be encrypted using the container password (the same password which is used for container initialization and authentication requests). This grants the possibility to restore the password itself and the access to the private keys in case when user lost (forgot) his/her password (this can be done using VSSPrivateKeysClient instance and -resetContainerPassword:completionHandler: method). When the new password will be given to the Virgil Private Keys Service it will decrypt the private keys using old-password and re-encrypt them using new one. So user will be available to further use his/her keys easily.

• Normal container type: in this case the private keys will be encrypted with a different password than that given during container initialization and authentication. This password should be given as a parameter for VSSPrivateKeysClient method call, so VSSPrivateKeysClient will encrypt the private key before sending it to the Virgil Private Keys Service. When Normal container type is used there is no way to reset password, because the Virgil Private Keys Service will not be able to decrypt the stored keys. So, in this case only user is responsible for access to his/her private keys and remembering his/her password.

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!")
}
//...

Get a private key from the Service

When the private key is stored at the Virgil Private Keys Service it is necessary to be able to access it and get it for security related activities. In case of using Normal container type the private key data returned from the Virgil Private Keys Service will be actually encrypted with some password (because all private keys for Normal container type become encrypted right before saving them at the Service). So, password should be provided and VSSPrivateKeysClient will decrypt private key data after receiving it from the Service. If container type is Easy, then it is expected that password parameter will be 'nil', so VSSPrivateKeysClient will use the password from its credentials.

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!")
}
//...

Requirements

Requires iOS 8.x or greater.

License

Usage is provided under the The BSD 3-Clause License. See LICENSE for the full details.