From a24dbf0f156ad98bd9030855fb2595097fcb3e21 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Fri, 12 Mar 2021 18:16:32 -0500 Subject: [PATCH 1/5] initial version --- proposals/xxxx-shareable-room-keys.md | 78 +++++++++++++++++++++++++++ 1 file changed, 78 insertions(+) create mode 100644 proposals/xxxx-shareable-room-keys.md diff --git a/proposals/xxxx-shareable-room-keys.md b/proposals/xxxx-shareable-room-keys.md new file mode 100644 index 00000000000..ae824a78e81 --- /dev/null +++ b/proposals/xxxx-shareable-room-keys.md @@ -0,0 +1,78 @@ +# MSCxxxx: Sharing room keys for past messages + +In Matrix, rooms can be configured via the `m.room.history_visibility` state +event such that historical messages can be visible to all Matrix users +(`world_readable`), all room members (`shared`), room members from the time +that they are invited to a room (`invited`), or room members from the time that +they join a room (`joined`). However, currently in encrypted rooms, rooms with +the history visibility set to `world_readable` or `shared` are effectively +set to `invited` since other members generally do not send new members the keys +to decrypt messages sent before they were invited or joined a room. + +We define a "shared-history" flag that identifies keys for messages that were +sent when the room's visibility setting was set to `world_readable` or +`shared`. This allows clients to know which keys are "safe" to share with new +members so that they can decrypt historical messages. We also give examples of +ways in which this flag can be used. + + +## Proposal + +A room key (such as a megolm session) is flagged as having been used for shared +history when it was used to encrypt a message while the room's history +visibility setting was set to `world_readable` or `shared`. Internally, a +client may use any mechanism it wants to keep track of this flag. When a room +key is marked as such: + +- `m.room_key` and `m.forwarded_room_key` messages used to share this key have + a `shared_history` property set to `true`, +- the `session_data` field in key backups of this key has a `shared_history` + property set to `true` in the decrypted JSON structure, and +- the `SessionData` type used in key exports has a `shared_history` property + that is set to `true` for this key. + +When a client obtains a key that has the `shared_history` property set to +`true`, then it flags the key internally as having been used for shared +history. Otherwise, the key should not be flagged as such. + +When the room's history visibility setting changes to `world_readable` or +`shared` from `invited` or `joined`, or changes to `invited` or `joined` from +`world_readable` or `shared`, senders that support this flag must rotate their +megolm sessions. + +Clients may use this flag to modify their behaviour with respect to sharing +keys. For example: + +- when the user invites someone to the room, they may preemptively share keys + that have this flag with the invited user. +- when the user receives a key share request, they may share the key with the + requester if the user is a current member of the room. The key may be shared + from the first available ratchet index, not just the requested index. +- when sending a message after a new user has joined the room, a sender may + share the megolm session from the first available index, rather than from the + current ratchet index. + +## Potential issues + +Room keys from clients that do not support this proposal will not be eligible +for the modified client behaviour. + +## Alternatives + +Rather than having the sender flagging keys, a client can paginate through the +room's history to determine the room's history visibility settings when the +room key was used. This would not require any changes, but has performance +problems. In addition, the server could lie about the room history while the +user is paginating through the history. By having the sender flag keys, this +ensures that the key is treated in a manner consistent with the sender's view +of the room. + +## Security considerations + +Clients should still ensure that keys are only shared with authorized users and +devices. + +## Unstable prefix + +Until this feature lands in the spec, the property name to be used is +`org.matrix.mscxxxx.shared_history` rather than `shared_history`. From 38f35c23e8cb013a59bbc9216eba7354de72ed2d Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Fri, 12 Mar 2021 18:18:38 -0500 Subject: [PATCH 2/5] use MSC number --- ...xxx-shareable-room-keys.md => 3061-shareable-room-keys.md} | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) rename proposals/{xxxx-shareable-room-keys.md => 3061-shareable-room-keys.md} (97%) diff --git a/proposals/xxxx-shareable-room-keys.md b/proposals/3061-shareable-room-keys.md similarity index 97% rename from proposals/xxxx-shareable-room-keys.md rename to proposals/3061-shareable-room-keys.md index ae824a78e81..fafd2fd1d5e 100644 --- a/proposals/xxxx-shareable-room-keys.md +++ b/proposals/3061-shareable-room-keys.md @@ -1,4 +1,4 @@ -# MSCxxxx: Sharing room keys for past messages +# MSC3061: Sharing room keys for past messages In Matrix, rooms can be configured via the `m.room.history_visibility` state event such that historical messages can be visible to all Matrix users @@ -75,4 +75,4 @@ devices. ## Unstable prefix Until this feature lands in the spec, the property name to be used is -`org.matrix.mscxxxx.shared_history` rather than `shared_history`. +`org.matrix.msc3061.shared_history` rather than `shared_history`. From af63c9c2f66cb54a9184f273ceb4a5b083e17e93 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Wed, 21 Dec 2022 18:38:38 -0500 Subject: [PATCH 3/5] address comments from review --- proposals/3061-shareable-room-keys.md | 111 +++++++++++++++++++++----- 1 file changed, 92 insertions(+), 19 deletions(-) diff --git a/proposals/3061-shareable-room-keys.md b/proposals/3061-shareable-room-keys.md index fafd2fd1d5e..21b9a98adf6 100644 --- a/proposals/3061-shareable-room-keys.md +++ b/proposals/3061-shareable-room-keys.md @@ -20,16 +20,74 @@ ways in which this flag can be used. A room key (such as a megolm session) is flagged as having been used for shared history when it was used to encrypt a message while the room's history -visibility setting was set to `world_readable` or `shared`. Internally, a -client may use any mechanism it wants to keep track of this flag. When a room -key is marked as such: +visibility setting was set to `world_readable` or `shared`. + +If the client does not have an `m.room.history_visibility` state event for the +room, or its value is not understood, the client should treat it as if its +value is `joined` for the purposes of determining whether the key is used for +shared history. This is in contrast with the normal processing of +`m.room.history_visibility` which defaults to `world_readable` when there is no +`m.room.history_visibility` state event or its value is not understood. This +is done so that, in the event of a bug that causes the client to fail to obtain +the state event, the client will fail in a secure manner. + +Internally, a client may use any mechanism it wants to keep track of this flag. +When a room key is marked as having been used for shared history: - `m.room_key` and `m.forwarded_room_key` messages used to share this key have - a `shared_history` property set to `true`, -- the `session_data` field in key backups of this key has a `shared_history` - property set to `true` in the decrypted JSON structure, and -- the `SessionData` type used in key exports has a `shared_history` property - that is set to `true` for this key. + a `shared_history` property set to `true` e.g. + + ```json + { + "type": "m.room_key", + "content": { + "algorithm": "m.megolm.v1.aes-sha2", + "room_id": "!room_id", + "session_id": "session_id", + "session_key": "session_key", + "shared_history": true + } + } + ``` + - the [`SessionData` type](https://spec.matrix.org/unstable/client-server-api/#definition-sessiondata) + in key backups (that is, the plaintext object that gets encrypted into the + `session_data` field) of this key has a `shared_history` property set to + `true` in the decrypted JSON structure e.g. + + ```json + { + "algorithm": "m.megolm.v1.aes-sha2", + "forwarding_curve25519_key_chain": [ + "hPQNcabIABgGnx3/ACv/jmMmiQHoeFfuLB17tzWp6Hw" + ], + "sender_claimed_keys": { + "ed25519": "aj40p+aw64yPIdsxoog8jhPu9i7l7NcFRecuOQblE3Y" + }, + "sender_key": "RF3s+E7RkTQTGF2d8Deol0FkQvgII2aJDf3/Jp5mxVU", + "session_key": "AgAAAADxKHa9uFxcXzwYoNueL5Xqi69IkD4sni8Llf...", + "shared_history": true + } + ``` + + and, +- the [`SessionData` type](https://spec.matrix.org/unstable/client-server-api/#key-export-format) + used in key exports has a `shared_history` property that is set to `true` for + this key e.g. + + ```json + { + "algorithm": "m.megolm.v1.aes-sha2", + "forwarding_curve25519_key_chain": [ + "hPQNcabIABgGnx3/ACv/jmMmiQHoeFfuLB17tzWp6Hw" + ], + "sender_claimed_keys": { + "ed25519": "aj40p+aw64yPIdsxoog8jhPu9i7l7NcFRecuOQblE3Y" + }, + "sender_key": "RF3s+E7RkTQTGF2d8Deol0FkQvgII2aJDf3/Jp5mxVU", + "session_key": "AgAAAADxKHa9uFxcXzwYoNueL5Xqi69IkD4sni8Llf...", + "shared_history": true + } + ``` When a client obtains a key that has the `shared_history` property set to `true`, then it flags the key internally as having been used for shared @@ -41,22 +99,24 @@ When the room's history visibility setting changes to `world_readable` or megolm sessions. Clients may use this flag to modify their behaviour with respect to sharing -keys. For example: - -- when the user invites someone to the room, they may preemptively share keys - that have this flag with the invited user. -- when the user receives a key share request, they may share the key with the - requester if the user is a current member of the room. The key may be shared - from the first available ratchet index, not just the requested index. -- when sending a message after a new user has joined the room, a sender may - share the megolm session from the first available index, rather than from the - current ratchet index. +keys. For example, when the user invites someone to the room, they may +preemptively share keys that have this flag with the invited user. Other +behaviours may be possible, but must be careful not to guard against malicious +homeservers. See the "Security Considerations" section. ## Potential issues Room keys from clients that do not support this proposal will not be eligible for the modified client behaviour. +The suggested behaviour in this MSC is to only share additional keys when +inviting another user. This does not allow users who join the room but were +not invited (for example, if membership is restricted to another space, or if +the room is publicly joinable) to receive the keys. Also, if the inviter does +not have all the keys available for whatever reason, the invitee has no way of +receiving the keys. This may be solved in the future when we have a mechanism +for verifying room membership. + ## Alternatives Rather than having the sender flagging keys, a client can paginate through the @@ -67,10 +127,23 @@ user is paginating through the history. By having the sender flag keys, this ensures that the key is treated in a manner consistent with the sender's view of the room. +Rather than using a boolean flag, we could include the history visibility +setting as-is. For example, a `history_visibility` field could be added, which +is set to the history visibility setting (e.g. `world_readable`). This +produces an equivalent effect, but it pushes the processing of the history +visibility setting to the receiver rather than the sender. For consistency, it +is better for as much of the decision-making done by the sender, rather than +the receiver. + ## Security considerations Clients should still ensure that keys are only shared with authorized users and -devices. +devices, as a malicious homeserver could inject fake room membership events. +One way to ensure that keys are only shared with authorized users is to only +share keys with users when the client invites them, as the client is then +certain that the user is allowed to be in the room. Another way is to have a +mechanism of verifying membership, such as the method proposed in +(MSC3917)[https://github.com/matrix-org/matrix-spec-proposals/pull/3917]. ## Unstable prefix From ac4e336541dd0fb9c8987517c89ffa9a581db57c Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Wed, 21 Dec 2022 18:42:15 -0500 Subject: [PATCH 4/5] fix list --- proposals/3061-shareable-room-keys.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/proposals/3061-shareable-room-keys.md b/proposals/3061-shareable-room-keys.md index 21b9a98adf6..6958b679b39 100644 --- a/proposals/3061-shareable-room-keys.md +++ b/proposals/3061-shareable-room-keys.md @@ -49,7 +49,8 @@ When a room key is marked as having been used for shared history: } } ``` - - the [`SessionData` type](https://spec.matrix.org/unstable/client-server-api/#definition-sessiondata) + +- the [`SessionData` type](https://spec.matrix.org/unstable/client-server-api/#definition-sessiondata) in key backups (that is, the plaintext object that gets encrypted into the `session_data` field) of this key has a `shared_history` property set to `true` in the decrypted JSON structure e.g. From 54286a633a3ce9e31d5d262d0473b9f8f51f488c Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Wed, 9 Aug 2023 08:36:11 -0400 Subject: [PATCH 5/5] fix markdown Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --- proposals/3061-shareable-room-keys.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/3061-shareable-room-keys.md b/proposals/3061-shareable-room-keys.md index 6958b679b39..39fc5b919bc 100644 --- a/proposals/3061-shareable-room-keys.md +++ b/proposals/3061-shareable-room-keys.md @@ -144,7 +144,7 @@ One way to ensure that keys are only shared with authorized users is to only share keys with users when the client invites them, as the client is then certain that the user is allowed to be in the room. Another way is to have a mechanism of verifying membership, such as the method proposed in -(MSC3917)[https://github.com/matrix-org/matrix-spec-proposals/pull/3917]. +[MSC3917](https://github.com/matrix-org/matrix-spec-proposals/pull/3917). ## Unstable prefix