[WIP] MSC2697: Device dehydration

proposals/2697-device-dehydration.md

@@ -0,0 +1,169 @@
+# MSC2697: Device Dehydration
+
+End-to-end encryption in Matrix relies on the sending device being able to send
+megolm sessions to the recipients' devices.  When a
+user logs into a new device, they can obtain the megolm sessions using key
+backup or key sharing if another of their devices had previously received the
+session.  However, when a user has no logged-in devices when a message is sent,
+they are unable to receive incoming megolm sessions.
+
+One solution to this is have a dehydrated device stored (encrypted)
+server-side, which may be rehydrated and used when the user creates a new
+login rather than creating a new device from scratch.  The new login will
+receive any to-device messages that were sent to the dehydrated device.
+
+## Proposal
+
+### Rehydrating a device
+
+A new parameter, `restore_device` is added to `POST /login`, indicating that the
+client can restore a previously stored device.  If the parameter is not
+present, it defaults to `false`.  If the server has a stored device that can be
+used, it will respond with the same response as a normal login, with the
+following exceptions:
+
+- no `access_token` is provided
+- a `device_data` property is provided, containing information about the
+  dehydrated device that the client uses to try to rehydrate the device
+- a `dehydration_token` is provided, giving a token that the client uses to
+  complete the login.  The token may be expired if it is not used within a
+  reasonable amount of time (for example, 10 minutes).
+
+If the server does not have a stored device, or does not understand device
+dehydration, then it will respond as if a normal login request were made.
+
+The client will try to decrypt the device data (see below for encryption).  The
+client will then make a `POST /restore_device` request, with the
+`dehydration_token` body parameter set to the token received from the server.
+If it was successful and it wishes to use the device, then it will set the
+`rehydrate` body parameter set to `true`.  Otherwise, it will set `rehydrate`
+to `false`.
+
+The server will return an object in the same format as the response for a
+normal login.  The client will use the device ID given to determine if it
+should use the dehydrated device, or if it should use a new device.  Even if
+the client was able to successfully decrypt the device data, it may not able to
+allowed to use it.  For example, two clients may race in trying to dehydrate
+the device; only one client should use the dehydrated device.  In the case of a
+race, the server will give the dehydrated device's ID to one client, and
+generate a new device ID for any other clients.  Another potential reason that
+the client may not be allowed to use the dehydrated device is if the device was
+deleted.
+
+If the dehydrated device is not used (whether because the client set
+`rehydrate` to `false`, or because the server indicated that the client is not
+able to use the dehydrated device), the server will use the `device_id` and
+`initial_device_display_name` parameters from the client's original call to
+`/login`, if they were provided, to create a device for the user.  If the
+dehydrated device is used, the server will set the device's name to the
+`initial_device_display_name` from the client's original call to `/login`, if
+it was provided.
+
+After `POST /restore_device` returns, the client is logged in and may proceed
+as normal.
+
+### Dehydrating a device
+
+To upload a new dehydrated device, a client will use `POST /device/dehydrate`.
+Each user has at most one dehydrated device; uploading a new dehydrated device
+will remove any previously-set dehydrated device.
+
+```json
+{
+  "device_data": {"device": "data"},
+  "initial_device_display_name": "foo bar",
+}
+```
+
+Result:
+
+```json
+{
+  "device_id": "deviceid"
+}
+```
+
+After the dehydrated device is uploaded, the client will upload the encryption
+keys using `POST /keys/upload/{device_id}`, where the `device_id` parameter is
+the device ID given in the response to `/device/dehydrate`.
+
+FIXME: synapse already supports `POST /keys/upload/{device_id}`, but requires
+that the given device ID matches the device ID of the client that made the
+call.  We need to (re-)add the endpoint, and allow uploading keys for the
+dehydrated device.
+
+### Device dehydration format
+
+The `device_data` property is an object that has an `algorithm` field
+indicating what other fields are present.
+
+#### `m.dehydration.v1.olm`
+
+- `passphrase`: Optional.  Indicates how to generate the decryption key from a
+  passphrase.  It is in the same format with Secure Secret Storage.
+- `account`: Required. ... FIXME: should we just reuse libolm's pickle format?
+
+## Potential issues
+
+### One-time key exhaustion
+
+The dehydrated device may run out of one-time keys, since it is not backed by
+an active client that can replenish them.  Once a device has run out of
+one-time keys, no new olm sessions can be established with it, which means that
+devices that have not already shared megolm keys with the dehydrated device
+will not be able to share megolm keys.  This issue is not unique to dehydrated
+devices; this also occurs when devices are offline for an extended period of
+time.
+
+This may be addressed by using fallback keys as described in
+[MSC2732](https://github.com/matrix-org/matrix-doc/pull/2732).
+
+To reduce the chances of one-time key exhaustion, if the user has an active
+client, it can periodically replace the dehydrated device with a new dehydrated
+device with new one-time keys.  If a client does this, then it runs the risk of
+losing any megolm keys that were sent to the dehydrated device, but the client
+would likely have received those megolm keys itself.
+
+Alternatively, the client could perform a `/sync` for the dehydrated device,
+dehydrate the olm sessions, and upload new one-time keys.  By doing this
+instead of overwriting the dehydrated device, the device can receive megolm
+keys from more devices.  However, this would require additional server-side
+changes above what this proposal provides, so this approach is not possible for
+the moment.
+
+### Accumulated to-device messages
+
+If a dehydrated device is not rehydrated for a long time, then it may
+accumulate many to-device messages from other clients sending it megolm
+sessions.  This may result in a slower initial sync when the device eventually
+does get rehydrated, due to the number of messages that it will retrieve.
+Again, this can be addressed by periodically replacing the dehydrated device,
+or by performing a `/sync` for the dehydrated device and updating it.
+
+## Alternatives
+
+Rather than uploading a dehydrated device to the server, we could instead have
+the sender resend the megolm session in the case where a user had no active
+devices at the time that a message was sent.  However this does not solve the
+issue for users who happen to never be online at the same time.  But this could
+be done in addition to the solution proposed here.
+
+The sender could also send the megolm session to a the user using a public key
+using some per-user mechanism.  This would require changes to both the sender
+and receiver (whereas this proposal only requires changes to the receiver), and
+would require developing a system by which the sender could determine whether
+the public key may be trusted (whereas this proposal the existing cross-signing
+mechanism).
+
+## Security considerations
+
+If the dehydrated device is encrypted using a weak password or key, an attacker
+could access it and read the user's encrypted messages.
+
+## Unstable prefix
+
+While this MSC is in development, the `POST /restore_device` endpoint will be
+reached at `POST /unstable/org.matrix.msc2697/restore_device`, and the `POST
+/device/dehydrate` endpoint will be reached at `POST
+/unstable/org.matrix.msc2697/device/dehydrate`.  The `restore_device` parameter
+for `POST /login` will be called `org.matrix.msc2697.restore_device`.