diff --git a/proposals/xxxx-e2e-verification-in-dms.md b/proposals/xxxx-e2e-verification-in-dms.md new file mode 100644 index 000000000..14b706dd2 --- /dev/null +++ b/proposals/xxxx-e2e-verification-in-dms.md @@ -0,0 +1,102 @@ +# Key verification in DMs + +Currently, key verification is done using `to_device` messages. However, since +`to_device` messages are not part of a timeline, there is no user-visible record +of the key verification. + +## Proposal + +The current [key verification +framework](https://matrix.org/docs/spec/client_server/r0.5.0#key-verification-framework) +will be replaced by a new framework that uses room messages rather than +`to_device` messages. Key verification messages will be sent in a [Direct +Messaging](https://matrix.org/docs/spec/client_server/r0.5.0#id185) room. If +there is no Direct Messaging room between the two users involved, the client +that initiates the key verification will create one. + +In this proposal, we use "Alice" to denote the user who initiates the key +verification, and "Bob" to denote the other user involved in the key +verification. + +### General framework + +#### Requesting a key verification + +To request a key verification, Alice will send an `m.room.message` event with the +following properties in its contents: + +- `body`: 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 +- `msgtype`: `m.key.verification.request` +- `methods`: the verification methods supported by Alice's client + +Key verifications will be identified by the event ID of the key verification +request event. + +Clients should ignore verification requests that have been accepted or cancelled. + +#### Accepting a key verification + +To accept a key verification, Bob will send an `m.key.verification.start` event +with the following properties in its contents: + +- `m.relates_to`: an object with the properties: + - `rel_type`: `m.key.verification` + - `event_id`: the event ID of the key verification request that is being + accepted +- `method`: the key verification method that is being used + +Clients should ignore `m.key.verification.start` events that correspond to +verification requests that it did not send. + +Clients may use this event as a place in the room's timeline do display +progress of the key verification process and to interact with the user as +necessary. + +#### Rejecting a key verification + +To reject a key verification, Bob will send an `m.key.verification.cancel` +event with the following properties in its contents: + +- `m.relates_to`: an object with the properties: + - `rel_type`: `m.key.verification` + - `event_id`: the event ID of the key verification that is being cancelled +- `body`: A human readable description of the `code`. The client should only + rely on this string if it does not understand the `code`. +- `code`: The error code for why the process/request was cancelled by the + user. The contents are the same as the `code` property of the currently + defined [`m.key.verification.cancel` to-device + event](https://matrix.org/docs/spec/client_server/r0.5.0#m-key-verification-cancel) + +This message may be sent at any point in the key verification process. Any +subsequent key verification messages relating to the same request are ignored. +However, this does not undo any verifications that have already been done. + +#### Other events + +Key verification methods may define their own event types, or extensions to the +above event types. All events sent as part of a key verification process +should have an `m.relates_to` property as defined for +`m.key.verification.accept` or `m.key.verification.cancel` events. + +Clients should ignore events with an `m.relates_to` that have a `rel_type` of +`m.key.verification` that refer to a verification where it is not the requester +nor the accepter. + +### SAS verification + +The messages used in SAS verification are the same as those currently defined, +except that instead of the `transaction_id` property, an `m.relates_to` +property, as defined above, is used instead. + +## Tradeoffs + + +## Potential issues + + +## Security considerations + + +## Conclusion