Skip to content

Add Olm unwedging #2059

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Jun 4, 2019
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelogs/client_server/newsfragments/2059.feature
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Add support for Olm sessions becoming un-stuck.
4 changes: 4 additions & 0 deletions event-schemas/examples/m.dummy
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
{
"content": {},
"type": "m.dummy"
}
23 changes: 23 additions & 0 deletions event-schemas/schema/m.dummy
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
---
allOf:
- $ref: core-event-schema/event.yaml

description: |-
This event type is used to indicate new Olm sessions for end-to-end encryption.
Typically it is encrypted as an ``m.room.encrypted`` event, then sent as a `to-device`_
event.

The event does not have any content associated with it. The sending client is expected
to send a key share request shortly after this message, causing the receiving client to
process this ``m.dummy`` event as the most recent event and using the keyshare request
to set up the session. The keyshare request and ``m.dummy`` combination should result
in the original sending client receiving keys over the newly established session.
properties:
content:
properties: {}
type: object
type:
enum:
- m.dummy
type: string
type: object
41 changes: 36 additions & 5 deletions specification/modules/end_to_end_encryption.rst
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
.. Copyright 2016 OpenMarket Ltd
.. Copyright 2019 The Matrix.org Foundation C.I.C.
..
.. Licensed under the Apache License, Version 2.0 (the "License");
.. you may not use this file except in compliance with the License.
Expand All @@ -18,7 +19,7 @@ End-to-End Encryption
.. _module:e2e:

Matrix optionally supports end-to-end encryption, allowing rooms to be created
whose conversation contents is not decryptable or interceptable on any of the
whose conversation contents are not decryptable or interceptable on any of the
participating homeservers.

Key Distribution
Expand Down Expand Up @@ -658,10 +659,38 @@ part of the ed25519 key it claims to have in the Olm payload.
This is crucial when the ed25519 key corresponds to a verified device.

If a client has multiple sessions established with another device, it should
use the session from which it last received a message. A client may expire old
sessions by defining a maximum number of olm sessions that it will maintain for
each device, and expiring sessions on a Least Recently Used basis. The maximum
number of olm sessions maintained per device should be at least 4.
use the session from which it last received and successfully decrypted a
message. For these purposes, a session that has not received any messages
should use its creation time as the time that it last received a message.
A client may expire old sessions by defining a maximum number of olm sessions
that it will maintain for each device, and expiring sessions on a Least Recently
Used basis. The maximum number of olm sessions maintained per device should
be at least 4.

Recovering from undecryptable messages
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<

Occasionally messages may be undecryptable by clients due to a variety of reasons.
When this happens to an Olm-encrypted message, the client should assume that the Olm
session has become corrupted and create a new one to replace it.

.. Note::
Megolm-encrypted messages generally do not have the same problem. Usually the key
for an undecryptable Megolm-encrypted message will come later, allowing the client
to decrypt it successfully. Olm does not have a way to recover from the failure,
making this session replacement process required.

To establish a new session, the client sends a `m.dummy <#m-dummy>`_ to-device event
to the other party to notify them of the new session details.

Clients should rate-limit the number of sessions it creates per device that it receives
a message from. Clients should not create a new session with another device if it has
already created one for that given device in the past 1 hour.

Clients should attempt to mitigate loss of the undecryptable messages. For example,
Megolm sessions that were sent using the old session would have been lost. The client
can attempt to retrieve the lost sessions through ``m.room_key_request`` messages.


``m.megolm.v1.aes-sha2``
~~~~~~~~~~~~~~~~~~~~~~~~
Expand Down Expand Up @@ -740,6 +769,8 @@ Events

{{m_forwarded_room_key_event}}

{{m_dummy_event}}

Key management API
~~~~~~~~~~~~~~~~~~

Expand Down