Use A User's Card for crypto operations

With a user's Card published on Virgil Cards Service, we can encrypt data and verify a signature using Virgil SDK and Crypto Library.

Prerequisites for work

Install SDK & Setup Virgil Crypto

The Virgil .NET SDK is provided as a package named Virgil.SDK. The package is distributed via NuGet package management system.

The package is available for:

.NET Framework 4.5 and newer.

Prerequisites:

Visual Studio 2013 RTM Update 2 and newer (Windows)

Installing the package:

1. Use NuGet Package Manager (Tools -> Library Package Manager -> Package Manager Console)
2. Run PM> Install-Package Virgil.SDK

The Virgil Go SDK is provided as a package named virgil. The package is distributed via github.

The package is available for Go 1.7.1 or newer.

Installing the package:

go get -u gopkg.in/virgil.v4

The Virgil Java SDK is provided as a package named com.virgilsecurity.sdk. The package is distributed via Maven repository.

The package is available for:

Java 7 and newer
Android API 16 and newer

Prerequisites:

Java Development Kit (JDK) 7+
Maven 3+

Installing the package:

You can easily add SDK dependency to your project, just follow the examples below (Maven):


    
        com.virgilsecurity.sdk
        crypto
        4.3.3
    
    
        com.virgilsecurity.sdk
        sdk
        4.3.3

The Virgil Javascript SDK can be used both on the frontend in a web browser, and on the backend in a Node application with the same API.

The client-side SDK targets ECMAScript5+ compatible browsers.

This module requires Node 4.0+ and can be installed via NPM.

npm install virgil-sdk --save

The Virgil PFS is provided as a package. The package is distributed via Carthage and CocoaPods.

The package is available for:

iOS 7.0+

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'
use_frameworks!

target '' do
    pod 'VirgilSDK', '~> 4.5.0'
end

Then, run the following command:

$ pod install

> CocoaPods 0.36+ is required to build VirgilSDK 4.0.0+.

Carthage

As of version 4.2.0 VirgilSDK is available for integration using 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:

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-x" ~> 4.6.0

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/VirgilCrypto.framework
$(SRCROOT)/Carthage/Build/iOS/VirgilSDK.framework
```

The Virgil SDK is provided as a package named virgil/sdk. The package is distributed via composer package management system.

You need to install php virgil crypto extension ext-virgil_crypto_php as one of dependency otherwise you will get the requested PHP extension virgil_crypto_php is missing from your system error during composer install.

In general to install virgil crypto extension follow next steps:

Download proper extension package for your platform from cdn like virgil-crypto-2.0.4-php-5.6-linux-x86_64.tgz.

Type following command to unpack extension in terminal:

$ tar -xvzf virgil-crypto-2.0.4-php-5.6-linux-x86_64.tgz

Place unpacked virgil_crypto_php.so under php extension path.

Add virgil extension to your php.ini configuration file like extension = virgil_crypto_php.so.

$ echo "extension=virgil_crypto_php.so" >> \
`php --ini | grep "Loaded Configuration" | sed -e "s|.*:\s*||"`

All necessary information about where php.ini or extension_dir are you can get from php_info() in case run php on server or call php -i | grep php.ini or php -i | grep extension_dir from CLI.

Prerequisites:

PHP 5.6.*
Composer
virgil_crypto_php.so

Installing the package:

$ composer require virgil/sdk

The Virgil Python SDK is provided as a package named virgil-sdk. The package is distributed via pip package manager.

The package is available for:

Python 2.7.x
Python 3.x

Installing the package:

The Virgil Python SDK is provided as a package named virgil-sdk. The package is distributed via Pypi package management system. To install the pip package use the command below:

pip install virgil-sdk

The Virgil Ruby SDK is provided as a package named virgil-sdk. The package is distributed via bundler package manager.

The package is available for Ruby 2.1 and newer.

Installing the package:

To install the gem use the command below:

gem install virgil-sdk

or add the following line to your Gemfile:

gem 'virgil-sdk', '~> 4.2.6'

The Virgil is provided as a package. The package is distributed via Carthage and CocoaPods.

The package is available for:

iOS 7.0+

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'
use_frameworks!

target '' do
    pod 'VirgilSDK', '~> 4.5.0'
end

Then, run the following command:

$ pod install

> CocoaPods 0.36+ is required to build VirgilSDK 4.0.0+.

Carthage

As of version 4.2.0 VirgilSDK is available for integration using 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:

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-x" ~> 4.6.0

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/VirgilCrypto.framework
$(SRCROOT)/Carthage/Build/iOS/VirgilSDK.framework
```

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.

If you want to use VirgilSDK from swift 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 lines:

