Merge branch 'main' into msc4077

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

changelogs/client_server/newsfragments/1629.clarification

@@ -0,0 +1 @@
+The [strike](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/strike) element is deprecated in the HTML spec. Clients should prefer [s](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/s) instead.

changelogs/client_server/newsfragments/1719.clarification

@@ -0,0 +1 @@
+Clarify that the HKDF calculation for SAS uses base64-encoded keys rather than the raw key bytes.

changelogs/client_server/newsfragments/1720.clarification

@@ -0,0 +1 @@
+Clarify how to perform the ECDH exchange in step 12 of the SAS process.

changelogs/client_server/newsfragments/1731.feature

@@ -0,0 +1 @@
+Use the `body` field as media caption, as per [MSC2530](https://github.com/matrix-org/matrix-spec-proposals/pull/2530).

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

@@ -660,10 +660,12 @@ The process between Alice and Bob verifying each other would be:
 11. Alice's device receives Bob's message and verifies the commitment
     hash from earlier matches the hash of the key Bob's device just sent
     and the content of Alice's `m.key.verification.start` message.
-12. Both Alice and Bob's devices perform an Elliptic-curve
+12. Both Alice's and Bob's devices perform an Elliptic-curve Diffie-Hellman using
-    Diffie-Hellman
+    their private ephemeral key, and the other device's ephemeral public key
-    (*ECDH(K<sub>A</sub><sup>private</sup>*, *K<sub>B</sub><sup>public</sup>*)),
+    (*ECDH(K<sub>A</sub><sup>private</sup>*, *K<sub>B</sub><sup>public</sup>*)
-    using the result as the shared secret.
+    for Alice's device and
+    *ECDH(K<sub>B</sub><sup>private</sup>*, *K<sub>A</sub><sup>public</sup>*)
+    for Bob's device), using the result as the shared secret.
 13. Both Alice and Bob's devices display a SAS to their users, which is
     derived from the shared key using one of the methods in this
     section. If multiple SAS methods are available, clients should allow
@@ -836,15 +838,15 @@ is the concatenation of:
 -   The Device ID of the device which sent the
     `m.key.verification.start` message, followed by `|`.
 -   The public key from the `m.key.verification.key` message sent by
-    the device which sent the `m.key.verification.start` message,
+    the device which sent the `m.key.verification.start` message, encoded as
-    followed by `|`.
+    unpadded base64, followed by `|`.
 -   The Matrix ID of the user who sent the `m.key.verification.accept`
     message, followed by `|`.
 -   The Device ID of the device which sent the
     `m.key.verification.accept` message, followed by `|`.
 -   The public key from the `m.key.verification.key` message sent by
-    the device which sent the `m.key.verification.accept` message,
+    the device which sent the `m.key.verification.accept` message, encoded as
-    followed by `|`.
+    unpadded base64, followed by `|`.
 -   The `transaction_id` being used.
 
 When the `key_agreement_protocol` is the deprecated method `curve25519`,

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

@@ -27,17 +27,25 @@ instead.
 
 Some message types support HTML in the event content that clients should
 prefer to display if available. Currently `m.text`, `m.emote`, `m.notice`,
-and `m.key.verification.request` support an additional `format` parameter of
+`m.image`, `m.file`, `m.audio`, `m.video` and `m.key.verification.request`
-`org.matrix.custom.html`. When this field is present, a `formatted_body`
+support an additional `format` parameter of `org.matrix.custom.html`. When this
-with the HTML must be provided. The plain text version of the HTML
+field is present, a `formatted_body` with the HTML must be provided. The plain
-should be provided in the `body`.
+text version of the HTML should be provided in the `body`.
+
+{{% boxes/note %}}
+{{% changed-in v="1.10" %}}
+In previous versions of the specification, the `format` and `formatted` fields
+were limited to `m.text`, `m.emote`, `m.notice`, and
+`m.key.verification.request`. This list is expanded to include `m.image`,
+`m.file`, `m.audio` and `m.video` for [media captions](#media-captions).
+{{% /boxes/note %}}
 
 Clients should limit the HTML they render to avoid Cross-Site Scripting,
 HTML injection, and similar attacks. The strongly suggested set of HTML
 tags to permit, denying the use and rendering of anything else, is:
 `font`, `del`, `h1`, `h2`, `h3`, `h4`, `h5`, `h6`, `blockquote`, `p`,
 `a`, `ul`, `ol`, `sup`, `sub`, `li`, `b`, `i`, `u`, `strong`, `em`,
-`strike`, `s`, `code`, `hr`, `br`, `div`, `table`, `thead`, `tbody`, `tr`,
+`s`, `code`, `hr`, `br`, `div`, `table`, `thead`, `tbody`, `tr`,
 `th`, `td`, `caption`, `pre`, `span`, `img`, `details`, `summary`.
 
 
@@ -335,6 +343,49 @@ to the media repository, then reference the `mxc://` URI in a markdown-style lin
 Clients SHOULD render spoilers differently with some sort of disclosure. For example, the
 client could blur the actual text and ask the user to click on it for it to be revealed.
 
+##### Media captions
+
+{{% added-in v="1.10" %}}
+
+Media messages, comprised of `m.image`, `m.file`, `m.audio` and `m.video`, can
+include a caption to convey additional information about the media.
+
+To send captions, clients MUST use the `filename` and the `body`, and optionally
+the `formatted_body` with the `org.matrix.custom.html` format, described above.
+
+If the `filename` is present, and its value is different than `body`, then
+`body` is considered to be a caption, otherwise `body` is a filename. `format`
+and `formatted_body` are only used for captions.
+
+{{% boxes/note %}}
+In previous versions of the specification, `body` was usually used to set the
+filename of the uploaded file, and `filename` was only present on `m.file` with
+the same purpose.
+{{% /boxes/note %}}
+
+An example of a media message with a caption is:
+
+```json
+{
+    "msgtype": "m.image",
+    "url": "mxc://example.org/abc123",
+    "filename": "dog.jpg",
+    "body": "this is a ~~cat~~ picture :3",
+    "format": "org.matrix.custom.html",
+    "formatted_body": "this is a <s>cat</s> picture :3",
+    "info": {
+        "w": 479,
+        "h": 640,
+        "mimetype": "image/jpeg",
+        "size": 27253
+    },
+    "m.mentions": {}
+}
+```
+
+Clients MUST render the caption alongside the media and SHOULD prefer its
+formatted representation.
+
 #### Server behaviour
 
 Homeservers SHOULD reject `m.room.message` events which don't have a

data/event-schemas/schema/m.room.message$m.audio.yaml

@@ -6,8 +6,29 @@ properties:
   content:
     properties:
       body:
-        description: "A description of the audio e.g. 'Bee Gees - Stayin' Alive', or some kind of content description for accessibility e.g. 'audio attachment'."
+        description: |-
+          If `filename` is not set or the value of both properties are
+          identical, this is the filename of the original upload. Otherwise,
+          this is a caption for the audio.
         type: string
+        x-changedInMatrixVersion:
+          "1.10": This property can act as a caption for the audio.
+      format:
+        description: |-
+          The format used in the `formatted_body`. Currently only
+          `org.matrix.custom.html` is supported.
+        type: string
+        x-addedInMatrixVersion: "1.10"
+      formatted_body:
+        description: |-
+          The formatted version of the `body`, when it acts as a caption. This
+          is required if `format` is specified.
+        type: string
+        x-addedInMatrixVersion: "1.10"
+      filename:
+        description: The original filename of the uploaded file.
+        type: string
+        x-addedInMatrixVersion: "1.10"
       info:
         description: Metadata for the audio clip referred to in `url`.
         properties:

data/event-schemas/schema/m.room.message$m.file.yaml

@@ -6,8 +6,25 @@ properties:
   content:
     properties:
       body:
-        description: A human-readable description of the file. This is recommended to be the filename of the original upload.
+        description: |-
+          If `filename` is not set or the value of both properties are
+          identical, this is the filename of the original upload. Otherwise,
+          this is a caption for the file.
         type: string
+        x-changedInMatrixVersion:
+          "1.10": This property can act as a caption for the file.
+      format:
+        description: |-
+          The format used in the `formatted_body`. Currently only
+          `org.matrix.custom.html` is supported.
+        type: string
+        x-addedInMatrixVersion: "1.10"
+      formatted_body:
+        description: |-
+          The formatted version of the `body`, when it acts as a caption. This
+          is required if `format` is specified.
+        type: string
+        x-addedInMatrixVersion: "1.10"
       filename:
         description: The original filename of the uploaded file.
         type: string

data/event-schemas/schema/m.room.message$m.image.yaml

@@ -6,8 +6,29 @@ properties:
   content:
     properties:
       body:
-        description: "A textual representation of the image. This could be the alt text of the image, the filename of the image, or some kind of content description for accessibility e.g. 'image attachment'."
+        description: |-
+          If `filename` is not set or the value of both properties are
+          identical, this is the filename of the original upload. Otherwise,
+          this is a caption for the image.
         type: string
+        x-changedInMatrixVersion:
+          "1.10": This property can act as a caption for the image.
+      format:
+        description: |-
+          The format used in the `formatted_body`. Currently only
+          `org.matrix.custom.html` is supported.
+        type: string
+        x-addedInMatrixVersion: "1.10"
+      formatted_body:
+        description: |-
+          The formatted version of the `body`, when it acts as a caption. This
+          is required if `format` is specified.
+        type: string
+        x-addedInMatrixVersion: "1.10"
+      filename:
+        description: The original filename of the uploaded file.
+        type: string
+        x-addedInMatrixVersion: "1.10"
       info:
         allOf:
           - $ref: core-event-schema/msgtype_infos/image_info.yaml

data/event-schemas/schema/m.room.message$m.video.yaml

@@ -6,8 +6,29 @@ properties:
   content:
     properties:
       body:
-        description: "A description of the video e.g. 'Gangnam style', or some kind of content description for accessibility e.g. 'video attachment'."
+        description: |-
+          If `filename` is not set or the value of both properties are
+          identical, this is the filename of the original upload. Otherwise,
+          this is a caption for the video.
         type: string
+        x-changedInMatrixVersion:
+          "1.10": This property can act as a caption for the video.
+      format:
+        description: |-
+          The format used in the `formatted_body`. Currently only
+          `org.matrix.custom.html` is supported.
+        type: string
+        x-addedInMatrixVersion: "1.10"
+      formatted_body:
+        description: |-
+          The formatted version of the `body`, when it acts as a caption. This
+          is required if `format` is specified.
+        type: string
+        x-addedInMatrixVersion: "1.10"
+      filename:
+        description: The original filename of the uploaded file.
+        type: string
+        x-addedInMatrixVersion: "1.10"
       info:
         description: Metadata about the video clip referred to in `url`.
         properties: