Verify Card's signatures

This guide shows how to set up CardVerifier that verifies the signatures of all the parties that signed a user's Card.

With CardVerifier you can verify the following:

Signature of a Card owner;
Card ID;
Signature of your App Server;
Signature of Virgil Cards Service.

Prerequisites for work

Install SDK and Set up Virgil Crypto

The Virgil С++ SDK is provided as a package named virgil_sdk.

Requirements

C++11 compatible compiler
CMake 3.10+

Virgil С++ SDK can be integrated using CMake in different ways.

One of them is to use custom CMake util You can find file called virgil_depends_local.cmake at sdk-cpp/cmake/utils. This is an in-house dependency loader based on pure CMake features.

Usage:

Create cmake configuration file for target dependency

cmake_minimum_required (VERSION @CMAKE_VERSION@ FATAL_ERROR)

project ("@VIRGIL_DEPENDS_PACKAGE_NAME@-depends")

include (ExternalProject)

# Configure additional CMake parameters
file (WRITE "@VIRGIL_DEPENDS_ARGS_FILE@"
"set (ENABLE_TESTING OFF CACHE INTERNAL \"\")\n"
"set (INSTALL_EXT_LIBS ON CACHE INTERNAL \"\")\n"
"set (INSTALL_EXT_HEADERS ON CACHE INTERNAL \"\")\n"
"set (UCLIBC @UCLIBC@ CACHE INTERNAL \"\")\n"
)

ExternalProject_Add (${PROJECT_NAME}
DOWNLOAD_DIR "@VIRGIL_DEPENDS_PACKAGE_DOWNLOAD_DIR@"
URL "https://github.com/VirgilSecurity/sdk-cpp/archive/v5.0.0.tar.gz"
URL_HASH SHA1=
PREFIX "@VIRGIL_DEPENDS_PACKAGE_BUILD_DIR@"
CMAKE_ARGS "@VIRGIL_DEPENDS_CMAKE_ARGS@"
)

add_custom_target ("${PROJECT_NAME}-build" ALL COMMENT "Build package ${PROJECT_NAME}")
add_dependencies ("${PROJECT_NAME}-build" ${PROJECT_NAME})

In the project, add the following code

include (virgil_depends)

virgil_depends (
PACKAGE_NAME "virgil_sdk"
CONFIG_DIR "${CMAKE_CURRENT_SOURCE_DIR}/dir_to_config_file_from_step_1"
)

virgil_find_package (virgil_sdk)

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

Supported Platforms:

- .NET Standard 1.1+
- .NET Framework 4.5+
- .NET Core 1.0+
- Universal Windows Platform 10
- Windows 8.0+
- Windows Phone 8.1+
- Xamarin.Android 7.0+
- Xamarin.iOS 10.0+
- Mono 4.6+ for x86-64(AMD64)

Installing the package using Package Manager Console:

Run PM> Install-Package Virgil.Crypto
Run PM> Install-Package Virgil.SDK

This language is only suitable for the Server Side.

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

The package is available for Go 1.10 or newer.

Installing the package:

go get -u gopkg.in/virgil.v5/...

Crypto library notice

The built in crypto library supports only following primitives:

ED25519 keys
SHA512 hashes
AES256_GCM encrypting

and is not recommended for production use.

On linux and macOS consider using external crypto library written in c++

Using external crypto library (c++)

If you are building from sources, install prerequisites as described here. and then

go get -u -d gopkg.in/virgilsecurity/virgil-crypto-go.v5
cd $(go env GOPATH)/src/gopkg.in/virgilsecurity/virgil-crypto-go.v5
make

If you use Linux x64 or Darwin x64 architecture, you can use the pre-built crypto binaries

for Linux:

CRYPTO_LIB=virgil-crypto-2.4.4-go-linux-x86_64.tgz

for MacOS

CRYPTO_LIB=virgil-crypto-2.4.4-go-darwin-17.4-x86_64.tgz

and then

go get -u -d gopkg.in/virgilsecurity/virgil-crypto-go.v5
wget https://cdn.virgilsecurity.com/virgil-crypto/go/$CRYPTO_LIB
tar -xvf $CRYPTO_LIB --strip-components=1 -C $(go env GOPATH)/src/gopkg.in/virgilsecurity/virgil-crypto-go.v5/

in your source code use crypto objects from this library as follows:



import (
    "gopkg.in/virgilsecurity/virgil-crypto-go.v5"
)

var (
    crypto      = virgil_crypto_go.NewVirgilCrypto()
    cardCrypto  = virgil_crypto_go.NewVirgilCardCrypto()
    tokenSigner = virgil_crypto_go.NewVirgilAccessTokenSigner()
)

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+

You can easily add SDK dependency to your project, just follow the examples below.

Maven

