# @virgilsecurity/keyknox

> Keyknox SDK allows developers to communicate with Virgil Keyknox Service to upload, download, and synchronize encrypted sensitive data (private keys) between different devices.

Latest version **1.0.4** (published 2024-04-19) · BSD-3-Clause license · 0 weekly downloads

## Install

```sh
npm install @virgilsecurity/keyknox
pnpm add @virgilsecurity/keyknox
yarn add @virgilsecurity/keyknox
bun add @virgilsecurity/keyknox
```

## Health

**Score 30/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.4 |
| Published | 2024-04-19 |
| First published | 2018-08-27 |
| Weekly downloads | 0 |
| License | BSD-3-Clause |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 4 |
| Unpacked size | 115.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 3 |
| Author | Virgil Security Inc. |
| Maintainers | rstp, ddain, mbalyaba |

## Links

- npm: https://www.npmjs.com/package/@virgilsecurity/keyknox
- Repository: https://github.com/VirgilSecurity/virgil-keyknox-javascript
- npm.io page: https://npm.io/package/@virgilsecurity/keyknox

## Dependencies (4)

- [axios](https://npm.io/package/axios.md) ^1.6.8
- [base-64](https://npm.io/package/base-64.md) ^0.1.0
- [@types/base-64](https://npm.io/package/@types/base-64.md) ^0.1.3
- [@virgilsecurity/crypto-types](https://npm.io/package/@virgilsecurity/crypto-types.md) ^2.0.0

## Recent versions

- 1.0.4 (latest) — 2024-04-19
- 0.4.0-next.4 (next) — 2020-01-24
- 1.0.3 — 2021-04-16
- 1.0.2 — 2021-03-12
- 1.0.1 — 2020-04-24
- 1.0.0 — 2020-02-18
- 0.4.0-next.3 — 2019-10-23
- 0.4.0-next.2 — 2019-10-16
- 0.3.3 — 2019-10-15
- 0.3.2 — 2019-10-10
- 0.3.1 — 2019-10-09
- 0.4.0-next.1 — 2019-10-07
- 0.4.0-next.0 — 2019-09-24
- 0.3.0 — 2019-09-17
- 0.3.0-alpha.1 — 2019-09-05
- … 12 more at https://npm.io/package/@virgilsecurity/keyknox/versions

## README

> This README is for Keyknox v1.0.0. Check the [v0.3.x branch](https://github.com/VirgilSecurity/virgil-keyknox-javascript/tree/v0.3.x) for Keyknox v0.3.x docs.

# Virgil Keyknox JavaScript SDK

[![npm](https://img.shields.io/npm/v/@virgilsecurity/keyknox.svg)](https://www.npmjs.com/package/@virgilsecurity/keyknox)
[![Build Status](https://img.shields.io/travis/VirgilSecurity/virgil-keyknox-javascript.svg)](https://travis-ci.org/VirgilSecurity/virgil-keyknox-javascript)
[![GitHub license](https://img.shields.io/badge/license-BSD%203--Clause-blue.svg)](https://github.com/VirgilSecurity/virgil-keyknox-javascript/blob/master/LICENSE)

[Introduction](#introduction) | [SDK Features](#sdk-features) | [Installation](#installation) | [Usage Example](#usage-example) | [Docs](#docs) | [Support](#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](https://virgilsecurity.com) 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](https://github.com/VirgilSecurity/virgil-crypto-javascript)
- use [Virgil SDK](https://github.com/VirgilSecurity/virgil-sdk-javascript)
- 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`.
```sh
npm install @virgilsecurity/keyknox
```

You will also need to install `virgil-crypto` and `virgil-sdk` from npm.
```sh
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.
```html
<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.
```html
<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

```js
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](example).

### 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.

```js
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.

* [Virgil Security Documentation](https://developer.virgilsecurity.com)

## License
This library is released under the [BSD 3-Clause License](LICENSE).

## Support
Our developer support team is here to help you. Find out more information on our [Help Center](https://help.virgilsecurity.com).

You can find us on [Twitter](https://twitter.com/VirgilSecurity) or send us email support@VirgilSecurity.com.

Also, get extra help from our support team on [Slack](https://virgilsecurity.com/join-community).

---
_Source: https://npm.io/package/@virgilsecurity/keyknox · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._