matrix-spec-proposals/proposals/2366-key-verification-accept.md

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