Skip to content

Latest commit

 

History

History
242 lines (165 loc) · 12 KB

README.md

File metadata and controls

242 lines (165 loc) · 12 KB
Raw

Virgil Security Objective-C/Swift SDK

VirgilSDK

Build Status CocoaPods Compatible Carthage compatible Platform codecov.io GitHub license

Installation | Encryption Example | Initialization | Documentation | Migration notes | Support

Virgil Security provides a set of APIs for adding security to any application. In a few simple steps you can encrypt communication, securely store data, provide passwordless login, and ensure data integrity.

For a full overview head over to our Objective-C/Swift Get Started guides.

Installation

The Virgil SDK is provided as module inside framework named VirgilSDK. VirgilSDK depends on another Virgil module called VirgilCrypto also packed inside framework named VirgilCrypto. Both packages are distributed via Carthage and CocoaPods. Carthage is RECOMMENDED way to integrate VirgilSDK into your projects. Carthage integration is easy, convenient and you can simultaniously use CocoaPods to manage all other dependencies. CocoaPods support for versions above 4.5.0 is SUSPENDED, more info below under CocoaPods section.

Packages are available for iOS 8.0+ and macOS 10.10+.

To link frameworks to your project follow instructions depending on package manager of your choice:

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 VirgilSDK into your Xcode project using Carthage, perform following steps:

If you're building for iOS
  1. 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.
  2. Add the following line to your Cartfile
github "VirgilSecurity/virgil-sdk-x" ~> 4.8.0
  1. Run carthage update --no-use-binaries --platform iOS. This will fetch dependencies into a Carthage/Checkouts folder inside your project's folder, then build each one or download a pre-compiled framework.
  2. 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.
  3. 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/VirgilSDK.framework
$(SRCROOT)/Carthage/Build/iOS/VirgilCrypto.framework
$(SRCROOT)/Carthage/Build/iOS/VSCCrypto.framework

This script works around an App Store submission bug triggered by universal binaries and ensures that necessary bitcode-related files and dSYMs are copied when archiving.

With the debug information copied into the built products directory, Xcode will be able to symbolicate the stack trace whenever you stop at a breakpoint. This will also enable you to step through third-party code in the debugger.

When archiving your application for submission to the App Store or TestFlight, Xcode will also copy these files into the dSYMs subdirectory of your application’s .xcarchive bundle.

If you're building for macOS
  1. 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.
  2. Add the following line to your Cartfile
github "VirgilSecurity/virgil-sdk-x" ~> 4.8.0
  1. Run carthage update --no-use-binaries --platform macOS. This will fetch dependencies into a Carthage/Checkouts folder inside your project's folder, then build each one or download a pre-compiled framework.
  2. On your application targets’ “General” settings tab, in the “Embedded Binaries” section, drag and drop each framework you want to use from the Carthage/Build folder inside your project's folder including VirgilSDK.framework, VirgilCrypto.framework and VSCCrypto.framework.

Additionally, you'll need to copy debug symbols for debugging and crash reporting on OS X.

  1. On your application target’s “Build Phases” settings tab, click the “+” icon and choose “New Copy Files Phase”.
  2. Click the “Destination” drop-down menu and select “Products Directory”.
  3. For each framework you’re using, drag and drop its corresponding dSYM file.

CocoaPods

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

$ gem install cocoapods

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

source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '10.0'

target '<Your Target Name>' do
    pod 'VirgilSDK', '~> 4.8.0'
end

Then, run the following command:

$ pod install

To import VirgilSDK and VirgilCrypto after linking frameworks to your project add following lines to your source files:

Objective-C
@import VirgilCrypto;
@import VirgilSDK;
Swift
import VirgilCrypto
import VirgilSDK

Swift note

Although VirgilSDK pod is using Objective-C as its primary language it might be quite easily used in a Swift application. All public API is available from Swift and is bridged using NS_SWIFT_NAME where needed.

Next: Get Started with the Objective-C/Swift SDK.

Encryption Example

Virgil Security makes it super easy to add encryption to any application. With our SDK you create a public Virgil Card for every one of your users and devices. With these in place you can easily encrypt any data in the client.

// find Alice's card(s)
virgil.cards.searchCards(withIdentities: ["alice"]) { aliceCards, error in
  // encrypt the message using Alice's cards
  let message = "Hello Alice!"
  let encryptedMessage = try! virgil.encrypt(message, for: aliceCards!)

  // transmit the message with your preferred technology
  self.transmit(message: encryptedMessage.base64EncodedString())
}

The receiving user then uses their stored private key to decrypt the message.

// load Alice's Key from storage.
let aliceKey = try! virgil.keys.loadKey(withName: "alice_key_1", password: "mypassword")

// decrypt the message using the key 
let originalMessage = String(data: try! aliceKey.decrypt(transferData), encoding: .utf8)!

Next: To get you properly started you'll need to know how to create and store Virgil Cards. Our Get Started guide will get you there all the way.

Also: Encrypted communication is just one of the few things our SDK can do. Have a look at our guides on Encrypted Storage, Data Integrity and Passwordless Login for more information.

Initialization

To use this SDK you need to sign up for an account and create your first application. Make sure to save the app id, private key and it's password. After this, create an application token for your application to make authenticated requests from your clients.

To initialize the SDK on the client side you will only need the access token you created.

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

Note: this client will have limited capabilities. For example, it will be able to generate new Cards but it will need a server-side client to transmit these to Virgil.

To initialize the SDK on the server side we will need the access token, app id and the App Key you created on the Developer Dashboard.

let url = Bundle.main.url(forResource: "[YOUR_APP_KEY_FILENAME_HERE]", withExtension: nil)!
let appPrivateKeyData = try! Data(contentsOf: url)
let credentials = VSSCredentials(appKeyData: appPrivateKeyData, appKeyPassword: "[YOUR_APP_KEY_PASSWORD_HERE]", appId: "[YOUR_APP_ID_HERE]")

let context = VSSVirgilApiContext(crypto: nil, token: "[YOUR_ACCESS_TOKEN_HERE]", credentials: credentials, cardVerifiers: nil)

let virgil = VSSVirgilApi(context: context)

Next: Learn more about our the different ways of initializing the Objective-C/Swift SDK in our documentation.

Documentation

Virgil Security has a powerful set of APIs, and the documentation is there to get you started today.

Migration notes

From version 4.7.0

  • VSCCrypto is now linked dynamically, so if you use Carthage you should link VSCCrypto.framework directly to your target and add it to Run script input files.

From version 4.4.0

List of the most important changes:

  • Renaming: VSSCreateGlobalCardRequest -> VSSCreateEmailCardRequest
  • Renaming: VSSCreateCardRequest -> VSSCreateUserCardRequest
  • Renaming: VSSRevokeGlobalCardRequest -> VSSRevokeEmailCardRequest
  • Renaming: VSSRevokeCardRequest -> VSSRevokeUserCardRequest

License

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

Support

Our developer support team is here to help you. You can find us on Twitter or send us email [email protected]