From ce31f30940fe875b768177c3409c32784c4e73f6 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Tue, 28 May 2024 20:18:45 -0400 Subject: [PATCH 01/12] initial version of including device keys with olm-encrypted events --- ...g-device-keys-with-olm-encrypted-events.md | 135 ++++++++++++++++++ 1 file changed, 135 insertions(+) create mode 100644 proposals/xxxx-including-device-keys-with-olm-encrypted-events.md diff --git a/proposals/xxxx-including-device-keys-with-olm-encrypted-events.md b/proposals/xxxx-including-device-keys-with-olm-encrypted-events.md new file mode 100644 index 00000000000..3463653c0af --- /dev/null +++ b/proposals/xxxx-including-device-keys-with-olm-encrypted-events.md @@ -0,0 +1,135 @@ +# MSCxxxx: Including device keys with Olm-encrypted events + +When a Megolm session is sent from one device to another via Olm, the recipient +can +[query](https://spec.matrix.org/unstable/client-server-api/#post_matrixclientv3keysquery) +the sender's device keys and check whether the device has been cross-signed in +order to determine whether the sending device can be trusted. However, this +does not work if the sending device has since logged out as the recipient will +not be able to query the sender's device keys. For example, this can happen if +the recipient is offline for a long time. + +One way to solve this is to include a copy of the device keys in the +Olm-encrypted message, along with the cross-signing signatures, so that the +recipient does not have to try to query the sender's keys. + +## Proposal + +The plaintext payload of the [`m.olm.v1.curve25519-aes-sha2` encryption +algorithm](https://spec.matrix.org/unstable/client-server-api/#molmv1curve25519-aes-sha2) +is currently of the form: + +```json +{ + "type": "", + "content": "", + "sender": "", + "recipient": "", + "recipient_keys": { + "ed25519": "" + }, + "keys": { + "ed25519": "" + } +} +``` + +We propose to add a new property: `device_keys`, which is a copy of what the +server would return in response to a +[`/keys/query`](https://spec.matrix.org/unstable/client-server-api/#post_matrixclientv3keysquery) +request, as the device keys for the sender's device. In other words, the +plaintext payload will now look something like: + +```json +{ + "type": "", + "content": "", + "sender": "", + "recipient": "", + "recipient_keys": { + "ed25519": "" + }, + "keys": { + "ed25519": "" + }, + "device_keys": { + "algorithms": ["", ""], + "user_id": "", + "device_id": "", + "keys": { + "ed25519:": "", + "curve25519:": "" + }, + "signatures": { + "": { + "ed25519:": "", + "ed25519:": "", + } + } + } +} +``` + +If this property is present, the `keys`.`ed25519` property of the plaintext +payload must be the same as the `device_keys`.`keys`.`ed25519:` +property. + +As the `keys` property is now redundant, it may be removed in a future version +of Olm. + +## Potential issues + +Adding this property will increase the size of the event. This could be +mitigated by only sending the `device_keys` in pre-key messages (Olm messages +with `type: 0` in the `m.room.encrypted` event -- with the rationale that if +the Olm message is a normal (non-pre-key) message, this means that the +recipient has already decrypted a pre-key message that contains the +information, and so does not need to be re-sent the information), or if the +signatures change (for example, if the sender resets their cross-signing keys), +or if the sender has not yet sent their `device_keys`. However, this requires +additional bookkeeping, and it is not clear whether this extra complexity is +worth the reduction in bandwidth. + +If the sender resets their cross-signing keys, then the self-signing signature +in the `device_keys` is meaningless. The recipient will need to re-query the +device keys, and will need to treat the sender as untrusted if it fails to do +so. The sender could include the self-signing key, signed by the +master-signing key, in the plaintext event, so that if the user only resets +their self-signing key but retains their masster-signing key, the recipient can +still check the sender's device keys. However, this will further increase the +size of the event, and it is not common for clients to reset the self-signing +key without also resetting the master-signing key, so this is unlikely to give +much benefit. + +## Alternatives + +The `device_keys` property could be added to the cleartext. That is, it could +be added as a property to the `m.room.encrypted` event. This information is +already public, as it is accessible from `/keys/query` (while the device is +logged in), and does not need to be authenticated as it is protected by .the +self-signing signature, so it does not seem to need to be encrypted. However, +there seems to be little reason not to encrypt the information. + +The `device_keys` property could be added to the cleartext by the sender's +homeserver, rather than by the sending client. Possibly within an `unsigned` +property, as that is where properties added by homeservers are customarily +added. It is not clear what advantage there would be to having this +information being added by the client. + +## Security considerations + +If a device is logged out, there is no indication why it was logged out. For +example, an attacker could steal a device and use it send a message. The user, +upon realizing that the device has been stolen, could log out the device, but +the message may still be sent, if the user does not notice the message and +redact it. Thus the recipient device should still indicate that the message +came from a deleted device. + +## Unstable prefix + +Until this MSC is accepted, the new property should be named +`org.matrix.mscxxxx.device_keys`. + +## Dependencies + +None From 4fa6b3fc7f2e79b8c4660031ca5f1f254ebb87d2 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Wed, 29 May 2024 16:35:40 -0400 Subject: [PATCH 02/12] use MSC number --- ...> 4147-including-device-keys-with-olm-encrypted-events.md} | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) rename proposals/{xxxx-including-device-keys-with-olm-encrypted-events.md => 4147-including-device-keys-with-olm-encrypted-events.md} (98%) diff --git a/proposals/xxxx-including-device-keys-with-olm-encrypted-events.md b/proposals/4147-including-device-keys-with-olm-encrypted-events.md similarity index 98% rename from proposals/xxxx-including-device-keys-with-olm-encrypted-events.md rename to proposals/4147-including-device-keys-with-olm-encrypted-events.md index 3463653c0af..4938d409181 100644 --- a/proposals/xxxx-including-device-keys-with-olm-encrypted-events.md +++ b/proposals/4147-including-device-keys-with-olm-encrypted-events.md @@ -1,4 +1,4 @@ -# MSCxxxx: Including device keys with Olm-encrypted events +# MSC4147: Including device keys with Olm-encrypted events When a Megolm session is sent from one device to another via Olm, the recipient can @@ -128,7 +128,7 @@ came from a deleted device. ## Unstable prefix Until this MSC is accepted, the new property should be named -`org.matrix.mscxxxx.device_keys`. +`org.matrix.msc4147.device_keys`. ## Dependencies From 62352ca35f65dedc897a42dacce38a35d4dde97a Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Wed, 29 May 2024 16:36:44 -0400 Subject: [PATCH 03/12] fix typo --- .../4147-including-device-keys-with-olm-encrypted-events.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/4147-including-device-keys-with-olm-encrypted-events.md b/proposals/4147-including-device-keys-with-olm-encrypted-events.md index 4938d409181..897c5d058ad 100644 --- a/proposals/4147-including-device-keys-with-olm-encrypted-events.md +++ b/proposals/4147-including-device-keys-with-olm-encrypted-events.md @@ -95,7 +95,7 @@ in the `device_keys` is meaningless. The recipient will need to re-query the device keys, and will need to treat the sender as untrusted if it fails to do so. The sender could include the self-signing key, signed by the master-signing key, in the plaintext event, so that if the user only resets -their self-signing key but retains their masster-signing key, the recipient can +their self-signing key but retains their master-signing key, the recipient can still check the sender's device keys. However, this will further increase the size of the event, and it is not common for clients to reset the self-signing key without also resetting the master-signing key, so this is unlikely to give From 419bed318aa7adf7b05b4763b652bad3b830e38e Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Mon, 10 Jun 2024 18:38:16 -0400 Subject: [PATCH 04/12] indicate what should happen if keys differ --- .../4147-including-device-keys-with-olm-encrypted-events.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/4147-including-device-keys-with-olm-encrypted-events.md b/proposals/4147-including-device-keys-with-olm-encrypted-events.md index 897c5d058ad..40473f31ca2 100644 --- a/proposals/4147-including-device-keys-with-olm-encrypted-events.md +++ b/proposals/4147-including-device-keys-with-olm-encrypted-events.md @@ -72,7 +72,7 @@ plaintext payload will now look something like: If this property is present, the `keys`.`ed25519` property of the plaintext payload must be the same as the `device_keys`.`keys`.`ed25519:` -property. +property. If they differ, the recipient should discard the event. As the `keys` property is now redundant, it may be removed in a future version of Olm. From 33bb7c292b189e0ca3cb22c62842639c67b801a8 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Thu, 17 Oct 2024 15:06:18 -0400 Subject: [PATCH 05/12] Apply suggestions from code review Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --- ...147-including-device-keys-with-olm-encrypted-events.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/proposals/4147-including-device-keys-with-olm-encrypted-events.md b/proposals/4147-including-device-keys-with-olm-encrypted-events.md index 40473f31ca2..87c5aa54391 100644 --- a/proposals/4147-including-device-keys-with-olm-encrypted-events.md +++ b/proposals/4147-including-device-keys-with-olm-encrypted-events.md @@ -15,7 +15,7 @@ recipient does not have to try to query the sender's keys. ## Proposal -The plaintext payload of the [`m.olm.v1.curve25519-aes-sha2` encryption +The plaintext payload of `m.room.encrypted` events encrypted with the [`m.olm.v1.curve25519-aes-sha2` encryption algorithm](https://spec.matrix.org/unstable/client-server-api/#molmv1curve25519-aes-sha2) is currently of the form: @@ -57,8 +57,8 @@ plaintext payload will now look something like: "user_id": "", "device_id": "", "keys": { - "ed25519:": "", - "curve25519:": "" + "ed25519:": "", + "curve25519:": "" }, "signatures": { "": { @@ -75,7 +75,7 @@ payload must be the same as the `device_keys`.`keys`.`ed25519:` property. If they differ, the recipient should discard the event. As the `keys` property is now redundant, it may be removed in a future version -of Olm. +of the Matrix specification. ## Potential issues From 04acb6b476248992a10b2105c389b780205280db Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Fri, 1 Nov 2024 16:40:34 +0000 Subject: [PATCH 06/12] switch to versioned spec links --- .../4147-including-device-keys-with-olm-encrypted-events.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/proposals/4147-including-device-keys-with-olm-encrypted-events.md b/proposals/4147-including-device-keys-with-olm-encrypted-events.md index 87c5aa54391..7038ffba2fc 100644 --- a/proposals/4147-including-device-keys-with-olm-encrypted-events.md +++ b/proposals/4147-including-device-keys-with-olm-encrypted-events.md @@ -2,7 +2,7 @@ When a Megolm session is sent from one device to another via Olm, the recipient can -[query](https://spec.matrix.org/unstable/client-server-api/#post_matrixclientv3keysquery) +[query](https://spec.matrix.org/v1.12/client-server-api/#post_matrixclientv3keysquery) the sender's device keys and check whether the device has been cross-signed in order to determine whether the sending device can be trusted. However, this does not work if the sending device has since logged out as the recipient will @@ -16,7 +16,7 @@ recipient does not have to try to query the sender's keys. ## Proposal The plaintext payload of `m.room.encrypted` events encrypted with the [`m.olm.v1.curve25519-aes-sha2` encryption -algorithm](https://spec.matrix.org/unstable/client-server-api/#molmv1curve25519-aes-sha2) +algorithm](https://spec.matrix.org/v1.12/client-server-api/#molmv1curve25519-aes-sha2) is currently of the form: ```json @@ -36,7 +36,7 @@ is currently of the form: We propose to add a new property: `device_keys`, which is a copy of what the server would return in response to a -[`/keys/query`](https://spec.matrix.org/unstable/client-server-api/#post_matrixclientv3keysquery) +[`/keys/query`](https://spec.matrix.org/v1.12/client-server-api/#post_matrixclientv3keysquery) request, as the device keys for the sender's device. In other words, the plaintext payload will now look something like: From 407e1d915b786660492505bd3655cb0e3e7b8d8b Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Fri, 1 Nov 2024 17:15:38 +0000 Subject: [PATCH 07/12] Clarify the problem being solved --- ...g-device-keys-with-olm-encrypted-events.md | 58 ++++++++++++------- 1 file changed, 38 insertions(+), 20 deletions(-) diff --git a/proposals/4147-including-device-keys-with-olm-encrypted-events.md b/proposals/4147-including-device-keys-with-olm-encrypted-events.md index 7038ffba2fc..ff7802c2c54 100644 --- a/proposals/4147-including-device-keys-with-olm-encrypted-events.md +++ b/proposals/4147-including-device-keys-with-olm-encrypted-events.md @@ -1,15 +1,37 @@ # MSC4147: Including device keys with Olm-encrypted events -When a Megolm session is sent from one device to another via Olm, the recipient -can -[query](https://spec.matrix.org/v1.12/client-server-api/#post_matrixclientv3keysquery) -the sender's device keys and check whether the device has been cross-signed in -order to determine whether the sending device can be trusted. However, this -does not work if the sending device has since logged out as the recipient will -not be able to query the sender's device keys. For example, this can happen if -the recipient is offline for a long time. - -One way to solve this is to include a copy of the device keys in the +Summary: a proposal to ensure that messages sent from short-lived devices can +be securely distinguished from a spoofed device. + +## Background + +When a Matrix client receives an encrypted message, it is necessary to +establish whether that message was sent from a device genuinely belonging to +the apparent sender, or from a spoofed device (for example, a device created by +an attacker with access to the sender's account such as the server admin, or a +man-in-the-middle). + +In short, this is done by requiring a signature on the sending device's device +keys from the sending user's [self-signing cross-signing +key](https://spec.matrix.org/v1.12/client-server-api/#cross-signing). Such a +signature proves that the sending device was genuine. + +Current client implementations check for such a signature by +[querying](https://spec.matrix.org/v1.12/client-server-api/#post_matrixclientv3keysquery) +the sender's device keys when an encrypted message is received. + +However, this does not work if the sending device logged out in the time +between sending the message and it being received. This is particularly likely +if the recipient is offline for a long time. In such a case, the sending server +will have forgotten the sending device (and any cross-signing signatures) by +the time the recipient queries for it. This makes the received message +indistinguishable from one sent from a spoofed device. + +Current implementations work around this by displaying a warning such as "sent +by a deleted or unknown device" against the received message, but such +messaging is unsatisfactory: a message should be either trusted or not. + +We propose to solve this is by including a copy of the device keys in the Olm-encrypted message, along with the cross-signing signatures, so that the recipient does not have to try to query the sender's keys. @@ -90,16 +112,12 @@ or if the sender has not yet sent their `device_keys`. However, this requires additional bookkeeping, and it is not clear whether this extra complexity is worth the reduction in bandwidth. -If the sender resets their cross-signing keys, then the self-signing signature -in the `device_keys` is meaningless. The recipient will need to re-query the -device keys, and will need to treat the sender as untrusted if it fails to do -so. The sender could include the self-signing key, signed by the -master-signing key, in the plaintext event, so that if the user only resets -their self-signing key but retains their master-signing key, the recipient can -still check the sender's device keys. However, this will further increase the -size of the event, and it is not common for clients to reset the self-signing -key without also resetting the master-signing key, so this is unlikely to give -much benefit. +This proposal is not a complete solution. In particular, if the sender resets +their cross-signing keys, and also logs out the sending device, the recipient +still has no way to verify the sending device. The device signature in the Olm +message is meaningless. A full solution would require the recipient to be able +to obtain a history of cross-signing key changes, and to expose that +information to the user; that is left for the future. ## Alternatives From 5bb2093a3a23ddb883bb009618b9d2c15a755df1 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Fri, 1 Nov 2024 17:41:05 +0000 Subject: [PATCH 08/12] another reason to encrypt device_keys --- ...including-device-keys-with-olm-encrypted-events.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/proposals/4147-including-device-keys-with-olm-encrypted-events.md b/proposals/4147-including-device-keys-with-olm-encrypted-events.md index ff7802c2c54..55a31f37db8 100644 --- a/proposals/4147-including-device-keys-with-olm-encrypted-events.md +++ b/proposals/4147-including-device-keys-with-olm-encrypted-events.md @@ -75,7 +75,7 @@ plaintext payload will now look something like: "ed25519": "" }, "device_keys": { - "algorithms": ["", ""], + "algorithms": ["", ""], "user_id": "", "device_id": "", "keys": { @@ -124,9 +124,12 @@ information to the user; that is left for the future. The `device_keys` property could be added to the cleartext. That is, it could be added as a property to the `m.room.encrypted` event. This information is already public, as it is accessible from `/keys/query` (while the device is -logged in), and does not need to be authenticated as it is protected by .the -self-signing signature, so it does not seem to need to be encrypted. However, -there seems to be little reason not to encrypt the information. +logged in), and does not need to be authenticated as it is protected by the +self-signing signature, so it does not seem to need to be encrypted. However, +there seems to be little reason not to encrypt the information. In addition, by +including it in the encrypted payload, it leaves open the possibility of +it replacing the `keys` property, which must be part of the encrypted payload +to prevent an [unknown key-share attack](https://github.com/element-hq/element-web/issues/2215). The `device_keys` property could be added to the cleartext by the sender's homeserver, rather than by the sending client. Possibly within an `unsigned` From 0deb58f06321ffe8510c93d4465f0dde6730b471 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Fri, 1 Nov 2024 18:01:09 +0000 Subject: [PATCH 09/12] Document alternative approach properly --- ...g-device-keys-with-olm-encrypted-events.md | 50 ++++++++++++++----- 1 file changed, 37 insertions(+), 13 deletions(-) diff --git a/proposals/4147-including-device-keys-with-olm-encrypted-events.md b/proposals/4147-including-device-keys-with-olm-encrypted-events.md index 55a31f37db8..13ab60bf4c0 100644 --- a/proposals/4147-including-device-keys-with-olm-encrypted-events.md +++ b/proposals/4147-including-device-keys-with-olm-encrypted-events.md @@ -101,16 +101,11 @@ of the Matrix specification. ## Potential issues -Adding this property will increase the size of the event. This could be -mitigated by only sending the `device_keys` in pre-key messages (Olm messages -with `type: 0` in the `m.room.encrypted` event -- with the rationale that if -the Olm message is a normal (non-pre-key) message, this means that the -recipient has already decrypted a pre-key message that contains the -information, and so does not need to be re-sent the information), or if the -signatures change (for example, if the sender resets their cross-signing keys), -or if the sender has not yet sent their `device_keys`. However, this requires -additional bookkeeping, and it is not clear whether this extra complexity is -worth the reduction in bandwidth. +Adding this property will increase the size of the event. We found it +increased the length of a typical `m.room_key` message from about 1400 to 2400 +bytes (a 70% increase). This will require increased storage on the recipient +homeserver, and increase bandwidth for both senders and recipients. See +[Alternatives](#alternatives) for discussion of mitigation strategies. This proposal is not a complete solution. In particular, if the sender resets their cross-signing keys, and also logs out the sending device, the recipient @@ -121,6 +116,8 @@ information to the user; that is left for the future. ## Alternatives +### Minor variations + The `device_keys` property could be added to the cleartext. That is, it could be added as a property to the `m.room.encrypted` event. This information is already public, as it is accessible from `/keys/query` (while the device is @@ -132,19 +129,46 @@ it replacing the `keys` property, which must be part of the encrypted payload to prevent an [unknown key-share attack](https://github.com/element-hq/element-web/issues/2215). The `device_keys` property could be added to the cleartext by the sender's -homeserver, rather than by the sending client. Possibly within an `unsigned` +homeserver, rather than by the sending client. Possibly within an `unsigned` property, as that is where properties added by homeservers are customarily added. It is not clear what advantage there would be to having this information being added by the client. +To mitigate the increased size of to-device events under this proposal, the +`device_keys` could be sent only in pre-key messages (Olm messages +with `type: 0` in the `m.room.encrypted` event) — with the rationale that if +the Olm message is a normal (non-pre-key) message, this means that the +recipient has already decrypted a pre-key message that contains the +information, and so does not need to be re-sent the information), or if the +signatures change (for example, if the sender resets their cross-signing keys), +or if the sender has not yet sent their `device_keys`. However, this requires +additional bookkeeping, and it is not clear whether this extra complexity is +worth the reduction in bandwidth. + +### Alternative approach + +A more radical proposal to decrease the overhead in to-device messages is to +instead specify that `/keys/query` must include deleted devices as well as +active ones, so that they can be reliably queried. Since the origin server +might be unreachable at the time the recipient receives the message, such +device lists would need to be cached on the recipient homeserver. + +In other words, this approach would require all homeservers to keep a permanent +record of all devices observed anywhere in the federation, at least for as long +as there are undelivered to-device events from such devices. + +Transparently: we have not significantly expolored this approach. We have a +working solution, and it is unclear that the advantages of this alternative +approach outweigh the opportunity cost and delay in rollout of an important +security feature. + ## Security considerations If a device is logged out, there is no indication why it was logged out. For example, an attacker could steal a device and use it send a message. The user, upon realizing that the device has been stolen, could log out the device, but the message may still be sent, if the user does not notice the message and -redact it. Thus the recipient device should still indicate that the message -came from a deleted device. +redact it. ## Unstable prefix From 28d03f50939bf989f606a20d0c463b6de7f5be3d Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Sat, 2 Nov 2024 18:45:44 +0000 Subject: [PATCH 10/12] minor edits --- ...ing-device-keys-with-olm-encrypted-events.md | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/proposals/4147-including-device-keys-with-olm-encrypted-events.md b/proposals/4147-including-device-keys-with-olm-encrypted-events.md index 13ab60bf4c0..e4876f1e7c3 100644 --- a/proposals/4147-including-device-keys-with-olm-encrypted-events.md +++ b/proposals/4147-including-device-keys-with-olm-encrypted-events.md @@ -1,15 +1,16 @@ # MSC4147: Including device keys with Olm-encrypted events -Summary: a proposal to ensure that messages sent from short-lived devices can -be securely distinguished from a spoofed device. +Summary: a proposal to ensure that messages sent from a short-lived (but +genuine) device can be securely distinguished from those sent from a spoofed +device. ## Background When a Matrix client receives an encrypted message, it is necessary to establish whether that message was sent from a device genuinely belonging to the apparent sender, or from a spoofed device (for example, a device created by -an attacker with access to the sender's account such as the server admin, or a -man-in-the-middle). +an attacker with access to the sender's account such as a malicious server +admin, or a man-in-the-middle). In short, this is done by requiring a signature on the sending device's device keys from the sending user's [self-signing cross-signing @@ -31,7 +32,7 @@ Current implementations work around this by displaying a warning such as "sent by a deleted or unknown device" against the received message, but such messaging is unsatisfactory: a message should be either trusted or not. -We propose to solve this is by including a copy of the device keys in the +We propose to solve this by including a copy of the device keys in the Olm-encrypted message, along with the cross-signing signatures, so that the recipient does not have to try to query the sender's keys. @@ -157,10 +158,12 @@ In other words, this approach would require all homeservers to keep a permanent record of all devices observed anywhere in the federation, at least for as long as there are undelivered to-device events from such devices. -Transparently: we have not significantly expolored this approach. We have a +Transparently: we have not significantly explored this approach. We have a working solution, and it is unclear that the advantages of this alternative approach outweigh the opportunity cost and delay in rollout of an important -security feature. +security feature. If, in future, the overhead of including the device keys +in the to-device messages is found to be significant, it would be worth +revisiting this. ## Security considerations From c7ff262541a90259b244f847124457e8881ca778 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Wed, 27 Nov 2024 18:06:37 +0000 Subject: [PATCH 11/12] device_keys -> sender_device_keys --- ...luding-device-keys-with-olm-encrypted-events.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/proposals/4147-including-device-keys-with-olm-encrypted-events.md b/proposals/4147-including-device-keys-with-olm-encrypted-events.md index e4876f1e7c3..72cb55471ed 100644 --- a/proposals/4147-including-device-keys-with-olm-encrypted-events.md +++ b/proposals/4147-including-device-keys-with-olm-encrypted-events.md @@ -57,8 +57,8 @@ is currently of the form: } ``` -We propose to add a new property: `device_keys`, which is a copy of what the -server would return in response to a +We propose to add a new property: `sender_device_keys`, which is a copy of what +the server would return in response to a [`/keys/query`](https://spec.matrix.org/v1.12/client-server-api/#post_matrixclientv3keysquery) request, as the device keys for the sender's device. In other words, the plaintext payload will now look something like: @@ -75,7 +75,7 @@ plaintext payload will now look something like: "keys": { "ed25519": "" }, - "device_keys": { + "sender_device_keys": { "algorithms": ["", ""], "user_id": "", "device_id": "", @@ -94,7 +94,7 @@ plaintext payload will now look something like: ``` If this property is present, the `keys`.`ed25519` property of the plaintext -payload must be the same as the `device_keys`.`keys`.`ed25519:` +payload must be the same as the `sender_device_keys`.`keys`.`ed25519:` property. If they differ, the recipient should discard the event. As the `keys` property is now redundant, it may be removed in a future version @@ -119,7 +119,7 @@ information to the user; that is left for the future. ### Minor variations -The `device_keys` property could be added to the cleartext. That is, it could +The `sender_device_keys` property could be added to the cleartext. That is, it could be added as a property to the `m.room.encrypted` event. This information is already public, as it is accessible from `/keys/query` (while the device is logged in), and does not need to be authenticated as it is protected by the @@ -129,14 +129,14 @@ including it in the encrypted payload, it leaves open the possibility of it replacing the `keys` property, which must be part of the encrypted payload to prevent an [unknown key-share attack](https://github.com/element-hq/element-web/issues/2215). -The `device_keys` property could be added to the cleartext by the sender's +The `sender_device_keys` property could be added to the cleartext by the sender's homeserver, rather than by the sending client. Possibly within an `unsigned` property, as that is where properties added by homeservers are customarily added. It is not clear what advantage there would be to having this information being added by the client. To mitigate the increased size of to-device events under this proposal, the -`device_keys` could be sent only in pre-key messages (Olm messages +`sender_device_keys` could be sent only in pre-key messages (Olm messages with `type: 0` in the `m.room.encrypted` event) — with the rationale that if the Olm message is a normal (non-pre-key) message, this means that the recipient has already decrypted a pre-key message that contains the From ca11f994c8454fbf31297e2aef054c13da9292ad Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Wed, 4 Dec 2024 21:44:11 +0000 Subject: [PATCH 12/12] event -> to-device message, in various places --- ...147-including-device-keys-with-olm-encrypted-events.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/proposals/4147-including-device-keys-with-olm-encrypted-events.md b/proposals/4147-including-device-keys-with-olm-encrypted-events.md index 72cb55471ed..9a2f46615b7 100644 --- a/proposals/4147-including-device-keys-with-olm-encrypted-events.md +++ b/proposals/4147-including-device-keys-with-olm-encrypted-events.md @@ -1,4 +1,4 @@ -# MSC4147: Including device keys with Olm-encrypted events +# MSC4147: Including device keys with Olm-encrypted to-device messages Summary: a proposal to ensure that messages sent from a short-lived (but genuine) device can be securely distinguished from those sent from a spoofed @@ -38,7 +38,7 @@ recipient does not have to try to query the sender's keys. ## Proposal -The plaintext payload of `m.room.encrypted` events encrypted with the [`m.olm.v1.curve25519-aes-sha2` encryption +The plaintext payload of to-device messages encrypted with the [`m.olm.v1.curve25519-aes-sha2` encryption algorithm](https://spec.matrix.org/v1.12/client-server-api/#molmv1curve25519-aes-sha2) is currently of the form: @@ -102,8 +102,8 @@ of the Matrix specification. ## Potential issues -Adding this property will increase the size of the event. We found it -increased the length of a typical `m.room_key` message from about 1400 to 2400 +Adding this property will increase the size of the to-device message. We found it +increased the length of a typical encrypted `m.room_key` message from about 1400 to 2400 bytes (a 70% increase). This will require increased storage on the recipient homeserver, and increase bandwidth for both senders and recipients. See [Alternatives](#alternatives) for discussion of mitigation strategies.