matrix-org / matrix-org/matrix-spec

Signatures object is not defined explicitly

Offen
#653 3 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen

Dieses Issue hat noch niemand übernommen.

A-Client-Server A-S2S clarification
Vorherrschende Sprache
HTML
Sterne
330
Forks
150
Ø Merge
2 Std. 21 Min.
Gemergte PRs (30 T.)
3

Beschreibung

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.

Beitragsleitfaden

Beitragsleitfaden öffnen

Erste Schritte

  1. Lies das ganze Issue und danach den Beitragsleitfaden des Projekts.
  2. Schreib ins Issue, dass du es übernimmst — das erspart doppelte Arbeit.
  3. Forke das Repository und arbeite in einem Branch.
  4. Öffne einen Pull Request, der die Issue-Nummer nennt.

Rechercherichtung

Beginne mit den Referenzen der Federation API zum Signatures-Objekt, lies anschließend den Signing JSON-Anhang, insbesondere Abschnitt 3.2, und vergleiche die Signaturbeispiele für device und server. Kläre das generische Entity-Namensmapping und dokumentiere die Varianten server, device, invite und identity-server. Als erledigt gilt die Aufgabe, wenn die referenzierten API-Abschnitte die Schlüsselnamen und Wertzuordnungen definieren, ohne dass Leser sie aus den Beispielen ableiten müssen.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Bewertung

Tech-Stack
json
Bereich
documentation
Issue-Typ
Dokumentation
Schwierigkeit
3/5
Geschätzter Aufwand
1-2 Tage
Aktivitätsstatus
Veraltet
Klarheit
Größtenteils klar
Anfängerfreundlichkeit
35/100

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.