matrix-org / matrix-org/matrix-spec

Use consistent terminology for E2EE room keys

Open
#1,104 0 comments 0 reactions 0 assignees View on GitHub
clarification
Dominant language
HTML
Stars
330
Forks
150
Avg merge
2h 21m
Merged PRs (30d)
3

Description

Our terminology for room keys (the things that decrypt room messages) is all over the place. Since the only currently allowed algorithm is Megolm, we import a lot of Megolm-specific terminology, so the terminology is a mix of algorithm-agnostic terminology ("key", "room key"), Megolm-specific terminology ("Megolm session", "group session") and a weird cross between the two (`session_key`, "the key for the session").

In particular, Megolm has a concept of "sessions", which for all intents and purposes are one concrete, specific implementation of the generic concept of a room key. Each session has a cryptographic ID, which in the context of Megolm could be called the session ID, but on the Matrix side would more properly be called a key ID (given the `m.room_key` terminology). Still, we call it `session_id`.

The point being, all of this is very confusing for someone encountering the ecosystem for the first time. We should strive to unify terminology as much as possible and use consistent phrasing to ease searching. Where unification is not possible (because, for instance, we already baked it into the protocol, as is the case for `session_id`), we should link together the connected concepts in the description of the concept/object/parameter.

# Proposed solution

This describes one possible solution to the problem. The steps are not necessarily exhaustive.

- Use the phrase "room key" as much as possible since it's relatively unambiguous and is already used throughout, especially in the client-facing sides of the protocol (e.g. `m.room_key`, `m.forwarded_room_key`, etc). When referring to Megolm specifically, use "Megolm room key".
- Mention that, for Megolm, the concept of "room key" is implemented using "Megolm sessions".
- ~~State explicitly that the concept of a "session" and that of a "key" are equivalent in this context.~~
- Or more likely reserve the term "session" for the low-level Olm and Megolm cryptographic packets, as described in the Olm and Megolm spec. Reserve "key" for the JSON bodies of `m.room_key` and `m.forwarded_room_key` which contain the session.
- Where it makes sense, remove direct references to Megolm and instead use algorithm-agnostic terminology. Then, if necessary, add another sentence to explain relation to Megolm specifically.

For example, the [`sessionId` parameter](https://spec.matrix.org/v1.2/client-server-api/#get_matrixclientv3room_keyskeysroomidsessionid) is explained as "The ID of the megolm session whose key is requested.", but it should likely read something like "The ID of the key (session) being requested. For Megolm, this is the Megolm session ID."
- Wherever possible, don't just refer to a "key" but to a "room key" ([example](https://spec.matrix.org/v1.2/client-server-api/#get_matrixclientv3room_keyskeysroomidsessionid). There are lots of keys in Matrix, it's better to be explicit in all locations for ease of navigation and search.
- For parameters like `session_id`, `session_key`, etc, mention that these refer to the key ID and the key (session) itself in their explanations.

Contributor guide

Open the contributing guide

Research direction

Begin with the linked Client-Server API sessionId parameter and search the specification for “session”, “session_id”, “session_key”, “key”, and “room key”. Review each occurrence against the proposed Megolm and room-key terminology, then update the relevant descriptions so related concepts are explicitly connected and wording is consistent throughout.

Written by the indexing model from the issue text.

Assessment

Domain
api, documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.