matrix-org / matrix-org/matrix-spec

Secret storage section needs cleanup

Open
#2,040 3 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

**Link to problem area**:

https://spec.matrix.org/v1.13/client-server-api/#storage

**Issue**

* It ploughs straight in with "Key storage: Each key has an ID". When you first read this, you think it's talking about the keys that are stored *in* secret storage (eg, cross signing keys); it is actually talking about the master secret-storage key that is used to encrypt the secrets. This really needs clarifying.
* The fact that, in practice, there is only one secret storage key that is used (the one referenced by `m.secret_storage.default_key`) at any given time could do with being made a lot more obvious.
* Given that there is only one encryption system in use currently (`m.secret_storage.v1.aes-hmac-sha2`), the whole thing is unnecessarily confusing. The spec effectively mandates `m.secret_storage.v1.aes-hmac-sha2` so let's stop saying "it depends on the algorithm" and dividing up the definitions into two parts. This is true both of "Key storage" and "Secret storage".
* There are three different account-data payload definitions in this section (`m.secret_storage.default_key`, `m.secret_storage.key.[key ID]`, `org.example.some.secret`), but they are all quite well hidden and do not use the standard, linkable, payload definition format. (See for example https://spec.matrix.org/v1.13/client-server-api/#midentity_server as an example of one that gets this right.)
* The [key storage](https://spec.matrix.org/v1.13/client-server-api/#key-storage) section is oddly separated from the [key representation](https://spec.matrix.org/v1.13/client-server-api/#key-representation) and [Deriving keys from passphrases](https://spec.matrix.org/v1.13/client-server-api/#deriving-keys-from-passphrases) sections by the "Secret storage" section. Why aren't all the things about SS keys grouped together.

Contributor guide

Open the contributing guide

Research direction

Start with the linked Secret storage, Key storage, Key representation, and Deriving keys from passphrases sections in the Client-Server API. Review the existing account-data payload definitions and compare their structure with the m.identity_server example. Done means the terminology is clarified, the current algorithm and single default key are explicit, payload definitions are linkable, and related key sections are grouped coherently.

Written by the indexing model from the issue text.

Assessment

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.