Filip/matrix-spec
1
0
Fork 0
mirror of https://github.com/matrix-org/matrix-spec synced 2026-01-07 00:13:43 +01:00
Code Issues Actions 3 Packages Projects Releases Wiki Activity

review comments

Browse source
This commit is contained in:
Andrew Morgan 2019-07-22 15:33:49 +01:00
parent 36cb8ed894
commit 0444c8016b
1 changed files with 30 additions and 22 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

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

@ -65,11 +65,7 @@ hashed). First the client must append the medium to the address:
```
Hashes must be peppered in order to reduce both the information an identity
server gains during the process, and attacks the client can perform. Clients
will have to generate a full rainbow table specific to the set pepper to
obtain all registered MXIDs, while the server has to generate a full rainbow
table with the specific pepper to get the plaintext 3pids for non-matrix
users.
server gains during the process, and attacks the client can perform. [0]
In order for clients to know the pepper and hashing algorithm they should use,
Identity servers must make the information available on the `/hash_details`
@ -87,13 +83,14 @@ GET /_matrix/identity/v2/hash_details
The name `lookup_pepper` was chosen in order to account for pepper values
being returned for other endpoints in the future. The contents of
`lookup_pepper` MUST match the regular expression `[a-zA-Z0-9]+` (unless no
hashing is being performed, as described below). If `lookup_pepper` is an
empty string, clients MUST cease the lookup operation.
hashing is being performed, as described below). If hashing is being
performed, and `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
hashing.
```
"alice@example.com email" -> "alice@example.com emailmatrixrocks"
"bob@example.com email" -> "bob@example.com emailmatrixrocks"
"carl@example.com email" -> "carl@example.com emailmatrixrocks"
@ -106,22 +103,26 @@ handle identity servers which may rotate their pepper values frequently.
Clients MUST choose one of the given hash algorithms to encrypt the 3PID
during lookup.
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
`algorithm` value `"sha256"`. SHA-256 was chosen as it is currently used
throughout the Matrix spec, as well as its properties of being quick to hash.
While this reduces the resources necessary to generate a rainbow table for
attackers, a fast hash is necessary if particularly slow mobile clients are
going to be hashing thousands of contact details. Other algorithms can be
negotiated by the client and server at their discretion.
Clients and identity servers MUST support SHA-256 as defined by [RFC
4634](https://tools.ietf.org/html/rfc4634), identified by the `algorithm`
value `"sha256"`. SHA-256 was chosen as it is currently used throughout the
Matrix spec, as well as its properties of being quick to hash. While this
reduces the resources necessary to generate a rainbow table for attackers, a
fast hash is necessary if particularly slow mobile clients are going to be
hashing thousands of contact details. Other algorithms can be negotiated by
the client and server at their discretion.
There are certain situations when an identity server cannot be expected to
compare hashed 3PID values; When a server is connected to a backend provider
such as LDAP, there is no way for the identity server to efficiently pull all
of the addresses and hash them. For this case, the `algorithm` field of `GET
/hash_details` may be set to `"m.none"`, and `lookup_pepper` will be an empty
string. No hashing will be performed if the client and server decide on this,
and 3PIDs will be sent in plain-text, similar to the v1 `/lookup` API.
compare hashed 3PID values; for example, when a server is connected to a
backend provider such as LDAP, there is no way for the identity server to
efficiently pull all of the addresses and hash them. For this case, clients
and server MUST also support sending plain-text 3PID values. To agree upon
this, the `algorithm` field of `GET /hash_details` MUST be set to `"m.none"`,
whereas `lookup_pepper` will be an empty string. No hashing will be performed
if the client and server decide on this, and 3PIDs will be sent in
plain-text, similar to the v1 `/lookup` API. When this occurs, it is STRONGLY
RECOMMENDED for the client to prompt the user before continuing, and receive
consent for sending 3PID details in plain-text to the identity server.
When performing a lookup, the pepper and hashing algorithm the client used
must be part of the request body (even when using the `"m.none"` algorithm
@ -277,3 +278,10 @@ This proposal outlines a simple method to stop bulk collection of user's
contact lists and their social graphs without any disastrous side effects. All
functionality which depends on the lookup service should continue to function
unhindered by the use of hashes.
## Footnotes
[0] Clients would have to generate a full rainbow table specific to the set
pepper to obtain all registered MXIDs, while the server would have to
generate a full rainbow table with the specific pepper to get the plaintext
3pids for non-matrix users.