Ability for client/server to decide on no hashing

pull/977/head
Andrew Morgan 5 years ago
parent ed67e26037
commit 3514437d24

@ -86,8 +86,9 @@ GET /_matrix/identity/v2/hash_details
The name `lookup_pepper` was chosen in order to account for pepper values The name `lookup_pepper` was chosen in order to account for pepper values
being returned for other endpoints in the future. The contents of being returned for other endpoints in the future. The contents of
`lookup_pepper` MUST match the regular expression `[a-zA-Z0-9]+`. If `lookup_pepper` MUST match the regular expression `[a-zA-Z0-9]+` (unless no
`lookup_pepper` is an empty string, clients MUST cease the lookup operation. hashing is being performed, as described below). If `lookup_pepper` is an
empty string, clients MUST cease the lookup operation.
``` ```
The client should append the pepper to the end of the 3PID string before The client should append the pepper to the end of the 3PID string before
@ -102,8 +103,8 @@ hashing.
Clients SHOULD request this endpoint each time before performing a lookup, to Clients SHOULD request this endpoint each time before performing a lookup, to
handle identity servers which may rotate their pepper values frequently. handle identity servers which may rotate their pepper values frequently.
Clients MUST choose one of the given hash algorithms to encrypt the 3PID during Clients MUST choose one of the given hash algorithms to encrypt the 3PID
lookup. during lookup.
At a minimum, clients and identity servers MUST support SHA-256 as defined by At a minimum, clients and identity servers MUST support SHA-256 as defined by
[RFC 4634](https://tools.ietf.org/html/rfc4634), identified by the [RFC 4634](https://tools.ietf.org/html/rfc4634), identified by the
@ -114,13 +115,21 @@ attackers, a fast hash is necessary if particularly slow mobile clients are
going to be hashing thousands of contact details. Other algorithms can be going to be hashing thousands of contact details. Other algorithms can be
negotiated by the client and server at their discretion. negotiated by the client and server at their discretion.
When performing a lookup, the pepper and hashing algorithm the client used must There are certain situations when an identity server cannot be expected to
be part of the request body. If they do not match what the server has on file compare hashed 3PID values; When a server is connected to a backend provider
(which may be the case if the pepper was changed right after the client's such as LDAP, there is no way for the identity server to efficiently pull all
request for it), then the server must inform the client that they need to query of the addresses and hash them. For this case, the `algorithm` field of `GET
the hash details again, instead of just returning an empty response, which /hash_details` may be set to `"none"`, and `lookup_pepper` will be an empty
clients would assume to mean that no contacts are registered on that identity string. No hashing will be performed if the client and server decide on this,
server. and 3PIDs will be sent in plain-text, similar to the v1 `/lookup` API.
When performing a lookup, the pepper and hashing algorithm the client used
must be part of the request body (even when using the `"none"` algorithm
value). If they do not match what the server has on file (which may be the
case if the pepper was changed right after the client's request for it), then
the server must inform the client that they need to query the hash details
again, instead of just returning an empty response, which clients would
assume to mean that no contacts are registered on that identity server.
If the algorithm does not match the server's, the server should return a `400 If the algorithm does not match the server's, the server should return a `400
M_INVALID_PARAM`. If the pepper does not match the server's, the server should M_INVALID_PARAM`. If the pepper does not match the server's, the server should

Loading…
Cancel
Save