Merge pull request #2687 from uhoreg/sas2_spec

document new key agreement method for SAS verification and deprecate old method

Author: uhoreg

changelogs/client_server/newsfragments/2687.breaking

@@ -0,0 +1 @@
+Document `curve25519-hkdf-sha256` key agreement method for SAS verification, and deprecate old method (MSC2630).

event-schemas/schema/m.key.verification.start$m.sas.v1

@@ -26,8 +26,8 @@ properties:
       key_agreement_protocols:
         type: array
         description: |-
-          The key agreement protocols the sending device understands. Must
-          include at least ``curve25519``.
+          The key agreement protocols the sending device understands. Should
+          include at least ``curve25519-hkdf-sha256``.
         items:
           type: string
       hashes:

specification/modules/end_to_end_encryption.rst

@@ -674,8 +674,27 @@ HKDF calculation
 
 In all of the SAS methods, HKDF is as defined in `RFC 5869 <https://tools.ietf.org/html/rfc5869>`_
 and uses the previously agreed-upon hash function for the hash function. The shared
-secret is supplied as the input keying material. No salt is used, and the info
-parameter is the concatenation of:
+secret is supplied as the input keying material. No salt is used. When the
+``key_agreement_protocol`` is ``curve25519-hkdf-sha256``, the info parameter is
+the concatenation of:
+
+  * The string ``MATRIX_KEY_VERIFICATION_SAS|``.
+  * The Matrix ID of the user who sent the ``m.key.verification.start`` message,
+    followed by ``|``.
+  * The Device ID of the device which sent the ``m.key.verification.start``
+    message, followed by ``|``.
+  * The public key from the ``m.key.verification.key`` message sent by the device
+    which sent the ``m.key.verification.start`` message, followed by ``|``.
+  * The Matrix ID of the user who sent the ``m.key.verification.accept`` message,
+    followed by ``|``.
+  * The Device ID of the device which sent the ``m.key.verification.accept``
+    message, followed by ``|``.
+  * The public key from the ``m.key.verification.key`` message sent by the device
+    which sent the ``m.key.verification.accept`` message, followed by ``|``.
+  * The ``transaction_id`` being used.
+
+When the ``key_agreement_protocol`` is the deprecated method ``curve25519``,
+the info parameter is the concatenation of:
 
   * The string ``MATRIX_KEY_VERIFICATION_SAS``.
   * The Matrix ID of the user who sent the ``m.key.verification.start`` message.
@@ -684,6 +703,8 @@ parameter is the concatenation of:
   * The Device ID of the device which sent the ``m.key.verification.accept`` message.
   * The ``transaction_id`` being used.
 
+New implementations are discouraged from implementing the ``curve25519`` method.
+
 .. admonition:: Rationale
 
   HKDF is used over the plain shared secret as it results in a harder attack