Set up authentication on a server side

Collect your Virgil developer credentials

Parameter	Description
APP_ID	ID of your Application at Virgil Dashboard
APP_KEY	A Private Key that is used to sign users' Cards. For security, you will only be shown the App Private Key when the key is created. Don't forget to save it in a secure location for the next step
APP_KEY_PASSWORD	A password to your APP KEY
ACCESS_TOKEN	An unique string that is used to authorize requests on Virgil Services.

Requests to your app server must be authorized. You can use any kind of authentication, for example, Google auth.

Next, you'll set up server-side SDK to sign and approve user's Card.

Here is an example of how to setup server side with an Access Token:

var virgil = new VirgilApi(new VirgilApiContext
{
  AccessToken = "[YOUR_ACCESS_TOKEN_HERE]",
  Credentials = new AppCredentials
  {
      AppId = "[YOUR_APP_ID_HERE]",
      AppKey = VirgilBuffer.FromFile("[YOUR_APP_KEY_FILEPATH_HERE]"),
      AppKeyPassword = "[YOUR_APP_KEY_PASSWORD_HERE]",
  }
});

keyfile, err := ioutil.ReadFile("[YOUR_APP_KEY_FILEPATH_HERE]")

api, err := virgilapi.NewWithConfig(virgilapi.Config{
        Token: "[YOUR_ACCESS_TOKEN_HERE]",
        Credentials: &virgilapi.AppCredentials{
            AppId:      "[YOUR_APP_ID_HERE]",
            PrivateKey: keyfile,
        },
    })

Crypto crypto = new VirgilCrypto();
VirgilClientContext ctx = new VirgilClientContext(APP_TOKEN);
VirgilClient client = new VirgilClient(ctx);
RequestSigner requestSigner = new RequestSigner(crypto);

// Import application private key
PrivateKey appKey = crypto.importPrivateKey(APP_PRIVATE_KEY.getBytes(),
    APP_PRIVATE_KEY_PASSWORD);

var fs = require('fs');
var api = virgil.API({
    accessToken: "[YOUR_ACCESS_TOKEN_HERE]",
    appCredentials: {
        appId: "[YOUR_APP_ID_HERE]",
        appKeyData: fs.readFileSync("[YOUR_APP_KEY_FILEPATH_HERE]"),
        appKeyPassword: "[YOUR_APP_KEY_PASSWORD_HERE]",
    }
});

$virgilApiContext = VirgilApiContext::create(
    [
        VirgilApiContext::AccessToken => '[YOUR_ACCESS_TOKEN_HERE]',
        VirgilApiContext::Credentials => new AppCredentials(
            '[YOUR_APP_ID_HERE]',
            Buffer::fromBase64('[YOUR_APP_PRIVATE_KEY_HERE]'),
            '[YOUR_APP_PRIVATE_KEY_PASS_HERE]'
        ),
    ]
);

$virgilApi = new VirgilApi($virgilApiContext);

key_file_content = open("[YOUR_APP_KEY_FILEPATH_HERE]", "r").read()
raw_private_key = base64.b64decode(key_file_content)

creds = Credentials(
    app_id="[YOUR_APP_ID_HERE]",
    app_key=raw_private_key,
    app_key_password="[YOUR_APP_KEY_PASSWORD_HERE]"
)

context = VirgilContext(
    access_token="[YOUR_ACCESS_TOKEN_HERE]",
    credentials=creds
)
virgil = Virgil(context=context)

virgil = VirgilApi.new(context: VirgilContext.new(
    access_token: "[YOUR_ACCESS_TOKEN_HERE]",
    credentials: VirgilAppCredentials.new(
        app_id: "[YOUR_APP_ID_HERE]",
        app_key_data: VirgilBuffer.from_file("[YOUR_APP_KEY_PATH_HERE]"),
        app_key_password: "[YOUR_APP_KEY_PASSWORD_HERE]"))
)

Set up authentication on a client side

In order to make call to Virgil Services, for example, to publish user's Card on Virgil Cards Service you need to have a Access Token. You have to generate for each Application an Access Token on Virgil Dashboard.

With the Access Token we can initialize the Virgil SDK on the client-side to start doing fun stuff like sending and receiving messages.

To initialize the Virgil SDK on a client-side you need to use the following code:

var virgil = new VirgilApi("[YOUR_ACCESS_TOKEN_HERE]");

api, err := virgilapi.New("[YOUR_ACCESS_TOKEN_HERE]")

VirgilApi virgil = new VirgilApiImpl("[YOUR_ACCESS_TOKEN_HERE]");

var api = virgil.API("[YOUR_ACCESS_TOKEN_HERE]");

