Deprecate the sender_key and device_id on Megolm events (#1101)

* Deprecate the `sender_key` and `device_id` on Megolm events

MSC: matrix-org/matrix-spec-proposals#3700 ([Markdown](https://github.com/matrix-org/matrix-spec-proposals/blob/main/proposals/3700-deprecate-sender-key.md))

The language around `m.room.encrypted` is a bit awkward because *technically* you can use the event to represent non-Megolm events, however that's considered an edge case at this time.

* changelog

* Apply wording changes

* Remove incorrect example

* Add missing sentence

changelogs/client_server/newsfragments/1101.deprecation

@@ -0,0 +1 @@
+Deprecate the `sender_key` and `device_id` on `m.megolm.v1.aes-sha2` events, and the `sender_key` on `m.room_key_request` to-device messages, as per [MSC3700](https://github.com/matrix-org/matrix-spec-proposals/pull/3700).

content/client-server-api/modules/end_to_end_encryption.md

@@ -1531,8 +1531,19 @@ For example, Megolm sessions that were sent using the old session would
 have been lost. The client can attempt to retrieve the lost sessions
 through `m.room_key_request` messages.
 
+{{% boxes/note %}}
+Clients should send key requests for unknown sessions to all devices for
+the user which used the session rather than just the `device_id` or
+`sender_key` denoted on the event.
+
+This is due to a deprecation of the fields. See
+[`m.megolm.v1.aes-sha2`](#mmegolmv1aes-sha2) for more information.
+{{% /boxes/note %}}
+
 ##### `m.megolm.v1.aes-sha2`
 
+{{% changed-in v="1.3" %}}
+
 The name `m.megolm.v1.aes-sha2` corresponds to version 1 of the Megolm
 ratchet, as defined by the [Megolm
 specification](http://matrix.org/docs/spec/megolm.html). This uses:
@@ -1580,10 +1591,36 @@ ratchet index that they have already decrypted. Care should be taken in
 order to avoid false positives, as a client may decrypt the same event
 twice as part of its normal processing.
 
-As with Olm events, clients must confirm that the `sender_key` belongs
-to the user who sent the message. The same reasoning applies, but the
-sender ed25519 key has to be inferred from the `keys.ed25519` property
-of the event which established the Megolm session.
+Similar to Olm events, clients should confirm that the user who sent the
+message corresponds to the user the message was expected to come from.
+For room events, this means ensuring the event's `sender`, `room_id`, and
+the recorded `session_id` match a trusted session (eg: the `session_id`
+is already known and validated to the client).
+
+{{% boxes/note %}}
+As of `v1.3`, the `sender_key` and `device_id` keys are **deprecated**. They
+SHOULD continue to be sent, however they MUST NOT be used to verify the
+message's source.
+
+Clients MUST NOT store or lookup sessions using the `sender_key` or `device_id`.
+
+In a future version of the specification the keys can be removed completely,
+including for sending new messages.
+{{% /boxes/note %}}
+
+{{% boxes/rationale %}}
+Removing the fields (eventually) improves privacy and security by masking the
+device which sent the encrypted message as well as reducing the client's
+dependence on untrusted data: a malicious server (or similar attacker) could
+change these values, and other devices/users can simply lie about them too.
+
+We can remove the fields, particularly the `sender_key`, because the `session_id`
+is already globally unique, therefore making storage and lookup possible without
+the need for added context from the `sender_key` or `device_id`.
+
+Removing the dependence on the fields gives a privacy gain while also increasing
+the security of messages transmitted over Matrix.
+{{% /boxes/rationale %}}
 
 In order to enable end-to-end encryption in a room, clients can send an
 `m.room.encryption` state event specifying `m.megolm.v1.aes-sha2` as its
@@ -1596,6 +1633,11 @@ that they can decrypt future messages encrypted using this session. An
 `m.room_key` events sent by other devices in order to decrypt their
 messages.
 
+When a client is updating a Megolm session (room key) in its store, the client MUST ensure:
+
+* that the updated session data comes from a trusted source.
+* that the new session key has a lower message index than the existing session key.
+
 #### Protocol definitions
 
 ##### Events

data/event-schemas/schema/m.room.encrypted.yaml

@@ -40,18 +40,42 @@ properties:
           Olm event. For more details, see [Messaging Algorithms](/client-server-api/#messaging-algorithms).
       sender_key:
         type: string
-        description: The Curve25519 key of the sender.
+        x-changedInMatrixVersion:
+          1.3: |-
+            Previously this field was required, however given it offers no additional
+            security or privacy benefit it has been deprecated for Megolm messages.
+            See [`m.megolm.v1.aes-sha2`](#mmegolmv1aes-sha2) for more information.
+        description: |-
+          The Curve25519 key of the sender. Required (not deprecated) if not using Megolm.
+
+          **Deprecated**: This field provides no additional security or privacy benefit
+          for Megolm messages and must not be read from if the encrypted event is using
+          Megolm. It should still be included on outgoing messages, however must not be
+          used to find the corresponding session. See [`m.megolm.v1.aes-sha2`](#mmegolmv1aes-sha2)
+          for more information.
       device_id:
         type: string
-        description: The ID of the sending device. Required with Megolm.
+        x-changedInMatrixVersion:
+          1.3: |-
+            Previously this field was required for Megolm messages, however given it
+            offers no additional security or privacy benefit it has been deprecated
+            for Megolm messages. See [`m.megolm.v1.aes-sha2`](#mmegolmv1aes-sha2) for
+            more information.
+        description: |-
+          The ID of the sending device.
+
+          **Deprecated**: This field provides no additional security or privacy benefit
+          for Megolm messages and must not be read from if the encrypted event is using
+          Megolm. It should still be included on outgoing messages, however must not be
+          used to find the corresponding session. See [`m.megolm.v1.aes-sha2`](#mmegolmv1aes-sha2)
+          for more information.
       session_id:
         type: string
         description: |-
           The ID of the session used to encrypt the message. Required with
           Megolm.
     required:
       - algorithm
-      - sender_key
       - ciphertext
     type: object
   type:

data/event-schemas/schema/m.room_key_request.yaml

@@ -23,16 +23,26 @@ properties:
             description: The room where the key is used.
           sender_key:
             type: string
+            x-changedInMatrixVersion:
+              1.3: |-
+                Previously this field was required, however given it offers no additional
+                security or privacy benefit it has been deprecated. See [`m.megolm.v1.aes-sha2`](#mmegolmv1aes-sha2)
+                for more information.
             description: |-
               The Curve25519 key of the device which initiated the session originally.
+
+              **Deprecated**: This field provides no additional security or privacy benefit
+              and must not be read from. It should still be included on outgoing messages
+              (if the event for which keys are being requested for *also* has a `sender_key`),
+              however must not be used to find the corresponding session. See [`m.megolm.v1.aes-sha2`](#mmegolmv1aes-sha2)
+              for more information.
           session_id:
             type: string
             description: The ID of the session that the key is for.
         required:
           - algorithm
           - room_id
           - session_id
-          - sender_key
         type: object
         title: RequestedKeyInfo
       action: