Awesome
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 | SDK Features | Installation | Usage Example | Docs | Support
Introduction
<a href="https://developer.virgilsecurity.com/docs"><img width="230px" src="https://cdn.virgilsecurity.com/assets/images/github/logos/virgil-logo-red.png" align="left" hspace="10" vspace="6"></a>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
is4.0.0
and minimum supported version ofvirgil-sdk
is6.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 useraccessTokenProvider
to provide access token for Virgil serviceskeyEntryStorage
to store data locallyprivateKey
of current device/userpublicKeys
of all devices/users that should have access to datavirgilCrypto
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());
Docs
Virgil Security has a powerful set of APIs, and the documentation below can get you started today.
License
This library is released under the BSD 3-Clause 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.