Apache Maven is a software project management and comprehension tool.

To integrate Virgil SDK into your Java project using Maven, set up dependencies in your pom.xml:


    
        com.virgilsecurity.sdk
        crypto
        5.0.2
    
    
        com.virgilsecurity.sdk
        sdk
        5.0.2

Gradle

Gradle is an open-source build automation system that builds upon the concepts of Apache Ant and Apache Maven and introduces a Groovy-based domain-specific language (DSL) instead of the XML form used by Apache Maven for declaring the project configuration.

Server

To integrate Virgil SDK into your Java project using Gradle, set up dependencies in your build.gradle:

dependencies {
    compile 'com.virgilsecurity.sdk:crypto:5.0.2'
    compile 'com.virgilsecurity.sdk:sdk:5.0.2'
}

Android

To integrate Virgil SDK into your Android project using Gradle, add jcenter() repository if missing:

repositories {
    jcenter()
}

Set up dependencies in your build.gradle:

dependencies {
    compile 'com.virgilsecurity.sdk:crypto-android:5.0.2@aar'
    compile 'com.virgilsecurity.sdk:sdk:5.0.2'
}

Virgil SDK for JavaScript can be used both server-side in a Node.js application, and client-side in a web browser.

NPM

The recommended way is to install from npm, the Node package manager that lets you install the libraries you need. Simply fire up a terminal or command line interface on your machine that already has Node and npm installed, and run the following command in a new directory.

If you want to use Virgil Crypto library, you will also need to install the virgil-crypto package separately.

npm install virgil-sdk virgil-crypto

Important! You will need node.js version >= 6 to use virgil-sdk. If you have a different version, consider upgrade or use nvm (or a similar tool) to install Node.js of supported version alongside your current installation. If you only intend to use virgil-sdk in a browser, you can ignore this warning.

CDN

The pre-built versions of the libraries can also be added to an html page via <script> tag:

For the pre-built versions all name exports of virgil-sdk are available on the Virgil global namespace and all name exports of virgil-crypto on the VirgilCrypto global namespace.

This language is only suitable for the Server Side.

The Virgil SDK is provided as a package named virgil/sdk.

The package is distributed via Composer package management system.

The package is available for PHP version 5.6 and newer.

Installing the package using Package Manager Console:

composer require virgil/sdk virgil/crypto

Be aware virgil/crypto package requires installed php virgil crypto extension ext-virgil_crypto_php.

Get extension from CDN

Also there is avaliable [setup your own Crypto library][_own_crypto] inside of the 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

This language is only suitable for the Client Side.

Virgil SDK is provided as a set of frameworks. These frameworks are distributed via Carthage and CocoaPods.

All frameworks are available for:

iOS 9.0+
macOS 10.10+
tvOS 9.0+
watchOS 2.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:

target '' do
  use_frameworks!

  pod 'VirgilCrypto', '~> 5.0.0-alpha'
  pod 'VirgilSDK', '~> 5.7'
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 VirgilSDK into your Xcode project using Carthage, create an empty file with name Cartfile in your project's root folder and add following lines to your Cartfile

github "VirgilSecurity/virgil-sdk-x" ~> 5.7
github "VirgilSecurity/virgil-crypto-x" ~> 5.0.0-alpha

Linking against prebuilt binaries

To link prebuilt frameworks to your app, run following command:

$ carthage update --no-use-binaries

This will build each dependency or download a pre-compiled framework from github Releases.

Building for iOS/tvOS/watchOS

On your application targets’ “General” settings tab, in the “Linked Frameworks and Libraries” section, add following frameworks from the Carthage/Build folder inside your project's folder:

VirgilSDK
VirgilCryptoAPI
VirgilCrypto
VirgilCryptoFoundation
VSCCommon
VSCFoundation

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/VirgilCryptoAPI.framework
$(SRCROOT)/Carthage/Build/iOS/VirgilCrypto.framework
$(SRCROOT)/Carthage/Build/iOS/VirgilCryptoFoundation.framework
$(SRCROOT)/Carthage/Build/iOS/VSCCommon.framework
$(SRCROOT)/Carthage/Build/iOS/VSCFoundation.framework

Building for macOS

On your application targets’ “General” settings tab, in the “Embedded Binaries” section, drag and drop following frameworks from the Carthage/Build folder on disk:

VirgilSDK
VirgilCryptoAPI
VirgilCrypto
VirgilCryptoFoundation
VSCCommon
VSCFoundation

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

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

Integrating as subproject

It is possible to use carthage just for fetching right sources for further integration into your project. Run following command:

$ carthage update --no-build

This will fetch dependencies into a Carthage/Checkouts folder inside your project's folder. Then, drag and drop VirgilCrypto.xcodeproj, VirgilCryptoAPI.xcodeproj and VirgilSDK.xcodeproj from corresponding folders inside Carthage/Checkouts folder to your Xcode Project Navigator sidebar.

