As healthcare technology advances, secure real-time communication is becoming increasingly crucial to any modern healthcare application. It’s essential to provide the technology experiences patients expect while protecting their privacy and healthcare data. Chat messages often contain protected health information (PHI), so you must consider end-to-end encryption when building chat
•November 1st 2019
In this tutorial, we will walk through how to create a full, end-to-end encrypted chat solution using Stream Chat combined with Virgil Security. These two services allow developers to integrate chat that is HIPAA compliant by protecting PHI and patient communications. The application embeds Virgil Security's eThree Kit with Stream Chat React's components. All source code for this application is available on GitHub.
Both Stream Chat and Virgil make it easy to build a solution with excellent security with all the features you expect.
What is end-to-end encryption?
End-to-end encryption means that they can only read messages sent between two people. To do this, the message is encrypted before it leaves a user's device, and can only be decrypted by the intended recipient.
During this tutorial, we will create a Stream Chat app that uses Virgil's encryption to prevent anyone except the intended parties from reading messages. No one in your company, nor any cloud provider you use, can read these messages. Even if a malicious person gained access to the database containing the messages, all they would see is encrypted text, called ciphertext.
Let's build a HIPAA compliant chat application using React!
To build this application, we're going to rely on three libraries,
Stream React Chat, Virgil SDK and Virgil Crypto. Our final product will encrypt text in the browser before sending a message. Decryption and verification will both happen in the receiver's browser.
To accomplish this, the app performs the following steps:
- A user authenticates with your backend.
- The user's app requests a Stream auth token and api key from the backend. The browser creates a Stream Chat Client for that user.
- The user's app requests a Virgil auth token from the backend and registers with Virgil. This generates their private and public key. The private key is stored locally, and the public key is stored in Virgil.
- Once the user decides who they want to chat with the app creates and joins a Stream Chat Channel.
- The app asks Virgil for the receiver's public key.
- The user types a message and sends it to stream. Before sending, the app passes the receiver's public key to Virgil to encrypt the message. The message is relayed through Stream Chat to the receiver. Stream receives ciphertext, meaning they can never see the original message.
- The receiving user decrypts the sent message using Virgil. When the message is received, the app decrypts the message using the Virgil and this is passed along to Stream's React components. Virgil verifies the message is authentic by using the sender's public key.
This looks intimidating, but luckily Stream and Virgil do the heavy lifting for us. As a developer using these services, our responsibility is to wire them together correctly.
The code is split between the React frontend contained in the
frontend folder and the Express (Node.js) backend is found in the
backend folder. See the
README.md in each folder to see installing and running instructions. If you'd like to follow along with running code, make sure you get both the
frontend running before continuing.
Let's walk through and look at the important code needed for each step.
Basic knowledge of React and Node.js is required to follow this tutorial. This code is intended to run locally on your machine.
You will need an account with Stream and Virgil. Once you've created your accounts, place your credentials in
backend/.env. You can use
backend/.env.example as a reference for what credentials are required.
This tutorial uses the following package versions:
- Node 11.14.0
- Yarn 1.17.0
- Stream Chat 0.13.3
- Stream Chat React 0.6.26
- Virgil Crypto 3.2.0
- Virgil SDK 5.3.0
- Virgil e3Kit 0.5.3
- Express 4.17.1
yarn, all of these dependencies are declared in
Step 0. Setup the Backend
For our React frontend to interact with Stream and Virgil, the
application provides three endpoints:
POST /v1/authenticate: This endpoint generates an auth token that allows the React frontend to communicate with
/v1/virgil-credentials. To keep things simple, this endpoint allows the client to be any user. The frontend tells the backend who it wants to authenticate as. In your application, this should be replaced with your API's authentication endpoint.
POST /v1/stream-credentials: This returns the data required for the React app to establish a session with Stream. In order return this info we need to tell Stream this user exists and ask them to create a valid auth token:
The response payload has this shape:
apiKeyis the stream account identifier for your Stream instance. Needed to identify what account your frontend is trying to connect with.
tokenJWT token to authorize the frontend with Stream.
user: This object contains the data that the frontend needs to connect and
render the user's view.
POST /v1/virgil-credentials: This returns the authentication token used to connect the frontend to Virgil. We use the Virgil Crypto SDK to generate a valid auth token for us:
In this case, the frontend only needs the auth token.
Step 1. User Authenticates with Backend
Now that we have our backend set up and running, it is time to authenticate with the backend. If you're running the application, you'll be presented with a screen like so:
This is a simple React form that takes the provided input, stores it in the state as
sender, and uses that information to authenticate against the backend:
Once we have created a sender identity with an auth token, we can connect to Stream and Virgil.
Step 2. User Connects to Stream
Using the credentials from Step 1, we can request Stream credentials from the backend. Using those we connect our frontend client to Stream:
This initializes the
StreamChat object from the
Stream Chat React library and authenticates a user using the token generated in the backend.
Step 3. User Connects to Virgil
Once again, using the credentials acquired in
Step 1 we ask the backend to generate a Virgil auth token. Using this token we initialize the
EThree object from Virgil's
Step 4. Create Stream Chat Channel
Once we're connected to both Stream and Virgil, we're ready to start chatting with someone. After you've clicked "Register" in the tutorial app, you'll see a screen like this:
This form asks for the identity of the user you want to chat with. If they have registered in another browser window, we can create a Stream Chat
Channel that's private to those two members:
The client we're accessing in the state is the one created in
Step 2. Calling
.channel will create or join a unique channel based on the identities of the members. Only those two members will be allowed in. However, this is not enough to protect Stream or others from viewing those users' messages.
Step 5. Lookup Virgil Public Keys
In order to encrypt a message before sending it through a Stream channel, we need to look up the receiver's public key:
eThree instance in our state is from Step 3. Assuming that the sender's identity is
will and the receiver's identity is
sara, this returns an object that looks like:
Since we need to decrypt received own messages for display, and for convenience, we ask for both public keys at the same time.
Step 6. Sender Encrypts Message and Sends it via Stream
We have everything we need to send a secure, end-to-end encrypted message via Stream. Time to chat! First, we need to show the user the chat room:
This renders the Stream React Chat component that creates a great out-of-the box experience for our users. If you're following along you'll see this:
Notice the line where we include our custom class
MessageInputEncrypted. This component uses the sender's public key from Virgil to encrypt, then wrap, a Stream React
MessageInput component before sending the message over the Stream channel:
Now all Stream will see is the ciphertext!
Step 7. Receiver Decrypts and Reads Message
The last thing to do is decrypt the sender's message on the receiver's side. Assuming you've gone through chat room setup you will see:
To decrypt the message we follow a similar pattern to
Step 6. If you look at how we create the
MessageList you'll see a custom
Message component called
Since we need to provide decryption props to add props for decryption to our custom
Message component, we add them to the props passed by the Stream React:
Once we have the props we need, we can decrypt each message:
This class decrypts the message before rendering the
MessageSimple component from Stream Chat React. To do this, we first determine if the message is actually our message with Stream's
.isMyMessage. We then find the correct public key and ask Virgil to decrypt it. Once that's done, we can pass the key
along with the rest of the props to the Stream's
_isMounted flag prevents updating the component after the message has been decrypted. This can occur if you're scrolling quickly, or upon page load when there are lots of messages.
Where to Go from Here
This tutorial is intended to help you build a HIPPA chat application as quickly as possible. Because of this, some critical functionality may be missing from your application. Here are some tips for what to do next with your app.
- Build real user registration and protect identity registration. This tutorial simplified registration and retrieving valid tokens to interact with Stream and Virgil.
- Backup user's private keys to restore sessions and for multiple devices. Using Virgil's
eThree.backupPrivateKey(pwd)will securely store the private key for restoration on any device.
- Integrate user image and file uploads. This functionality is hidden in this app via CSS. You can look at hooking into Stream React Chat's MessageInput or use as a jumping-off point to build your own chat widget.
- Review our list of the top HIPAA compliant chat apps for design and development inspiration for your app.
That's a Wrap!
Happy coding! ✌️