matrix-spec-proposals/data/event-schemas/schema/m.forwarded_room_key.yaml

---
allOf:
  - $ref: core-event-schema/event.yaml

description: |-
  This event type is used to forward keys for end-to-end encryption. Typically
  it is encrypted as an `m.room.encrypted` event, then sent as a [to-device](/client-server-api/#send-to-device-messaging)
  event.
properties:
  content:
    properties:
      algorithm:
        type: string
        description: |-
          The encryption algorithm the key in this event is to be used with.
      room_id:
        type: string
        description: The room where the key is used.
      sender_key:
        type: string
        description: |-
          The Curve25519 key of the device which initiated the session originally.
      session_id:
        type: string
        description: The ID of the session that the key is for.
      session_key:
        type: string
        description: The key to be exchanged.
      sender_claimed_ed25519_key:
        type: string
        description: |-
          The Ed25519 key of the device which initiated the session originally.
          It is 'claimed' because the receiving device has no way to tell that the
          original room_key actually came from a device which owns the private part of
          this key unless they have done device verification.
      forwarding_curve25519_key_chain:
        type: array
        items:
          type: string
        description: |-
          Chain of Curve25519 keys. It starts out empty, but each time the
          key is forwarded to another device, the previous sender in the chain is added
          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](/client-server-api/#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
      - session_id
      - session_key
      - sender_claimed_ed25519_key
      - forwarding_curve25519_key_chain
      - sender_key
    type: object
  type:
    enum:
      - m.forwarded_room_key
    type: string
type: object