diff --git a/proposals/2366-key-verification-accept.md b/proposals/2366-key-verification-accept.md new file mode 100644 index 00000000000..bc355601ff9 --- /dev/null +++ b/proposals/2366-key-verification-accept.md @@ -0,0 +1,80 @@ +# Key verification flow additions: `m.key.verification.ready` and `m.key.verification.done` + +The current key verification framework is asymmetrical in that the user who +requests the verification is unable to select the key verification method. +This makes it harder for more experienced users who wish to guide less +experienced users through the verification process, especially if they are not +verifying in-person, but are using a trusted but remote channel of verification +(such as telephone or video conference). + +As an example, let us say that Alice is an experienced Matrix user and is +introducing Bob to the wonders of federated communications. Alice wants to +verify keys with Bob, so she clicks on the "Verify" button in her client on +Bob's profile (which sends a `m.key.verification.request` message to Bob). +Bob's device receives the verification request and prompts Bob to accept the +verification request. At this point, under the current framework, Bob is +responsible for choosing the verification method to use. However, with this +proposal, Bob would be able to just accept the verification request without +choosing a method, and allow Alice to choose the verification method. + +In addition, the current key verification framework does not have a method for +clients to signal to the other side that a key verification was successful. +Some clients may wish to wait until the other side has either confirmed a +successful verification or indicated an error before displaying the result of +the verification, in order to give the two users a consistent view of the +verification as a whole. + +## Proposal + +Two new event types are added to the [key verification +framework](https://matrix.org/docs/spec/client_server/r0.6.1#key-verification-framework) +when verifying in to-device messages. The new event +types are already described in [MSC2241 (Key verification in +DMs)](https://github.com/matrix-org/matrix-doc/pull/2241). This proposal adds +them to verifications in to-device messages. + +The first event type is `m.key.verification.ready`, which must be sent by the +target of the `m.key.verification.request` message, upon receipt of the +`m.key.verification.request` event. It has the fields: + +- `from_device`: the ID of the device that sent the `m.key.verification.ready` + message +- `methods`: an array of verification methods that the device supports + +It also has the usual `transaction_id` or `m.relates_to` fields for key +verification events, depending on whether it is sent as a to-device event +or an in-room event. + +After the `m.key.verification.ready` event is sent, either party can send an +`m.key.verification.start` event to begin the verification. If both parties +send an `m.key.verification.start` event, and they both specify the same +verification method, then the event sent by the user whose user ID is the +lexicographically smallest is used, and the other `m.key.verification.start` event is ignored. +In the case of a single user verifying two of their devices, the device ID is +compared instead. If both parties send an `m.key.verification.start` event, +but they specify different verification methods, the verification should be +cancelled with a `code` of `m.unexpected_message`. + +With to-device messages, previously the sender of the +`m.key.verification.request` message would send an `m.key.verification.cancel` +message to the recipient's other devices when it received an +`m.key.verification.start` event. With this new event, the sender of the +`m.key.verification.request` message should send an `m.key.verification.cancel` +message when it receives an `m.key.verification.ready` or +`m.key.verification.start` message, whichever comes first. + +The `m.key.verification.ready` event is required for verifications in both DMs +and in to-device messages to accept verifications requested using an +`m.key.verification.request` event. + +The second event type is `m.key.verification.done`, which has no fields other +than the usual `transaction_id` or `m.relates_to` field. This indicates that +the device has successfully completed its side of the verification. + +## Potential issues + +Clients that follow the Client-Server 0.6.0 spec may not expect an +`m.key.verification.ready` message in response to `m.key.verification.request`. +However to our knowledge, no clients implement `m.key.verification.request` in +this way yet -- to our knowledge, all clients that implement verification +implement this proposal.