MSC2134: Identity Hash Lookups

proposals/2134-identity-hash-lookup.md

@@ -28,31 +28,81 @@ other endpoints):
 - `/_matrix/identity/v2/lookup`
 - `/_matrix/identity/v2/bulk_lookup`
 
-The parameters will remain the same, but `address` should no longer be in a
-plain-text format. `address` will now take a hash value, and the resulting
-digest should be encoded in unpadded base64. For example:
+`address` should no longer be in a plain-text format, but will now take a hash
+value, and the resulting digest should be encoded in unpadded base64. For
+example:
 
 ```python
 address = "[email protected]"
-salt = "matrix"
-digest = hashlib.sha256((salt + address).encode()).digest()
+pepper = "matrix"
+digest = hashlib.sha256((pepper + address).encode()).digest()
 result_address = unpaddedbase64.encode_base64(digest)
 print(result_address)
 CpvOgBf0hFzdqZD4ASvWW0DAefErRRX5y8IegMBO98w
 ```
 
-### Example request
-
 SHA-256 has been chosen as it is [currently used
 elsewhere](https://matrix.org/docs/spec/server_server/r0.1.2#adding-hashes-and-signatures-to-outgoing-events)
-in the Matrix protocol. Additionally a hardcoded salt (“matrix” or something)
-must be prepended to the data before hashing in order to serve as a weak
-defense against existing rainbow tables. As time goes on, this algorithm may be
-changed provided a spec bump is performed. Then, clients making a request to
-`/lookup` must use the hashing algorithm defined in whichever version of the CS
-spec they and the IS have agreed to speaking.
-
-No parameter changes will be made to /bind, but identity services should keep a
+in the Matrix protocol. Additionally a
+[pepper](https://en.wikipedia.org/wiki/Pepper_(cryptography)) must be prepended
+to the data before hashing in order to serve as a weak defense against existing
+rainbow tables. This pepper will be specified by the identity server in order
+to prevent a single rainbow table being generated for all identity servers. As
+time goes on, this algorithm may be changed provided a spec bump is performed.
+Then, clients making a request to `/lookup` must use the hashing algorithm
+defined in whichever version of the CS spec they and the IS have agreed to
+speaking.
+
+Identity servers can specify their own peppers, which can be handy if a rainbow table is released for their current one. Identity servers could also set a timer for rotating this value to further impede rainbow table publishing. As such, it must be possible for clients to be able to query what pepper an identity server requires before sending it hashes. Thus a new endpoint must be added:
+
+```
+GET /_matrix/identity/v2/lookup_pepper
+```
+
+This endpoint takes no parameters, and simply returns the current pepper as a JSON object:
+
+```
+{
+  "pepper": "matrixrocks"
+}
+```
+
+In addition, the pepper the client used must be appended as a parameter to the
+new `/lookup` and `/bulk_lookup` endpoints, ensuring that the client is using
+the right one. 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 client
+will know to query the pepper again instead of just getting a response saying
+no contacts are registered on that identity server.
+
+Thus, a call to `/bulk_lookup` would look like the following:
+
+```
+{
+  "threepids": [
+    [
+      "email",
+      "[email protected]"
+    ],
+    [
+      "msisdn",
+      "123456789"
+    ],
+    [
+      "email",
+      "[email protected]"
+    ]
+  ],
+  "pepper": "matrixrocks"
+}
+```
+
+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
+'$server_pepper'`. Clients should ensure they don't enter an infinite loop if
+they receive this error more than once even after changing to the correct
+pepper.
+
+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
 quicker. It is the recommendation that this is done during the act of binding.
 
@@ -87,11 +137,19 @@ bind, as it cannot trust a homeserver to do so as the homeserver may be lying.
 Additionally, only storing 3pid hashes at rest instead of the plain-text
 versions is impractical if the hashing algorithm ever needs to be changed.
 
-Bloom filters are an alternative method of providing private contact discovery, however does not scale well due to clients needing to download a large filter that needs updating every time a new bind is made. Further considered solutions are explored in https://signal.org/blog/contact-discovery/ Signal's eventual solution of using SGX is considered impractical for a Matrix-style setup.
-
-We could let an identity server specify its own salt for the hashes, however it
-would require an extra network call before uploading 3pid hashes in order for
-the client to ask the server which salt it requires.
+Bloom filters are an alternative method of providing private contact discovery,
+however does not scale well due to clients needing to download a large filter
+that needs updating every time a new bind is made. Further considered solutions
+are explored in https://signal.org/blog/contact-discovery/ Signal's eventual
+solution of using SGX is considered impractical for a Matrix-style setup.
+
+Bit out of scope for this MSC, but there was an argument for not keeping all
+IDs as hashed on disk in the identity server, that being if a hashing algorithm
+was broken, we couldn't update the hashing algorithm without having the
+plaintext 3PIDs. Well @toml helpfully said that we could just take the old
+hashes and rehash them in the more secure hashing algorithm, thus transforming
+the algo from ex. SHA256 to SHA256+SomeBetterAlg. This may spur an MSC in the
+future that supports this, unless it is just an implementation detail.
 
 ## Conclusion