Add Olm unwedging

changelogs/client_server/newsfragments/2059.feature

@@ -0,0 +1 @@
+Add support for Olm sessions becoming un-stuck.

event-schemas/examples/m.dummy

@@ -0,0 +1,4 @@
+{
+  "content": {},
+  "type": "m.dummy"
+}

event-schemas/schema/m.dummy

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

specification/modules/end_to_end_encryption.rst

@@ -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.
@@ -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
@@ -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``
 ~~~~~~~~~~~~~~~~~~~~~~~~
@@ -740,6 +769,8 @@ Events
 
 {{m_forwarded_room_key_event}}
 
+{{m_dummy_event}}
+
 Key management API
 ~~~~~~~~~~~~~~~~~~