VSSVirgilApi *virgil = [[VSSVirgilApi alloc]
  initWithToken:@"[YOUR_ACCESS_TOKEN_HERE]"];

$virgilApi = VirgilApi::create('[YOUR_ACCESS_TOKEN_HERE]');

virgil = Virgil("[YOUR_ACCESS_TOKEN_HERE]")

virgil = VirgilApi.new(access_token: "[YOUR_ACCESS_TOKEN_HERE]")

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

Set up Card Verifier

Virgil Card Verifier helps you automatically verify signatures of a User's Card, for example when you get Card from Virgil Cards Service.

By default, CardVerifiers verifies only two signatures - those of a Card owner and Virgil Cards Service.

Set up CardVerifiers with the following lines of code:

var appPublicKey = VirgilBuffer
    .From("[YOUR_APP_PUBLIC_KEY_HERE]", StringEncoding.Base64);

// initialize High Level Api
var virgil = new VirgilApi(new VirgilApiContext {
    AccessToken = "[YOUR_ACCESS_TOKEN_HERE]",
    CardVerifiers = new [] {
        new CardVerifierInfo {
            CardId = "[YOUR_APP_CARD_ID_HERE]",
            PublicKeyData = appPublicKey
        }
    }
});

var aliceCards = await virgil.Cards.FindAsync("alice");

appPublicKey, err := virgilapi.BufferFromBase64String("[YOUR_APP_PUBLIC_KEY_HERE]")

// initialize High Level Api with custom verifiers
api, err := virgilapi.NewWithConfig(virgilapi.Config{
    Token: "[YOUR_ACCESS_TOKEN_HERE]",
    CardVerifiers: map[string]virgilapi.Buffer{
            "[YOUR_APP_CARD_ID_HERE]": appPublicKey,
        },
})

aliceCards, err := api.Cards.Find("alice")

VirgilBuffer appPublicKey = VirgilBuffer.from("[YOUR_APP_PUBLIC_KEY_HERE]",
    StringEncoding.Base64);

// initialize High Level Api with custom verifiers
VirgilApiContext context = new VirgilApiContext("[YOUR_ACCESS_TOKEN_HERE]");
context.setCardVerifiers(Arrays.asList(
    new CardVerifierInfo("[YOUR_APP_CARD_ID_HERE]", appPublicKey)));

VirgilApi virgil = new VirgilApiImpl(context);

VirgilCards aliceCards = virgil.getCards().find("alice");

var appPublicKey = new Buffer("[YOUR_APP_PUBLIC_KEY_HERE]", "base64");

// initialize High Level Api with custom verifiers
var api = virgil.API({
    accessToken: "[YOUR_ACCESS_TOKEN_HERE]",
    cardVerifiers: [{
        cardId: "[YOUR_APP_CARD_ID_HERE]",
        publicKeyData: appPublicKey
    }]
});

api.cards.find("alice")
    .then(function (aliceCards) {
        // Alice's cards passed integrity checks
    });

NSData *appPublicKey = [[NSData alloc]
    initWithBase64EncodedString:"[YOUR_APP_PUBLIC_KEY_HERE]" options:0];

// initialize High Level Api with custom verifiers
VSSCardVerifierInfo *appVerifierInfo = [[VSSCardVerifierInfo alloc]
    initWithCardId:@"[YOUR_APP_CARD_ID_HERE]" publicKeyData:appPublicKey];
VSSVirgilApiContext *context = [[VSSVirgilApiContext alloc] initWithCrypto:nil
    token:@"[YOUR_ACCESS_TOKEN_HERE]" credentials:nil
    cardVerifiers:@[appVerifierInfo]];
VSSVirgilApi *virgil = [[VSSVirgilApi alloc] initWithContext:context];

[virgil.cards searchCardsWithIdentities:@[@"alice"]
    completion:^(NSArray* aliceCards, NSError *error) {
    //...
}];

// initialize context with custom card verifiers.
$virgilApiContext = VirgilApiContext::create(
    [
        VirgilApiContext::AccessToken   => '[YOUR_ACCESS_TOKEN_HERE]',
        VirgilApiContext::CardVerifiers => [
            new CardVerifier(
                '[YOUR_CARD_ID_HERE]',
                Buffer::fromBase64('[YOUR_PUBLIC_KEY_HERE]')
            ),
        ],
    ]
);

// initialize High level Api
$virgilApi = new VirgilApi($virgilApiContext);

$aliceCards = $virgilApi->Cards->find(['alice']);

crypto = VirgilCrypto()

# import your app private key
app_key_raw = "[YOUR_PRIVATE_KEY_STRING]"
app_key = base64.b64decode(app_key_raw)
app_private_key = crypto.import_private_key(app_key, "[YOU_APP_KEY_PASSWORD]")

