-
Notifications
You must be signed in to change notification settings - Fork 370
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
MSC2399: Reporting that decryption keys are withheld #2399
Merged
Merged
Changes from all commits
Commits
Show all changes
9 commits
Select commit
Hold shift + click to select a range
e2e83b1
initial proposal for reporting of withheld keys
uhoreg c878025
fix typos, add information
uhoreg 654a957
rename to match MSC number
uhoreg a0fcb7d
make code required, and some more details about no_olm
uhoreg a6ae757
Fix typo
uhoreg 9ccfe61
add some clarifications and add sharing withheld reason with other de…
uhoreg 915e698
clarify which key
uhoreg 64b1ea3
clarify which key again
uhoreg 40ec1ae
clarification
uhoreg File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,100 @@ | ||
# 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, 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 | ||
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_key.withheld` event has | ||
the properties: | ||
|
||
- `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 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 | ||
- `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 | ||
- `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. The | ||
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 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 | ||
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. 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 | ||
the keys. Sending `m.room_key.withheld` is optional. | ||
uhoreg marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
## Unstable prefix | ||
|
||
While in development, clients will send events of type | ||
`org.matrix.room_key.withheld`. |
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'd have gone with something slightly more generic here, since the problem is a failure to create a peer to peer encrypted channel rather than anything specific to olm (one day people might use another mechanism). Not a strong opinion though.