You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
matrix-spec-proposals/event-schemas/schema/m.room_key.withheld

87 lines
3.3 KiB
Plaintext

---
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
enum:
- m.blacklisted
- m.unverified
- m.unauthorised
- m.unavailable
- m.no_olm
description: |-
A machine-readable code for why the key was not sent. Codes beginning
with `m.` are reserved for codes defined in the Matrix
specification. Custom codes must use the Java package naming
convention.
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