# extract app public key
app_public_key = crypto.extract_public_key(app_private_key)

# prepare public key for use 
app_public_key_bytes = VirgilBuffer.from_bytes(bytearray(crypto.export_public_key(app_public_key)))

# initialize context with custom card verifiers.
context = VirgilContext(
        access_token="[YOUR_ACCESS_TOKEN_HERE]",
        card_verifiers=[
            CardVerifierInfo(
                card_id="[YOUR_APP_CARD_ID_HERE]",
                public_key=app_public_key_bytes
            )
        ]
    )

# initialize High level Api
virgil = Virgil(context=context)

alice_cards = virgil.cards.find(["alice"])

app_public_key = VirgilBuffer.from_base64("[YOUR_APP_PUBLIC_KEY_HERE]")

# initialize High Level Api with custom verifiers
virgil = VirgilApi.new(context: VirgilContext.new(
            access_token: "[YOUR_ACCESS_TOKEN_HERE]",
            card_verifiers: [VirgilCardVerifierInfo.new("[YOUR_APP_CARD_ID_HERE]", app_public_key)])
            )

alice_cards = virgil.cards.find("alice")

// initialize High Level Api with custom verifiers
let appVerifierInfo = VSSCardVerifierInfo(cardId: "[YOUR_APP_CARD_ID_HERE]",
    publicKeyData: appPublicKey)
let context = VSSVirgilApiContext(crypto: nil, token: [YOUR_ACCESS_TOKEN_HERE],
    credentials: nil, cardVerifiers: [appVerifierInfo])

let virgil = VSSVirgilApi(context: context)

virgil.cards.searchCards(withIdentities: ["alice"]) { aliceCards, error in
    //...
}

Encrypt data

Data encryption

Encrypt Data on a Public Key with the following code:

// search for Virgil Cards
var bobCards = await virgil.Cards.FindAsync("bob");

var message = "Hey Bob, how's it going?";

// encrypt the message using found Virgil Cards
var ciphertext = bobCards.Encrypt(message).ToString(StringEncoding.Base64);

// search for Virgil Cards
bobCards, err := api.Cards.Find("bob")

message := "Hey Bob, how's it going?"

// encrypt the message using found Virgil Cards
ciphertextBuf, err := bobCards.EncryptString(message)
ciphertext := ciphertextBuf.ToBase64String()

// search for Virgil Cards
VirgilCards bobCards = virgil.getCards().find("bob");

String message = "Hey Bob, how's it going?";

// encrypt the message using found Virgil Cards
String ciphertext = bobCards.encrypt(message).toString(StringEncoding.Base64);

// search for Cards
api.cards.find(["bob"])
  .then(function(bobCards) {
    // message for encryption
    var message = "Hey Bob, how's it going?";
    // encrypt the message
    var ciphertext = api.encryptFor(message, bobCards).toString("base64");
  });

// search for Virgil Cards
[virgil.cards searchCardsWithIdentities:@[@"bob"]
    completion:^(NSArray* bobCards, NSError *error) {
    NSString *message = @"Hey Bob, how's it going?";

    // encrypt the buffer using found Virgil Cards
NSString *ciphertext = [[virgil encryptString:message for:bobCards error:nil]
    base64EncodedStringWithOptions:0];
}];

// search for Bob's Virgil Cards
$bobCards = $virgilApi->Cards->find(['bob']);

$message = "Hey Bob, how's it going?";

// encrypt the message using found Virgil Cards
$cipherText = $bobCards->encrypt($message)->toBase64();

# search for Virgil Cards
bob_cards = virgil.cards.find(["bob"])

message = "Hey Bob, how's it going?"

# encrypt the message using found Virgil Cards
cipher_text = virgil.encrypt_for(bob_cards, message).to_string("base64")

# search for Virgil Cards
bob_cards = virgil.cards.find("bob")

message = "Hey Bob, how's it going?"

# encrypt the message using found Virgil Cards
ciphertext = bob_cards.encrypt(message).to_base64

// search for Virgil Cards
virgil.cards.searchCards(withIdentities: ["bob"]) { bobCards, error in
    let message = "Hey Bob, how's it going?"

    // encrypt the buffer using found Virgil Cards
    let ciphertext = (try! virgil.encrypt(message, for: bobCards!))
        .base64EncodedString()
}

Decrypt data

Once the Users receive the signed and encrypted message, they can decrypt it with their own Private Key. Data decryption

Use the following code to decrypt

// load a Virgil Key from device storage
var bobKey = virgil.Keys.Load("[KEY_NAME]", "[OPTIONAL_KEY_PASSWORD]");