Next, on your application targets’ “General” settings tab, in the “Embedded Binaries” section add following frameworks from subprojects:

VirgilSDK
VirgilCryptoAPI
VirgilCrypto
VirgilCryptoFoundation
VSCCommon
VSCFoundation

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, VirgilCardVerifier verifies only two signatures - those of a Card owner and Virgil Cards Service.

Set up VirgilCardVerifier with the following lines of code:

#include 

using virgil::sdk::VirgilBase64;
using virgil::sdk::cards::verification::VirgilCardVerifier;
using virgil::sdk::cards::verification::VerifierCredentials;
using virgil::sdk::cards::verification::Whitelist;
using virgil::sdk::crypto::Crypto;

auto crypto = std::shared_ptr();

auto publicKeyData = VirgilBase64::decode(publicKeyStr);
auto yourBackendVerifierCredentials = VerifierCredentials("YOUR_BACKEND", publicKeyData);

auto yourBackendWhitelist = Whitelist({ yourBackendVerifierCredentials });

auto cardVerifier = VirgilCardVerifier(crypto, { yourBackendWhitelist });

using Virgil.Crypto;
using Virgil.SDK;

// initialize Crypto library
var cardCrypto = new VirgilCardCrypto();

var yourBackendVerifierCredentials = new VerifierCredentials()
{
    Signer = "YOUR_BACKEND",
    PublicKeyBase64 = publicKeyStr
};

 var yourBackendWhitelist = new Whitelist()
{
    VerifiersCredentials = new List()
    {
        yourBackendVerifierCredentials
    }
};

var verifier = new VirgilCardVerifier(cardCrypto)
            {
                Whitelists = new List() { yourBackendWhitelist }
            };

    cardVerifier, err := sdk.NewVirgilCardVerifier(cardCrypto, true, true)
    if err != nil {
        //handle error
    }

// initialize Crypto library
CardCrypto cardCrypto = new VirgilCardCrypto();

VerifierCredentials yourBackendVerifierCredentials =
        new VerifierCredentials("YOUR_BACKEND",
                ConvertionUtils.base64ToBytes(PUBLIC_KEY_STR));

Whitelist yourBackendWhiteList =
        new Whitelist(Arrays.asList(yourBackendVerifierCredentials));

CardVerifier cardVerifier = new VirgilCardVerifier(cardCrypto,
        Arrays.asList(yourBackendWhiteList));

import { VirgilCrypto, VirgilCardCrypto } from 'virgil-crypto';
import { VirgilCardVerifier } from 'virgil-sdk';

// initialize Crypto library
const cardCrypto = new VirgilCardCrypto(new VirgilCrypto());
const cardVerifier = new VirgilCardVerifier(cardCrypto);

use Virgil\CryptoImpl\VirgilCardCrypto;
use Virgil\CryptoImpl\VirgilCrypto;

use Virgil\Sdk\Verification\VerifierCredentials;
use Virgil\Sdk\Verification\VirgilCardVerifier;
use Virgil\Sdk\Verification\Whitelist;

// initialize Crypto library
$crypto = new VirgilCrypto();
$cardCrypto = new VirgilCardCrypto();

$publicKey = $crypto->importPublicKey("EXPORTED_PUBLIC_KEY");

$yourBackendVerifierCredentials = new VerifierCredentials("YOUR_BACKEND", $publicKey);

$yourBackendWhitelist = new Whitelist([$yourBackendVerifierCredentials]);

$cardVerifier = new VirgilCardVerifier($cardCrypto, true, true, $yourBackendWhitelist);

from virgil_crypto.card_crypto import CardCrypto
from virgil_sdk import VirgilCardVerifier
from virgil_sdk.verification import VerifierCredentials, WhiteList

# initialize Crypto library
card_crypto = CardCrypto()
your_backend_verifier_credentials = VerifierCredentials(signer="YOUR_BACKEND", public_key_base64=public_key_str)

your_backend_white_list = WhiteList()
your_backend_white_list.verifiers_credentials = your_backend_verifier_credentials

verifier = VirgilCardVerifier(card_crypto, white_lists=[your_backend_white_list])

import VirgilSDK
import VirgilCrypto

// initialize Crypto library
let cardCrypto = VirgilCardCrypto()

let yourBackendVerifierCredentials =
    VerifierCredentials(signer: "YOUR_BACKEND",
                        publicKey: Data(base64Encoded: publicKeyStr)!)

let yourBackendWhitelist =
    try! Whitelist(verifiersCredentials: [yourBackendVerifierCredentials])

let cardVerifier = VirgilCardVerifier(cardCrypto: cardCrypto,
                                      whitelists: [yourBackendWhitelist])