MSC4147: Including device keys with Olm-encrypted events

Signed-off-by: Johannes Marbach <n0-0ne+github@mailbox.org>

content/client-server-api/modules/end_to_end_encryption.md

@@ -1512,20 +1512,7 @@ message.
 
 The plaintext payload is of the form:
 
-```json
+{{% definition path="api/client-server/definitions/olm_payload" %}}
-{
-  "type": "<type of the plaintext event>",
-  "content": "<content for the plaintext event>",
-  "sender": "<sender_user_id>",
-  "recipient": "<recipient_user_id>",
-  "recipient_keys": {
-    "ed25519": "<our_ed25519_key>"
-  },
-  "keys": {
-    "ed25519": "<sender_ed25519_key>"
-  }
-}
-```
 
 The type and content of the plaintext message event are given in the
 payload.
@@ -1536,15 +1523,19 @@ claiming to have sent messages which they didn't. `sender` must
 correspond to the user who sent the event, `recipient` to the local
 user, and `recipient_keys` to the local ed25519 key.
 
-Clients must confirm that the `sender_key` property in the cleartext
+Clients must ensure that the sending device owns the private part of
-`m.room.encrypted` event body, and the `keys.ed25519` property in the
+the ed25519 key it claims to have in the Olm payload. This is crucial
-decrypted plaintext, match the keys returned by
+when the ed25519 key corresponds to a verified device. To perform
-[`/keys/query`](#post_matrixclientv3keysquery) for
+this check, clients MUST confirm that the `sender_key` property in the
-the given user. Clients must also verify the signature of the keys from the
+cleartext `m.room.encrypted` event body, and the `keys.ed25519` property
-`/keys/query` response. Without this check, a client cannot be sure that
+in the decrypted plaintext, match the keys under the `sender_device_keys`
-the sender device owns the private part of the ed25519 key it claims to
+property. Additionally, clients MUST also verify the signature of the keys.
-have in the Olm payload. This is crucial when the ed25519 key corresponds
+If `sender_device_keys` is absent, clients MUST retrieve the sender's
-to a verified device.
+keys from [`/keys/query`](#post_matrixclientv3keysquery) instead. This
+will not allow them to verify key ownership if the sending device was
+logged out or had its keys reset since sending the event. Therefore,
+clients MUST populate the `sender_device_keys` property when sending
+events themselves.
 
 If a client has multiple sessions established with another device, it
 should use the session from which it last received and successfully

data/api/client-server/definitions/olm_payload.yaml

@@ -0,0 +1,87 @@
+# Copyright 2025 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.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+type: object
+title: OlmPayload
+description: |-
+  The plaintext payload of Olm message events.
+properties:
+  type:
+    type: string
+    description: The type of the event.
+  content:
+    type: object
+    description: The event content.
+  sender:
+    type: string
+    description: The user ID of the event sender.
+  recipient:
+    type: string
+    description: The user ID of the intended event recipient.
+  recipient_keys:
+    description: The recipient's signing keys of the encrypted event.
+    $ref: "#/components/schemas/SigningKeys"
+  keys:
+    $ref: "#/components/schemas/SigningKeys"
+    description: The sender's signing keys of the encrypted event.
+  sender_device_keys:
+    $ref: device_keys.yaml 
+    description: The sender's device keys.
+required:
+  - type
+  - content
+  - sender
+  - recipient
+  - recipient_keys
+  - keys
+components:
+  schemas:
+    SigningKeys:
+      type: object
+      title: SigningKeys
+      description: Public keys used for an `m.olm.v1.curve25519-aes-sha2` event.
+      properties:
+        ed25519:
+          type: string
+          description: The Ed25519 public key encoded using unpadded base64.
+      required:
+        - ed25519
+example: {
+  "type": "<type of the plaintext event>",
+  "content": "<content for the plaintext event>",
+  "sender": "<sender_user_id>",
+  "recipient": "<recipient_user_id>",
+  "recipient_keys": {
+    "ed25519": "<our_ed25519_key>"
+  },
+  "keys": {
+    "ed25519": "<sender_ed25519_key>"
+  },
+  "sender_device_keys": {
+    "algorithms": ["<supported>", "<algorithms>"],
+    "user_id": "<user_id>",
+    "device_id": "<device_id>",
+    "keys": {
+      "ed25519:<device_id>": "<sender_ed25519_key>",
+      "curve25519:<device_id>": "<sender_curve25519_key>"
+    },
+    "signatures": {
+      "<user_id>": {
+        "ed25519:<device_id>": "<device_signature>",
+        "ed25519:<ssk_id>": "<ssk_signature>",
+      }
+    }
+  }
+}