matrix-org / matrix-org/matrix.org
Relationship between E2EE implementation guide and the spec unclear
Nobody has claimed this yet.
- 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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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