Introduction

In this tutorial, we help you to add end-to-end encryption (E2EE) in your digital solutions like: Messenger App, ChatBot, IoT devices in order to communicate securely.

Remember, this is the simplest possible implementation of E2EE chat and it works perfectly for simple chat apps between 2 users where conversations are short-lived and it's okay to lose the message history if a device is lost with the private key on it. For a busier, Slack-like chat app where history is important and users are joining and leaving channels all the time, we’ll build another use case PFS Encrypted Communication.

What you'll learn at the end of the tutorial

How to encrypt chat messages with a receiver's public key before sending.

How to decrypt encrypted messages with a sender's private key after receiving.

How to create tamper proof signature to be sure of data integrity.

We publish the users’ public keys on Virgil Cards Service so that chat users are able to look up each other and encrypt messages for each other or verify signature. The private keys will stay on users' devices.

What Virgil provides to developers

Open source Crypto Library. Used to perform cryptographic operations.

Virgil Services. For storing and managing users' Public Keys and for the validation of user identities in anything from emails to applications.

Virgil SDK Allows you to easily manage a Crypto Library and communicate with Virgil Services.

What's needed from developer's side

a backend server for your app.

a client-side application.

OK, enough talking! Let's get started!

Collect Account information

The first thing you need to do is grab all the necessary information from your Virgil account. To set up your Client and Server Sides, you need the following values from your account:

Account values

Description

ACCESS_TOKEN

Used to authenticate your users on Virgil Services.

APP_KEY

Private Key that is generated during an Application registration on your dashboard.

APP_KEY_PASSWORD

A password that established for a Private Key of your Application.

APP_ID

Your application identifier.

Set up your server side

Your server should be able to authorize your users, store your Application's Virgil Key and use the Virgil SDK for cryptographic operations or for requests to Virgil Services. You can configure your server using the next steps:

Install SDK & Setup Virgil Crypto

The Virgil Javascript SDK can be used both on the frontend in a web browser, and on the backend in a Node application with the same API.

Set up your Client side

Set up the client side to provide your users with an access token after their registration at your Application Server to authenticate them for further operations and transmit their Virgil Cards to the server. Configure the client side using the next steps:

Install SDK & Setup Virgil Crypto

The Virgil Javascript SDK can be used both on the frontend in a web browser, and on the backend in a Node application with the same API.

The client-side SDK targets ECMAScript5+ compatible browsers.

This module requires Node 4.0+ and can be installed via NPM.

npm install virgil-sdk --save

Set up authentication on a client side

In order to make call to Virgil Services, for example, to publish user's Card on Virgil Cards Service you need to have a Access Token.

With the Access Token we can initialize the Virgil SDK on the client-side to start doing fun stuff like sending and receiving messages.

To initialize the Virgil SDK on a client-side you need to use the following code:

Register Users

Now you need to register users who will participate in encrypted communications.

In order to sign and encrypt a message, each user must have his or her own tools, which allow him or her to perform cryptographic operations, and these tools must contain the necessary information to identify users. In Virgil Security, these tools are the Virgil Key and the Virgil Card.

When you have set up the Virgil SDK on the server & client sides, you can finally create Virgil Cards for the users and transmit the Cards to your Server for further publication on Virgil Services.

Generate Keys and Create Virgil Card

Use the Virgil SDK on the client side to generate a new Key Pair, and then create a user's Virgil Card using the recently generated Virgil Key. All keys are generated and stored on the client side.

In this example we:

use Virgil Crypto Library to generate Key Pair;

save a Private Key into Key Storage created by the Virgil Client SDK on user's device;

create a user's Virgil Card. Each Virgil Card is signed by a user's Virgil Key, which guarantees the Virgil Card's content integrity over its life cycle.

Virgil doesn't keep a copy of your Virgil Key. If you lose a Virgil Key, there is no way to recover it.

In order for the Sender to be able to send a message, we also need a Virgil Card associated with the Recipient. Thus, create one more user Virgil Card to be used in this tutorial for demonstration purposes.

Transmit Cards to Your Server

In order to add the signature of your app server to a user's Card you need to transmit an existing user's Card to your server. You can use any suitable way to transmit the Card.

If you need to export a user's Card to a string representation on a client side or import a Card from the string representation on a server side, use the following lines of code:

With the user's Private Key and Cards in place, you will be ready to sign and encrypt a message for encrypted communication. Also, once the Recipient receives the signed and encrypted message, he or she can decrypt the message and verify the signature.

Sign & Encrypt a message

As previously noted, we encrypt data for secure communication, but a recipient also must be sure that no third party modified any of the message's content and that they can trust a sender, which is why we provide Data Integrity by adding a Digital Signature. Therefore we must sign the data first and then encrypt it.

In order to first sign and then encrypt messages, the Sender must load his or her own recently generated Private Key and search for the receiver's Virgil Cards on Virgil Services, where all Virgil Cards are saved.

With the signature in place, the Sender is now ready to transmit the signed and encrypted message to the Receiver.

Use your application to transmit a message.

Decrypt a message & Verify its signature

Once the Recipient receives the signed and encrypted message, he or she can decrypt and validate the message. Verifying the signature against the Sender's Virgil Card proves that the message has not been tampered with.

In order to decrypt the encrypted message and then verify the signature, we need to load a private receiver's Key and search for the sender's Virgil Card at Virgil Services.

What's next?

HIPAA compliant Chat App

For best practices and to better understand how to add End-to-End encryption to a chat app, explore another tutorial we wrote describing how to build an End-to-End Encrypted chat app on top of Back4app Server Platform. Follow the instructions to configure and run a chat on your machine and use the account values you created above.

Virgil & Twilio Programmable Chat

Add extra security layer

See the related use case where we will help two people or IoT devices to communicate with End-to-End Encryption with Perfect Forward Secrecy enabled. You’ll find out how to protect previously intercepted traffic from being decrypted even if the main private key is compromised.

Get Help

Need some extra help? Get help now from our support team on Slack. Have fun building your digital solution with End-to-End encryption!

Don’t forget to subscribe to our Youtube channel. There you will find video series on how to do End-to-End Encryption.