Filip/matrix-spec
1
0
Fork 0
mirror of https://github.com/matrix-org/matrix-spec synced 2026-04-20 01:44:09 +02:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

Specify hash algorithm and fallback considerations

Browse source
This commit is contained in:
Andrew Morgan 2019-06-20 14:36:47 +01:00
parent f28476f0f3
commit 1343e19a6d
1 changed files with 30 additions and 14 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

44
proposals/2134-identity-hash-lookup.md
View file

@ -61,23 +61,28 @@ identity server requires before sending it hashes. Thus a new endpoint must be
added: added:
``` ```
GET /_matrix/identity/v2/lookup_pepper GET /_matrix/identity/v2/hash_details
``` ```
This endpoint takes no parameters, and simply returns the current pepper as a JSON object: This endpoint takes no parameters, and simply returns the current pepper as a JSON object:
``` ```
{ {
"pepper": "matrixrocks" "pepper": "matrixrocks",
"algorithm": "sha256",
} }
``` ```
In addition, the pepper the client used must be appended as a parameter to the Clients should request this endpoint every time before making a
new `/lookup` and `/bulk_lookup` endpoints, ensuring that the client is using `/(bulk_)lookup`, to handle identity servers which may rotate their pepper
the right one. If it does not match what the server has on file (which may be values frequently.
the case is it rotated right after the client's request for it), then client
will know to query the pepper again instead of just getting a response saying In addition, the pepper and hashing algorithm the client used must be a request
no contacts are registered on that identity server. body field for the new `/lookup` and `/bulk_lookup` endpoints, ensuring that
the client is using the right parameters. If it does not match what the server
has on file (which may be the case is it rotated right after the client's
request for it), then the client will know to query the hash details again
instead of assuming that no contacts are registered on that identity server.
Thus, a call to `/bulk_lookup` would look like the following: Thus, a call to `/bulk_lookup` would look like the following:
@ -97,22 +102,33 @@ Thus, a call to `/bulk_lookup` would look like the following:
"BJaLI0RrLFDMbsk0eEp5BMsYDYzvOzDneQP/9NTemYA" "BJaLI0RrLFDMbsk0eEp5BMsYDYzvOzDneQP/9NTemYA"
] ]
], ],
"pepper": "matrixrocks" "pepper": "matrixrocks",
"algorithm": "sha256"
} }
``` ```
If the pepper does not match the server's, the client should receive a `400 If the pepper does not match the server's, the client should receive a `400
M_INVALID_PARAM` with the error `Provided pepper value does not match M_INVALID_PARAM` with the error `Provided pepper does not match
'$server_pepper'`. Clients should ensure they don't enter an infinite loop if '$server_pepper'`. If the algorithm does not match the server's, the client
they receive this error more than once even after changing to the correct should receive a `400 M_INVALID_PARAM` with the error `Provided algorithm does
pepper. not match '$server_algorithm'`. Clients should ensure they don't enter an
infinite loop if they receive these errors more than once even after changing
to the correct pepper and hash.
No parameter changes will be made to /bind, but identity servers should keep a No parameter changes will be made to /bind, but identity servers should keep a
hashed value for each address it knows about in order to process lookups hashed value for each address it knows about in order to process lookups
quicker. It is the recommendation that this is done during the act of binding. quicker. It is the recommendation that this is done during the act of binding.
## Fallback considerations
`v1` versions of these endpoints may be disabled at the discretion of the `v1` versions of these endpoints may be disabled at the discretion of the
implementation, and should return a `M_FORBIDDEN` `errcode` if so. implementation, and should return a HTTP 403 with a `M_FORBIDDEN` `errcode` if
so.
If an identity server is too old and a HTTP 404 is received when accessing the
`v2` endpoint, they should fallback to the `v1` endpoint instead. However,
clients should be aware that plain-text 3pids are required, and should ask for
user consent accordingly.
## Tradeoffs ## Tradeoffs