Merge pull request #412 from matrix-org/rav/e2e_impl/check_uks_attacks

E2E impl guide: Document unknown key-share mitigations

supporting-docs/guides/2016-10-18-e2e_implementation.rst

@@ -292,15 +292,30 @@ At the end of this, the client will hopefully have successfully
 decrypted the payload.
 
 As well as the ``type`` and ``content`` properties, the payload should
-contain a ``keys`` property, which should be an object with a property
+contain a number of other properties. Each of these should be checked as
-ed25519. The client should check that the value of this property matches
+follows [#]_.
-the sender's fingerprint key when `marking the event as verified`_ [#]_.
 
-.. [#] This prevents an attacker publishing someone else's curve25519 keys as
+``sender``
-   their own and subsequently claiming to have sent messages which they didn't
+  The user ID of the sender. The client should check that this matches the
-   (see
+  ``sender`` in the event.
-   https://github.com/vector-im/vector-web/issues/2215#issuecomment-247630155).
 
+``recipient``
+  The user ID of the recipient. The client should check that this matches the
+  local user ID.
+
+``keys``
+  an object with a property ``ed25519``, The client should check that the
+  value of this property matches the sender's fingerprint key when `marking
+  the event as verified`_\ .
+
+``recipient_keys``
+
+  an object with a property ``ed25519``. The client should check that the
+  value of this property matches its own fingerprint key.
+
+.. [#] These tests prevent an attacker publishing someone else's curve25519
+   keys as their own and subsequently claiming to have sent messages which they
+   didn't.
 
 ``m.megolm.v1.aes-sha2``
 ~~~~~~~~~~~~~~~~~~~~~~~~
@@ -509,10 +524,15 @@ When encrypting an event using Olm, the client should:
      {
        "type": "<event type>",
        "content": "<event content>",
+       "sender": "<our user ID>",
        "sender_device": "<our device ID>",
        "keys": {
          "ed25519": "<our ed25519 fingerprint key>"
-       }
+       },
+       "recipient": "<recipient user ID>",
+       "recipient_keys": {
+         "ed25519": "<recipient's ed25519 fingerprint key>"
+       },
      }
 
 -  Check if it has an existing Olm session; if it does not, `start a new