matrix-org / matrix-org/matrix-spec

Signatures object is not defined explicitly

Ouverte
#653 3 commentaires 0 réactions 0 personnes assignées Voir sur GitHub

Personne n'a encore pris cette issue.

A-Client-Server A-S2S clarification
Langage dominant
HTML
Étoiles
330
Forks
150
Merge moyen
2 h 21 min
PR mergées (30 j)
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.

Guide de contribution

Ouvrir le guide de contribution

Par où commencer

  1. Lisez l'issue en entier, puis le guide de contribution du projet.
  2. Signalez en commentaire que vous la prenez — cela évite que deux personnes fassent le même travail.
  3. Forkez le dépôt et travaillez sur une branche.
  4. Ouvrez une pull request qui référence le numéro de l'issue.

Piste de recherche

Commencez par les références de la Federation API à l’objet Signatures, puis lisez l’annexe Signing JSON, en particulier la Section 3.2, et comparez les exemples de signatures de device et server. Clarifiez le mappage générique des noms d’entités et documentez les variantes server, device, invite et identity-server. Le travail est terminé lorsque les sections de l’API référencées définissent les noms des clés et les mappages de valeurs sans obliger les lecteurs à les déduire des exemples.

Rédigé par le modèle d'indexation à partir du texte de l'issue.

Évaluation

Stack technique
json
Domaine
documentation
Type d'issue
Documentation
Difficulté
3/5
Temps estimé
1-2 jours
Activité
À l'abandon
Clarté
Plutôt claire
Accessibilité débutants
35/100

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.