Home

Awesome

This README is for virgil-pythia v1.0.x. Check the v0.2.7 branch for virgil-pythia docs.

Virgil Pythia Node.js SDK

npm Build Status GitHub license

Introduction | SDK Features | Install and configure SDK | Usage Examples | 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 Pythia Service and implement Pythia protocol for the following use cases:.

In both cases you get the mechanism which assures you that neither Virgil nor attackers know anything about user's password.

SDK Features

Install and configure SDK

Install Pythia SDK with the following code:

npm install virgil-pythia

You will also need to install the virgil-crypto, @virgilsecurity/pythia-crypto and virgil-sdk packages.

npm install virgil-crypto @virgilsecurity/pythia-crypto virgil-sdk

Configure SDK

The library needs the following information from your Virgil Dashboard account:

ParameterDescriptionPurpose
API_KEY_IDId of the API KeyUsed for JWT generation
API_KEYThe private key of the API KeyUsed for JWT generation
APP_IDId of the Pythia AppUsed for JWT generation
PROOF_KEYThe Proof Key of the Pythia AppUsed to verify the cryptographic proof that transformed password returned form service is correct

Here is an example of how to configure the library for work with Virgil Pythia Service:


import { initPythia, VirgilPythiaCrypto } from '@virgilsecurity/pythia-crypto';
import { initCrypto, VirgilCrypto, VirgilAccessTokenSigner } from 'virgil-crypto';
import { createPythia } from 'virgil-pythia';
import { JwtGenerator, GeneratorJwtProvider } from 'virgil-sdk';

Promise.all([initCrypto(), initPythia()])
  .then(() => {
    const virgilCrypto = new VirgilCrypto();
    const virgilPythiaCrypto = new VirgilPythiaCrypto();
    const jwtGenerator = new JwtGenerator({
      apiKey: crypto.importPrivateKey(process.env.API_KEY),
      apiKeyId: process.env.API_KEY_ID,
      appId: process.env.APP_ID,
      accessTokenSigner: new VirgilAccessTokenSigner(crypto),
    });
    const accessTokenProvider = new GeneratorJwtProvider(jwtGenerator);
    const pythia = createPythia({
      virgilCrypto,
      virgilPythiaCrypto,
      accessTokenProvider,
      proofKeys: [
        process.env.PROOF_KEY,
      ],
    });
  });

Usage Examples

Virgil Pythia SDK lets you create, verify and update user's breach-proof password using Virgil Crypto library.

First of all, you need to set up your database to store users' breach-proof passwords. Create additional columns in your database for storing the following parameters:

<table class="params"> <thead> <tr> <th>Parameters</th> <th>Type</th> <th>Size (bytes)</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td>salt</td> <td>blob</td> <td>32</td> <td> Unique random string that is generated by Pythia SDK for each user</td> </tr> <tr> <td>deblindedPassword</td> <td>blob </td> <td>384 </td> <td>user's breach-proof password</td> </tr> <tr> <td>version</td> <td>int </td> <td>4 </td> <td>Version of your Pythia Application credentials. This parameter has the same value for all users unless you generate new Pythia credentials on Virgil Dashboard</td> </tr> </tbody> </table>

Now we can start creating breach-proof passwords for users. Depending on the situation, you will use one of the following Pythia SDK functions:

Create Breach-Proof Password

Use this flow to create a new breach-proof password for a user.

Remember, if you already have a database with user passwords, you don't have to wait until a user logs in into your system to implement Pythia. You can go through your database and create breach-proof user passwords at any time.

So, in order to create a user's breach-proof password for a new database or existing one, take the following actions:

// create a new Breach-proof password using user's password or its hash
pythia.createBreachProofPassword('USER_PASSWORD')
  .then(bpPassword => {
    // save the breach-proof password parameters into your database
    console.log(bpPassword.salt.toString('base64')); // salt is a Buffer
    console.log(bpPassword.deblindedPassword.toString('base64')); // deblindedPassword is a Buffer
    console.log(bpPassword.version);
  });

The result of calling createBreachProofPassword is an object containing parameters mentioned previously (salt, deblindedPassword, version), save these parameters into corresponding columns in your database.

Check that you've updated all database records and delete the now unnecessary column where users' passwords were previously stored.

Verify Breach-Proof Password

