Generate a Key Pair

This guide shows how to generate an asymmetric Private Key using Virgil Crypto Library.

Prerequisites for work

Install Virgil Crypto

The Virgil С++ Crypto is provided as a part of the 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 Crypto is provided as a package named Virgil.SDK.Crypto. The package is distributed via NuGet package management system.

Supported Platforms:

.NET Framework 4.5+
ASP.NET Core 1.0+
Windows 8+
Windows Phone 8.1+
Windows Phone Silverlight 8+

Installing the package using Package Manager Console:

Run PM> Install-Package Virgil.Crypto

To install the latest wrapper version run:

go get -d gopkg.in/virgilsecurity/virgil-crypto-go.v5

and then run:

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

Depending on your choice of crypto implementation you should create crypto instance by calling:

var (
    crypto = virgil_crypto_go.NewVirgilCrypto()
)

var (
    crypto = cryptoimpl.NewVirgilCrypto()
)

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 Crypto for JavaScript is available on npm:

NPM

$ npm install virgil-crypto

Important! You will need Node.js version >=6 to use virgil-crypto. 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-crypto in a browser, you can ignore this warning.

CDN

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

The Virgil Python SDK is provided as a package named virgil-sdk. The package is distributed via Pypi package management system.

Supported Platforms:

Linux
Windows
OS X

Prerequisites:

Python 2.7.x
Python 3.x

To install the pip package use the command below:

pip install virgil-crypto

VirgilCrypto 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.9+
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 VirgilCrypto into your Xcode project using CocoaPods, specify it in your Podfile:

target '' do
  use_frameworks!

  pod 'VirgilCrypto', '~> 5.0.0-alpha'
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-crypto-x" ~> 5.0.0-alpha

Linking against prebuilt binaries

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

$ carthage update

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:

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

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

This will fetch dependencies into a Carthage/Checkouts folder inside your project's folder. Then, drag and drop VirgilCrypto.xcodeproj and VirgilCryptoAPI.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:

VirgilCryptoAPI
VirgilCrypto
VirgilCryptoFoundation
VSCCommon
VSCFoundation

You can also generate a Private Key with the default key pair algorithm or choose a specific algorithm available on this table. Also, during Key generation you can protect it with a password.

Virgil doesn't keep a copy of your Key. If you lose a Key, there is no way to recover it.

Generate a Private Key with the default algorithm (EC_X25519):

#include 

using virgil::sdk::crypto::Crypto;

Crypto crypto;

//generate a key pair
auto keyPair = crypto.generateKeyPair();

using Virgil.Crypto;

var crypto = new VirgilCrypto();
var keyPair = crypto.GenerateKeys();

    keypair, err := crypto.GenerateKeypair()

VirgilCrypto crypto = new VirgilCrypto();
VirgilKeyPair keyPair = crypto.generateKeys();

import { VirgilCrypto } from 'virgil-crypto';

const virgilCrypto = new VirgilCrypto();
const keyPair = virgilCrypto.generateKeys();

use Virgil\CryptoImpl\VirgilCrypto;

$crypto = new VirgilCrypto();
$keyPair = $crypto->generateKeys();

crypto = VirgilCrypto()
key_pair = crypto.generate_keys()

import VirgilCrypto

let crypto = try! VirgilCrypto()
let keyPair = try! crypto.generateKeyPair()

Generate a Private Key with a specific algorithm:

using Virgil.Crypto;

var crypto = new VirgilCrypto(KeyPairType.RSA_4096);
var keyPair = crypto.GenerateKeys();

    crypto.SetKeyType(virgil_crypto_go.RSA_4096)
    keypair, err := crypto.GenerateKeypair()

VirgilCrypto crypto = new VirgilCrypto(KeysType.RSA_4096);
VirgilKeyPair keyPair = crypto.generateKeys();

import { VirgilCrypto, KeyPairType } from 'virgil-crypto';

// construct instance that always creates 256-bits NIST curve keys
const virgilCrypto = new VirgilCrypto({ defaultKeyPairType: KeyPairType.EC_SECP256R1 });
const keyPair = virgilCrypto.generateKeys();

// alternatively, you can pass the type of keys to generate directly into `generateKeys`
const otherKeyPair = virgilCrypto.generateKeys(KeyPairType.RSA_4096);

use Virgil\CryptoImpl\KeyPairTypes;
use Virgil\CryptoImpl\VirgilCrypto;

$crypto = new VirgilCrypto();
$keyPair = $crypto->generateKeys(KeyPairTypes::RSA4096);

crypto = VirgilCrypto()
key_pair = crypto.generate_keys(KeyPairType.RSA_4096)

import VirgilCrypto

let crypto = VirgilCrypto(defaultKeyType: .RSA_4096)
let keyPair = try! crypto.generateKeyPair()