matrix-org / matrix-org/matrix-spec

Signatures object is not defined explicitly

Aperta
#653 3 commenti 0 reazioni 0 assegnatari Vedi su GitHub

Nessuno ha ancora preso questa issue.

A-Client-Server A-S2S clarification
Lingua principale
HTML
Stelle
330
Fork
150
Merge medio
2h 21m
PR unite (30g)
3

Descrizione

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.

Guida per i contributori

Apri la guida per i contributori

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Direzione di ricerca

Inizia con i riferimenti della Federation API all’oggetto Signatures, poi leggi l’appendice Signing JSON, in particolare la Section 3.2, e confronta gli esempi di firma di device e server. Chiarisci la mappatura generica dei nomi delle entità e documenta le varianti server, device, invite e identity-server. Il lavoro è completato quando le sezioni dell’API referenziate definiscono i nomi delle chiavi e le mappe dei valori senza richiedere ai lettori di dedurli dagli esempi.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Valutazione

Stack tecnologico
json
Ambito
documentation
Tipo di issue
Documentazione
Difficoltà
3/5
Tempo stimato
1-2 giorni
Stato di attività
Ferma
Chiarezza
Abbastanza chiara
Idoneità per principianti
35/100

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.