Virgil SWIFT PFS SDK

Introduction | SDK Features | Installation | Initialization | Chat Example | Register Users | Docs | Support

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

Virgil SWIFT PFS SDK is suitable only for Client Side.

The Virgil PFS is provided as a package.

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

Virgil SWIFT PFS SDK is suitable only for Client Side.

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

To initialize the SWIFT PFS SDK at the Client Side, you need only 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 technology, 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-technology 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 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 session is finished.

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

// 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 Virgil Card
var aliceCard = try! virgil.cards.
  createCard(with: aliceIdentity, ownerKey:aliceKey)

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

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

When Virgil Card created, sign and publish it with Application Private Virgil Key at the server side.

SWIFT is not supported for publishing Virgil Cards on Virgil Services. We recommend using one of the supported languages with this guide.

Docs

Virgil Security has a powerful set of APIs and the documentation to help you get started:

• PFS Encrypted Сommunication
• Perfect Forwad Secrecy

To find more examples how to use Virgil Products, take a look at SWIFT SDK documentation.

License

This library is released under the 3-clause BSD License.

Support

Our developer support team is here to help you. Find out more information on our Help Center.

You can find us on Twitter or send us email [email protected].

Also, get extra help from our support team on Slack.