Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/VirgilSecurity/virgil-sdk-pfs-x

Virgil PFS SDK Objective-C/Swift
https://github.com/VirgilSecurity/virgil-sdk-pfs-x

carthage cocoapods cryptography encryption perfect-forward-secrecy pki swift virgil-cards virgil-pfs-sdk

Last synced: about 2 months ago
JSON representation

Virgil PFS SDK Objective-C/Swift

Lists

README 

        
# Virgil SWIFT PFS SDK



[![Build Status](https://api.travis-ci.org/VirgilSecurity/virgil-sdk-pfs-x.svg?branch=master)](https://travis-ci.org/VirgilSecurity/virgil-sdk-pfs-x)

[![CocoaPods Compatible](https://img.shields.io/cocoapods/v/VirgilSDKPFS.svg)](https://img.shields.io/cocoapods/v/VirgilSDKPFS.svg)

[![Carthage compatible](https://img.shields.io/badge/Carthage-compatible-4BC51D.svg?style=flat)](https://github.com/Carthage/Carthage)

[![GitHub license](https://img.shields.io/badge/license-BSD%203--Clause-blue.svg)](https://github.com/VirgilSecurity/virgil/blob/master/LICENSE)



[Introduction](#introduction) | [SDK Features](#sdk-features) | [Installation](#installation) | [Initialization](#initialization) | [Chat Example](#chat-example) | [Register Users](#register-users) | [Docs](#docs) | [Support](#support)



## Introduction



 [Virgil Security](https://virgilsecurity.com) 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][_pfs_service] and add the [Perfect Forward Secrecy][_pfs_reference_api] (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][_sdk_x] package.



# SDK Features

- communicate with [Virgil PFS Service][_pfs_service]

- manage users' OTC and LTC cards

- use Virgil [Crypto library][_virgil_crypto]



## Installation



The Virgil PFS is provided as a package `VirgilSDKPFS`.



### COCOAPODS



[CocoaPods](http://cocoapods.org) is a dependency manager for Cocoa projects. You can install it with the following command:



```bash

$ gem install cocoapods

```



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



```bash

target '' do

  use_frameworks!



  pod 'VirgilSDKPFS', '~> 1.2.1'

end

```



Then, run the following command:



```bash

$ 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][_dashboard] and created your application.



To initialize the SWIFT PFS SDK, you need the __Access Token__ created for a client at [Dashboard][_dashboard].

The Access Token helps to authenticate client's requests.



```swift

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](#register-users).



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



```swift

// 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:



```swift

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:



```swift

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][_use_case_pfs] 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__:



```swift

// 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](https://developer.virgilsecurity.com/docs/how-to/public-key-management/v4/create-card).



## Docs



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



* [PFS Service][_pfs_reference_api]

* [Perfect Forward Secrecy use case][_use_case_pfs]



To find more examples how to use Virgil Products, take a look at [SWIFT SDK documentation](https://github.com/VirgilSecurity/virgil-sdk-x/blob/v4/README.md).



## License



This library is released under the [3-clause BSD License](LICENSE.md).



## Support

Our developer support team is here to help you. Find out more information on our [Help Center](https://help.virgilsecurity.com/).



You can find us on [Twitter](https://twitter.com/VirgilSecurity) or send us email [email protected].



Also, get extra help from our support team on [Slack](https://virgilsecurity.com/join-community).



[_pfs_service]: https://developer.virgilsecurity.com/docs/api-reference/pfs-service/v4

[_sdk_x]: https://github.com/VirgilSecurity/virgil-sdk-x/tree/v4



[_dashboard]: https://dashboard.virgilsecurity.com/

[_virgil_crypto]: https://github.com/VirgilSecurity/virgil-crypto

[_reference_api]: https://developer.virgilsecurity.com/docs/api-reference

[_pfs_reference_api]: https://developer.virgilsecurity.com/docs/references/perfect-forward-secrecy

[_use_cases]: https://developer.virgilsecurity.com/docs/use-cases

[_use_case_pfs]:https://developer.virgilsecurity.com/docs/swift/use-cases/v4/perfect-forward-secrecy