// decrypt a ciphertext using loaded Virgil Key
var originalMessage = bobKey.Decrypt(ciphertext).ToString();

// load a Virgil Key from device storage
bobKey, err := api.Keys.Load("[KEY_NAME]", "[KEY_PASSWORD]")
// decrypt a ciphertext using loaded Virgil Key
originalMessageBuf, err := bobKey.Decrypt(ciphertext)

originalMessage := originalMessageBuf.ToString()

// load a Virgil Key from device storage
VirgilKey bobKey = virgil.getKeys().load("[KEY_NAME]",
    "[OPTIONAL_KEY_PASSWORD]");

// decrypt a ciphertext using loaded Virgil Key
String originalMessage = bobKey.decrypt(ciphertext).toString();

// load Key
api.keys.load("[KEY_NAME]", "[KEY_PASSWORD]")
    .then(function (bobKey) {
        // decrypt the message.
        var originalMessage = bobKey.decrypt(ciphertext).toString();
    });

// load a Virgil Key from device storage
VSSVirgilKey *bobKey = [virgil.keys loadKeyWithName:@"[KEY_NAME]"
  password:@"[OPTIONAL_KEY_PASSWORD]" error:nil];

// decrypt a ciphertext using loaded Virgil Key
NSString *originalMessage = [[NSString alloc]
  initWithData:[bobKey decryptBase64String:ciphertext error:nil]
  encoding:NSUTF8StringEncoding];

// load Bob's Key from storage
$bobKey = $virgilApi->Keys->load('[KEY_NAME]', '[KEY_PASSWORD]');

// decrypt message using Bob's Key
$originalMessage = $bobKey->decrypt($cipherText)->toString();

# load a Virgil Key from device storage
bob_key = virgil.keys.load("[KEY_NAME]", "[OPTIONAL_KEY_PASSWORD]")

# cipher_buffer from cipher text
cipher_buffer = VirgilBuffer.from_string(cipher_text, "base64")

# decrypt a ciphertext using loaded Virgil Key
original_message = bob_key.decrypt(cipher_buffer).to_string()

# load a Virgil Key from device storage
bob_key = virgil.keys.load("[KEY_NAME]", "[OPTIONAL_KEY_PASSWORD]")

# decrypt a ciphertext using loaded Virgil Key
original_message = bob_key.decrypt(ciphertext).to_s

// load a Virgil Key from device storage
let bobKey = try! virgil.keys.loadKey(withName: "[KEY_NAME]",
  password: "[OPTIONAL_KEY_PASSWORD]")

// decrypt a ciphertext using loaded Virgil Key
let originalMessage = String(data: try! bobKey.decrypt(base64: ciphertext),
  encoding: .utf8)!

Sign data

A valid digital signature gives a recipient reason to believe that the message was created by a known sender, that the sender cannot deny having sent the message, and that the message was not altered in transit.

Creating signature

Use the following code to sign data:

// prepare a message
var message = "Hey Bob, hope you are doing well.";

// generate signature
var signature = aliceKey.Sign(message);

// prepare a message
message := "Hey Bob, hope you are doing well."

// generate signature
signature, err := aliceKey.SignString(message)

// prepare a message
String message = "Hey Bob, hope you are doing well.";

// generate signature
VirgilBuffer signature = aliceKey.sign(message);

// prepare message
var message = "Hey Bob, hope you are doing well.";

// generate signature
var signature = aliceKey.sign(message);

// prepare a message
NSString *message = @"Hey Bob, hope you are doing well.";

// generate signature
NSData *signature = [aliceKey generateSignatureForString:message error:nil];

// load Alice's Key from storage
$aliceKey = $virgilApi->Keys->load('[KEY_NAME]', '[KEY_PASSWORD]');

$message = 'Hey Bob, hope you are doing well.';

// generate signature of the message using Alice's key
$aliceSignature = $aliceKey->sign($message);

# prepare a message
message = "Hey Bob, hope you are doing well."

# wrap data to buffer
data_buff = VirgilBuffer.from_string(message)

# generate signature
signature = alice_key.sign(data_buff)

# prepare a message
message = "Hey Bob, hope you are doing well."

# generate signature
signature = alice_key.sign(message)

// prepare a message
let message = "Hey Bob, hope you are doing well."

// generate signature
let signature = try! aliceKey.generateSignature(for: message)

Verify signature

In order to verify the digital Signature, Bob has to have Alice's Virgil Card

Verify a signature

use the following code to verify a signature:

// search for Virgil Card
var aliceCard = await virgil.Cards.Get("[ALICE_CARD_ID_HERE]");

