{"id":15016748,"url":"https://github.com/soatok/mastodon-e2ee-specification","last_synced_at":"2025-05-09T00:10:27.022Z","repository":{"id":63127881,"uuid":"565380905","full_name":"soatok/mastodon-e2ee-specification","owner":"soatok","description":"Soatok's Proposal for End-to-End Encryption in Mastodon","archived":false,"fork":false,"pushed_at":"2023-01-30T21:03:28.000Z","size":91,"stargazers_count":214,"open_issues_count":5,"forks_count":3,"subscribers_count":36,"default_branch":"main","last_synced_at":"2025-05-06T21:33:57.916Z","etag":null,"topics":["activitypub","crypto","cryptography","e2ee","encryption","end-to-end-encryption","fediverse","mastodon"],"latest_commit_sha":null,"homepage":"https://soatok.blog/2022/11/22/towards-end-to-end-encryption-for-direct-messages-in-the-fediverse/","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/soatok.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-11-13T08:05:40.000Z","updated_at":"2025-05-05T18:11:17.000Z","dependencies_parsed_at":"2023-02-16T11:30:26.259Z","dependency_job_id":null,"html_url":"https://github.com/soatok/mastodon-e2ee-specification","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soatok%2Fmastodon-e2ee-specification","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soatok%2Fmastodon-e2ee-specification/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soatok%2Fmastodon-e2ee-specification/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/soatok%2Fmastodon-e2ee-specification/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/soatok","download_url":"https://codeload.github.com/soatok/mastodon-e2ee-specification/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253096775,"owners_count":21853667,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["activitypub","crypto","cryptography","e2ee","encryption","end-to-end-encryption","fediverse","mastodon"],"created_at":"2024-09-24T19:49:19.436Z","updated_at":"2025-05-09T00:10:26.994Z","avatar_url":"https://github.com/soatok.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# End-to-End Encryption for Mastodon\n\n\u003e **Note:** This document is _very much_ a work in progress.\n\u003e Soatok will remove this notice when the specification is ready to review.\n\u003e Until then, enjoy seeing my rough drafts evolve into something sane.\n\n## This is NOT ready for your input or feedback yet.\n\nPlease watch the repository for updates. It should be ready for feedback in 2023.\n\nDo not ask about sections that have not yet been written, or advocate for specific protocols to be adopted. For all you\nknow, that's exactly what I was planning to do anyway.\n\nYou should assume everything will be rewritten multiple times before I'm happy with it. **Mastodon developers should\nespecially avoid poisoning their perceptions by early drafts.**\n\n## Background\n\nAs a federated system, users may expect that their direct messages between users would be encrypted such that only they\nand the people they tag can read the conversation. However, no such end-to-end encryption is currently implemented in \nMastodon's direct messages.\n\nThere have been [prior attempts to deliver E2EE in Mastodon](https://github.com/mastodon/mastodon/pull/13820), but this\nwork is incomplete (i.e. only implemented in the server-side Ruby code), and was not spearheaded by cryptography experts.\nTo wit: The linked pull request proposed an HMAC-SHA256 _over the plaintext_ to achieve message franking, when there are \nbetter ways to achieve these security goals without risking confidentiality.\n\nAs cryptographers and security engineers, we aim to deliver end-to-end encryption to the Fediverse through ActivityPub,\nso that we might communicate privately when using Mastodon. Thus, while the goal is E2EE DMs in Mastodon, the scope will\nbe appropriately broad in some areas.\n\n## Executive Summary\n\nTo achieve our end goal of end-to-end encryption (E2EE) for Direct Messages in Mastodon (and other ActivityPub\nsoftware), we will divide this work into four distinct problem domains and then define how they are unified together.\n\nWe propose an architecture that's predicated on key material never being revealed to the server. To this end, we begin\nwith a proposal for Client-Side Key Management. This will be realized through multiple clients (iOS, Android, Desktop)\nas well as a Browser Extension, but not through in-browser JavaScript delivered from a website.\n\nWith a reasonable proposal for securing users' secret key material in play, propose a Federated Public Key \nInfrastructure. This allows users to fetch each other's public keys with some assurance that it's the correct public key\nfor their recipient.\n\nNext, we specify an Asynchronous Forward-Secure Ratcheting Protocol for negotiating the symmetric keys needed to encrypt\nmessages between users. We focus on group messaging as a first-class feature, with authenticated group actions that do\nnot depend on a trusted server.\n\nFinally, we propose a Symmetric-Key Message Encryption Format that is fast, secure, and resilient against multi-key\nattacks (see: [Invisible Salamanders](https://eprint.iacr.org/2019/016)). We define both message encryption and media\nencryption in this level.\n\nThe primary output of the Secret Key Management component is a Public Key, which is passed to the Federated Public Key\nInfrastructure. Group Messaging uses these Public Keys for group membership verification as it operates a forward-secure\nratchet. This ratcheting protocol produces symmetric keys for encrypting messages and media attachments.\n\nWith these pieces in place, we can deliver secure end-to-end encryption to the fediverse. Security experts can focus on\nthe components independently, or in conjunction with each other.\n\n## Design Tenets\n\n1. **Usability**. The implementation must be both **easy to use** and **difficult to misuse**. \n   * The details of the cryptography should be almost entirely invisible to the end user.\n   * Nobody should care about exotic ciphersuites or funky AES modes.\n2. **Minimize Agility.** Each version of our protocol will contain a single set of ciphers and modes\n   that are permitted.\n3. **Minimize Complexity.** Every complication must be justified by a security goal. \n   * Eschew X.509, ASN.1, etc. in favor of simpler binary formats, where possible.\n4. **Use State-of-the-Art Cryptography.** We're writing this in the later months of 2022, not the 1990's.\n   We don't need to be backwards compatible with legacy formats. Absolutely no RSA, AES-CBC, etc.\n\n### Anti-Tenets\n\n1. **Interoperability with Legacy.** We aren't interested in our proposal interoperating with OpenPGP,\n   Matrix, etc.\n   * If someone else wants to build something interoperable with our cryptography, that's okay. But we're not aiming\n     to support existing designs.\n2. **Competing with Secure Messaging apps.** We aren't building a replacement for Signal. We just want direct messages\n   to remain confidential.\n3. **Deniability and/or Anonymity.** We cannot hide the social graph from ActivityPub, nor escape the use of\n   [HTTP Signatures](https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-message-signatures-13).\n   Given the environment we're operating under, we cannot reasonably tackle these security properties at this time.\n4. **Government Compliance.** We aren't selling anything to a government, nor to corporations that sell to governments.\n   There's no sense in catering to their lists of approved cryptographic algorithms.\n\n### Security Goals\n\n1. **Confidentiality**. Direct Messages are currently shared between instances such that they are encrypted in transit\n   (provided by TLS). However, the contents of the messages are not end-to-end encrypted, so a curious instance admin\n   may read their users' DMs. We want to provide confidentiality between all users.\n2. **Integrity**. Direct Messages that use end-to-end encryption should be tamper-resistant for all participants in\n   a conversation.\n3. **Authenticity**. All participants in a group should be able to prove who sent a given encrypted message.\n4. **Abuse-Resistant**. It should be possible to report abusive messages to an instance admin.\n   * Instead of message franking, we will opt for committing AEAD constructions.\n5. **Domain Separation**. Every use of a hash function or KDF will be isolated through domain separation constants to\n   prevent cryptographic outputs from being accepted in an inappropriate context.\n6. **Protocol Lucidity**. All encrypted messages will be bound to a given context, to avoid Confused Deputy attacks.\n   We will use versioned protocols instead of in-band negotiation, to avoid Algorithm Confusion attacks.\n7. **Negative Known Answer Tests**. Every security property **SHOULD** be accompanied by a Known Answer Test (also\n   sometimes called a Test Vector) that is intended to fail, so that implementations can be secure by design.\n\n## Components\n\n* [Client-Side Key Management](components/client-side-key-management.md)\n* [Federated Public Key Infrastructure](components/federated-pki.md)\n* [Asynchronous Forward-Secure Ratcheting Protocol](components/async-forward-secure-ratcheting.md)\n* [Symmetric-Key Message Encryption Format](components/symmetric-key-encryption-format.md)\n\n## How the Components Will Fit Together\n\nThe client-side key management is solely concerned with managing users' secret keys across devices.\n\nE2EE-capable clients will output an Ed25519 public key, which will be used with the Federated Public Key Infrastructure\n(FPKI).\n\nWhen a user wants to send an encrypted message to another user, they will first fetch their public key from the fPKI.\nThis public key will allow them to verify the protocol messages sent by the asynchronous forward-secure ratcheting\nprotocol.\n\nFinally, each conversation will involve messages and media encrypted using the keys derived from the ratcheting \nprotocol. This is the only part that interacts with user-generated content (rather than device-generated entropy).\n\n## Structure of the Deliverables\n\n### Kotlin Libraries\n\n* Client-Side Key Management:\n* Interacting with the Federated Public Key Infrastructure:\n* Asynchronous Forward-Secure Ratcheting Protocol:\n* Symmetric-Key Message Encryption Format:\n\n### Ruby Libraries\n\n* Interacting with the Federated Public Key Infrastructure:\n\n### Swift Libraries\n\n* Client-Side Key Management:\n* Interacting with the Federated Public Key Infrastructure:\n* Asynchronous Forward-Secure Ratcheting Protocol:\n* Symmetric-Key Message Encryption Format:\n\n### TypeScript Libraries\n\n* Client-Side Key Management:\n* Interacting with the Federated Public Key Infrastructure:\n* Asynchronous Forward-Secure Ratcheting Protocol:\n* Symmetric-Key Message Encryption Format:\n\n### Mastodon-Android\n\n* See: [Kotlin libraries](#kotlin-libraries)\n* New classes/functions:\n  * ...\n\n### Mastodon-iOS\n\n* See: [Swift libraries](#swift-libraries)\n* New classes/functions:\n  * ...\n\n### Mastodon (Web Server)\n\n* See: [Ruby libraries](#ruby-libraries)\n* New classes/functions:\n  * ...\n\n### Browser Extension\n\n* See: [TypeScript libraries](#typescript-libraries)\n\n## Project Plan\n\nThis is the plan (as of 2022-12-21) for this project. \n\n1. Write a design document containing the scope of work, threat models, and a formal specification\n   of every component and the overall architecture. **(WIP)**\n2. Review these designs with peers from the cryptography community. (2023-01-xx?)\n3. Share this design document with the Mastodon community for their consideration. (2023-01-xx?)\n4. Investigate formal methods and symbolic model checking before we even implementation. (2023-01-xx?)\n5. Implement in JavaScript for inclusion in Mastodon for Web. (2023-02-xx?)\n6. Create a Pull Request for Mastodon on GitHub to implement the necessary parts. (2023-04-xx?) \n7. Implement in Kotlin for inclusion in Mastodon for Android. (2023-05-xx?)\n8. Implement in Swift for inclusion in Mastodon for iOS. (2023-05-xx?)\n9. Beta test the implementations in a limited environment; engage the security community for feedback. (2023-06-xx?)\n10. Launch in the next major version of Mastodon. (2023-08-xx?)\n11. Investigate improvement plans (i.e. post-quantum cryptography). (2024 and beyond)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoatok%2Fmastodon-e2ee-specification","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsoatok%2Fmastodon-e2ee-specification","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoatok%2Fmastodon-e2ee-specification/lists"}