Merge pull request #1465 from Zil0/key_sharing

Document key sharing events

changelogs/client_server/newsfragments/1465.feature

@@ -0,0 +1 @@
+Share room decryption keys between devices

event-schemas/examples/m.forwarded_room_key

@@ -0,0 +1,14 @@
+{
+  "content": {
+    "algorithm": "m.megolm.v1.aes-sha2",
+    "room_id": "!Cuyf34gef24t:localhost",
+    "session_id": "X3lUlvLELLYxeTx4yOVu6UDpasGEVO0Jbu+QFnm0cKQ",
+    "session_key": "AgAAAADxKHa9uFxcXzwYoNueL5Xqi69IkD4sni8Llf...",
+    "sender_key": "RF3s+E7RkTQTGF2d8Deol0FkQvgII2aJDf3/Jp5mxVU",
+    "sender_claimed_ed25519_key": "aj40p+aw64yPIdsxoog8jhPu9i7l7NcFRecuOQblE3Y",
+    "forwarding_curve25519_key_chain": [
+      "hPQNcabIABgGnx3/ACv/jmMmiQHoeFfuLB17tzWp6Hw"
+    ]
+  },
+  "type": "m.room_key"
+}

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.forwarded_room_key

@@ -0,0 +1,59 @@
+---
+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`_
+  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.
+    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

event-schemas/schema/m.room_key_request

@@ -0,0 +1,61 @@
+---
+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. Required when ``action`` is
+          ``request``.
+        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 that the key is for.
+        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,31 @@ 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.
+
+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
+``cancel_request`` to the other devices that it had originally sent the key
+request to; a device that receives a ``cancel_request`` should disregard any
+previously-received ``request`` message with the same ``request_id`` and
+``requesting_device_id``.
+
+.. 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
 --------------------
 
@@ -470,6 +495,10 @@ Events
 
 {{m_room_key_event}}
 
+{{m_room_key_request_event}}
+
+{{m_forwarded_room_key_event}}
+
 Key management API
 ~~~~~~~~~~~~~~~~~~