matrix-org / matrix-org/matrix-spec
Notary server needs to clarify the exact signatures present
Nobody has claimed this yet.
- Dominant language
- HTML
- Stars
- 330
- Forks
- 150
- Avg merge
- 2h 21m
- Merged PRs (30d)
- 3
Description
In https://spec.matrix.org/unstable/server-server-api/#querying-keys-through-another-server there's statements alluding to multiple signatures (emphasis mine):
> The notary server will **additionally** sign the response from the queried server before returning the results.
But this is then clouded by further statements (emphasis mine):
> The keys for the queried servers, **signed by the notary server**.
> The queried server’s keys, **signed by the notary server**.
And sorta wrong in places:
> Digital signatures for this object signed using the verify_keys.
(it is also signed by the notary server who doesn't have `verify_keys` in this object.)
The example alludes to multiple signatures again:
```
"signatures": {
"example.org": {
"ed25519:abc123": "VGhpcyBzaG91bGQgYWN0dWFsbHkgYmUgYSBzaWduYXR1cmU"
},
"notary.server.com": {
"ed25519:010203": "VGhpcyBpcyBhbm90aGVyIHNpZ25hdHVyZQ"
}
},
```
Asking on #homeservers-dev:matrix.org and @richvdh clarified:
> you do need both signatures, and yeah you either need to store the raw json, or be able to reconstruct it
To make this clearer, I would:
- Emphasise **additionally** like I did.
- Have a paragraph explaining that the raw JSON returned from remote servers MUST be preserved (or re-creatable) in order for the signature of the remote server to remain valid.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Read the Matrix server-server API section on querying keys through another server, including its explanatory text and example. Clarify that the notary server adds an additional signature, explain that both signatures must remain valid, and state that the raw remote JSON must be preserved or reproducible. Done means the signature roles and preservation requirement are unambiguous.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 1/5
- Estimated time
- 1-3 hours
- Activity status
- Stale
- Clarity
- Clearly specified
- Newbie friendliness
- 52/100