diff --git a/content/client-server-api/modules/end_to_end_encryption.md b/content/client-server-api/modules/end_to_end_encryption.md index fb94f03f7..2bf2e58e9 100644 --- a/content/client-server-api/modules/end_to_end_encryption.md +++ b/content/client-server-api/modules/end_to_end_encryption.md @@ -1533,6 +1533,8 @@ through `m.room_key_request` messages. ##### `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 +1582,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 +1624,13 @@ 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 session key in its store, the client MUST ensure: + +* that the updated session data comes from a trusted source, where a trusted source + could be the signatures on the session or comes from the user's session key backup; + and +* that the new session key has a lower message index than the existing session key. + #### Protocol definitions ##### Events diff --git a/data/event-schemas/schema/m.room.encrypted.yaml b/data/event-schemas/schema/m.room.encrypted.yaml index 32e869029..51024f7e2 100644 --- a/data/event-schemas/schema/m.room.encrypted.yaml +++ b/data/event-schemas/schema/m.room.encrypted.yaml @@ -40,10 +40,35 @@ 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: |- @@ -51,7 +76,6 @@ properties: Megolm. required: - algorithm - - sender_key - ciphertext type: object type: diff --git a/data/event-schemas/schema/m.room_key_request.yaml b/data/event-schemas/schema/m.room_key_request.yaml index 99afdb191..acabe2d93 100644 --- a/data/event-schemas/schema/m.room_key_request.yaml +++ b/data/event-schemas/schema/m.room_key_request.yaml @@ -23,8 +23,19 @@ 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. @@ -32,7 +43,6 @@ properties: - algorithm - room_id - session_id - - sender_key type: object title: RequestedKeyInfo action: