From 191450ea73607d3d98d3c1e611b340f834de2303 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Tue, 4 Oct 2022 17:49:36 -0400 Subject: [PATCH 1/5] add in-room m.key.verification.request msgtype --- .../modules/end_to_end_encryption.md | 15 +++-- .../modules/instant_messaging.md | 4 +- ...om.message$m.key.verification.request.yaml | 19 ++++++ .../schema/m.key.verification.request.yaml | 4 +- ...om.message$m.key.verification.request.yaml | 67 +++++++++++++++++++ layouts/shortcodes/msgtypes.html | 5 +- 6 files changed, 104 insertions(+), 10 deletions(-) create mode 100644 data/event-schemas/examples/m.room.message$m.key.verification.request.yaml create mode 100644 data/event-schemas/schema/m.room.message$m.key.verification.request.yaml 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 10f21e86..1c310e78 100644 --- a/content/client-server-api/modules/end_to_end_encryption.md +++ b/content/client-server-api/modules/end_to_end_encryption.md @@ -434,11 +434,14 @@ shared by the other messages of that session. In general, verification operates as follows: -- Alice requests a key verification with Bob by sending an - `m.key.verification.request` event. This event indicates the verification - methods that Alice's client supports. (Note that "Alice" and "Bob" may in - fact be the same user, in the case where a user is verifying their own - devices.) +- Alice requests a key verification with Bob by sending an key verification + request event. If the verification is being requested in a room, this will + be an event with type `m.room.message` and `msgtype` + `m.key.verification.request`; if the verification is being requested using + to-device messaging, this will be an event with type + `m.key.verification.request`. This event indicates the verification methods + that Alice's client supports. (Note that "Alice" and "Bob" may in fact be the + same user, in the case where a user is verifying their own devices.) - Bob's client prompts Bob to accept the key verification. When Bob accepts the verification, Bob's client sends an `m.key.verification.ready` event. This event indicates the verification methods, corresponding to the @@ -562,6 +565,8 @@ in this specification must be under the `m.key.verification` namespace and any other event types must be namespaced according to the Java package naming convention. +{{% event event="m.room.message$m.key.verification.request" %}} + {{% event event="m.key.verification.request" %}} {{% event event="m.key.verification.ready" %}} diff --git a/content/client-server-api/modules/instant_messaging.md b/content/client-server-api/modules/instant_messaging.md index 47440cd3..a3676e3a 100644 --- a/content/client-server-api/modules/instant_messaging.md +++ b/content/client-server-api/modules/instant_messaging.md @@ -29,8 +29,8 @@ optional keys, as outlined below. If a client cannot display the given instead. Some message types support HTML in the event content that clients should -prefer to display if available. Currently `m.text`, `m.emote`, and -`m.notice` support an additional `format` parameter of +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`. diff --git a/data/event-schemas/examples/m.room.message$m.key.verification.request.yaml b/data/event-schemas/examples/m.room.message$m.key.verification.request.yaml new file mode 100644 index 00000000..54aae86c --- /dev/null +++ b/data/event-schemas/examples/m.room.message$m.key.verification.request.yaml @@ -0,0 +1,19 @@ +{ + "event_id": "$143273582443PhrSn:example.org", + "origin_server_ts": 1432735824653, + "room_id": "!jEsUZKDJdhlrceRyVU:example.org", + "sender": "@alice:example.org", + "type": "m.room.message", + "unsigned": { + "age": 1234 + }, + "content": { + "body": "Alice is requesting to verify your device, but your client does not support verification, so you may need to use a different verification method.", + "from_device": "AliceDevice2", + "methods": [ + "m.sas.v1" + ], + "to": "@bob:example.org", + "msgtype": "m.key.verification.request" + } +} diff --git a/data/event-schemas/schema/m.key.verification.request.yaml b/data/event-schemas/schema/m.key.verification.request.yaml index 7732cf38..76ba618d 100644 --- a/data/event-schemas/schema/m.key.verification.request.yaml +++ b/data/event-schemas/schema/m.key.verification.request.yaml @@ -3,7 +3,9 @@ allOf: - $ref: core-event-schema/event.yaml description: |- - Requests a key verification with another user's devices. + Requests a key verification using to-device messaging. When requesting a key + verification in a room, a `m.room.message` should be used, with + [`m.key.verification.request`](#mroommessagemkeyverificationrequest) as msgtype. properties: content: properties: diff --git a/data/event-schemas/schema/m.room.message$m.key.verification.request.yaml b/data/event-schemas/schema/m.room.message$m.key.verification.request.yaml new file mode 100644 index 00000000..4eb4483a --- /dev/null +++ b/data/event-schemas/schema/m.room.message$m.key.verification.request.yaml @@ -0,0 +1,67 @@ +--- +allOf: + - $ref: core-event-schema/room_event.yaml +description: + Requests a key verification in a room. When requesting a key verification + using to-device messaging, an event with type [`m.key.verification.request`](#mkeyverificationrequest) + should be used. +properties: + content: + properties: + body: + type: string + description: |- + a fallback message to alert users that their client does not support + the key verification framework, and that they should use a different method + to verify keys. For example, "Alice is requesting to verify keys with you. + However, your client does not support this method, so you will need to use + the legacy method of key verification." + + Clients that do support the key verification framework should hide the body + and instead present the user with an interface to accept or reject the key + verification. + format: + description: |- + The format used in the `formatted_body`. Currently only + `org.matrix.custom.html` is supported. + type: string + formatted_body: + description: |- + The formatted version of the `body`. This is required if `format` is + specified. As with the `body`, clients that do support the key + verification framework should hide the formatted body and instead + present the user with an interface to accept or reject the key + verification. + type: string + from_device: + type: string + description: |- + The device ID which is initiating the request. + methods: + type: array + description: |- + The verification methods supported by the sender. + items: + type: string + to: + description: |- + The user that the verification request is intended for. Users who + are not named in this field and who did not send this event should + ignore all other events that have an `m.reference` relationship with + this event. + type: string + msgtype: + enum: + - m.key.verification.request + type: string + required: + - from_device + - methods + - msgtype + type: object + type: + enum: + - m.room.message + type: string +title: KeyVerification +type: object diff --git a/layouts/shortcodes/msgtypes.html b/layouts/shortcodes/msgtypes.html index ccdfda5f..ba731111 100644 --- a/layouts/shortcodes/msgtypes.html +++ b/layouts/shortcodes/msgtypes.html @@ -16,9 +16,10 @@ {{ $msgtypes := (slice "m.room.message$m.text" "m.room.message$m.emote" "m.room.message$m.notice" "m.room.message$m.image" "m.room.message$m.file") }} {{/* - It excludes `m.room.message$m.server_notice` + It excludes `m.room.message$m.server_notice` and `m.room.message$m.key.verification.request` + since they are in their own modules. */}} -{{ $excluded := slice "m.room.message$m.server_notice" }} +{{ $excluded := slice "m.room.message$m.server_notice" "m.room.message$m.key.verification.request" }} {{/* It then adds any other events that start with `m.room.message`. From 9d8e17fb226fbde00d245bd6ed78799510851bbe Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Tue, 4 Oct 2022 17:53:15 -0400 Subject: [PATCH 2/5] add changelog --- changelogs/client_server/newsfragments/1271.feature | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/1271.feature diff --git a/changelogs/client_server/newsfragments/1271.feature b/changelogs/client_server/newsfragments/1271.feature new file mode 100644 index 00000000..8d3cb3f8 --- /dev/null +++ b/changelogs/client_server/newsfragments/1271.feature @@ -0,0 +1 @@ +Add missing documentation for `m.key.verification.request` msgtype for in-room verification. From c0d54ab4d9a8a0fd97f1effadc49cd987a0aa857 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Wed, 12 Oct 2022 09:52:04 -0400 Subject: [PATCH 3/5] Apply suggestions from code review Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --- content/client-server-api/modules/end_to_end_encryption.md | 2 +- .../schema/m.room.message$m.key.verification.request.yaml | 3 ++- 2 files changed, 3 insertions(+), 2 deletions(-) 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 1c310e78..51251b0d 100644 --- a/content/client-server-api/modules/end_to_end_encryption.md +++ b/content/client-server-api/modules/end_to_end_encryption.md @@ -434,7 +434,7 @@ shared by the other messages of that session. In general, verification operates as follows: -- Alice requests a key verification with Bob by sending an key verification +- Alice requests a key verification with Bob by sending a key verification request event. If the verification is being requested in a room, this will be an event with type `m.room.message` and `msgtype` `m.key.verification.request`; if the verification is being requested using diff --git a/data/event-schemas/schema/m.room.message$m.key.verification.request.yaml b/data/event-schemas/schema/m.room.message$m.key.verification.request.yaml index 4eb4483a..c0a0764c 100644 --- a/data/event-schemas/schema/m.room.message$m.key.verification.request.yaml +++ b/data/event-schemas/schema/m.room.message$m.key.verification.request.yaml @@ -11,7 +11,7 @@ properties: body: type: string description: |- - a fallback message to alert users that their client does not support + A fallback message to alert users that their client does not support the key verification framework, and that they should use a different method to verify keys. For example, "Alice is requesting to verify keys with you. However, your client does not support this method, so you will need to use @@ -58,6 +58,7 @@ properties: - from_device - methods - msgtype + - to type: object type: enum: From 76bf60a12fed9d4395c9329554986b0dbada5aab Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Wed, 12 Oct 2022 15:46:03 -0400 Subject: [PATCH 4/5] set the title of m.key.verification.request in-room event --- content/client-server-api/modules/end_to_end_encryption.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 51251b0d..6f2d00b2 100644 --- a/content/client-server-api/modules/end_to_end_encryption.md +++ b/content/client-server-api/modules/end_to_end_encryption.md @@ -565,7 +565,7 @@ in this specification must be under the `m.key.verification` namespace and any other event types must be namespaced according to the Java package naming convention. -{{% event event="m.room.message$m.key.verification.request" %}} +{{% event event="m.room.message$m.key.verification.request" title="`m.room.message` with `msgtype: m.key.verification.request`" %}} {{% event event="m.key.verification.request" %}} From f76ff365456ea38d5d0082284e97e13b70221abb Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Wed, 12 Oct 2022 16:32:00 -0400 Subject: [PATCH 5/5] add links --- .../modules/end_to_end_encryption.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) 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 6f2d00b2..0fb74931 100644 --- a/content/client-server-api/modules/end_to_end_encryption.md +++ b/content/client-server-api/modules/end_to_end_encryption.md @@ -436,20 +436,20 @@ In general, verification operates as follows: - Alice requests a key verification with Bob by sending a key verification request event. If the verification is being requested in a room, this will - be an event with type `m.room.message` and `msgtype` - `m.key.verification.request`; if the verification is being requested using + be an event with type [`m.room.message` and `msgtype: + m.key.verification.request`](#mroommessagemkeyverificationrequest); if the verification is being requested using to-device messaging, this will be an event with type - `m.key.verification.request`. This event indicates the verification methods + [`m.key.verification.request`](#mkeyverificationrequest). This event indicates the verification methods that Alice's client supports. (Note that "Alice" and "Bob" may in fact be the same user, in the case where a user is verifying their own devices.) - Bob's client prompts Bob to accept the key verification. When Bob accepts - the verification, Bob's client sends an `m.key.verification.ready` event. + the verification, Bob's client sends an [`m.key.verification.ready`](#mkeyverificationready) event. This event indicates the verification methods, corresponding to the verification methods supported by Alice's client, that Bob's client supports. - Alice's or Bob's devices allow their users to select one of the verification methods supported by both devices to use for verification. When Alice or Bob selects a verification method, their device begins the verification by - sending an `m.key.verification.start` event, indicating the selected + sending an [`m.key.verification.start`](#mkeyverificationstart) event, indicating the selected verification method. Note that if there is only one verification method in common between the devices then the receiver's device (Bob) can auto-select it. @@ -457,11 +457,11 @@ In general, verification operates as follows: verification method. This could involve their clients exchanging messages, Alice and Bob exchanging information out-of-band, and/or Alice and Bob interacting with their devices. -- Alice's and Bob's clients send `m.key.verification.done` events to indicate +- Alice's and Bob's clients send [`m.key.verification.done`](#mkeyverificationdone) events to indicate that the verification was successful. Verifications can be cancelled by either device at any time by sending an -`m.key.verification.cancel` event with a `code` field that indicates the reason +[`m.key.verification.cancel`](#mkeyverificationcancel) event with a `code` field that indicates the reason it was cancelled. When using to-device messages, Alice may not know which of Bob's devices to