// verify signature using Alice's Virgil Card
if (!aliceCard.Verify(message, signature))
{
    throw new Exception("Aha... Alice it's not you.");
}

// search for Virgil Card
aliceCard, err := api.Cards.Get("[ALICE_CARD_ID_HERE]")

// verify signature using Alice's Virgil Card
if res, err := aliceCard.Verify(message, signature); !res || err != nil {
        panic("Alice, it's not you!")
}

// search for Virgil Card
VirgilCard aliceCard = virgil.getCards().get("[ALICE_CARD_ID_HERE]");

// verify signature using Alice's Virgil Card
if (!aliceCard.verify(message, signature)) {
    throw new Exception("Aha... Alice it's not you.");
}

// search for Virgil Card
api.cards.get("ALICE_CARD_ID")
    .then(function(aliceCard) {
        // verify signature
        if (!aliceCard.verify(message, signature)) {
          throw new Error("The message is not from Alice.");
        }
    })

// search for Virgil Card
[virgil.cards getCardWithId:@"[ALICE_CARD_ID_HERE]"
    completion:^(VSSVirgilCard *aliceCard, NSError *error) {
    // verify signature using Alice's Virgil Card
    BOOL verified = [aliceCard verifyString:message
        withSignature:signature error:nil];

    if (!verified) {
        // "Aha... Alice it's not you."
    }
}];

// search for Virgil Card
$aliceCard = $virgilApi->Cards->get('[ALICE_CARD_ID_HERE]');

// verify signature using Alice's Virgil Card
if (!$aliceCard->verify($message, $signature)) {
    throw new Exception("Aha... Alice it's not you.");
}

# search for Virgil Card
alice_card = virgil.cards.get("[ALICE_CARD_ID_HERE]")

# verify signature using Alice's Virgil Card
if not alice_card.verify(message, signature):
    raise Exception("Aha... Alice it's not you.")

# search for Virgil Card
alice_card = virgil.cards.get("[ALICE_CARD_ID_HERE]")

# verify signature using Alice's Virgil Card
unless alice_card.verify(message, signature)

    raise "Aha... Alice it's not you."
end

// search for Virgil Card
virgil.cards.getCard(withId: "[ALICE_CARD_ID_HERE]") { aliceCard, error in
    do {
        try aliceCard!.verify(message, withSignature: signature)
    }
    catch {
        // "Aha... Alice it's not you."
    }
}

Sign then encrypt data

In order to sign then encrypt data, you need to load a Private Key from a customized Key Storage and get recipient's Card from the Virgil Cards Services.

Recipient's Card contains a Public Key on which we will encrypt the data and verify a signature.

Sign then encrypt data

Use the following code to sign then encrypt data:

// load a Virgil Key from device storage
var aliceKey = virgil.Keys.Load("[KEY_NAME]", "[OPTIONAL_KEY_PASSWORD]");

// search for Virgil Cards
var bobCards = await virgil.Cards.FindAsync("bob");

// prepare the message
var message = "Hey Bob, how's it going?";

// sign and encrypt the message
var ciphertext = aliceKey.SignThenEncrypt(message, bobCards)
    .ToString(StringEncoding.Base64);

// load a Virgil Key from device storage
aliceKey, err := api.Keys.Load("[KEY_NAME]", "[OPTIONAL_KEY_PASSWORD]")

// search for Virgil Cards
bobCards, err := api.Cards.Find("bob")

// prepare the message
message := "Hey Bob, how's it going?"

// sign and encrypt the message
ciphertextBuf, err := aliceKey.SignThenEncryptString(message, bobCards...)

ciphertext :=   ciphertextBuf.ToBase64String()

// load a Virgil Key from device storage
VirgilKey aliceKey = virgil.getKeys().load("[KEY_NAME]",
    "[OPTIONAL_KEY_PASSWORD]");

// search for Virgil Cards
VirgilCards bobCards = virgil.getCards().find("bob");

// prepare the message
String message = "Hey Bob, how's it going?";

// sign and encrypt the message
String ciphertext = aliceKey.signThenEncrypt(message, bobCards)
    .toString(StringEncoding.Base64);

Promise.all([
    // load Key
    api.keys.load("[KEY_NAME]", "[KEY_PASSWORD]"),
    // search for Cards
    api.cards.find("bob")
]).then(function(results) {
    var aliceKey = results[0];
    var bobCards = results[1];
    // prepare message
    var message = "Hey Bob, how's it going?";
    // sign then encrypt
    var encryptedData = aliceKey
      .signThenEncrypt(message, bobCards).toString("base64");
});

