From 38350002a62f6896ae8e0485280956be619104ce Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Mon, 19 Oct 2020 18:57:39 -0400 Subject: [PATCH] add spec for reporting that keys are withheld --- event-schemas/examples/m.room_key.withheld | 12 +++ event-schemas/schema/m.forwarded_room_key | 9 +++ event-schemas/schema/m.room_key.withheld | 77 +++++++++++++++++++ .../modules/end_to_end_encryption.rst | 46 +++++++++-- 4 files changed, 136 insertions(+), 8 deletions(-) create mode 100644 event-schemas/examples/m.room_key.withheld create mode 100644 event-schemas/schema/m.room_key.withheld diff --git a/event-schemas/examples/m.room_key.withheld b/event-schemas/examples/m.room_key.withheld new file mode 100644 index 00000000..fa8f135f --- /dev/null +++ b/event-schemas/examples/m.room_key.withheld @@ -0,0 +1,12 @@ +{ + "$ref": "core/event.json", + "type": "m.room_key.withheld", + "content": { + "algorithm": "m.megolm.v1.aes-sha2", + "room_id": "!Cuyf34gef24t:localhost", + "session_id": "X3lUlvLELLYxeTx4yOVu6UDpasGEVO0Jbu+QFnm0cKQ", + "sender_key": "RF3s+E7RkTQTGF2d8Deol0FkQvgII2aJDf3/Jp5mxVU", + "code": "m.unverified", + "reason": "Device not verified" + } +} diff --git a/event-schemas/schema/m.forwarded_room_key b/event-schemas/schema/m.forwarded_room_key index f0beed2b..7350a25b 100644 --- a/event-schemas/schema/m.forwarded_room_key +++ b/event-schemas/schema/m.forwarded_room_key @@ -43,6 +43,15 @@ properties: to the end of the list. For example, if the key is forwarded from A to B to C, this field is empty between A and B, and contains A's Curve25519 key between B and C. + withheld: + type: object + description: |- + Indicates that the key cannot be used to decrypt all the messages + from the session because a portion of the session was withheld as + described in `Reporting that decryption keys are withheld`_. This + object must include the ``code`` and ``reason`` properties from the + ``m.room_key.withheld`` message that was received by the sender of + this message. required: - algorithm - room_id diff --git a/event-schemas/schema/m.room_key.withheld b/event-schemas/schema/m.room_key.withheld new file mode 100644 index 00000000..f37b24ee --- /dev/null +++ b/event-schemas/schema/m.room_key.withheld @@ -0,0 +1,77 @@ +--- +allOf: + - $ref: core-event-schema/event.yaml + +description: |- + This event type is used to indicate that the sender is not sharing room keys + with the recipient. It is sent as a to-device event. + + Possible values for ``code`` include: + + * ``m.blacklisted``: the user/device was blacklisted. + * ``m.unverified``: the user/device was not verified, and the sender is only + sharing keys with verified users/devices. + * ``m.unauthorised``: the user/device is not allowed to have the key. For + example, this could be sent in response to a key request if the user/device + was not in the room when the original 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. + + In most cases, this event refers to a specific room key. The one exception to + this is when 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. +properties: + content: + properties: + algorithm: + type: string + enum: ["m.megolm.v1.aes-sha2"] + description: |- + The encryption algorithm for the key that this event is about. + room_id: + type: string + description: |- + Required if ``code`` is not ``m.no_olm``. The room for the key that + this event is about. + session_id: + type: string + description: |- + Required of ``code`` is not ``m.no_olm``. The session ID of the key + that this event is aboutis for. + sender_key: + type: string + description: |- + The unpadded base64-encoded device curve25519 key of the event\'s + sender. + code: + type: string + description: |- + A machine-readable code for why the key was not sent. + reason: + type: string + description: |- + 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``. + required: + - algorithm + - sender_key + - code + type: object + type: + enum: + - m.room_key.withheld + type: string +type: object diff --git a/specification/modules/end_to_end_encryption.rst b/specification/modules/end_to_end_encryption.rst index 63c1e0d1..4f60c848 100644 --- a/specification/modules/end_to_end_encryption.rst +++ b/specification/modules/end_to_end_encryption.rst @@ -792,14 +792,19 @@ Key requests When a device is missing keys to decrypt messages, it can request the keys by sending `m.room_key_request`_ to-device messages to other devices with -``action`` set to ``request``. If a device wishes to share the keys with that -device, it can forward the keys to the first device by sending an encrypted -`m.forwarded_room_key`_ to-device message. The first device should then send an -`m.room_key_request`_ to-device message with ``action`` set to -``request_cancellation`` to the other devices that it had originally sent the key -request to; a device that receives a ``request_cancellation`` should disregard any -previously-received ``request`` message with the same ``request_id`` and -``requesting_device_id``. +``action`` set to ``request``. + +If a device wishes to share the keys with that device, it can forward the keys +to the first device by sending an encrypted `m.forwarded_room_key`_ to-device +message. The first device should then send an `m.room_key_request`_ to-device +message with ``action`` set to ``request_cancellation`` to the other devices +that it had originally sent the key request to; a device that receives a +``request_cancellation`` should disregard any previously-received ``request`` +message with the same ``request_id`` and ``requesting_device_id``. + +If a device does not wish to share keys with that device, it can indicate this +by sending an `m.room_key.withheld`_ to-device message, as described in +`Reporting that decryption keys are withheld`_. .. NOTE:: @@ -1333,6 +1338,31 @@ Example response: } } +Reporting that decryption keys are withheld +------------------------------------------- + +When sending an encrypted event to a room, a client can signal to other devices +in that room that it is not sending them the keys needed to decrypt the event. +In this way, the receiving client can indicate to the user why it cannot +decrypt the event, rather than just showing a generic error message. + +In the same way, when one device requests keys from another using `Key +requests`_, the device from which the key is being requested may want to tell +the requester that it is purposely not sharing the key. + +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. + +{{m_room_key_withheld_event}} + + .. References .. _ed25519: http://ed25519.cr.yp.to/