@virgilsecurity/keyknox NPM

This README is for Keyknox v1.0.0. Check the v0.3.x branch for Keyknox v0.3.x docs.

Virgil Keyknox JavaScript SDK

Introduction

Virgil Security provides an SDK which allows you to communicate with Virgil Keyknox Service. Virgil Keyknox Service allows users to store their sensitive data (such as Private Key) encrypted (with end-to-end encryption) for using and sharing it between different devices.

SDK Features

use Virgil Crypto library
use Virgil SDK
upload encrypted sensitive data to Virgil Keyknox Service
download the data from Virgil Keyknox Service
update and synchronize the data

Installation

You can install this module from npm. Another option is to add it via script tag in browser.

npm

You will need to install @virgilsecurity/keyknox.

npm install @virgilsecurity/keyknox

You will also need to install virgil-crypto and virgil-sdk from npm.

npm install virgil-crypto virgil-sdk

Note that minimum supported version of virgil-crypto is 4.0.0 and minimum supported version of virgil-sdk is 6.0.0.

In browser via `script` tag

You will need to add @virgilsecurity/keyknox script.

<script src="https://unpkg.com/@virgilsecurity/keyknox@^1.0.0/dist/keyknox.umd.js"></script>

You will also need to add virgil-crypto and virgil-sdk scripts.

<script src="https://unpkg.com/virgil-crypto@^4.0.0/dist/browser.umd.js"></script>
<script src="https://unpkg.com/virgil-sdk@^6.0.0/dist/virgil-sdk.browser.umd.js"></script>

Now you can use global variables Keyknox, Virgil and VirgilCrypto as namespace objects, containing all of @virgilsecurity/keyknox, virgil-sdk and virgil-crypto exports as properties.

Usage Example

To begin using Virgil Keyknox SDK you'll need to initialize SyncKeyStorage class. This class is responsible for synchronization between device storage - IndexedDB in a browser or file system in Node.js - and Keyknox Cloud. In order to initialize SyncKeyStorage class you'll need the following values:

identity of the user
accessTokenProvider to provide access token for Virgil services
keyEntryStorage to store data locally
privateKey of current device/user
publicKeys of all devices/users that should have access to data
virgilCrypto to perform all cryptographic operations

const { SyncKeyStorage } = require('@virgilsecurity/keyknox');
const { initCrypto, VirgilCrypto } = require('virgil-crypto');

initCrypto().then(() => {
  // Identity of the user
  const identity = ...;

  // Setup Access Token provider to provide access token for Virgil services
  // Check https://github.com/VirgilSecurity/virgil-sdk-javascript
  const accessTokenProvider = ...;

  // Setup Key Entry Storage to store data locally
  // Check https://github.com/VirgilSecurity/virgil-sdk-javascript
  const keyEntryStorage = ...;

  // Public keys of users that should have access to data
  const publicKeys = ...;

  // Private key of current user
  const privateKey = ...;

  // An instance of `VirgilCrypto` class
  const virgilCrypto = new VirgilCrypto();

  const syncKeyStorage = SyncKeyStorage.create({
    identity,
    accessTokenProvider,
    keyEntryStorage,
    privateKey,
    publicKeys,
    virgilCrypto,
  });
});

You can find a complete example of simple client-server application here.

What if I lost my private key?

If you lost your private key, you are not able to decrypt saved data anymore. So you need to reset your stored data in the Virgil Keyknox Service and start over.

import { KeyknoxClient } from '@virgilsecurity/keyknox';

const tokenPromise = accessTokenProvider.getToken({ operation: 'delete' });
const resetPromise = tokenPromise.then(token => new KeyknoxClient().resetValue(token.toString()));
const syncKeyStorage = SyncKeyStorage.create(...);

resetPromise.then(() => syncKeyStorage.sync());