Search user's Card by user's identity

This guide shows how to get a user's Card from Virgil Cards Service by user's identity and identityType.

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 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
    //...
}

Search User's Cards

Use the following code to search Cards on the Virgil Cards Service by identity and identityType:

// search for all User's Virgil Cards.
var aliceCards = await virgil.Cards.FindAsync("alice");

// search for all User's Virgil Cards with identity type 'member'
var bobCards = await virgil.Cards.FindAsync("member", new[] { "bob" });

// search for all Global Virgil Cards
bobGlobalCards, err := api.Cards.FindGlobal("email", "bob@VirgilSecurity.com")

// search for Application Virgil Card
appCards, err := api.Cards.FindGlobal("application", "com.username.appname")

// search for all User's Virgil Cards.
VirgilCards aliceCards = virgil.getCards().find("alice");

// search for all User's Virgil Cards with identity type 'member'
VirgilCards bobCards = virgil.getCards().find("member", Arrays.asList("bob"));

// search for all Virgil Cards.
api.cards.find("alice")
    .then(function(aliceCards) {
        // do something with Alice's Virgil Cards
    });

// Virgil cards with type 'member'
api.cards.find(["bob"], "member")
    .then(function(bobCards) {
        // do something with Bob's Virgil Cards
    });

// search for all User's Virgil Cards.
[virgil.cards searchCardsWithIdentities:@[@"alice"]
    completion:^(NSArray* aliceCards, NSError *error) {
    //...
}];

// search for all User's Virgil Cards with identity type 'member'
[virgil.cards searchCardsWithIdentityType:@"member" identities:@[@"bob"]
    completion:^(NSArray* bobCards, NSError *error) {
    //...
}];

// search for all Alice's Virgil Cards.
$aliceCards = $virgilApi->Cards->find(['alice']);

// search for all Bob's Virgil Cards with identity type 'member'
$bobCards = $virgilApi->Cards->find(['bob'], 'member');

# search for all Global Virgil Cards
list_for_search = ["bob@VirgilSecurity.com"]
bob_global_cards = virgil.cards.find_global(list_for_search)

# search for Application Virgil Card
app_cards = virgil.cards.find_global("com.username.appname")

# search for all Global Virgil Cards
bob_global_cards = virgil.cards.find_global(VirgilIdentity::EMAIL,
 "bob@VirgilSecurity.com")

# search for Application Virgil Card
app_cards = virgil.cards.find_global(VirgilIdentity::APPLICATION, "com.username.appname")

// search for all Global Virgil Cards
virgil.cards.searchGlobalCards(withIdentities: ["bob@VirgilSecurity.com"])
    { bobGlobalCards, error in
    //...
}

// search for Application Virgil Card
virgil.cards.searchGlobalCards(withIdentities: ["com.username.appname"])
    { appCards, error in
    //...
}