Virgil SDK allows developers to get up and running with Virgil API quickly and add full end-to-end (E2EE) security to their existing digital solutions to become HIPAA and GDPR compliant and more.
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
api
config/checkstyle
crypto-android
crypto
examples
sdk
.gitignore
.travis.yml
CONTRIBUTING.md
LICENSE.md
README.md
pom.xml

README.md

Virgil Security SDK and Crypto stack Java/Android

Build Status Maven GitHub license

Introduction | SDK Features | Library purposes | Installation | Usage Examples | Docs | Support

Introduction

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.

The Virgil SDK allows developers to get up and running with Virgil API quickly and add full end-to-end security to their existing digital solutions to become HIPAA and GDPR compliant and more.

SDK Features

Crypto Library purposes

  • Asymmetric Key Generation
  • Encryption/Decryption of data and streams
  • Generation/Verification of digital signatures
  • PFS (Perfect Forward Secrecy)

Installation

The Virgil SDK is provided as set of packages named com.virgilsecurity.sdk. Packages are distributed via Maven repository. Also in this guide, you find one more package - Virgil Crypto Library that is used by the SDK to perform cryptographic operations.

Target

  • Java 7+.
  • Android API 16+.

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

Use this packages for Java projects.

<dependencies>
    <dependency>
        <groupId>com.virgilsecurity.sdk</groupId>
        <artifactId>crypto</artifactId>
        <version>5.0.5</version>
    </dependency>
    <dependency>
        <groupId>com.virgilsecurity.sdk</groupId>
        <artifactId>sdk</artifactId>
        <version>5.0.5</version>
    </dependency>
</dependencies>

Gradle

Add jcenter() repository if missing:

repositories {
    jcenter()
}

Use this packages for Android projects.

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

Usage Examples

Before start practicing with the usage examples be sure that the SDK is configured. Check out our SDK configuration guides for more information.

Generate and publish user's Cards with Public Keys inside on Cards Service

Use the following lines of code to create and publish a user's Card with Public Key inside on Virgil Cards Service:

import com.virgilsecurity.crypto.VirgilCrypto;

VirgilCrypto crypto = new VirgilCrypto();

// generate a key pair
VirgilKeyPair keyPair = crypto.generateKeys();

// save a private key into key storage
privateKeyStorage.store(keyPair.getPrivateKey(), "Alice", null);

// publish user's card on the Cards Service
try {
    Card card = cardManager.publishCard(keyPair.getPrivateKey(), keyPair.getPublicKey(), "Alice");
    // Card is created
} catch (Exception e) {
    // Error occured
}

Sign then encrypt data

Virgil SDK lets you use a user's Private key and his or her Cards to sign, then encrypt any kind of data.

In the following example, we 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.

import com.virgilsecurity.crypto.VirgilCrypto;

VirgilCrypto crypto = new VirgilCrypto();

// prepare a message
String messageToEncrypt = "Hello, Bob!";
byte[] dataToEncrypt = ConvertionUtils.toBytes(messageToEncrypt);

// prepare a user's private key
Tuple<PrivateKey, Map<String, String>> alicePrivateKeyEntry =
        privateKeyStorage.load("Alice");
VirgilPrivateKey alicePrivateKey =
        (VirgilPrivateKey) alicePrivateKeyEntry.getLeft();

// using cardManager search for user's cards on Cards Service
try {
    List<Card> cards = cardManager.searchCards("Bob");
    // Cards are obtained
    List<VirgilPublicKey> bobRelevantCardsPublicKeys = new ArrayList<>();
    for (Card card : cards) {
        if (!card.isOutdated()) {
            bobRelevantCardsPublicKeys.add(
                    (VirgilPublicKey) card.getPublicKey());
        }
    }
    // sign a message with a private key then encrypt on a public key
    byte[] encryptedData = crypto.signThenEncrypt(dataToEncrypt,
            alicePrivateKey, bobRelevantCardsPublicKeys);
} catch (CryptoException | VirgilServiceException e) {
    // Error occured
}

Decrypt then verify data

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:

import com.virgilsecurity.crypto.VirgilCrypto;

VirgilCrypto crypto = new VirgilCrypto();

// prepare a user's private key
Tuple<PrivateKey, Map<String, String>> bobPrivateKeyEntry =
        privateKeyStorage.load("Bob");
VirgilPrivateKey bobPrivateKey =
        (VirgilPrivateKey) bobPrivateKeyEntry.getLeft();

try {
    // using cardManager search for user's cards on Cards Service
    List<Card> cards = cardManager.searchCards("Alice");
    // Cards are obtained
    List<VirgilPublicKey> aliceRelevantCardsPublicKeys = new ArrayList<>();
    for (Card card : cards) {
        if (!card.isOutdated()) {
            aliceRelevantCardsPublicKeys.add(
                    (VirgilPublicKey) card.getPublicKey());
        }
    }

    // decrypt with a private key and verify using a public key
    byte[] decryptedData = crypto.decryptThenVerify(encryptedData,
            bobPrivateKey, aliceRelevantCardsPublicKeys);
} catch (CryptoException | VirgilServiceException e) {
    // Error occured
}

Docs

Virgil Security has a powerful set of APIs, and the documentation below can get you started today.

In order to use the Virgil SDK with your application, you will need to first configure your application. By default, the SDK will attempt to look for Virgil-specific settings in your application but you can change it during SDK configuration.

License

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

Support

Our developer support team is here to help you. Find out more information on our Help Center.

You can find us on Twitter or send us email support@VirgilSecurity.com.

Also, get extra help from our support team on Slack.