matrix-org / matrix-org/matrix-spec

Signatures object is not defined explicitly

Open
#653 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

A-Client-Server A-S2S clarification
Dominant language
HTML
Stars
330
Forks
150
Avg merge
2h 21m
Merged PRs (30d)
3

Description

I'm not quite sure how to organize this, but I think that the Signatures object could use a little more definition.

The `Signatures` object is referred to several times in the Federation API, but it isn't explicitly defined like other objects types are. There is a reference to the Signing JSON (section 3) in the appendix, but the actual schema isn't described until Section 3.2. It requires some scrolling to get down to the definition from the link given in the Federation API.

A sentence in Section 3.2 of the appendix mentions that the key for the field is "the name of the entity signing it." For device signatures, it is explicitly stated that the entity name is the User ID and the _signing key identifier_ is the concatenation of the algorithm and device ID. (Cf. `signatures` request parameter in [key claim endpoint](https://matrix.org/docs/spec/server_server/r0.1.4#post-matrix-federation-v1-user-keys-query).

On the other hand, for server signatures it doesn't seem to be explicitly stated that the key for a homeserver signature should be the server name. This can be inferred from the examples, but it could be made more explicit. I think it would be nice to have a type defined for `Signatures` something like this:

**Signatures** (generic)
| Parameter | Type | Description |
|--|--|--|
| `` | { string: string } | Map from signing key identifier to Base64-encoded string of signature. The field name should be the name of the entity signing the content. |

This could be further specified for each signature type:

**Server Signatures**
| Parameter | Type | Description |
|--|--|--|
| `` | { string: string} | Map from a homeserver key identifier to Base64-encoded string of signature. The field name should be the server name of the homeserver signing the content.|

**Device Signatures**
| Parameter | Type | Description |
|--|--|--|
| `` | { string: string} | Map from device key identifiers to Base64-encoded string of signature. The field name should be the ID of the user who owns the device. |

... and similarly for the `Invite Signatures` and `Identity Server Signatures` types.

(Now that I write this, it seems that the difficulty with this is being able to specify types for field names...)

Sorry for the rambling; let me know if I didn't get the problem across.

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

Start with the Federation API references to the Signatures object, then read the Signing JSON appendix, especially Section 3.2, and compare the device and server signature examples. Clarify the generic entity-name mapping and document the server, device, invite, and identity-server variants. Done means the referenced API sections define the key names and value maps without requiring readers to infer them from examples.

Written by the indexing model from the issue text.

Assessment

Tech stack
json
Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 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.