buddahld / virgil-sdk-javascript

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.

Virgil Security JavaScript SDK

Introduction | SDK Features | 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

• communicate with Virgil Cards Service
• manage users' Public Keys
• store private keys in secure local storage
• use Virgil Crypto library
• use your own Crypto

Installation

This module can be used both server-side in a Node application, and client-side in a web browser.

On a server

The recommended way is to install from npm:

npm install virgil-sdk

You will also need to install the virgil-crypto package from npm, unless plan to use custom crypto

npm install virgil-crypto

Important! You will need node.js version >= 6 to use virgil-sdk.
If you have a different version, consider upgrading 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 environment, you can ignore this warning.

In the browser

The client-side SDK targets ECMAScript5+ compatible browsers. It is compatible with module bundlers like Rollup, Webpack and Browserify. If you're using those, you need to install from npm. It can be added to the html page directly via script tag as well.

Note that the virgil-crypto script must also be added to the page.

<script src="https://unpkg.com/virgil-crypto/dist/virgil-crypto.browser.umd.min.js"></script>
<script src="https://unpkg.com/virgil-sdk/dist/virgil-sdk.browser.umd.min.js"></script>
<script>
	// here you can use the global variables `Virgil` and `VirgilCrypto` as namespace objects,
	// containing all of `virgil-sdk` and `virgil-crypto` exports as properties

	// note that you cannot declare a variable named `crypto` in
	// global scope (i.e. outside of any function) in browsers that
	// implement Web Crypto API
	const virgilCrypto = new VirgilCrypto.VirgilCrypto();
	const virgilCardCrypto = new VirgilCrypto.VirgilCardCrypto(virgilCrypto);

	const jwtProvider = new Virgil.CachingJwtProvider(fetchVirgilJwt);
	const cardVerifier = new Virgil.VirgilCardVerifier(virgilCardCrypto);
	const cardManager = new Virgil.CardManager({
		cardCrypto: virgilCardCrypto,
		accessTokenProvider: jwtProvider,
		cardVerifier: cardVerifier
	});
</script>

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 code to create and publish a user's Card with Public Key inside on Virgil Cards Service:

import { VirgilCrypto, VirgilCardCrypto, VirgilPrivateKeyExporter } from 'virgil-crypto';
import { CachingJwtProvider, CardManager, PrivateKeyStorage, VirgilCardVerifier } from 'virgil-sdk';

(async function() {
	const virgilCrypto = new VirgilCrypto();
	const cardCrypto = new VirgilCardCrypto(virgilCrypto);
	
	const jwtProvider = new CachingJwtProvider(fetchVirgilJwt);
	const cardVerifier = new VirgilCardVerifier(cardCrypto);
	const cardManager = new CardManager({
		cardCrypto: cardCrypto,
		accessTokenProvider: jwtProvider,
		cardVerifier: cardVerifier
	});
	const privateKeyStorage = new PrivateKeyStorage(
		new VirgilPrivateKeyExporter(
			virgilCrypto,
			'[OPTIONAL_PASSWORD_TO_ENCRYPT_THE_KEYS_WITH]'
		)
	);
	
	// Generate a key pair
	const keyPair = virgilCrypto.generateKeys();
	
	// Store the private key
	await privateKeyStorage.save('alice_private_key', keyPair.privateKey);
	
	// Publish user's card on the Cards Service
	const card = await cardManager.publishCard({
		privateKey: keyPair.privateKey,
		publicKey: keyPair.publicKey,
		identity: '[email protected]'
	});
})();

async function fetchVirgilJwt (context) {
	// assuming your backend server is serving Virgil JWT tokens in plaintext
	// at /virgil-access-token endpoint
	const response = await fetch('/virgil-access-token');
	if (!response.ok) {
		throw new Error('Failed to get Virgil Access Token');
	}

	return await response.text();
}

Sign then encrypt data

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

In the following example, we load a Private Key from persistent storage and get recipient's Card from the Virgil Cards Service.

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

import { VirgilCrypto, VirgilPrivateKeyExporter } from 'virgil-crypto';
import { PrivateKeyStorage } from 'virgil-sdk';

(async function() {
	const virgilCrypto = new VirgilCrypto();
	const privateKeyStorage = new PrivateKeyStorage(
		new VirgilPrivateKeyExporter(
			virgilCrypto,
			'[OPTIONAL_PASSWORD_TO_ENCRYPT_THE_KEYS_WITH]'
		)
	);
	
	// Load the private key
	const alicePrivateKey = await privateKeyStorage.load('alice_private_key');
	if (alicePrivateKey === null) {
		console.log('Private key named "alice_private_key" does not exist');
		return;
	}
	
	const cards = await cardManager.searchCards('[email protected]');
	if (cards.length === 0) {
		console.log('Virgil Card with identity "[email protected]" does not exist');
		return;
	}
	
	const messageToEncrypt = 'Hello, Bob!';
	const bobPublicKeys = cards.map(card => card.publicKey);
	const encryptedMessage = virgilCrypto.signThenEncrypt(messageToEncrypt, alicePrivateKey, bobPublicKeys);
	console.log(encryptedMessage.toString('base64'));
})();

Decrypt then verify data

Once the users receive the signed and encrypted message, they can decrypt it with their own private key and verify the signature with the Sender's public key:

import { VirgilCrypto, VirgilPrivateKeyExporter } from 'virgil-crypto';
import { PrivateKeyStorage } from 'virgil-sdk';

(async function() {
	const virgilCrypto = new VirgilCrypto();
	const privateKeyStorage = new PrivateKeyStorage(
		new VirgilPrivateKeyExporter(
			virgilCrypto,
			'[OPTIONAL_PASSWORD_TO_ENCRYPT_THE_KEYS_WITH]'
		)
	);
	
	// Load the private key 
	const bobPrivateKey = await privateKeyStorage.load('bob_private_key');
	if (bobPrivateKey === null) {
		console.log('Private key named "bob_private_key" does not exist');
		return;
	}
	
	const cards = await cardManager.searchCards('[email protected]');
	if (cards.length === 0) {
		console.log('Virgil Card with identity "[email protected]" does not exist');
		return;
	}
	
	const alicePublicKeys = cards.map(card => card.publicKey);
	const decryptedMessage = virgilCrypto.decryptThenVerify(encryptedMessage, bobPrivateKey, alicePublicKeys);
	console.log(decryptedMessage.toString());
})();

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.

• Configure the SDK documentation
  • Setup authentication to make API calls to Virgil Services
  • Setup Card Manager to manage user's Public Keys
  • Setup Card Verifier to verify signatures inside of user's Card
  • Setup Key storage to store Private Keys
  • Setup your own Crypto library inside of the SDK
• More usage examples
  • Create & publish a Card that has a Public Key on Virgil Cards Service
  • Search user's Card by user's identity
  • Get user's Card by its ID
  • Use Card for crypto operations
• API Reference

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 [email protected].

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