Introduction

As it exists today, end-to-end encryption is mostly device-based, because that has been the surest way to both verify that a user is who they say they are and to safeguard against large-scale breaches. But that also makes practical usage frustrating for users. A real life reality is that we often switch phones or need to log in from a friend's computer, which is tricky with a product using end-to-end encryption and leads to security shortcuts in favor of convenience.

Imagine a Private Key that can be lost and you don't have to worry about losing your encrypted data forever. Or, imagine a Private Key that you can use between devices without needing to transfer the Key around.

Virgil has taken Pythia, designed by Adam Everspaugh and Rahul Chaterjee, University of Wisconsin–Madison; Samuel Scott, University of London; Ari Juels and Thomas Ristenpart, Cornell Tech, and built a cloud service that lets you generate a Brain Key.

Press here to read more about the solution

Problem

A basic User Private Key that is generated using a Crypto Library has limited entropy source

If you get a new device, you need to re-encrypt data for a new key pair or you need to transmit a previously generated private key but that has security risks.

Solution

Virgil Security presents Pythia Service which can be used to generate strong cryptographic keys based on a user's password. We call this key a BrainKey. When you need to restore a Private Key, you only use a user's password and Pythia Service.

Virgil helps you create BrainKey based on your PASSWORD, without having to know a your password or its hash.

You don't need to recreate a new Key or re-encrypt data if you lost your private key or device.

How it works

Register your E2EE application on the Virgil Dashboard and get your app credentials

Generate your API key or use your existing app's API key

Set up JWT provider using previously mentioned parameters (App ID, API key, API key ID) on the Server side

Generate JWT token with user's identity inside and transmit it to the Client side (user's side)

On the Client, side set up AccessTokenProvider in order to specify JWT provider

Initialize and create an instance of BrainKey class with AccessTokenProvider and pass over the user's password

Send BrainKey request to Pythia Service

Generate BrainKey keypair based on the transformed password that you received from Pythia Service and create user's Card

Setup your cardVerifier and cardManager

Pass user's Card to cardManager

Publish user's Card that is related to the BrainKey

All operations are performed under a user's password on the Client side, so Virgil will never see a user's password or its hash. Technical details can be found in the Virgil Security Pythia white paper.

What Virgil provides for developers

Virgil Cards Service: stores & manages your users' Public Keys

Virgil SDK: allows you to easily manage a Crypto Library and communicate with Virgil Cards Service

Virgil Pythia Service: creates a user's protected blinded password that will be used to generate BrainKey on Client side.

Virgil Pythia SDK: allows you to communicate with Virgil Pythia Service and implement the Pythia protocol

Let's get started!

Collect account information

The first thing you need to do is to create an E2EE v5 Application on Virgil Dashboard and collect all the relevant credentials to set up your Server side.

You need the following account and application parameters from your dashboard:

Set up Server side

You need to install and set up the Virgil SDK on your Server side in order to provide your users with a JWT token. Users use this token to communicate with the two relevant Virgil Services: Pythia Service (to get BrainKey) and Cards Service (to publish the user's BrainKey Card).

Maven

To integrate Virgil SDK into your Java project using Maven, set up dependencies in your pom.xml:

com.virgilsecurity.sdkcrypto5.0.2com.virgilsecurity.sdksdk5.0.2

Gradle

Gradle is an open-source build automation system that builds upon the concepts of Apache Ant and Apache Maven and introduces a Groovy-based domain-specific language (DSL) instead of the XML form used by Apache Maven for declaring the project configuration.

Server

To integrate Virgil SDK into your Java project using Gradle, set up dependencies in your build.gradle:

Configure SDK

Configure Virgil SDK

Next, you'll set up the JwtGenerator and generate a JWT using the Virgil SDK.

You'll use your API Key that was created at Virgil Dashboard. For security purposes, you have to generate JWT on your server side.

Each JWT is granted access to a specific Application and has a limited lifetime, which is configured by you. The best practice is to generate JWT only for the shortest amount of time practical for your application.

Maven

To integrate Virgil SDK into your Java project using Maven, set up dependencies in your pom.xml:

com.virgilsecuritypythia0.1.0

Gradle

Gradle is an open-source build automation system that builds upon the concepts of Apache Ant and Apache Maven and introduces a Groovy-based domain-specific language (DSL) instead of the XML form used by Apache Maven for declaring the project configuration.

Server

To integrate Virgil SDK into your Java project using Gradle, set up dependencies in your build.gradle:

Configure Pythia SDK

Set up SDK on a client in order to generate BrainKey, publish Card or do other operations that require an interaction with Virgil infrastructure.

Set up and initialize Card Manager which contains three main modules:

Virgil cardVerifier helps you automatically verify signatures of a User's Card each time a Card is used. (By default, Virgil Card Verifier verifies only two signatures - that of a Card owner and of Virgil Cards Service. More information on how to set up Card Verifier can be found here. )

Virgil cardCrypto allows you to specify that Virgil Crypto Library will be used for crypto operations.

Generate BrainKey and Publish BrainKey Card

When you're done installing Virgil SDK on you Server side and Virgil Pythia SDK on your Client side, you wil then generate a user's BrainKey on the Client side and publish a user's BrainKey Card on the Cards Service.