Use this flow when you need to verify that the user-provided plaintext password matches the breach-proof password stored in your database. You will have to pass their plaintext password into the verifyBreachProofPassword function:

import { BreachProofPassword } from 'virgil-pythia';

// get user's Breach-proof password parameters from your users DB
// ...
// assuming user is the object representing your database record
const bpPassword = new BreachProofPassword(user.salt, user.deblindedPassword, user.version);

// calculate user's Breach-proof password parameters
// compare these parameters with parameters from your DB
pythia.verifyBreachProofPassword('USER_PASSWORD', bpPassword, false)
  .then(verified => {
    console.log(verified); // true if the plaintext password matches the stored one, otherwise false
  });

The difference between the verifyBreachProofPassword and createBreachProofPassword functions is that the verification of Pythia Service's response is optional in verifyBreachProofPassword function, which allows you to achieve maximum performance when processing data. You can turn on the proof step in verifyBreachProofPassword function if you have any suspicions that a user or Pythia Service were compromised.

Update breach-proof passwords

This step will allow you to use an updateToken in order to update users' breach-proof passwords in your database.

Use this flow only if your database was COMPROMISED.

How it works:

Here is an example of using the updateBreachProofPassword function:

//get previous user's breach-proof password parameters from a compromised DB

// ...

// set up an updateToken that you got on the Virgil Dashboard
// update previous user's deblindedPassword and version, and save new one into your DB

const updatedBpPassword = pythia.updateBreachProofPassword('UT.1.2.UPDATE_TOKEN', bpPassword);
console.log(updatedBpPassword.deblindedPassword.toString('base64'));
console.log(updatedBpPassword.version);

BrainKey

PYTHIA Service can be used directly as a means to generate strong cryptographic keys based on user's password or other secret data. We call these keys the BrainKeys. Thus, when you need to restore a Private Key you use only user's Password and Pythia Service.

In order to create a user's BrainKey, go through the following operations:

Generate BrainKey based on user's password

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Title</title>
  <script type="text/javascript" src="https://unpkg.com/@virgilsecurity/pythia-crypto@^1.0.0/dist/browser.umd.js"></script>
  <script type="text/javascript" src="https://unpkg.com/virgil-crypto@^4.0.0/dist/browser.umd.js"></script>
  <script type="text/javascript" src="https://unpkg.com/virgil-pythia@^1.0.0/dist/browser.umd.js"></script>
  <script type="text/javascript" src="https://unpkg.com/virgil-sdk@^6.0.0/dist/virgil-sdk.browser.umd.js"></script>
</head>
<body>
<script>
  const fetchJwt = (context) => fetch('/virgil-access-token').then(response => {
    if (!response.ok) {
      throw new Error('Failed to get Virgil access token');
    }
    return response.text();
  });

  Promise.all([VirgilCrypto.initCrypto(), VirgilPythiaCrypto.initPythia()])
    .then(() => {
      const virgilCrypto = new VirgilCrypto.VirgilCrypto();
      const virgilBrainKeyCrypto = new VirgilPythiaCrypto.VirgilBrainKeyCrypto();
      const accessTokenProvider = new Virgil.CachingJwtProvider(fetchJwt);
      const brainKey = VirgilPythia.createBrainKey({
        virgilCrypto,
        virgilBrainKeyCrypto,
        accessTokenProvider,
      });

      // Generate default public/private keypair which is ED25519
      // If you need to generate several BrainKeys for the same password, use different IDs.
      brainKey.generateKeyPair('your password', 'optional_id')
        .then(keyPair => {
          console.log(keyPair);
        });
    });
</script>
</body>
</html>

Generate BrainKey based on unique URL

The typical BrainKey implementation uses a password or concatenated answers to security questions to regenerate the user’s private key. But a unique session link generated by the system admin can also do the trick.

This typically makes the most sense for situations where it’s burdensome to require a password each time a user wants to send or receive messages, like single-session chats in a browser application.

Here’s the general flow of how BrainKey can be used to regenerate a private key based on a unique URL:

Important notes for implementation:

...
brainKey.generateKeyPair('abcdef13803488', 'optional_user_ssn')
  .then(keyPair => {
    console.log(keyPair);
  });
...

Note! if you don't need to use additional parameters, like "Optional User SSN", you can just omit it: brainKey.generateKeyPair('abcdef13803488')

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