From c87802587a4320610c13cba00f0978faf8f3a2f6 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Thu, 2 Jan 2020 17:02:19 -0500 Subject: [PATCH] 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`.