// load a Virgil Key from device storage
VSSVirgilKey *aliceKey = [virgil.keys loadKeyWithName:@"[KEY_NAME]"
    password:@"[OPTIONAL_KEY_PASSWORD]" error:nil];

// search for Virgil Cards
[virgil.cards searchCardsWithIdentities:@[@"bob"]
    completion:^(NSArray* bobCards, NSError *error) {
    // prepare the message
    NSString *message = @"Hey Bob, are you crazy?";

    // encrypt the buffer using found Virgil Cards
    NSString *cipherText = [[aliceKey signThenEncryptString:message
        forRecipients:bobCards] base64EncodedStringWithOptions:0];
}];

// load Alice's Key from storage
$aliceKey = $virgilApi->Keys->load('[KEY_NAME]', '[KEY_PASSWORD]');

// search for Bob's Cards
$bobCards = $virgilApi->Cards->find(['bob']);

$message = "Hey Bob, how's it going?";

// sign by Alice's key and then encrypt message for found Bob's Cards
$cipherText = $aliceKey->signThenEncrypt($message, $bobCards)->toBase64();

# load a Virgil Key from device storage
alice_key = virgil.keys.load("[KEY_NAME]", "[OPTIONAL_KEY_PASSWORD]")

# search for Virgil Cards
bob_cards = virgil.cards.find(["bob"])

# prepare the message
message = "Hey Bob, how's it going?"

# sign and encrypt the message
cipher_text = alice_key.sign_then_encrypt(message, bob_cards).to_string("base64")

# load a Virgil Key from device storage
alice_key = virgil.keys.load("[KEY_NAME]", "[OPTIONAL_KEY_PASSWORD]")

# search for Virgil Cards
bob_cards = await virgil.cards.find("bob")

# prepare the message
message = "Hey Bob, how's it going?"

# sign then encrypt the message
ciphertext = alice_key.sign_then_encrypt(message, bob_cards).to_base64

// load a Virgil Key from device storage
let aliceKey = try! virgil.keys.loadKey(withName: "[KEY_NAME]",
    password: "[OPTIONAL_KEY_PASSWORD]")

// search for Bob's cards on Virgil Services
virgil.cards.searchCards(withIdentities: ["bob"]) { bobCards, error in
    // prepare the message
    let message = "Hey Bob, are you crazy?"

    // encrypt the buffer using found Virgil Cards
    let ciphertext = (try! aliceKey.signThenEncrypt(message, for: bobCards!))
        .base64EncodedString()
}

Decrypt data then verify signature

Once the Users receive the signed and encrypted message, they can decrypt it with their own Private Key and verify signature with a Sender's Card.

Decrypt then verify

Use the following code to decrypt then verify:

// load a Virgil Key from device storage
var bobKey = virgil.Keys.Load("[KEY_NAME]", "[OPTIONAL_KEY_PASSWORD]");

// get a sender's Virgil Card
var aliceCard = await virgil.Cards.Get("[ALICE_CARD_ID]");

// decrypt the message
var originalMessage = bobKey.DecryptThenVerify(ciphertext, aliceCard).ToString();

// load a Virgil Key from device storage
bobKey, err := api.Keys.Load("[KEY_NAME]", "[OPTIONAL_KEY_PASSWORD]")

// get a sender's Virgil Card
aliceCard, err := api.Cards.Get("[ALICE_CARD_ID]")

// decrypt the message
originalMessageBuf, err := bobKey.DecryptThenVerify(ciphertext, aliceCard)

originalMessage := originalMessageBuf.ToString()

// load a Virgil Key from device storage
VirgilKey bobKey = virgil.getKeys().load("[KEY_NAME]",
    "[OPTIONAL_KEY_PASSWORD]");

// get a sender's Virgil Card
VirgilCard aliceCard = virgil.getCards().get("[ALICE_CARD_ID]");

// decrypt the message
String originalMessage = bobKey.decryptThenVerify(ciphertext, aliceCard)
    .toString();

Promise.all([
    // load key
    api.keys.load("[KEY_NAME]", "[KEY_PASSWORD]"),
    // search for Card
    api.cards.find("alice")
]).then(function(results) {
    var bobKey = results[0];
    var aliceCards = results[1];
    var alicePhoneCard = aliceCards.find(function (card) {
      return card.device === "iPhone7";
    });
    // decrypt the message
    var originalMessage = bobKey
      .decryptThenVerify(encryptedData, alicePhoneCard).toString();
});

// load a Virgil Key from device storage
VSSVirgilKey *bobKey = [virgil.keys loadKeyWithName:@"[KEY_NAME]"
    password:@"[OPTIONAL_KEY_PASSWORD]" error:nil];

