Virgil SWIFT PFS SDK

Introduction

Virgil Security provides a set of APIs for adding security to any application.

The Virgil PFS SDK allows developers to get up and running with the Virgil PFS Service and add the Perfect Forward Secrecy (PFS) technologies to their digital solutions to protect previously intercepted traffic from being decrypted even if the main Private Key is compromised.

Virgil SWIFT PFS SDK contains dependent Virgil SWIFT SDK package.

SDK Features

communicate with Virgil PFS Service
manage users' OTC and LTC cards
use Virgil Crypto library

Installation

The Virgil PFS is provided as a package VirgilSDKPFS.

COCOAPODS

CocoaPods is a dependency manager for Cocoa projects. You can install it with the following command:

$ gem install cocoapods

To integrate VirgilSDK PFSinto your Xcode project using CocoaPods, specify it in your Podfile:

target '<Your Target Name>' do
  use_frameworks!

  pod 'VirgilSDKPFS', '~> 1.2.1'
end

Then, run the following command:

$ pod install

Carthage

Carthage is a decentralized dependency manager that builds your dependencies and provides you with binary frameworks. You can install Carthage with Homebrew using the following command:

$ brew update
$ brew install carthage

To integrate VirgilSDKPFS into your Xcode project using Carthage, perform following steps:

Create an empty file with name Cartfile in your project's root folder, that lists the frameworks you’d like to use in your project.
Add the following line to your Cartfile:

github "VirgilSecurity/virgil-sdk-pfs-x" ~> 1.2.1

Run carthage update. This will fetch dependencies into a Carthage/Checkouts folder inside your project's folder, then build each one or download a pre-compiled framework.
On your application targets’ “General” settings tab, in the “Linked Frameworks and Libraries” section, add each framework you want to use from the Carthage/Build folder inside your project's folder.
On your application targets’ “Build Phases” settings tab, click the “+” icon and choose “New Run Script Phase”. Create a Run Script in which you specify your shell (ex: /bin/sh), add the following contents to the script area below the shell:

/usr/local/bin/carthage copy-frameworks

and add the paths to the frameworks you want to use under “Input Files”, e.g.:

$(SRCROOT)/Carthage/Build/iOS/VSCCrypto.framework
$(SRCROOT)/Carthage/Build/iOS/VirgilCrypto.framework
$(SRCROOT)/Carthage/Build/iOS/VirgilSDK.framework
$(SRCROOT)/Carthage/Build/iOS/VirgilSDKPFS.framework

Initialization

Be sure that you have already registered at the Developer Dashboard and created your application.

To initialize the SWIFT PFS SDK, you need the Access Token created for a client at Dashboard. The Access Token helps to authenticate client's requests.

let virgil = VSSVirgilApi(token: "[YOUR_ACCESS_TOKEN_HERE]")

Chat Example

Before chat initialization, each user must have a Virgil Card on Virgil Card Service. If you have no Virgil Card yet, you can easily create it with our guide.

To begin communicating with PFS service, every user must run the initialization:

// initialize Virgil crypto instance
// enter User's credentials to create OTC and LTC Cards
let secureChatPreferences = SecureChatPreferences (
    crypto: "[CRYPTO]", // (e.g. VSSCrypto())
    identityPrivateKey: bobKey.privateKey,
    identityCard: bobCard.card!,
    accessToken: "[YOUR_ACCESS_TOKEN_HERE]")

// this class performs all PFS logic: creates LTC and OTL Cards, publishes them, etc.
self.secureChat = SecureChat(preferences: secureChatPreferences)

try self.secureChat.initialize()

// the method is periodically called to:
// - check availability of user's OTC Cards on the service
// - add new Cards till their quantity reaches the number (100) noted in current method
self.secureChat.rotateKeys(desiredNumberOfCards: 100) { error in
    //...
}

Then Sender establishes a secure PFS conversation with Receiver, encrypts and sends the message:

func sendMessage(forReceiver receiver: User, message: String) {
    guard let session = self.chat.activeSession(
        withParticipantWithCardId: receiver.card.identifier) else {
        // start new session with recipient if session wasn't initialized yet
        self.chat.startNewSession(
            withRecipientWithCard: receiver.card) { session, error in

            guard error == nil, let session = session else {
                // Error handling
                return
            }

            // get an active session by recipient's Card ID
            self.sendMessage(forReceiver: receiver,
                usingSession: session, message: message)
        }
        return
    }

    self.sendMessage(forReceiver: receiver,
        usingSession: session, message: message)
}

func sendMessage(forReceiver receiver: User,
    usingSession session: SecureSession, message: String) {
    let ciphertext: String
    do {
        // encrypt the message using previously initialized session
        ciphertext = try session.encrypt(message)
    }
    catch {
        // Error handling
        return
    }

    // send a cipher message to recipient using your messaging service
    self.messenger.sendMessage(
        forReceiverWithName: receiver.name, text: ciphertext)
}

Receiver decrypts the incoming message using the conversation he has just created:

func messageReceived(fromSenderWithName senderName: String, message: String) {
    guard let sender = self.users.first(where: { $0.name == senderName }) else {
        // User not found
        return
    }

    self.receiveMessage(fromSender: sender, message: message)
}

func receiveMessage(fromSender sender: User, message: String) {
    do {
        let session = try self.chat.loadUpSession(
            withParticipantWithCard: sender.card, message: message)

        // decrypt message using established session
        let plaintext = try session.decrypt(message)

        // show a message to the user
        print(plaintext)
    }
    catch {
        // Error handling
    }
}

With the open session, which works in both directions, Sender and Receiver can continue PFS-encrypted communication.

Take a look at our Use Case to see the whole scenario of the PFS-encrypted communication.

Register Users

In Virgil every user has a Private Key and is represented with a Virgil Card (Identity Card), which contains a Public Key and user's identity.

Using Identity Cards, we generate special Cards that have their own life-time:

One-time Card (OTC)
Long-time Card (LTC)

For each session you can use new OTC and delete it after the session is finished.

To create user's Identity Virgil Cards, use the following code on the Client side:

// generate a new Virgil Key
let aliceKey = virgil.keys.generateKey()

// save the Virgil Key into storage
try! aliceKey.store(withName: @"[KEY_NAME]",
  password: @"[KEY_PASSWORD]")

// create identity for Alice
let aliceIdentity = virgil.identities.
  createUserIdentity(withValue: "alice", type: "name")

// create a create Virgil Card request
var aliceCard = try! virgil.cards.
  createCard(with: aliceIdentity, ownerKey:aliceKey)

// export a create Virgil Card request to string
let exportedCard = aliceCard.exportData()

// transmit the create Virgil Card request to the server and receive response
let cardData = TransmitToServer(exportedCard)

When create Virgil Card request is created and transmitted to the server side, sign it with Application Private Virgil Key and publish user's Card on Virgil Cards Service.