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
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
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 matrix.org), 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
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
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
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.