diff --git a/changelogs/client_server/newsfragments/1629.clarification b/changelogs/client_server/newsfragments/1629.clarification new file mode 100644 index 00000000..81ed5aaa --- /dev/null +++ b/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. \ No newline at end of file diff --git a/changelogs/client_server/newsfragments/1719.clarification b/changelogs/client_server/newsfragments/1719.clarification new file mode 100644 index 00000000..031e1e41 --- /dev/null +++ b/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. diff --git a/changelogs/client_server/newsfragments/1720.clarification b/changelogs/client_server/newsfragments/1720.clarification new file mode 100644 index 00000000..e8c8a623 --- /dev/null +++ b/changelogs/client_server/newsfragments/1720.clarification @@ -0,0 +1 @@ +Clarify how to perform the ECDH exchange in step 12 of the SAS process. diff --git a/changelogs/client_server/newsfragments/1731.feature b/changelogs/client_server/newsfragments/1731.feature new file mode 100644 index 00000000..f4561bf3 --- /dev/null +++ b/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). \ No newline at end of file diff --git a/content/client-server-api/modules/end_to_end_encryption.md b/content/client-server-api/modules/end_to_end_encryption.md index 880082bb..6c3bbbea 100644 --- a/content/client-server-api/modules/end_to_end_encryption.md +++ b/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 - Diffie-Hellman - (*ECDH(KAprivate*, *KBpublic*)), - using the result as the shared secret. +12. Both Alice's and Bob's devices perform an Elliptic-curve Diffie-Hellman using + their private ephemeral key, and the other device's ephemeral public key + (*ECDH(KAprivate*, *KBpublic*) + for Alice's device and + *ECDH(KBprivate*, *KApublic*) + 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, - followed by `|`. + the device which sent the `m.key.verification.start` message, encoded as + 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, - followed by `|`. + the device which sent the `m.key.verification.accept` message, encoded as + unpadded base64, followed by `|`. - The `transaction_id` being used. When the `key_agreement_protocol` is the deprecated method `curve25519`, diff --git a/content/client-server-api/modules/instant_messaging.md b/content/client-server-api/modules/instant_messaging.md index 28b627c2..485a0749 100644 --- a/content/client-server-api/modules/instant_messaging.md +++ b/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 -`org.matrix.custom.html`. When this field is present, a `formatted_body` -with the HTML must be provided. The plain text version of the HTML -should be provided in the `body`. +`m.image`, `m.file`, `m.audio`, `m.video` and `m.key.verification.request` +support an additional `format` parameter of `org.matrix.custom.html`. When this +field is present, a `formatted_body` with the HTML must be provided. The plain +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 cat 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 diff --git a/data/event-schemas/schema/m.room.message$m.audio.yaml b/data/event-schemas/schema/m.room.message$m.audio.yaml index 6cf742e4..825419bd 100644 --- a/data/event-schemas/schema/m.room.message$m.audio.yaml +++ b/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: diff --git a/data/event-schemas/schema/m.room.message$m.file.yaml b/data/event-schemas/schema/m.room.message$m.file.yaml index af181964..8e269366 100644 --- a/data/event-schemas/schema/m.room.message$m.file.yaml +++ b/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 diff --git a/data/event-schemas/schema/m.room.message$m.image.yaml b/data/event-schemas/schema/m.room.message$m.image.yaml index 91985ed0..15bdeda4 100644 --- a/data/event-schemas/schema/m.room.message$m.image.yaml +++ b/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 diff --git a/data/event-schemas/schema/m.room.message$m.video.yaml b/data/event-schemas/schema/m.room.message$m.video.yaml index e3b782b8..75752534 100644 --- a/data/event-schemas/schema/m.room.message$m.video.yaml +++ b/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: