Merge pull request #1465 from Zil0/key_sharing

Document key sharing events
pull/977/head
Hubert Chathi 6 years ago committed by GitHub
commit 4230e375fa
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

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

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

@ -0,0 +1,8 @@
{
"content": {
"action": "cancel_request",
"requesting_device_id": "RJYKSTBOIE",
"request_id": "1495474790150.19"
},
"type": "m.room_key_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"
}

@ -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

@ -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

@ -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 decrypted by such a device. For the Olm protocol, this is documented at
https://matrix.org/git/olm/about/docs/signing.rst. 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 Messaging Algorithms
-------------------- --------------------
@ -470,6 +495,10 @@ Events
{{m_room_key_event}} {{m_room_key_event}}
{{m_room_key_request_event}}
{{m_forwarded_room_key_event}}
Key management API Key management API
~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~

Loading…
Cancel
Save