// get a sender's Virgil Card
[virgil.cards getCardWithId:@"[ALICE_CARD_ID]"
    completion:^(VSSVirgilCard *aliceCard, NSError *error) {
    NSData *originalMessage = [[NSString alloc] initWithData:[bobKey
    decryptThenVerifyBase64String:ciphertext from:aliceCard error:nil]
    encoding:NSUTF8StringEncoding];
}];

// load a Virgil Key from device storage
$bobKey = $virgilApi->Keys->load('[KEY_NAME]', '[OPTIONAL_KEY_PASSWORD]');

// get a sender's Virgil Card
$aliceCard = $virgilApi->Cards->get('[ALICE_CARD_ID]');

// decrypt the message
$originalMessage = $bobKey->decryptThenVerify($cipherText, $aliceCard)->toString();

# load a Virgil Key from device storage
bob_key = virgil.keys.load("[KEY_NAME]", "[OPTIONAL_KEY_PASSWORD]")

# get a sender's Virgil Card
alice_card = virgil.cards.get("[ALICE_CARD_ID]")

cipher_buff = VirgilBuffer.from_string(cipher_text, "base64")

# decrypt the message
original_message = bob_key.decrypt_then_verify(cipher_buff, alice_card).to_string()

# load a Virgil Key from device storage
bob_key = virgil.keys.load("[KEY_NAME]", "[OPTIONAL_KEY_PASSWORD]")

# get a sender's Virgil Card
alice_card = virgil.cards.get("[ALICE_CARD_ID]")

# decrypt the message
original_message = bob_key.decrypt_then_verify(ciphertext, alice_card).to_s

// load a Virgil Key from device storage
let bobKey = try! virgil.keys.loadKey(withName: "[KEY_NAME]",
    password: "[OPTIONAL_KEY_PASSWORD]")

virgil.cards.getCard(withId: "[ALICE_CARD_ID]") { aliceCard, error in
    // decrypt the message
    let originalMessage = String(data: try! bobKey.decryptThenVerify(base64: ciphertext,
        from: aliceCard!), encoding: .utf8)!
}

Encrypt Data for multiple recipients

Encrypting for multiple recipients

Use the following code to encrypt data for multiple recipients:

// search for Cards
var bobCards = await virgil.Cards.FindAsync("bob");
// message for encryption
var message = "Hey Bob, how's it going?";
// encrypt the message
var ciphertext = bobCards.Encrypt(message).ToString(StringEncoding.Base64);

// search for Cards
bobCards, err := api.Cards.Find("bob")
// message for encryption
message := "Hey Bob, how's it going?"
// encrypt the message
ciphertextBuf, err := bobCards.EncryptString(message)

ciphertext := ciphertextBuf.ToBase64String()

// search for Cards
VirgilCards bobCards = virgil.getCards().find("bob");
// message for encryption
String message = "Hey Bob, how's it going?";
// encrypt the message
String ciphertext = bobCards.encrypt(message).toString(StringEncoding.Base64);

// search for Cards
api.cards.find(["bob"])
  .then(function(bobCards) {
    // message for encryption
    var message = "Hey Bob, how's it going?";
    // encrypt the message
    var ciphertext = api.encryptFor(message, bobCards).toString("base64");
  });

// search for Cards
[virgil.cards searchCardsWithIdentities:@[@"bob"]
    completion:^(NSArray* bobCards, NSError *error) {
    // message for encryption
    NSString *message = @"Hey Bob, how's it going?";

    // encrypt the message
    NSString *ciphertext = [[virgil encryptString:message for:bobCards error:nil]
        base64EncodedStringWithOptions:0];
}];

// search for Bob's and Alice's Cards
$bobAndAliceCards = $virgilApi->Cards->find(['bob', 'alice']);

$message = "Hey Bob, how's it going?";

// encrypt the message for multiple recipients
$cipherText = $bobAndAliceCards->encrypt($message)->toBase64();

# search for Cards
bob_cards = virgil.cards.find(["bob"])

# message for encryption
message = "Hey Bob, how's it going?"

# encrypt the message
cipher_text = virgil.encrypt_for(bob_cards, message).to_string("base64")

# search for Cards
bob_cards = virgil.cards.find("bob")

# message for encryption
message = "Hey Bob, how's it going?"

# encrypt the message
ciphertext = bob_cards.encrypt(message).to_base64

// search for Cards
virgil.cards.searchCards(withIdentities: ["bob"]) { bobCards, error in
    // message for encryption
    let message = "Hey Bob, are you crazy?"

    // encrypt the buffer using found Virgil Cards
    let ciphertext = (try! virgil.encrypt(message, for: bobCards!))
        .base64EncodedString()
}