Merge pull request #1271 from uhoreg/add_verification_request_msgtype

add in-room m.key.verification.request msgtype

Author: uhoreg

changelogs/client_server/newsfragments/1271.feature

@@ -0,0 +1 @@
+Add missing documentation for `m.key.verification.request` msgtype for in-room verification.

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

@@ -434,31 +434,34 @@ 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 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`](#mroommessagemkeyverificationrequest); if the verification is being requested using
+  to-device messaging, this will be an event with type
+  [`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.
 - Alice and Bob complete the verification as defined by the selected
   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
@@ -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" title="`m.room.message` with `msgtype: m.key.verification.request`" %}}
+
 {{% event event="m.key.verification.request" %}}
 
 {{% event event="m.key.verification.ready" %}}

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`.

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"
+    }
+}

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:

data/event-schemas/schema/m.room.message$m.key.verification.request.yaml

@@ -0,0 +1,68 @@
+---
+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
+      - to
+    type: object
+  type:
+    enum:
+      - m.room.message
+    type: string
+title: KeyVerification
+type: object

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`.