Merge branch 'hs/hash-identity' of github.com:matrix-org/matrix-doc into hs/hash-identity

proposals/2134-identity-hash-lookup.md

@@ -78,14 +78,14 @@ hashed). Note that "pepper" in this proposal simply refers to a public,
 opaque string that is used to produce different hash results between identity
 servers. Its value is not secret.
 
-First the client must prepend the medium (plus a space) to the address:
+First the client must append the medium (plus a space) to the address:
 
 ```
-"alice@example.com" -> "email alice@example.com"
-"bob@example.com"   -> "email bob@example.com"
-"carl@example.com"  -> "email carl@example.com"
-"+1 234 567 8910"   -> "msisdn 12345678910"
-"denny@example.com" -> "email denny@example.com"
+"alice@example.com" -> "alice@example.com email"
+"bob@example.com"   -> "bob@example.com email"
+"carl@example.com"  -> "carl@example.com email"
+"+1 234 567 8910"   -> "12345678910 msisdn"
+"denny@example.com" -> "denny@example.com email"
 ```
 
 Hashes must be peppered in order to reduce both the information an identity
@@ -107,18 +107,18 @@ 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]+`, whether
-hashing is being performed or not. When no hashing is occuring, a pepper
-value of at least length 1 is still required.
+hashing is being performed or not. When no hashing is occuring, a valid
+pepper value of at least length 1 is still required.
 
 If hashing, the client appends the pepper to the end of the 3PID string,
 after a space.
 
 ```
-"alice@example.com email" -> "email alice@example.com matrixrocks"
-"bob@example.com email"   -> "email bob@example.com matrixrocks"
-"carl@example.com email"  -> "email carl@example.com matrixrocks"
-"12345678910 msdisn"      -> "msisdn 12345678910 matrixrocks"
-"denny@example.com email" -> "email denny@example.com matrixrocks"
+"alice@example.com email" -> "alice@example.com email matrixrocks"
+"bob@example.com email"   -> "bob@example.com email matrixrocks"
+"carl@example.com email"  -> "carl@example.com email matrixrocks"
+"12345678910 msdisn"      -> "12345678910 msisdn matrixrocks"
+"denny@example.com email" -> "denny@example.com email matrixrocks"
 ```
 
 Clients can cache the result of this endpoint, but should re-request it
@@ -182,11 +182,11 @@ performed, the client sends each hash in an array.
 ```
 NOTE: Hashes are not real values
 
-"email alice@example.com matrixrocks" -> "y_TvXLKxFT9CURPXI1wvfjvfvsXe8FPgYj-mkQrnszs"
-"email bob@example.com matrixrocks"   -> "r0-6x3rp9zIWS2suIque-wXTnlv9sc41fatbRMEOwQE"
-"email carl@example.com matrixrocks"  -> "ryr10d1K8fcFVxALb3egiSquqvFAxQEwegXtlHoQFBw"
-"msisdn 12345678910 matrixrocks"      -> "c_30UaSZhl5tyanIjFoE1IXTmuU3vmptEwVOc3P2Ens"
-"email denny@example.com matrixrocks" -> "bxt8rtRaOzMkSk49zIKE_NfqTndHvGbWHchZskW3xmY"
+"alice@example.com email matrixrocks" -> "y_TvXLKxFT9CURPXI1wvfjvfvsXe8FPgYj-mkQrnszs"
+"bob@example.com email matrixrocks"   -> "r0-6x3rp9zIWS2suIque-wXTnlv9sc41fatbRMEOwQE"
+"carl@example.com email matrixrocks"  -> "ryr10d1K8fcFVxALb3egiSquqvFAxQEwegXtlHoQFBw"
+"12345678910 msisdn matrixrocks"      -> "c_30UaSZhl5tyanIjFoE1IXTmuU3vmptEwVOc3P2Ens"
+"denny@example.com email matrixrocks" -> "bxt8rtRaOzMkSk49zIKE_NfqTndHvGbWHchZskW3xmY"
 
 POST /_matrix/identity/v2/lookup
 
@@ -236,11 +236,11 @@ lookup pepper, as no hashing will occur. Appending a space and the 3PID
 medium to each address is still necessary:
 
 ```
-"alice@example.com" -> "email alice@example.com"
-"bob@example.com"   -> "email bob@example.com"
-"carl@example.com"  -> "email carl@example.com"
-"+1 234 567 8910"   -> "msisdn 12345678910"
-"denny@example.com" -> "email denny@example.com"
+"alice@example.com" -> "alice@example.com email"
+"bob@example.com"   -> "bob@example.com email"
+"carl@example.com"  -> "carl@example.com email"
+"+1 234 567 8910"   -> "12345678910 msisdn"
+"denny@example.com" -> "denny@example.com email"
 ```
 
 The client then sends these off to the identity server in a `POST` request to
@@ -251,11 +251,11 @@ POST /_matrix/identity/v2/lookup
 
 {
   "addresses": [
-    "email alice@example.com",
-    "email bob@example.com",
-    "email carl@example.com",
-    "msisdn 12345678910",
-    "email denny@example.com"
+    "alice@example.com email",
+    "bob@example.com email",
+    "carl@example.com email",
+    "12345678910 msisdn",
+    "denny@example.com email"
   ],
   "algorithm": "none",
   "pepper": "matrixrocks"
@@ -274,8 +274,8 @@ it has that correspond to these 3PID addresses, and returns them:
 ```
 {
   "mappings": {
-    "email alice@example.com": "@alice:example.com",
-    "msisdn 12345678910": "@fred:example.com"
+    "alice@example.com email": "@alice:example.com",
+    "12345678910 msisdn": "@fred:example.com"
   }
 }
 ```
@@ -309,8 +309,8 @@ types that have been leaked in database dumps are more susceptible to hash
 reversal.
 
 Mediums and peppers are appended to the address as to prevent a common prefix
-for each plain-text string, which prevents attackers from pre-computing bits
-of a stream cipher.
+for each plain-text string, which prevents attackers from pre-computing the
+internal state of the hash function
 
 ## Other considered solutions