From e2e83b130d072f26f1e0384824288a2e63f99fab Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Mon, 16 Dec 2019 15:15:46 -0500 Subject: [PATCH 1/9] initial proposal for reporting of withheld keys --- proposals/xxxx-reporting-no-key-sent.md | 58 +++++++++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 proposals/xxxx-reporting-no-key-sent.md diff --git a/proposals/xxxx-reporting-no-key-sent.md b/proposals/xxxx-reporting-no-key-sent.md new file mode 100644 index 00000000..79157f1d --- /dev/null +++ b/proposals/xxxx-reporting-no-key-sent.md @@ -0,0 +1,58 @@ +# Reporting that decryption keys are withheld + +When an encrypted message is sent in a room, the megolm key might not be +sent to all devices present in the room. Sometimes this may be inadvertent (for +example, if the sending device is not aware of some devices that have joined), +but some times, this may be purposeful. For example, the sender may have +blacklisted certain devices or users, or may be choosing to not send the megolm +key to devices that they have not verified yet. + +Currently, when this happens, there is no feedback given to the affected +devices; devices that have not received keys do not know why they did not +receive the key, and so cannot inform the user as to whether it is expected +that the message cannot be decrypted. To address this, senders can send a +message to devices indicating that they purposely did not send a megolm +key. + +A similar issue happens with keyshare requests; devices are not informed when +other devices decide not to send back keys, and so do not know whether to +expect to receive a key in response to the request. + +## Proposal + +Devices that purposely do not send megolm keys to a device may instead send an +`m.room_key.withheld` event as a to-device message to the device to indicate +that it should not expect to receive keys for the message. This message may +also be sent in reply to a `m.room_key_request`. The `m.room.no_key` event has +the properties: + +- `room_id`: Required. The ID of the room that the session belongs to. +- `session_id`: Required. The ID of the session. +- `code`: An machine-readable code for why the key was not sent. + Possible values are: + - `m.blacklisted`: the user/device was blacklisted + - `m.unverified`: the user/devices is unverified + - `m.unauthorised`: the user/device is not allowed have the key. For + example, this would usually be sent in response to a key request if the + user was not in the room when the message was sent + - `m.unavailable`: sent in reply to a key request if the device that the key + is requested from does not have the requested key +- `reason`: A human-readable reason for why the key was not sent. If there is + a `code`, this should be a human-readable representation of `code`. The + receiving client should only use this string if it does not understand the + `code` or if `code` is not provided. + +## Potential issues + +This does not handle all possible reasons why a device may not have received +megolm keys. + +## Security considerations + +A user might not want to notify another user of the reason why it was not sent +the keys. Sending `m.room_key.witheld`, or specifying the `reason`/`code` are +optional. + +## Unstable prefix + +While in development, clients will send events of type `org.matrix.room_key.witheld`. From c87802587a4320610c13cba00f0978faf8f3a2f6 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Thu, 2 Jan 2020 17:02:19 -0500 Subject: [PATCH 2/9] fix typos, add information --- proposals/xxxx-reporting-no-key-sent.md | 32 +++++++++++++++++++++---- 1 file changed, 27 insertions(+), 5 deletions(-) diff --git a/proposals/xxxx-reporting-no-key-sent.md b/proposals/xxxx-reporting-no-key-sent.md index 79157f1d..46ec8c7f 100644 --- a/proposals/xxxx-reporting-no-key-sent.md +++ b/proposals/xxxx-reporting-no-key-sent.md @@ -26,9 +26,12 @@ that it should not expect to receive keys for the message. This message may also be sent in reply to a `m.room_key_request`. The `m.room.no_key` event has the properties: -- `room_id`: Required. The ID of the room that the session belongs to. -- `session_id`: Required. The ID of the session. -- `code`: An machine-readable code for why the key was not sent. +- `room_id`: Required if `code` is not `m.no_olm`. The ID of the room that the + session belongs to. +- `algorithm`: Required. The encryption algorithm that the key is for. +- `session_id`: Required if `code` is not `m.no_olm`. The ID of the session. +- `sender_key`: Required. The key of the session creator. +- `code`: A machine-readable code for why the key was not sent. Possible values are: - `m.blacklisted`: the user/device was blacklisted - `m.unverified`: the user/devices is unverified @@ -37,11 +40,29 @@ the properties: user was not in the room when the message was sent - `m.unavailable`: sent in reply to a key request if the device that the key is requested from does not have the requested key + - `m.no_olm`: an olm session could not be established. This may happen, for + example, if the sender was unable to obtain a one-time key from the + recipient. - `reason`: A human-readable reason for why the key was not sent. If there is a `code`, this should be a human-readable representation of `code`. The receiving client should only use this string if it does not understand the `code` or if `code` is not provided. +An `m.room_key.withheld` event should only be sent once per session; the +recipient of the event should assume that the event applies to all messages in +that session. If a sender unblocks a recipient, it may re-use the existing +session for which the recipient was previously informed that it was blocked, in +which case, the recipient of the `m.room_key.withheld` message should assume +that the event applies to all messages in the session prior to the index of the +first key that it has received for that session. + +A `code` of `m.no_olm` is used to indicate that the sender is unable to +establish an olm session with the recipient. When this happens, multiple +sessions will be affected. In order to avoid filling the recipient's device +mailbox, the sender should only send one `m.room_key.withheld` message with no +`room_id` nor `session_id` set. FIXME: how does the recipient determine which +sessions the notification applies to? + ## Potential issues This does not handle all possible reasons why a device may not have received @@ -50,9 +71,10 @@ megolm keys. ## Security considerations A user might not want to notify another user of the reason why it was not sent -the keys. Sending `m.room_key.witheld`, or specifying the `reason`/`code` are +the keys. Sending `m.room_key.withheld`, or specifying the `reason`/`code` are optional. ## Unstable prefix -While in development, clients will send events of type `org.matrix.room_key.witheld`. +While in development, clients will send events of type +`org.matrix.room_key.withheld`. From 654a9574bedd540d8a5547ab24fbd67319a039e2 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Thu, 2 Jan 2020 17:05:12 -0500 Subject: [PATCH 3/9] rename to match MSC number --- ...xxx-reporting-no-key-sent.md => 2399-reporting-no-key-sent.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename proposals/{xxxx-reporting-no-key-sent.md => 2399-reporting-no-key-sent.md} (100%) diff --git a/proposals/xxxx-reporting-no-key-sent.md b/proposals/2399-reporting-no-key-sent.md similarity index 100% rename from proposals/xxxx-reporting-no-key-sent.md rename to proposals/2399-reporting-no-key-sent.md From a0fcb7d9e140ded9ed5ed8f4980bff6d5c02e3c1 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Thu, 19 Mar 2020 17:10:44 -0400 Subject: [PATCH 4/9] make code required, and some more details about no_olm --- proposals/2399-reporting-no-key-sent.md | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/proposals/2399-reporting-no-key-sent.md b/proposals/2399-reporting-no-key-sent.md index 46ec8c7f..58f2acb8 100644 --- a/proposals/2399-reporting-no-key-sent.md +++ b/proposals/2399-reporting-no-key-sent.md @@ -31,7 +31,7 @@ the properties: - `algorithm`: Required. The encryption algorithm that the key is for. - `session_id`: Required if `code` is not `m.no_olm`. The ID of the session. - `sender_key`: Required. The key of the session creator. -- `code`: A machine-readable code for why the key was not sent. +- `code`: Required. A machine-readable code for why the key was not sent. Possible values are: - `m.blacklisted`: the user/device was blacklisted - `m.unverified`: the user/devices is unverified @@ -43,10 +43,9 @@ the properties: - `m.no_olm`: an olm session could not be established. This may happen, for example, if the sender was unable to obtain a one-time key from the recipient. -- `reason`: A human-readable reason for why the key was not sent. If there is - a `code`, this should be a human-readable representation of `code`. The +- `reason`: A human-readable reason for why the key was not sent. The receiving client should only use this string if it does not understand the - `code` or if `code` is not provided. + `code`. An `m.room_key.withheld` event should only be sent once per session; the recipient of the event should assume that the event applies to all messages in @@ -60,8 +59,11 @@ A `code` of `m.no_olm` is used to indicate that the sender is unable to establish an olm session with the recipient. When this happens, multiple sessions will be affected. In order to avoid filling the recipient's device mailbox, the sender should only send one `m.room_key.withheld` message with no -`room_id` nor `session_id` set. FIXME: how does the recipient determine which -sessions the notification applies to? +`room_id` nor `session_id` set. In response to receiving this message, the +recipient may start an olm session with the sender, and send an `m.dummy` +message to notify the sender of the new olm session. The recipient may assume +that this `m.room_key.withheld` message applies to all encrypted room messages +sent before it receives the message. ## Potential issues @@ -71,8 +73,7 @@ megolm keys. ## Security considerations A user might not want to notify another user of the reason why it was not sent -the keys. Sending `m.room_key.withheld`, or specifying the `reason`/`code` are -optional. +the keys. Sending `m.room_key.withheld` is optional. ## Unstable prefix From a6ae757e7a977805b9ff32ea52fade0db73709f5 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Wed, 13 May 2020 12:47:46 -0400 Subject: [PATCH 5/9] Fix typo --- proposals/2399-reporting-no-key-sent.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2399-reporting-no-key-sent.md b/proposals/2399-reporting-no-key-sent.md index 58f2acb8..b31644dc 100644 --- a/proposals/2399-reporting-no-key-sent.md +++ b/proposals/2399-reporting-no-key-sent.md @@ -23,7 +23,7 @@ expect to receive a key in response to the request. Devices that purposely do not send megolm keys to a device may instead send an `m.room_key.withheld` event as a to-device message to the device to indicate that it should not expect to receive keys for the message. This message may -also be sent in reply to a `m.room_key_request`. The `m.room.no_key` event has +also be sent in reply to a `m.room_key_request`. The `m.room_key.withheld` event has the properties: - `room_id`: Required if `code` is not `m.no_olm`. The ID of the room that the From 9ccfe61674e9e461978c46e2e52736b896da281e Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Wed, 13 May 2020 14:22:26 -0400 Subject: [PATCH 6/9] add some clarifications and add sharing withheld reason with other devices --- proposals/2399-reporting-no-key-sent.md | 35 +++++++++++++++++++------ 1 file changed, 27 insertions(+), 8 deletions(-) diff --git a/proposals/2399-reporting-no-key-sent.md b/proposals/2399-reporting-no-key-sent.md index b31644dc..9655574f 100644 --- a/proposals/2399-reporting-no-key-sent.md +++ b/proposals/2399-reporting-no-key-sent.md @@ -10,9 +10,9 @@ key to devices that they have not verified yet. Currently, when this happens, there is no feedback given to the affected devices; devices that have not received keys do not know why they did not receive the key, and so cannot inform the user as to whether it is expected -that the message cannot be decrypted. To address this, senders can send a -message to devices indicating that they purposely did not send a megolm -key. +that the message cannot be decrypted. To address this, this proposal defines a +message that senders can (optionally) send to devices indicating that they +purposely did not send a megolm key. A similar issue happens with keyshare requests; devices are not informed when other devices decide not to send back keys, and so do not know whether to @@ -59,17 +59,36 @@ A `code` of `m.no_olm` is used to indicate that the sender is unable to establish an olm session with the recipient. When this happens, multiple sessions will be affected. In order to avoid filling the recipient's device mailbox, the sender should only send one `m.room_key.withheld` message with no -`room_id` nor `session_id` set. In response to receiving this message, the -recipient may start an olm session with the sender, and send an `m.dummy` -message to notify the sender of the new olm session. The recipient may assume -that this `m.room_key.withheld` message applies to all encrypted room messages -sent before it receives the message. +`room_id` nor `session_id` set. If the sender retries and fails to create an +olm session again in the future, it should not send another +`m.room_key.withheld` message with a `code` of `m.no_olm`, unless another olm +session was previously established successfully. In response to receiving an +`m.room_key.withheld` message with a `code` of `m.no_olm`, the recipient may +start an olm session with the sender and send an `m.dummy` message to notify +the sender of the new olm session. The recipient may assume that this +`m.room_key.withheld` message applies to all encrypted room messages sent +before it receives the message. + +### Interaction with key sharing + +If Alice withholds a megolm session from Bob for some messages in a room, and +then later on decides to allow Bob to decrypt later messages, she can send Bob +the megolm session, ratcheted up to the point at which she allows Bob to +decrypt the messages. If Bob logs into a new device and uses key sharing to +obtain the decryption keys, the new device will be sent the megolm sessions +that have been ratcheted up. Bob's old device can include the reason that the +session was initially not shared by including a `withheld` property in the +`m.forwarded_room_key` message that is an object with the `code` and `reason` +properties from the `m.room_key.withheld` message. ## Potential issues This does not handle all possible reasons why a device may not have received megolm keys. +There is currently no way of indicating that part of a session was withheld in +key backups. + ## Security considerations A user might not want to notify another user of the reason why it was not sent From 915e698c2300f62c694560f3c216df267247bf48 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Thu, 21 May 2020 16:48:27 -0400 Subject: [PATCH 7/9] clarify which key --- proposals/2399-reporting-no-key-sent.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2399-reporting-no-key-sent.md b/proposals/2399-reporting-no-key-sent.md index 9655574f..05f5dd64 100644 --- a/proposals/2399-reporting-no-key-sent.md +++ b/proposals/2399-reporting-no-key-sent.md @@ -31,7 +31,7 @@ the properties: - `algorithm`: Required. The encryption algorithm that the key is for. - `session_id`: Required if `code` is not `m.no_olm`. The ID of the session. - `sender_key`: Required. The key of the session creator. -- `code`: Required. A machine-readable code for why the key was not sent. +- `code`: Required. A machine-readable code for why the megolm key was not sent. Possible values are: - `m.blacklisted`: the user/device was blacklisted - `m.unverified`: the user/devices is unverified From 64b1ea332319f98f5380fd504305bdc8614ddc73 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Fri, 22 May 2020 15:00:44 -0400 Subject: [PATCH 8/9] clarify which key again --- proposals/2399-reporting-no-key-sent.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2399-reporting-no-key-sent.md b/proposals/2399-reporting-no-key-sent.md index 05f5dd64..14fa5e2b 100644 --- a/proposals/2399-reporting-no-key-sent.md +++ b/proposals/2399-reporting-no-key-sent.md @@ -30,7 +30,7 @@ the properties: session belongs to. - `algorithm`: Required. The encryption algorithm that the key is for. - `session_id`: Required if `code` is not `m.no_olm`. The ID of the session. -- `sender_key`: Required. The key of the session creator. +- `sender_key`: Required. The unpadded base64-encoded device curve25519 key of the session creator. - `code`: Required. A machine-readable code for why the megolm key was not sent. Possible values are: - `m.blacklisted`: the user/device was blacklisted From 40ec1ae1a998b273c3b2b6600df6bd433d01d820 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Fri, 22 May 2020 15:01:32 -0400 Subject: [PATCH 9/9] clarification --- proposals/2399-reporting-no-key-sent.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2399-reporting-no-key-sent.md b/proposals/2399-reporting-no-key-sent.md index 14fa5e2b..2550fdbf 100644 --- a/proposals/2399-reporting-no-key-sent.md +++ b/proposals/2399-reporting-no-key-sent.md @@ -47,7 +47,7 @@ the properties: receiving client should only use this string if it does not understand the `code`. -An `m.room_key.withheld` event should only be sent once per session; the +An `m.room_key.withheld` event should only be sent once per session per target; the recipient of the event should assume that the event applies to all messages in that session. If a sender unblocks a recipient, it may re-use the existing session for which the recipient was previously informed that it was blocked, in