September 21, 2017
15:51 -0400
Hubert Chathi: Congratulations to for the successful Kickstarter. Looking forward to seeing the improvements.
September 13, 2017
00:12 -0400
Hubert Chathi: Don't get an iPhone X. Pre-order a phone that will leave you in control.
September 10, 2017

An introduction to end-to-end encryption in Matrix and Riot

21:10 -0400


End-to-end encryption in Matrix and in Riot are in Beta, and may be subject to change.

I have made every effort to ensure the accuracy of the information in this post, but this should not be viewed as an official guide to end-to-end encryption in Matrix or Riot.


End-to-end encryption is one of the main features of the Matrix communications protocol and of Riot, a glossy client for Matrix. This post provides a high-level overview of what end-to-end encryption is, how it works in Matrix and Riot, and how to use it. It is intended to be understandable to people who are starting with little to no knowledge of encryption, while still being as accurate as possible, and the goal is to help people get a better understanding of end-to-end encryption in Matrix so that they can use it more securely and effectively.

What is end-to-end encryption?

Encryption is a way of ensuring that unauthorized people cannot view information that is not intended for them. Encryption takes the information and, using an encryption key, scrambles the information in a such a way that it cannot be read without the corresponding decryption key. (In some encryption systems, the encryption and decryption keys are the same, whereas in others, they are different.)

In some communication systems that involve a server, the connection between each user and the server is encrypted so that anyone who taps into that connection cannot read any messages. By default, all communication in Matrix is encrypted in this way. However, this still allows messages to be read by server administrators, or anyone who manages to gain access to the server.

End-to-end encryption (sometimes abbreviated as e2e encryption, or simply e2e or e2ee) means that messages are encrypted by the sender in such a way that only the people you are communicating with can read it — none of the servers in between can read the message.

Why do I need end-to-end encryption?

Whether it's our credit card or banking details, health records, corporate strategy, or even plans for a surprise party, we all have things that we would prefer not to be made public. End-to-end encryption helps maintain your privacy.

Using end-to-end encryption even for messages that don't need to be secret also helps increase the security of messages that do need to be secret, as it prevents someone from determining which messages have sensitive information and which ones don't.

Are all conversations in Matrix end-to-end encrypted?

End-to-end encryption can be enabled on each room individually. While encryption is still in beta, all rooms are unencrypted by default. Once encryption is out of beta, then private rooms will be encrypted by default.

If you have sufficient privileges (normally moderator or admin permissions) in a room, you can go to the room settings and enable encryption. Note that once encryption is enabled in a room, it cannot be disabled again.

Riot indicates encrypted rooms with a locked icon next to the message input box, and unencrypted rooms with an unlocked icon.

Why won't all rooms be encrypted?

