matrix-org / matrix-org/matrix.org

Relationship between E2EE implementation guide and the spec unclear

Open
#3,203 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

guides
Dominant language
JavaScript
Stars
616
Forks
463
Avg merge
2d 3h
Merged PRs (30d)
19

Description

It currently seems unclear where the line of scope is drawn between the [E2EE guide](https://matrix.org/docs/matrix-concepts/end-to-end-encryption) and the [spec](https://spec.matrix.org/latest/).

Usage of libolm functions feels like a good case for the guide as these are an implementation of the spec. On the other hand, the guide contains additional recommendations for how to securely implement E2EE. These seem better suited for the spec because we can use normative wording there to ensure that Matrix' security guarantees are in fact upheld in complying implementations.

One example of this are the steps for verifying decrypted Olm messages. In the guide these read like advice ("should"). However, the steps also exist in the [spec](https://spec.matrix.org/v1.17/client-server-api/#validation-of-incoming-decrypted-events) where they are REQUIRED.

Other recommendations from the guide such as storing a flag to remember encrypted rooms and preventing a MITM from disabling encryption again don't seem to exist in the spec at all but possibly should?

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Compare the E2EE implementation guide with the linked Matrix spec, especially the sections on libolm usage and validation of incoming decrypted events. Identify which guidance is normative, which belongs in the guide, and which recommendations are absent from the spec. Done means the scope boundary and any required spec or guide changes are agreed and documented.

Written by the indexing model from the issue text.

Assessment

Domain
documentation, security
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.