add spec for reporting that keys are withheld

pull/977/head
Hubert Chathi 4 years ago
parent deaa82c653
commit 38350002a6

@ -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"
}
}

@ -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

@ -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

@ -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/

Loading…
Cancel
Save