From 191450ea73607d3d98d3c1e611b340f834de2303 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Tue, 4 Oct 2022 17:49:36 -0400 Subject: [PATCH] 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`.