There are several reasons why some rooms will not be encrypted even after encryption is out of beta. In brief, some of the reasons are that encryption interferes with certain types of integrations (including the bots and bridges hosted by, encryption prevents people from reading messages sent before they joined the room (which is useful for some rooms such as rooms used as support forums), encryption can slow down sending messages (which should not be noticeable in small rooms, but could be quite significant in large rooms), and encryption is of questionable value in a room that anyone can join and read.

What's the deal with all these devices?

Matrix encrypts messages to devices rather than to users. This allows for greater flexibility and privacy. For example, if your phone gets stolen, then you can tell your contacts to blacklist your phone, and whoever has your phone will not be able to decrypt any future conversations, without affecting any of your other devices.

Why does Riot complain about "unknown devices" when I send a message in an encrypted chat?

When you try to communicate with someone, Riot will fetch the list of that person's devices from the server, including an encryption key for each device that can be used to encrypt messages so that they can be read on that device. However, Riot has no way of determining whether that the key is legitimate or if it was planted or altered by someone trying to snoop in on your conversations, so it warns you when it encounters a device that it hasn't seen before.

Riot allows you the option to send messages even to devices that you haven't verified, or to verify the key to tell Riot that it is trusted, or to blacklist the device to tell Riot that it should never encrypt messages to that device.

How do I verify devices?

Note that the current device verification process is only temporary and in the future will be replaced by something that's easier to use.

In order to verify someone's device, you need to have some reasonably secure way to communicate with them. It doesn't have to be secret (if someone listens in on the key verification process, it won't make it any less secure), but it has to be something that won't allow someone else to be able to impersonate you or the device's owner. For example, if you know the device owner's voice, you can phone them, or even start a video call with them in Riot. You can also verify someone's devices if you meet them in person.

When you're ready to verify someone's devices, you can click on their avatar in any conversation that you have with them, and Riot will show you a list of their devices. Find the device that you want to verify, and click the "Verify" button under it. This will show the device's name, ID and key.

The other person will then have to go to their user settings on the device that you want to verify, and find the device key there. You can then compare the keys, and if they match, then you can click the button saying so, and their device is now verified.

Repeat this for all of their devices that you want to verify.

This may seem like a lot of work, and it is, but there are plans to improve this in the future, before end-to-end encryption leaves Beta. For example, in the future your devices may be able to vouch for each other so that others will only have to verify one of your devices.

How does encryption work in Matrix?

Conceptually, when you first send a message in an encrypted room, your Riot client generates a random key to encrypt your message, sends the encrypted message to the server, and then sends the decryption key to all the devices in the room that should be allowed to decrypt the message. Of course, the decryption key is sent encrypted (based on¹ the device's unique key, which you verified above) so that it cannot be intercepted. The recipient then fetches the message decryption key and the encrypted message and decrypts the message.

In order to avoid having to re-send decryption keys to every device for every message you send, Matrix's encryption system includes a method for generating a new key based on an old key. So for the next message you send, your Riot client will use that method on your previous encryption key to generate a new key, and the recipients will use the same method and generate the same key, so that when you send a message encrypted using the new key, the recipients can decrypt the message without any extra key exchange. The new key will only need to be sent to any new devices that showed up in between when the first message was sent and when the second message was sent.

Riot will occasionally start from scratch, generating a new random key and sending it to all the devices in the room. This happens, for example, whenever someone leaves a room, after you have sent a certain number of messages, or after a certain amount of time.

As a result of how encryption is done in Matrix, there are several encryption and decryption keys being used. The main ones that you may need to be aware of are the device keys and the message decryption keys. The message decryption keys allow you to decrypt encrypted messages, and device keys allow you to send the decryption keys securely to other devices. Device keys are unique to each device and cannot be copied from one device to another, whereas decryption keys may be sent from one device to another, or exported from one device and imported to another, in order to allow you to read older messages.

¹ The decryption key is not encrypted directly with the device's key, but uses a more complicated method to improve security.

Help! I can't read some encrypted messages!

There are a few main possible reasons for not being able to decrypt a message.

The first possible reason is that you were not a member of the chat when the message was sent. In this case, it is by design that you cannot decrypt the message; decryption keys for messages are only sent to the users that are in the room when the message was sent.

Another possible reason is that your device was not registered at the time the message was sent. When a message is sent, the sender only sends the decryption key to devices that it knows about; when you log into a new device, that device has not yet received the decryption key for the message, and so cannot decrypt the message. (Note that when you log out and log in again, your new session is considered a new device from Riot's perspective.) There are two ways around this. One way is to export the decryption keys from another device that is able to decrypt the message, and import the keys into the new device. Another way is to verify your new device with another device: When Riot encounters a message that it cannot decrypt, it will ask your other devices for the decryption keys for that message. If you have verified that device from your other devices, then they will send the decryption key to your new device. Recent versions of Riot may automatically prompt you to verify new devices.

The final reason that you might not be able to decrypt a message is that you have encountered a bug. If you are interested in the technical details, you can see the tracking issue for encryption bugs, but the short story is that developers are aware of most (if not all) of the bugs and are working on fixing them. Some bugs can be worked around by the sender clearing Riot's cache and reloading (in their user settings), or by leaving a room and rejoining. Other bugs can only by worked around by logging out and logging back in. However, note that this will create a new device that will need to be re-verified by others, and you will probably want to export your decryption keys before logging out and import them after you log back in so that you can read old messages.

When will encryption be out of beta?

Before encryption is out of beta, the developers need to fix some of the remaining bugs that prevent people from decrypting messages that they should be able to decrypt, and to make the device verification process more usable. It is difficult to estimate when this work will be completed as the developers are working on other issues as well.

July 14, 2017

Matrix community roundup

08:34 -0400

Last week, the Matrix team put out a call to arms for the community to support Matrix financially, and the community response has been great. Response in online forums such as reddit and Hacker News has been extremely positive, and in the first 24 hours, the community pledged well over $1000/month through Patreon and Liberapay. Although it has slowed down since then, it is now over $1700/month, getting close to the first goal of supporting one developer working half time on Matrix.

While last week was the first time that the Matrix community was able to contribute hard dollars towards the development of Matrix, the community has been supporting Matrix in other ways for quite a while. Since I started following Matrix a little less than a year ago, I've seen that the Matrix community has been quite active testing, filing and triaging bugs, contributing code to core projects, writing bots and bridges, providing support in the Matrix rooms, and more.

Here's a quick roundup of some of the new things that the community has come up with since the Matrix Holiday Special. I have undoubtedly missed some projects, so apologies in advance for all those that I've missed.


TravisR has been experimenting a lot with Matrix, and one of the unique things he has come up with is a bot that maps out how Matrix rooms are related to each other by noting when one room is mentioned in another room. The results are then mapped in a massive graph.

Linux distributions

Gentoo: PureTryOut has created an overlay for Gentoo for installing some Matrix-related software.

Debian: Synapse and the Matrix plugin for Pidgin have been packaged for Debian and are included in Debian unstable, and other Matrix-related software has been packaged and submitted for inclusion. Myself and others have also been working on forming a Matrix packaging team.


One of Matrix's main features is the ability to bridge with different networks, and while the core Matrix team has had their hands full maintaining the IRC, Gitter, and Slack bridges, the community has been writing bridges to other networks.

Puppeting bridges: The Matrix Hacks group has added quite a few new bridges this year so far. Looking at their GitHub account, they have bridges for Hangouts, Slack, Skype, Signal, and GroupMe, in addition to the previously-announced iMessage bridge. Discussion and support for these bridges take place in

email: Two email integrations have been written, which work in different ways. Max's bridge allows email users to participate in Matrix rooms while TravisR's bot sends messages to rooms when it receives an email.

Discord: Half-Shot has also written a Discord bridge.


Riot: While the core Riot team was busy working on creating an improved experience for new users, the community implemented some of Riot Web/Desktop's most requested features, resulting in the release of Riot Web/Desktop 0.10 in which all of the major new features were initiated by the community. I think that's an achievement that the community can be very proud of, as well as the core Riot team, for being able to foster such an active community.

Nheko: As good as Riot is, it isn't for everyone. Development on other clients such as Quaternion has continued, but a new one, Nheko, has been started recently which already seems quite promising.

Matrix Recorder: Although Matrix keeps all history on the server, some people want to keep their own copy of history. Alex created Matrix Recorder, which saves history to a local SQLite database. Matrix Recorder even supports saving history from end-to-end encrypted rooms.

e2e crypto: While end-to-end cryptography is still in beta in Riot, some brave souls have been experimenting with it in other clients. In addition to Matrix Recorder's support of e2e rooms as mentioned above, penguin42 has done work on adding e2e to the Matrix Pidgin plugin and davidar has added e2e support to his Hubot adapter.

SHA2017 badge: One of the most intriguing projects is the badge for the SHA2017 camp, which reportedly contains a Matrix client. I don't know what they're using Matrix for, so I hope they do a write up at some point.


The Matrix community has been busy writing documentation and blog posts, and doing talks about Matrix. Coffee has been collecting helpful information about Matrix into a machine-readable knowledge base. Some guides for Riot have been written, including usage basics by muppeth, maxigaz's guide, and an introduction from an IRC perspective. CryptoAUSTRALIA recently had a workshop for setting up Synapse and Riot, and published a tutorial online. And PureTryOut did a Matrix talk at the Dutch Linux User's Group a few months ago. There have certainly been other people from the community doing talks about Matrix that I am not aware of.

Server list

A federated communications protocol is less valuable if users can't find servers to join. Since there is no official list yet, Alex set up a list of Matrix servers. Though to call it just a list of servers is an understatement. It includes statistics on each server such as uptime, response times from various locations, and SSL test scores, so that users can make a more informed choice of servers. If you are running a Matrix server, whether public or private, please consider submitting your server to the list to improve visibility for your server and to strengthen the federation.


Matrix was again accepted as a mentoring organization for Google Summer of Code and has three students. Two of them are working on iOS-related projects, and since I don't have an iOS device, I haven't been following their progress. However, Michael (a.k.a t3chguy), in addition to improving Riot, has been working on creating a search engine-friendly view of public rooms, which will be helpful for Matrix rooms that are used as support forums.

Matrix would not be what it is today without the support of the community, and I'm looking forward to seeing what the community will develop in the future. Last week, the community was invited to contribute financially towards Matrix's development. But for those who are unable to contribute in this way but still want to support Matrix, or for those who have pledged money but still want to do more, hopefully this list gives some ideas for how you can help out, either by supporting an existing project or starting your own.

Addendum (July 19, 2017)

Some projects that I missed:

Max has written an alternative Identity Server implementation called mxisd. Identity Servers haven't been getting as much attention as homeservers, application services, or clients, so it's great that someone has been working on an alternative implementation.

TravisR has also been working on an Dimension, alternative implementation of Riot's integration manager.

July 2, 2017
23:12 -0400
Hubert Chathi: Celebrated Canada Day in two different provinces, and glad to finally be home after a long night and day of driving through two more provinces.
July 1, 2017
07:52 -0400
Hubert Chathi: Happy 150th birthday!
June 30, 2017
16:39 -0400
Hubert Chathi: My # talk for has been accepted. # #
May 28, 2017
11:34 -0400
Hubert Chathi: After about 2.5 years, I'm finally back in the keyring
April 1, 2017

An alternate transport for the Matrix Client-Server API

00:00 -0400

Matrix is an open communications protocol that has many great features. However, one flaw that it has is that the baseline specification is based on long-polling HTTP requests, which is not very efficient. In order to address this deficiency, I've created a spec that presents an alternative transport for the Matrix Client-Server API that uses a protocol that was designed for real-time communications instead of using HTTP.

March 13, 2017

The latest additions to my init.el

11:00 -0400

Inspired by xkcd (but using Alt-mousewheel):

(global-set-key (kbd "<M-mouse-5>") 'undo)
(global-set-key (kbd "<M-mouse-4>") 'redo)

And, since I sometimes need to paste from an HTTP request into a buffer:

(defun insert-from-url (url)
  (interactive "MURL: ")
  (let ((url-request-method "GET")
        (dest (current-buffer))
        (src (url-retrieve-synchronously url)))
    (set-buffer src)
    (goto-char (point-min))
    (search-forward "\n\n")
    (set-buffer dest)
    (insert-buffer-substring src (match-end 0))))
March 9, 2017
23:00 -0500
Hubert Chathi: First, combines Google Talk with Hangouts, and now they are separating the conferencing and chat functionality again
March 3, 2017
15:19 -0500
Hubert Chathi: so true
February 27, 2017
20:11 -0500
Hubert Chathi: Congratulations to all the organizations accepted to GSoC
February 24, 2017
09:56 -0500
Hubert Chathi: Well, thats just embarassing.
February 23, 2017
22:12 -0500
Hubert Chathi: Anyone proxied by or using sites proxied by them: your private data may have been leaked #
11:18 -0500
Hubert Chathi: SHA-1 is officially broken #
February 15, 2017
19:02 -0500
Hubert Chathi: RIP Stuart McLean
February 11, 2017
10:00 -0500
Hubert Chathi: Sign the petition to ask the government to honour their promise to fix our electoral system #
January 31, 2017
08:54 -0500
Hubert Chathi: Got our free Parks Canada Discovery Pass yesterday. Get yours at
January 25, 2017

On transparency

21:01 -0500

I've written briefly before about the value of companies being open and transparent. Back then, I wrote that the way that companies react when things go wrong is a good way to differentiate between them. No matter what company you deal with, things will go wrong at one point or another. Some companies try to avoid responsibility, or only tell you that something has happened if you ask them. Others companies are much more open about what happened. (and the associated is an example of a team that falls into the latter category. And last night's incident is a good example. Their post-mortem blog post is a great example for others to follow. It gives a detailed timeline of what happened and why the outage occurred. And it finishes off with steps that they will take to prevent future incidents.

Kudos to the team for their transparency.