document key sharing and m.room_key_request

event-schemas/examples/m.room_key_request#cancel_request

@@ -0,0 +1,8 @@
+{
+  "content": {
+    "action": "cancel_request",
+    "requesting_device_id": "RJYKSTBOIE",
+    "request_id": "1495474790150.19"
+  },
+  "type": "m.room_key_request"
+}

event-schemas/examples/m.room_key_request#request

@@ -0,0 +1,14 @@
+{
+  "content": {
+    "body": {
+      "algorithm": "m.megolm.v1.aes-sha2",
+      "room_id": "!Cuyf34gef24t:localhost",
+      "session_id": "X3lUlvLELLYxeTx4yOVu6UDpasGEVO0Jbu+QFnm0cKQ",
+      "sender_key": "RF3s+E7RkTQTGF2d8Deol0FkQvgII2aJDf3/Jp5mxVU"
+    },
+    "action": "request",
+    "requesting_device_id": "RJYKSTBOIE",
+    "request_id": "1495474790150.19"
+  },
+  "type": "m.room_key_request"
+}

event-schemas/schema/m.room_key_request

@@ -0,0 +1,59 @@
+---
+allOf:
+  - $ref: core-event-schema/event.yaml
+
+description: |-
+  This event type is used to request keys for end-to-end encryption. It is sent as an
+  unencrypted `to-device`_ event.
+properties:
+  content:
+    properties:
+      body:
+        description: Information about the requested key.
+        properties:
+          algorithm:
+            type: string
+            description: |-
+              The encryption algorithm the requested 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 holding the key.
+        required:
+          - algorithm
+          - room_id
+          - session_id
+          - sender_key
+        type: object
+        title: RequestedKeyInfo
+      action:
+        enum:
+          - request
+          - cancel_request
+        type: string
+      requesting_device_id:
+        description: ID of the device requesting the key.
+        type: string
+      request_id:
+        description: |-
+          A random string uniquely identifying the request for a key. If the key is
+          requested multiple times, it should be reused. It should also reused in order
+          to cancel a request.
+        type: string
+    required:
+      - action
+      - requesting_device_id
+      - request_id
+    type: object
+  type:
+    enum:
+      - m.room_key_request
+    type: string
+type: object

specification/modules/end_to_end_encryption.rst

@@ -283,6 +283,20 @@ Device verification may reach one of several conclusions. For example:
    decrypted by such a device. For the Olm protocol, this is documented at
    https://matrix.org/git/olm/about/docs/signing.rst.
 
+Key sharing
+-----------
+
+If Bob has an encrypted conversation with Alice on his computer, and then logs in
+through his phone for the first time, he may want to have access to the previously
+exchanged messages. To address this issue, events exist for requesting and sending
+keys from device to device.
+
+.. NOTE::
+
+  Key sharing can be a big attack vector, thus it must be done very carefully.
+  A reasonable stategy is for a user's client to only send keys requested by the
+  verified devices of the same user.
+
 Messaging Algorithms
 --------------------
 
@@ -464,6 +478,10 @@ Events
 
 {{m_room_key_event}}
 
+{{m_room_key_request_event}}
+
+{{m_forwarded_room_key_event}}
+
 Key management API
 ~~~~~~~~~~~~~~~~~~