When transmitting or storing user data, especially private conversations, it's essential to consider employing cryptographic techniques to ensure privacy.
Please note that this tutorial is very basic and strictly educational, may contain simplifications, and rolling your own encryption protocol is not advisable. The algorithms used can contain certain 'gotchas' if not employed properly with the help of security professionals
End-to-end encryption is a communication system where the only people who can read the messages are the people communicating. No eavesdropper can access the cryptographic keys needed to decrypt the conversation—not even a company that runs the messaging service.
The Web Cryptography API defines a low-level interface to interacting with cryptographic key material that is managed or exposed by user agents. The API itself is agnostic of the underlying implementation of key storage but provides a common set of interfaces that allow rich web applications to perform operations such as signature generation and verification, hashing and verification, encryption and decryption, without requiring access to the raw keying material.
In the following steps, we'll declare the essential functions involved in end-to-end encryption. You can copy each one into a dedicated
.js file under a
lib folder. Note that all of them are
async functions due to the Web Crypto API's asynchronous nature.
Note: Not all browsers implement the algorithms we'll use. Namely, Internet Explorer and Microsoft Edge. Check the compatibility table at MDN web docs: Subtle Crypto - Web APIs.
Cryptographic key pairs are essential to end-to-end encryption. A key pair consists of a public key and a private key. Each user in your application should have a key pair to protect their data, with the public component available to other users and the private component only accessible to the key pair's owner. You'll understand how these come into play in the next section.
To generate the key pair, we'll use the
window.crypto.subtle.generateKey method, and export the private and public keys using
PS: if you don't see
generateKeyPair.js below due to a bug in dev.to, refresh this page.
Additionally, I chose the ECDH algorith with the P-256 elliptic curve as it is well supported and the right balance between security and performance. This preference can change with time as new algorithms become available.
Note: exporting the private key can lead to security issues, so it must be handled carefully. The approach of allowing the user to copy and paste it that will be presented in the integration part of this tutorial is not a great practice and only done for educational purposes.
We'll use the key pair generated in the last step to derive the symmetric cryptographic key that encrypts and decrypts data and is unique for any two communicating users. For example, User A derives the key using their private key with User B's public key, and User B derives the same key using their private key and User A's public key. No one can generate the derived key without access to at least one of the users' private keys, so it's essential to keep them safe.
In the previous step, we exported the key pair in the JWK format. Before we can derive the key, we need to import those back to the original state using
window.crypto.subtle.importKey. To derive the key, we'll use the
In this case, I chose the AES-GCM algorithm for its known security/performance balance and browser availability.
Now we can use the derived key to encrypt text, so it's safe to transmit it.
Before encryption, we encode the text to a
Uint8Array, since that's what the encrypt function takes. We encrypt that array using
window.crypto.subtle.encrypt, and then we turn its
ArrayBuffer output back to
Uint8Array, which we then turn to
As you can see, the AES-GCM algorithm parameter includes an initialization vector (iv). For every encryption operation, it can be random, but absolutely must be unique to ensure the strength of the encryption. It is included in the message so it can be used in the decryption process, which is the next step. Also, though unlikely to reach this number, you should discard the keys after 2^32 usages, as the random IV can repeat at that point.
Now we can use the derived key to decrypt any encrypted text we receive, doing precisely the opposite from the encrypt step.
Before decryption, we retrieve the initialization vector, convert the string back from Base64, turn it into a
Uint8Array, and decrypt it using the same algorithm definition. After that, we decode the
ArrayBuffer and return the human-readable string.
It's also possible that this decryption process will fail due to using a wrong derived key or initialization vector, which means the user does not have the correct key pair to decrypt the text they received. In such a case, we return an error message.
And that is all the cryptographic work required! In the following sections, I'll explain how I used the methods we implemented above to end-to-end encrypt a chat application built with Stream Chat's powerful React chat components.
Clone the encrypted-web-chat repository in a local folder, install the dependencies and run it.
After that, a browser tab should open. But first, we need to configure the project with our own Stream Chat API key.
Create your account at GetStream.io, create an application, and select development instead of production.
To simplify, let's disable both auth checks and permission checks. Make sure to hit save. When your app is in production, you should keep these enabled and have a backend to provide tokens for the users.
Please take note of the Stream credentials, as we'll use them to initialize the chat client in the app in the next step. Since we disabled authentication and permissions, we'll only really need the key for now. Still, in the future, you'll use the secret in your backend to implement authentication to issue user tokens for Stream Chat, so your chat app can have proper access controls.
As you can see, I've redacted my keys. It would be best if you kept these credentials safe.
src/lib/chatClient.js, change the key with yours. We'll use this object to make API calls and configure the chat components.
After this, you should be able to test the application. In the following steps, you'll understand where the functions we defined fit in.
src/lib/setUser.js, we define the function that sets the chat client's user and updates it with the given key pair's public key. Sending the public key is necessary for other users to derive the key required for encrypting and decrypting communication with our user.
In this function, we import the
chatClient defined in the previous step. It takes a user id and a key pair, then it calls
chatClient.setUser to set the user. After that, it checks whether that user already has a public key and if it matches the public key in the key pair given. If the public key matches or is non-existent, we update that user with the given public key; if not, we disconnect and display an error.
src/components/Sender.js, we define the first screen, where we choose our user id, and can generate a key pair using the function we described in
generateKey.js, or, if this is an existing user, paste the key pair generated at the time of user creation.
src/components/Recipient.js, we define the second screen, where we choose the id of the user with whom we want to communicate. The component will fetch this user with
chatClient.queryUsers. The result of that call will contain the user's public key, which we'll use to derive the encryption/decryption key.
src/components/KeyDeriver.js, we define the third screen, where the key is derived using the method we implemented in
deriveKey.js with the sender's (us) private key and the recipient's public key. This component is merely a passive loading screen since the information needed was collected in the previous two screens. But it will show an error if there's an issue with the keys.
src/components/EncryptedMessage.js, we customize Stream Chat's Message component to decrypt the message using the method we defined in
decrypt.js alongside the encrypted data and the derived key.
Without this customization of the Message component, it would show up like this:
The customization is done by wrapping Stream Chat's
MessageSimple component and using the
useEffect hook to modify the message prop with the decrypt method.
src/components/EncryptedMessageInput.js, we customize Stream Chat's MessageInput component to encrypt the message written before sending it using the method we defined in
encrypt.js alongside the original text.
The customization is done by wrapping Stream Chat's
MessageInputLarge component and settings the
overrideSubmitHandler prop to a function that encrypts the text before sending to the channel.
And finally, in
src/components/Chat.js, we build the whole chat screen using Stream Chat's components and our custom Message and EncryptedMessageInput components.
MessageList component has a
Message prop, set to the custom
EncryptedMessage component, and the
EncryptedMessageInput can just be placed right below it in the hierarchy.
Congratulations! You just learned how to implement basic end-to-end encryption in your web apps. It's important to know this is the most basic form of end-to-end encryption. It lacks some additional tweaks that can make it more bullet-proof for the real world, such as randomized padding, digital signature, and forward secrecy, among others. Also, for real-world usage, it's vital to get the help of application security professionals.
PS: Special thanks to Junxiao in the comments for correcting my mistakes :-)