add introduction and discourage new implementations from using old method
-# SAS verification, v2
+# checking public keys in SAS verification
+
+The current SAS protocol does not ensure that the two users correctly received
+each other's public keys. An attacker could send Alice and Bob public keys
+that he has created and, if the attacker is lucky, could obtain the same shared
+secret with both Alice and Bob, so that when they verify the SAS string, will
+believe that the exchange was secure.
+
+To mitigate against this, Alice and Bob can use the two public keys in the
+generation of the SAS string by including it in the info parameter of the HKDF.
+Thus if an attacker sends them different public keys, the info parameters will
+be different, and so the key generated by the HKDF will be different.
## Proposal
-A new `key_agreement_protocol`, `curve25519-hkdf-sha256` is introduced. It is
-the same as `curve25519` except that the info parameter for the HKDF is the
+A new `key_agreement_protocol`, `curve25519-hkdf-sha256` is introduced, and
+will be mandatory for clients to support when performing SAS verification. It
+is the same as `curve25519` except that the info parameter for the HKDF is the
concatenation of:
* The string `MATRIX_KEY_VERIFICATION_SAS|`.
@@ -25,12 +37,5 @@ The differences from `curve25519` are the addition of the public keys, and the
addition of `|` as delimiter between the fields.
The `key_agreement_protocol` `curve25519` is deprecated and may be removed in
-the future.
-
-## Potential issues
-
-## Alternatives
-
-## Security considerations
-
-## Unstable prefix
+the future. It will no longer be mandatory for clients to support, and new
+implementations are discouraged from implementing it.
