add spec for reporting that keys are withheld

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

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

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

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/