Specify hash algorithm and fallback considerations

proposals/2134-identity-hash-lookup.md

@@ -61,23 +61,28 @@ identity server requires before sending it hashes. Thus a new endpoint must be
 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:
 
 ```
 {
-  "pepper": "matrixrocks"
+  "pepper": "matrixrocks",
+  "algorithm": "sha256",
 }
 ```
 
-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.
+Clients should request this endpoint every time before making a
+`/(bulk_)lookup`, to handle identity servers which may rotate their pepper
+values frequently.
+
+In addition, the pepper and hashing algorithm the client used must be a request
+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:
 
@@ -97,22 +102,33 @@ Thus, a call to `/bulk_lookup` would look like the following:
       "BJaLI0RrLFDMbsk0eEp5BMsYDYzvOzDneQP/9NTemYA"
     ]
   ],
-  "pepper": "matrixrocks"
+  "pepper": "matrixrocks",
+  "algorithm": "sha256"
 }
 ```
 
 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.
+M_INVALID_PARAM` with the error `Provided pepper does not match
+'$server_pepper'`. If the algorithm does not match the server's, the client
+should receive a `400 M_INVALID_PARAM` with the error `Provided algorithm does
+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
 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.
 
+## Fallback considerations
+
 `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