You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Jeff Martin 0dcc882e0b spelling and grammatical fixes to the e2ee readme 3 months ago
.. spelling and grammatical fixes to the e2ee readme 3 months ago

End-to-end Encryption for Mastodon DMs

a Mastodon mod by Jeff Martin


In stock Mastodon, DMs aren't very private. At any time, for any reason, an instance admin could read them from the database. A nice admin probably never wants to do this, but even nice admins could be compelled to do it by outside forces. Or, you know, a non-compliant Mastodon implementation might just dump them into a public timeline out of sheer negligence.

In a better world, instance admins wouldn't be able to read your DMs even if they wanted to. This mod hopes to provide that privacy for anyone who wants it. Anyone who is using the default web interface, that is. If you're using an app or a third-party web interface, all bets are off.

How does it work?

This mod uses a browser extension called Burger Identity Manager to handle the cryptographic secrets used in the encryption and makes sure they never end up on the Mastodon instance.

In a nutshell, first you create your identity inside the browser extension. The identity contains the private keys needed to decrypt your messages, so you lock the private part of your identity with a password. Keep a backup copy of your identity in a file somewhere reliable in case anything happens to your browser.

Your identity also contains public keys that your contacts need so they can send you the encrypted messages. So you send a copy of the public part of your identity to your Mastodon instance for your contacts to find.

With the public part of your identity in-hand, your contacts can send you encrypted DMs. And finally, you can use your private part of the identity to read them. Asymmetric cryptography is fun and useful!

Threat Model

AKA does this mod provide any actual privacy?

In stock Mastodon, the threat model is basically a bored (or a compelled) instance administrator rummaging through the instance database looking for juicy DMs. Because they can.

In Mastodon modded with this mod, when the identities are handled as designed, a decryption key should never make it onto a Mastodon instance. So an admin would have to break the encryption the hard way to read your DMs. It's not impossible, but it's probably out of reach for all instance admins at the moment.

There's one catch though. This encryption scheme currently trusts the Mastodon instance to provide a copy of the public part of your identity faithfully to your contacts. PKI, you ask? What's that?

So there's an attack called, among many things, machine-in-the-middle that could let an instance admin read your encrypted DMs. Here's how it works. The instance admin has to actively install code into the Mastodon source (and this mod) that lies to you about what's in your contacts' public identities. If they do that, they can give out a fake public identity that they hold the private keys for. If you send encrypted messages to that fake identity, thinking it's your contact, then the admin can decrypt them and read them.

But the trick is the admin has to backdoor the software before you send the messages in order to read them. The attack won't work after the messages have already been sent.

So here's the deal with this mod. If you trust your instance admin to not actively backdoor your Mastodon instance, then this mod provides some extra privacy over the stock Mastodon experience.

This mod basically shifts the threats we care about from:

  • Bored (or compelled) admin looking for juicy DMs after-the-fact


  • Actively malicious admin installing an always-on backdoor onto the instance with the expectation of collecting and leaking private information

I think it's enough of an improvement to the threat model to be worth trying out. And if you can't trust your instance admin to not be actively malicious, I question why you're still hanging around that instance. There are so many excellent ones to choose instead.

It's also possible that we'll have better options for Public Key Infrastructure (PKI) in the future, and we won't even have to trust the admin not to backdoor your instance anymore. But good PKI is hard and we're not quite there yet with this mod.

Getting Started

Ok, with the preliminaries and warnings out of the way, here's how to install and use the mod.

For Instance Members

  • First, be on an instance that has the mod installed on the server side.

  • Then, install the web browser extension for your browser. See the browser extension README for instructions:

    NOTE: Currently, only Firefox is supported.

  • Then, create your identity inside the extension. The User Guide has detailed instructions for how to do this.

  • Then, save your public identity to the Mastodon instance. In the account Preferences area, go to the Profile section. Then go to the Identities page. It's a new page added by the mod. Follow the instructions on the page to save your identity to the instance.

  • Finally, start sending/receiving DMs to/from contacts that have also saved their identity to their instance. The toot compose form will update automatically with the status of the message encryption.

    • If encryption is enabled, you'll see a big green bubble above the compose form with a lock icon in it and the text Encrypted.
    • Otherwise, you'll see a regular blue bubble with a warning icon and the text Not Encrypted. The bubble should also have information on why encryption isn't possible that time.

For Instance Administrators

Mastodon modding seems to be somewhat of a new field. At least, from what I can see. Sure, there are plenty of forks around, but not many actual mods that I know of. So here's my plan for installing a Mastodon mod:

Uhh... just cherry pick a commit and hope nothing conflicts!

Sounds great, right? What could go wrong.

Assuming you have a Mastodon source tree on your instance and you're on a nice clean tagged official release commit, all you should need are a few shell commands. Read on to see the Mastodon versions officially supported by this mod and what shell commands to use.

Make sure the instance isn't running first. It's probably possible to do a no-downtime install somehow, but I have no idea how.

WARNING: And for the love of all that is holy, back up your database first! You're installing a mod from a random person on the internet. I might be a huge idiot that doesn't know what they're doing. You don't know.

Mastodon v4.0.2

Double extra make sure you're on the right commit before starting:

git checkout v4.0.2

To install the mod source code:

git fetch --tags e2ee-4.0.2
git cherry-pick refs/tags/e2ee-4.0.2-v0.1

Then do a database migration to install the Postgres schema:

RAILS_ENV=production bundle exec rake db:migrate

That should be it. You can bring the instance back up now. Hopefully everything worked?

Mastodon v4.1

TODO: Someday I'll get around to this.