From e2e83b130d072f26f1e0384824288a2e63f99fab Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Mon, 16 Dec 2019 15:15:46 -0500 Subject: [PATCH] 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 000000000..79157f1da --- /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`.