Merge 2fca4789ca into 6b6d351ef8

Signed-off-by: Tulir Asokan <tulir@maunium.net>
Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>

changelogs/client_server/newsfragments/2301.feature

@@ -0,0 +1 @@
+Add recommendation about excluding non-cross-signed devices from encrypted conversations, as per [MSC4153](https://github.com/matrix-org/matrix-spec-proposals/pull/4153).

changelogs/server_server/newsfragments/2284.clarification

@@ -0,0 +1 @@
+Specify validation for PDUs passed to and returned from federation membership endpoints.

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

@@ -5,6 +5,91 @@ Matrix optionally supports end-to-end encryption, allowing rooms to be
 created whose conversation contents are not decryptable or interceptable
 on any of the participating homeservers.
 
+#### Recommended client behaviour
+
+{{% added-in v="1.18" %}}
+
+While clients are able to choose what encryption features they implement based
+on their threat model, this section recommends behaviours that will improve the
+overall user experience and security of encrypted conversations.
+
+While a user may be unable to [verify](#device-verification) every other user
+that they communicate with, or may be unaware of the need to verify other users,
+[cross-signing](#cross-signing) gives some measure of protection and so SHOULD
+be used where possible. In particular, clients SHOULD implement the following
+recommendations.
+
+* Clients SHOULD create new [cross-signing keys](#cross-signing) for users who
+  do not yet have cross-signing keys.
+* Clients SHOULD encourage users to set up their [Secret Storage](#storage) to
+  avoid needing to reset their cryptographic identity in case the user does not
+  have an existing device that can [share the secrets](#sharing) with the new
+  device. The user's Secret Storage SHOULD contain the user's cross-signing
+  private keys and the [key backup](#server-side-key-backups) decryption key
+  (if the user is using key backup). The user's Secret Storage SHOULD have a
+  [default key](#key-storage) (a key referred to by
+  `m.secret_storage.default_key`) that encrypts the private cross-signing keys
+  and key backup decryption key (if available).
+* Clients SHOULD encourage users to [cross-sign](#cross-signing) their devices.
+  This includes both when logging in a new device, and for existing devices.
+  Clients MAY even go so  far as to require cross-signing of devices by
+  preventing the user from using  the client until the device is cross-signed.
+  If the user cannot cross-sign their device (for example, if they have
+  forgotten their Secret Storage key), the client can allow users to reset their
+  [Secret Storage](#storage), cross-signing keys, and [key backup](#server-side-key-backups).
+* When Alice [verifies](#device-verification) Bob, the verification SHOULD
+  verify their [cross-signing keys](#cross-signing). Any flow between different
+  users that does not verify the users' cross-signing keys (it verifies only the
+  device keys) is deprecated.
+* Clients SHOULD flag when [cross-signing keys](#cross-signing) change. If
+  Alice's cross-signing keys change, Alice's own devices MUST alert her to this
+  fact, and prompt her to re-cross-sign those devices. If Bob is in an
+  encrypted room with Alice,  Bob's devices SHOULD inform him of Alice's key
+  change and SHOULD prevent him from sending an encrypted message to Alice
+  without acknowledging the change. Bob's clients may behave differently
+  depending on whether Bob had previously [verified](#device-verification)
+  Alice or not. For example, if Bob had previously verified Alice, and Alice's
+  keys change, Bob's client may require Bob to re-verify, or may display a more
+  aggressive warning.
+* Clients SHOULD NOT send encrypted [to-device](#send-to-device-messaging)
+  messages, such as [room keys](#sharing-keys-between-devices) or [secrets](#secrets)
+  (via [Secret Sharing](#sharing)), to [non-cross-signed](#cross-signing)
+  devices by default. Non-cross-signed devices don't provide any assurance that
+  the device belongs to the user, and server admins can trivially create new
+  devices for users. When sending room keys, clients can use a
+  [`m.room_key.withheld`](#mroom_keywithheld) message with a code of
+  `m.unverified` to indicate to the non-cross-signed device why it is not
+  receiving the room key.
+
+  Note that clients cannot selectively send room events only to cross-signed
+  devices. The only way to exclude non-cross-signed devices from encrypted
+  conversations is to not send the room keys so those devices won't be able to
+  decrypt the messages.
+* Similarly, messages sent from [non-cross-signed](#cross-signing) devices
+  cannot be trusted and SHOULD NOT be displayed to the user. Clients have no
+  assurance that encrypted messages sent from non-cross-signed devices were sent
+  by the user, rather than an impersonator.
+* Matrix clients MUST NOT consider non-cryptographic devices (devices which do
+  not have [device identity keys](#device-keys) uploaded to the homeserver) to
+  be equivalent to [non-cross-signed](#cross-signing) cryptographic devices for
+  purposes of enforcing E2EE policy. For example, clients SHOULD NOT warn nor
+  refuse to send messages due to the presence of non-cryptographic devices. For
+  all intents and purposes, non-cryptographic devices are a completely separate
+  concept and do not exist from the perspective of the cryptography layer since
+  they do not have identity keys, so it is impossible to send them decryption
+  keys.
+* Clients MAY make provisions for encrypted bridges. Some bridges are structured
+  in a way such that only one user controlled by the bridge (often called the
+  bridge bot) participates in encryption, and encrypted messages from other
+  bridge users are encrypted by the bridge bot. Thus encrypted messages sent by
+  one user could be encrypted by a [Megolm](#mmegolmv1aes-sha2) session sent by
+  a different user. Clients MAY accept such messages, provided the session
+  creator's device is [cross-signed](#cross-signing). However, the client MUST
+  annotate the message with a warning, unless the client has a way to check that
+  the bridge bot is permitted to encrypt messages on behalf of the user. Future
+  MSCs such as [MSC4350](https://github.com/matrix-org/matrix-spec-proposals/pull/4350)
+  may provide a secure way to allow such impersonation.
+
 #### Key Distribution
 
 Encryption and Authentication in Matrix is based around public-key
@@ -674,8 +759,11 @@ The process between Alice and Bob verifying each other would be:
     their devices if they match or not.
 15. Assuming they match, Alice and Bob's devices each calculate Message
     Authentication Codes (MACs) for:
-    * Each of the keys that they wish the other user to verify (usually their
+    * {{% changed-in v="1.18" %}} Each of the keys that they wish the other user
-      device ed25519 key and their master cross-signing key).
+      to verify (usually their device ed25519 key and their master cross-signing
+      key). The master cross-signing key SHOULD be included when two different
+      users are verifying each other. Verifying individual devices of other
+      users is deprecated.
     * The complete list of key IDs that they wish the other user to verify.
 
     The MAC calculation is defined [below](#mac-calculation).

content/server-server-api.md

@@ -868,8 +868,10 @@ selecting a resident from the candidate list, and using the
 enough information for the joining server to fill in the event.
 
 The joining server is expected to add or replace the `origin`,
-`origin_server_ts`, and `event_id` on the templated event received by
+`origin_server_ts`, and `event_id` on the templated event received by the
-the resident server. This event is then signed by the joining server.
+resident server. The joining server MUST also verify that the `type`, `room_id`,
+`sender`, `state_key` and `content.membership` fields have the expected values.
+This event is then signed by the joining server.
 
 To complete the join handshake, the joining server submits this new event
 to the resident server it used for `GET /make_join`, using the `PUT /send_join`

data/api/server-server/invites-v1.yaml

@@ -36,6 +36,28 @@ paths:
         Also note that if the remote homeserver is already in the room, it will receive the
         invite event twice; once through this endpoint, and again through a [federation
         transaction](/server-server-api/#transactions).
+
+        Servers MUST apply certain validation to ensure they don't accidentally sign non-invite
+        events from a malicious server. A specific error code is not mandated, but servers SHOULD
+        return `M_INVALID_PARAM` if:
+
+        * The invite event fails a [signature check](/server-server-api/#validating-hashes-and-signatures-on-received-events).
+        * The event type is not `m.room.member`.
+        * The `membership` field inside the event content is not `invite`.
+        * The event sender is not a user ID on the origin server.
+        * The `state_key` is not a user ID on the receiving server.
+
+        The `invite_room_state` has additional validation, which servers MAY apply to room versions
+        1 through 11 and SHOULD apply to all other room versions. As with the above errors, servers
+        SHOULD return `M_INVALID_PARAM` if:
+
+        * The `m.room.create` event is missing from `invite_room_state`.
+        * One or more entries in `invite_room_state` are not formatted according
+          to the room's version.
+        * One or more events fails a [signature check](/server-server-api/#validating-hashes-and-signatures-on-received-events).
+        * One or more events does not reside in the same room as the invite.
+          Note: Some room versions may require calculating the room ID for an
+          event rather than relying on the presence of `room_id`.
       operationId: sendInviteV1
       security:
         - signedRequest: []
@@ -83,8 +105,7 @@ paths:
                             MUST additionally be formatted according to the room version specification.
 
                             Servers might need to apply validation to the `invite_room_state` depending
-                            on room version. See the `400 M_MISSING_PARAM` error definition for more
+                            on room version. See endpoint description for more information.
-                            information.
 
                             Note that events have a different format depending on the room
                             version - check the [room version specification](/rooms) for
@@ -178,23 +199,7 @@ paths:
                   }
         "400":
           description: |-
-            The `M_MISSING_PARAM` error code is used to indicate one or more of
+            The request is invalid in some way.
-            the following:
-
-            * The `m.room.create` event is missing from `invite_room_state`.
-            * One or more entries in `invite_room_state` are not formatted according
-              to the room's version.
-            * One or more events fails a [signature check](/server-server-api/#validating-hashes-and-signatures-on-received-events).
-            * One or more events does not reside in the same room as the invite.
-              Note: Some room versions may require calculating the room ID for an
-              event rather than relying on the presence of `room_id`.
-
-            Servers MAY apply the validation above to room versions 1 through 11,
-            and SHOULD apply the validation above to all other room versions.
-
-            If `M_MISSING_PARAM` is returned and the request is associated with a
-            Client-Server API request, the Client-Server API request SHOULD fail
-            with a 5xx error rather than being passed through.
           content:
             application/json:
               schema:
@@ -202,7 +207,7 @@ paths:
               examples:
                 response:
                   value: {
-                    "errcode": "M_MISSING_PARAM",
+                    "errcode": "M_INVALID_PARAM",
                     "error": "Create event not among invite state entries."
                   }
 servers:

data/api/server-server/invites-v2.yaml

@@ -40,6 +40,28 @@ paths:
         Also note that if the remote homeserver is already in the room, it will receive the
         invite event twice; once through this endpoint, and again through a [federation
         transaction](/server-server-api/#transactions).
+
+        Servers MUST apply certain validation to ensure they don't accidentally sign non-invite
+        events from a malicious server. A specific error code is not mandated, but servers SHOULD
+        return `M_INVALID_PARAM` if:
+
+        * The invite event fails a [signature check](/server-server-api/#validating-hashes-and-signatures-on-received-events).
+        * The event type is not `m.room.member`.
+        * The `membership` field inside the event content is not `invite`.
+        * The event sender is not a user ID on the origin server.
+        * The `state_key` is not a user ID on the receiving server.
+
+        The `invite_room_state` has additional validation, which servers MAY apply to room versions
+        1 through 11 and SHOULD apply to all other room versions. As with the above errors, servers
+        SHOULD return `M_INVALID_PARAM` if:
+
+        * The `m.room.create` event is missing from `invite_room_state`.
+        * One or more entries in `invite_room_state` are not formatted according
+          to the room's version.
+        * One or more events fails a [signature check](/server-server-api/#validating-hashes-and-signatures-on-received-events).
+        * One or more events does not reside in the same room as the invite.
+          Note: Some room versions may require calculating the room ID for an
+          event rather than relying on the presence of `room_id`.
       operationId: sendInviteV2
       security:
         - signedRequest: []
@@ -84,8 +106,7 @@ paths:
                     MUST additionally be formatted according to the room version specification.
 
                     Servers might need to apply validation to the `invite_room_state` depending
-                    on room version. See the `400 M_MISSING_PARAM` error definition for more
+                    on room version. See the endpoint description for more information.
-                    information.
 
                     Note that events have a different format depending on the room
                     version - check the [room version specification](/rooms) for
@@ -154,22 +175,8 @@ paths:
             The error should be passed through to clients so that they
             may give better feedback to users.
 
-            The `M_MISSING_PARAM` error code is used to indicate one or more of
+            If `M_MISSING_PARAM` or `M_INVALID_PARAM` is returned and the request is associated
-            the following:
+            with a Client-Server API request, the Client-Server API request SHOULD fail
-
-            * The `m.room.create` event is missing from `invite_room_state`.
-            * One or more entries in `invite_room_state` are not formatted according
-              to the room's version.
-            * One or more events fails a [signature check](/server-server-api/#validating-hashes-and-signatures-on-received-events).
-            * One or more events does not reside in the same room as the invite.
-              Note: Some room versions may require calculating the room ID for an
-              event rather than relying on the presence of `room_id`.
-
-            Servers MAY apply the validation above to room versions 1 through 11,
-            and SHOULD apply the validation above to all other room versions.
-
-            If `M_MISSING_PARAM` is returned and the request is associated with a
-            Client-Server API request, the Client-Server API request SHOULD fail
             with a 5xx error rather than being passed through.
           content:
             application/json:

data/api/server-server/joins-v1.yaml

@@ -23,6 +23,17 @@ paths:
       description: |-
         Asks the receiving server to return information that the sending
         server will need to prepare a join event to get into the room.
+
+        Before signing the returned template and calling `/send_join`,
+        the sending server MUST verify that:
+
+        * the `room_id` is equal to the `roomId` path parameter.
+        * both the `sender` and `state_key` are equal to the `userId` path parameter.
+        * the `type` of the event is `m.room.member`.
+        * the `membership` field inside `content` is `join`.
+
+        In case any of the above checks fail, the response MUST be treated as malformed and
+        discarded. The caller MAY try to join through another server.
       operationId: makeJoin
       security:
         - signedRequest: []
@@ -36,7 +47,7 @@ paths:
             type: string
         - in: path
           name: userId
-          description: The user ID the join event will be for.
+          description: The user ID the join event will be for. This MUST be a user ID on the origin server.
           required: true
           example: "@someone:example.org"
           schema:
@@ -238,6 +249,15 @@ paths:
         **The request and response body here describe the common
         event fields in more detail and may be missing other required
         fields for a PDU.**
+
+        The receiving server MUST apply certain validation before accepting the event.
+        A specific error code is not mandated, but servers SHOULD return `M_INVALID_PARAM` if:
+
+        * The join event fails a [signature check](/server-server-api/#validating-hashes-and-signatures-on-received-events).
+        * The event type is not `m.room.member`.
+        * The `membership` field inside the event content is not `join`.
+        * The event sender is not a user ID on the origin server.
+        * The `state_key` is not equal to the `sender`.
       operationId: sendJoinV1
       security:
         - signedRequest: []
@@ -388,6 +408,33 @@ paths:
                       }
                     }
                   ]
+        "400":
+          description: |-
+            The request is invalid in some way.
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_INVALID_PARAM",
+                    "error": "Not a join event."
+                  }
+        "403":
+          description: |-
+            The room that the joining server is attempting to join does not permit the user
+            to join.
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_FORBIDDEN",
+                    "error": "You are not invited to this room"
+                  }
 servers:
   - url: "{protocol}://{hostname}{basePath}"
     variables:

data/api/server-server/joins-v2.yaml

@@ -38,6 +38,15 @@ paths:
         **The request and response body here describe the common
         event fields in more detail and may be missing other required
         fields for a PDU.**
+
+        The receiving server MUST apply certain validation before accepting the event.
+        A specific error code is not mandated, but servers SHOULD return `M_INVALID_PARAM` if:
+
+        * The join event fails a [signature check](/server-server-api/#validating-hashes-and-signatures-on-received-events).
+        * The event type is not `m.room.member`.
+        * The `membership` field inside the event content is not `join`.
+        * The event sender is not a user ID on the origin server.
+        * The `state_key` is not equal to the `sender`.
       operationId: sendJoinV2
       security:
         - signedRequest: []
@@ -247,6 +256,10 @@ paths:
             The error should be passed through to clients so that they
             may give better feedback to users.
 
+            If `M_MISSING_PARAM` or `M_INVALID_PARAM` is returned and the request is associated
+            with a Client-Server API request, the Client-Server API request SHOULD fail
+            with a 5xx error rather than being passed through.
+
             New in `v1.2`, the following error conditions might happen:
 
             If the room is [restricted](/client-server-api/#restricted-rooms)

data/api/server-server/knocks.yaml

@@ -23,6 +23,17 @@ paths:
       description: |-
         Asks the receiving server to return information that the sending
         server will need to prepare a knock event for the room.
+
+        Before signing the returned template and calling `/send_knock`,
+        the sending server MUST verify that:
+
+        * the `room_id` is equal to the `roomId` path parameter.
+        * both the `sender` and `state_key` are equal to the `userId` path parameter.
+        * the `type` of the event is `m.room.member`.
+        * the `membership` field inside `content` is `knock`.
+
+        In case any of the above checks fail, the response MUST be treated as malformed and
+        discarded. The caller MAY try to knock through another server.
       operationId: makeKnock
       security:
         - signedRequest: []
@@ -36,7 +47,7 @@ paths:
             type: string
         - in: path
           name: userId
-          description: The user ID the knock event will be for.
+          description: The user ID the knock event will be for. This MUST be a user ID on the origin server.
           required: true
           example: "@someone:example.org"
           schema:
@@ -204,6 +215,15 @@ paths:
         **The request and response body here describe the common
         event fields in more detail and may be missing other required
         fields for a PDU.**
+
+        The receiving server MUST apply certain validation before accepting the event.
+        A specific error code is not mandated, but servers SHOULD return `M_INVALID_PARAM` if:
+
+        * The knock event fails a [signature check](/server-server-api/#validating-hashes-and-signatures-on-received-events).
+        * The event type is not `m.room.member`.
+        * The `membership` field inside the event content is not `knock`.
+        * The event sender is not a user ID on the origin server.
+        * The `state_key` is not equal to the `sender`.
       operationId: sendKnock
       security:
         - signedRequest: []
@@ -330,6 +350,19 @@ paths:
                       "$ref": "./examples/invite_or_knock_state.json"
                     }
                   }
+        "400":
+          description: |-
+            The request is invalid in some way.
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_INVALID_PARAM",
+                    "error": "Not a knock event."
+                  }
         "403":
           description: |-
             The knocking server or user is not permitted to knock on the room, such as when the

data/api/server-server/leaving-v1.yaml

@@ -23,6 +23,17 @@ paths:
       description: |-
         Asks the receiving server to return information that the sending
         server will need to prepare a leave event to get out of the room.
+
+        Before signing the returned template and calling `/send_leave`,
+        the sending server MUST verify that:
+
+        * the `room_id` is equal to the `roomId` path parameter.
+        * both the `sender` and `state_key` are equal to the `userId` path parameter.
+        * the `type` of the event is `m.room.member`.
+        * the `membership` field inside `content` is `leave`.
+
+        In case any of the above checks fail, the response MUST be treated as malformed and
+        discarded. The caller MAY try to leave through another server.
       operationId: makeLeave
       security:
         - signedRequest: []
@@ -36,7 +47,7 @@ paths:
             type: string
         - in: path
           name: userId
-          description: The user ID the leave event will be for.
+          description: The user ID the leave event will be for. This MUST be a user ID on the origin server.
           required: true
           example: "@someone:example.org"
           schema:
@@ -153,6 +164,15 @@ paths:
         **The request and response body here describe the common
         event fields in more detail and may be missing other required
         fields for a PDU.**
+
+        The receiving server MUST apply certain validation before accepting the event.
+        A specific error code is not mandated, but servers SHOULD return `M_INVALID_PARAM` if:
+
+        * The leave event fails a [signature check](/server-server-api/#validating-hashes-and-signatures-on-received-events).
+        * The event type is not `m.room.member`.
+        * The `membership` field inside the event content is not `leave`.
+        * The event sender is not a user ID on the origin server.
+        * The `state_key` is not equal to the `sender`.
       operationId: sendLeaveV1
       security:
         - signedRequest: []
@@ -249,6 +269,19 @@ paths:
                     200,
                     {}
                   ]
+        "400":
+          description: |-
+            The request is invalid in some way.
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_INVALID_PARAM",
+                    "error": "Not a leave event."
+                  }
 servers:
   - url: "{protocol}://{hostname}{basePath}"
     variables:

data/api/server-server/leaving-v2.yaml

@@ -38,6 +38,15 @@ paths:
         **The request and response body here describe the common
         event fields in more detail and may be missing other required
         fields for a PDU.**
+
+        The receiving server MUST apply certain validation before accepting the event.
+        A specific error code is not mandated, but servers SHOULD return `M_INVALID_PARAM` if:
+
+        * The leave event fails a [signature check](/server-server-api/#validating-hashes-and-signatures-on-received-events).
+        * The event type is not `m.room.member`.
+        * The `membership` field inside the event content is not `leave`.
+        * The event sender is not a user ID on the origin server.
+        * The `state_key` is not equal to the `sender`.
       operationId: sendLeaveV2
       security:
         - signedRequest: []
@@ -134,6 +143,19 @@ paths:
               examples:
                 response:
                   value: {}
+        "400":
+          description: |-
+            The request is invalid in some way.
+          content:
+            application/json:
+              schema:
+                $ref: ../client-server/definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_INVALID_PARAM",
+                    "error": "Not a leave event."
+                  }
 servers:
   - url: "{protocol}://{hostname}{basePath}"
     variables: