From 4f655247b047136970d06c826697130d7ad31fe6 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Wed, 21 Aug 2019 21:17:41 -0700 Subject: [PATCH 01/18] initial draft of verification in DMs --- proposals/xxxx-e2e-verification-in-dms.md | 102 ++++++++++++++++++++++ 1 file changed, 102 insertions(+) create mode 100644 proposals/xxxx-e2e-verification-in-dms.md diff --git a/proposals/xxxx-e2e-verification-in-dms.md b/proposals/xxxx-e2e-verification-in-dms.md new file mode 100644 index 00000000000..14b706dd2f0 --- /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 From fb724bc625f0e0ea89284eeb5463c3d732ecbec1 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Wed, 21 Aug 2019 21:22:03 -0700 Subject: [PATCH 02/18] rename to match PR number --- ...e2e-verification-in-dms.md => 2241-e2e-verification-in-dms.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename proposals/{xxxx-e2e-verification-in-dms.md => 2241-e2e-verification-in-dms.md} (100%) diff --git a/proposals/xxxx-e2e-verification-in-dms.md b/proposals/2241-e2e-verification-in-dms.md similarity index 100% rename from proposals/xxxx-e2e-verification-in-dms.md rename to proposals/2241-e2e-verification-in-dms.md From 0e6286f5d062361688bf6fcd2ff3e084866d33c2 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Sat, 24 Aug 2019 12:38:13 -0700 Subject: [PATCH 03/18] write more stuff --- proposals/2241-e2e-verification-in-dms.md | 58 +++++++++++++++++++++-- 1 file changed, 54 insertions(+), 4 deletions(-) diff --git a/proposals/2241-e2e-verification-in-dms.md b/proposals/2241-e2e-verification-in-dms.md index 14b706dd2f0..8f98ac2ec8d 100644 --- a/proposals/2241-e2e-verification-in-dms.md +++ b/proposals/2241-e2e-verification-in-dms.md @@ -1,8 +1,15 @@ # 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. +`to_device` messages are not part of a timeline, there is no user-visible +record of the key verification. + +As well, the current key verification framework does not provide any feedback +when interacting with clients that do not support it; if a client does not +support the key verification framework, there is no way for users to discover +this other than waiting for a while and noticing that nothing is happening. + +This proposal will solve both problems. ## Proposal @@ -27,9 +34,27 @@ 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 + to verify keys. The message should contain Bob's Matrix ID in order to + trigger a notification so that Bob's client will highlight the room for him, + making it easier for him to find it. For example, "@bob:example.com: 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. + + The event may also contain `format` and `formatted_body` properties as + described in the [m.room.message + msgtypes](https://matrix.org/docs/spec/client_server/r0.5.0#m-room-message-msgtypes) + section of the spec. Clients that support the key verification should + similarly hide these from the user. - `msgtype`: `m.key.verification.request` - `methods`: the verification methods supported by Alice's client +- `to`: Bob's Matrix ID. Users should only respond to verification requests if + they are named in this field. Users who are not named in this field and who + did not send this event should ignore all other events that have a + `m.key.verification` relationship with this event. Key verifications will be identified by the event ID of the key verification request event. @@ -67,7 +92,8 @@ event with the following properties in its contents: - `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) + event](https://matrix.org/docs/spec/client_server/r0.5.0#m-key-verification-cancel), + or as defined for specific key verification methods. 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. @@ -95,8 +121,32 @@ property, as defined above, is used instead. ## Potential issues +If a user wants to verify their own device, this will require the creation of a +Direct Messaging room with themselves. + +Direct Messaging rooms could have end-to-end encryption enabled, and some +clients can be configured to only send decryption keys to verified devices. +Key verification messages should be granted an exception to this (so that +decryption keys are sent to all of the target user's devices), or should be +sent unencrypted, so that unverified devices will be able to be verified. + +Users might have multiple Direct Messaging rooms with other users. In this +case, clients will need to prompt the user to select the room in which they +want to perform the verification. ## Security considerations +Key verification is subject to the room's visibility settings, and may be +visible to other users in the room. However, key verification does not rely on +secrecy, so this will no affect the security of the key verification. This may +reveal to others in the room that Alice and Bob know each other, but this is +already revealed by the fact that they share a Direct Messaging room. + +This framework allows users to see what key verifications they have performed +in the past. However, since key verification messages are not secured, this +should not be considered as authoritative. ## Conclusion + +By using room messages to perform key verification rather than `to_device` +messages, the user experience of key verification can be improved. From 0007498b4ca47a9640def3dc3ea395ddb34c0cfb Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Thu, 5 Sep 2019 11:54:33 -0400 Subject: [PATCH 04/18] remove empty tradeoffs section --- proposals/2241-e2e-verification-in-dms.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/proposals/2241-e2e-verification-in-dms.md b/proposals/2241-e2e-verification-in-dms.md index 8f98ac2ec8d..3663dfef349 100644 --- a/proposals/2241-e2e-verification-in-dms.md +++ b/proposals/2241-e2e-verification-in-dms.md @@ -116,9 +116,6 @@ 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 If a user wants to verify their own device, this will require the creation of a From e19fca7d54ec6716e6ebce66b19559e86ebcf751 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Wed, 25 Sep 2019 15:31:01 -0400 Subject: [PATCH 05/18] make some fixes, add a clarification, add a message to indicate completion --- proposals/2241-e2e-verification-in-dms.md | 29 +++++++++++++++++++++-- 1 file changed, 27 insertions(+), 2 deletions(-) diff --git a/proposals/2241-e2e-verification-in-dms.md b/proposals/2241-e2e-verification-in-dms.md index 3663dfef349..e21976e9394 100644 --- a/proposals/2241-e2e-verification-in-dms.md +++ b/proposals/2241-e2e-verification-in-dms.md @@ -67,7 +67,7 @@ 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` + - `rel_type`: `m.reference` - `event_id`: the event ID of the key verification request that is being accepted - `method`: the key verification method that is being used @@ -85,7 +85,7 @@ 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` + - `rel_type`: `m.reference` - `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`. @@ -99,6 +99,20 @@ 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. +#### Concluding a key verification + +When the other user's key is verified and no more messages are expected, each +party will send an `m.key.verification.done` event with the following +properties in its contents: + +- `m.relates_to`: an object with the properties: + - `rel_type`: `m.reference` + - `event_id`: the event ID of the key verification that is being cancelled + +This provides a record within the room of the result of the verification. + +Any subsequent key verification messages relating to the same request are ignored. + #### Other events Key verification methods may define their own event types, or extensions to the @@ -116,6 +130,17 @@ 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. +## Alternatives + +Messages sent by the verification methods, after the initial key verification +request message, could be sent as to-device messages. The +`m.key.verification.start`, `m.key.verification.cancel`, and +`m.key.verification.done` messages must be still be sent in the room, as the +`m.key.verification.start` notifies the sender's other devices that the request +has been acknowledged, and the `m.key.verification.cancel` and +`m.key.verification.done` provide a record of the status of the key +verification. + ## Potential issues If a user wants to verify their own device, this will require the creation of a From 7469198d8b900f8acd8a682182f8134536c1efcc Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Tue, 8 Oct 2019 16:19:39 -0400 Subject: [PATCH 06/18] add from_device fields and a FIXME --- proposals/2241-e2e-verification-in-dms.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/proposals/2241-e2e-verification-in-dms.md b/proposals/2241-e2e-verification-in-dms.md index e21976e9394..f049540ca74 100644 --- a/proposals/2241-e2e-verification-in-dms.md +++ b/proposals/2241-e2e-verification-in-dms.md @@ -55,6 +55,8 @@ following properties in its contents: they are named in this field. Users who are not named in this field and who did not send this event should ignore all other events that have a `m.key.verification` relationship with this event. +- `from_device`: Alice's device ID. This is required since some verification + methods may use the device IDs as part of the verification process. Key verifications will be identified by the event ID of the key verification request event. @@ -66,11 +68,16 @@ Clients should ignore verification requests that have been accepted or cancelled To accept a key verification, Bob will send an `m.key.verification.start` event with the following properties in its contents: +TODO: MSC1849 may use `m.relationship` rather than `m.relates_to`, in which +case this proposal should follow suit. + - `m.relates_to`: an object with the properties: - `rel_type`: `m.reference` - `event_id`: the event ID of the key verification request that is being accepted - `method`: the key verification method that is being used +- `from_device`: Bob's device ID. This is required since some verification + methods may use the device IDs as part of the verification process. Clients should ignore `m.key.verification.start` events that correspond to verification requests that it did not send. From ab3ed738e4b49fec76f0aecca4b210bc7afe57f2 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Tue, 8 Oct 2019 16:27:53 -0400 Subject: [PATCH 07/18] drop the recommendation that requests highlight the user --- proposals/2241-e2e-verification-in-dms.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/proposals/2241-e2e-verification-in-dms.md b/proposals/2241-e2e-verification-in-dms.md index f049540ca74..9d53a29014b 100644 --- a/proposals/2241-e2e-verification-in-dms.md +++ b/proposals/2241-e2e-verification-in-dms.md @@ -34,11 +34,9 @@ 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. The message should contain Bob's Matrix ID in order to - trigger a notification so that Bob's client will highlight the room for him, - making it easier for him to find it. For example, "@bob:example.com: 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." + 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 From 1f1d22f66706e77026920ea2936f663d2cdb9d8e Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Tue, 8 Oct 2019 16:46:15 -0400 Subject: [PATCH 08/18] fix a couple of missed m.reference changes --- proposals/2241-e2e-verification-in-dms.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/2241-e2e-verification-in-dms.md b/proposals/2241-e2e-verification-in-dms.md index 9d53a29014b..ea813fdb27f 100644 --- a/proposals/2241-e2e-verification-in-dms.md +++ b/proposals/2241-e2e-verification-in-dms.md @@ -52,7 +52,7 @@ following properties in its contents: - `to`: Bob's Matrix ID. Users should only respond to verification requests if they are named in this field. Users who are not named in this field and who did not send this event should ignore all other events that have a - `m.key.verification` relationship with this event. + `m.reference` relationship with this event. - `from_device`: Alice's device ID. This is required since some verification methods may use the device IDs as part of the verification process. @@ -126,7 +126,7 @@ 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 +`m.reference` that refer to a verification where it is not the requester nor the accepter. ### SAS verification From 06ee66d6b08b3162ca94df38f9b82b5e4a49860e Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Wed, 23 Oct 2019 15:30:07 +0100 Subject: [PATCH 09/18] Apply suggestions from code review Co-Authored-By: Kitsune Ral Co-Authored-By: David Baker --- proposals/2241-e2e-verification-in-dms.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/proposals/2241-e2e-verification-in-dms.md b/proposals/2241-e2e-verification-in-dms.md index ea813fdb27f..eccc36c253d 100644 --- a/proposals/2241-e2e-verification-in-dms.md +++ b/proposals/2241-e2e-verification-in-dms.md @@ -78,9 +78,9 @@ case this proposal should follow suit. methods may use the device IDs as part of the verification process. Clients should ignore `m.key.verification.start` events that correspond to -verification requests that it did not send. +verification requests that they did not send. -Clients may use this event as a place in the room's timeline do display +Clients may use this event as a place in the room's timeline to display progress of the key verification process and to interact with the user as necessary. @@ -129,7 +129,7 @@ Clients should ignore events with an `m.relates_to` that have a `rel_type` of `m.reference` that refer to a verification where it is not the requester nor the accepter. -### SAS verification +### 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` From 1d165eec2968ede8f6731c040ba9484fe6a06300 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Wed, 23 Oct 2019 13:22:10 -0400 Subject: [PATCH 10/18] add clarifications --- proposals/2241-e2e-verification-in-dms.md | 25 ++++++++++++++++++----- 1 file changed, 20 insertions(+), 5 deletions(-) diff --git a/proposals/2241-e2e-verification-in-dms.md b/proposals/2241-e2e-verification-in-dms.md index ea813fdb27f..6e1976cfeca 100644 --- a/proposals/2241-e2e-verification-in-dms.md +++ b/proposals/2241-e2e-verification-in-dms.md @@ -59,7 +59,26 @@ following properties in its contents: 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. +Clients should ignore verification requests that have been accepted or +cancelled, or if they do not belong to the sending or target users. + +The way that clients display this event can depend on which user and device the +client belongs to, and what state the verification is in. For example: + +- If the verification has been completed (there is an `m.key.verification.done` + or `m.key.verification.cancel` event), the client can indicate that the + verification was successful or had an error. +- If the verification has been accepted (there is an `m.key.verification.start` + event) but has not been completed, the two devices involved can indicate that + the verification is in progress and can use this event as a place in the + room's timeline to display progress of the key verification and to interact + with the user as necessary. Other devices can indicate that the verification + is in progress on other devices. +- If the verification has not been accepted, clients for the target user can + indicate that a verification has been requested and allow the user to accept + the verification on that device. The sending client can indicate that it is + waiting for the request to be accepted, and the sending user's other clients + can indicate the that a request was initiated on a different device. #### Accepting a key verification @@ -80,10 +99,6 @@ case this proposal should follow suit. 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` From 746695574458feda6022c95ed464a6d8d637cb26 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Fri, 1 Nov 2019 14:54:58 -0400 Subject: [PATCH 11/18] add note that verifying yourself may want to use to_device instead --- proposals/2241-e2e-verification-in-dms.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/proposals/2241-e2e-verification-in-dms.md b/proposals/2241-e2e-verification-in-dms.md index fbfbe62e557..77340c5b4de 100644 --- a/proposals/2241-e2e-verification-in-dms.md +++ b/proposals/2241-e2e-verification-in-dms.md @@ -164,7 +164,8 @@ verification. ## Potential issues If a user wants to verify their own device, this will require the creation of a -Direct Messaging room with themselves. +Direct Messaging room with themselves. Instead, clients may use the current +`to_device` messages for verifying the user's other devices. Direct Messaging rooms could have end-to-end encryption enabled, and some clients can be configured to only send decryption keys to verified devices. From f4bad37c10f6817d557b1cb5b381493d1351823f Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Tue, 5 Nov 2019 16:20:41 -0500 Subject: [PATCH 12/18] add notes about redactions/edits --- proposals/2241-e2e-verification-in-dms.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/proposals/2241-e2e-verification-in-dms.md b/proposals/2241-e2e-verification-in-dms.md index 77340c5b4de..a29d7703f8c 100644 --- a/proposals/2241-e2e-verification-in-dms.md +++ b/proposals/2241-e2e-verification-in-dms.md @@ -144,6 +144,11 @@ Clients should ignore events with an `m.relates_to` that have a `rel_type` of `m.reference` that refer to a verification where it is not the requester nor the accepter. +Clients should not redact or edit verification messages. A client may ignore +redactions or edits of key verification messages, or may cancel the +verification with a `code` of `m.unexpected_message` when it receives a +redaction or edit. + ### SAS verification The messages used in SAS verification are the same as those currently defined, From a514485bcb733fb58847872a2ed81723c015b224 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Tue, 5 Nov 2019 16:22:45 -0500 Subject: [PATCH 13/18] add note about displaying other events --- proposals/2241-e2e-verification-in-dms.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/proposals/2241-e2e-verification-in-dms.md b/proposals/2241-e2e-verification-in-dms.md index a29d7703f8c..e3d7239f477 100644 --- a/proposals/2241-e2e-verification-in-dms.md +++ b/proposals/2241-e2e-verification-in-dms.md @@ -80,6 +80,10 @@ client belongs to, and what state the verification is in. For example: waiting for the request to be accepted, and the sending user's other clients can indicate the that a request was initiated on a different device. +Clients may choose to display or not to display events of any other type that +reference the original request event; but it must not have any effect on the +verification itself. + #### Accepting a key verification To accept a key verification, Bob will send an `m.key.verification.start` event From 1590ae224c476d90cdc14bee9c0a632768ecb9f6 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Mon, 18 Nov 2019 16:24:59 -0500 Subject: [PATCH 14/18] make hash commitment always include the m.relates_to --- proposals/2241-e2e-verification-in-dms.md | 79 +++++++++++++++++++++++ 1 file changed, 79 insertions(+) diff --git a/proposals/2241-e2e-verification-in-dms.md b/proposals/2241-e2e-verification-in-dms.md index e3d7239f477..50e16c322b5 100644 --- a/proposals/2241-e2e-verification-in-dms.md +++ b/proposals/2241-e2e-verification-in-dms.md @@ -159,6 +159,85 @@ 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. +If the key verification messages are encrypted, the hash commitment sent in the +`m.key.verification.accept` message MUST be based on the decrypted +`m.key.verification.start` message contents, and include the `m.relates_to` +field, even if the decrypted message contents do not include that field. For +example, if Alice sends a message to start the SAS verification: + +```json +{ + "content": { + "algorithm": "m.megolm.v1.aes-sha2", + "ciphertext": "ABCDEFG...", + "device_id": "Dynabook", + "sender_key": "alice+sender+key", + "session_id": "session+id", + "m.relates_to": { + "rel_type": "m.reference", + "event_id": "$verification_request_event" + } + }, + "event_id": "$event_id", + "origin_server_ts": 1234567890, + "sender": "@alice:example.org", + "type": "m.room.encrypted", + "room_id": "!room_id:example.org" +} +``` + +which, when decrypted, yields: + +```json +{ + "room_id": "!room_id:example.org", + "type": "m.key.verification.start", + "content": { + "from_device": "Dynabook", + "hashes": [ + "sha256" + ], + "key_agreement_protocols": [ + "curve25519" + ], + "message_authentication_codes": [ + "hkdf-hmac-sha256" + ], + "method": "m.sas.v1", + "short_authentication_string": [ + "decimal", + "emoji" + ] + } +} +``` + +then the hash commitment will be based on the message contents: + +```json +{ + "from_device": "Dynabook", + "hashes": [ + "sha256" + ], + "key_agreement_protocols": [ + "curve25519" + ], + "message_authentication_codes": [ + "hkdf-hmac-sha256" + ], + "method": "m.sas.v1", + "short_authentication_string": [ + "decimal", + "emoji" + ], + "m.relates_to": { + "rel_type": "m.reference", + "event_id": "$verification_request_event" + } +} +``` + ## Alternatives Messages sent by the verification methods, after the initial key verification From 91f51bb23e30d511a274f5b05504a6ee69583d10 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Wed, 15 Apr 2020 16:09:36 -0400 Subject: [PATCH 15/18] use .ready to accept a verification, plus some clarification --- proposals/2241-e2e-verification-in-dms.md | 52 ++++++++++++++++++----- 1 file changed, 41 insertions(+), 11 deletions(-) diff --git a/proposals/2241-e2e-verification-in-dms.md b/proposals/2241-e2e-verification-in-dms.md index 50e16c322b5..90fa59fc7f9 100644 --- a/proposals/2241-e2e-verification-in-dms.md +++ b/proposals/2241-e2e-verification-in-dms.md @@ -86,7 +86,7 @@ verification itself. #### Accepting a key verification -To accept a key verification, Bob will send an `m.key.verification.start` event +To accept a key verification, Bob will send an `m.key.verification.ready` event with the following properties in its contents: TODO: MSC1849 may use `m.relationship` rather than `m.relates_to`, in which @@ -96,17 +96,38 @@ case this proposal should follow suit. - `rel_type`: `m.reference` - `event_id`: the event ID of the key verification request that is being accepted -- `method`: the key verification method that is being used +- `methods`: an array of verification methods that the device supports - `from_device`: Bob's device ID. This is required since some verification methods may use the device IDs as part of the verification process. -Clients should ignore `m.key.verification.start` events that correspond to +Clients should ignore `m.key.verification.ready` events that correspond to verification requests that they did not send. +After this, either Alice or Bob may start the verification by sending an +`m.key.verification.start` event with the following properties in its contents: + +- `m.relates_to`: an object with the properties: + - `rel_type`: `m.reference` + - `event_id`: the event ID of the key verification request that is being + started +- `method`: the key verification method that is being used. This should be a + method that both Alice's and Bob's devices support. +- `from_device`: The user's device ID. + +If both Alice and Bob send an `m.key.verification.start` message, and they both +specify the same verification method, then the event sent by the user whose +user ID is the smallest is used, and the other event is ignored. If they both +send an `m.key.verification.start` message and the method is different, then +the verification should be cancelled with a `code` of `m.unexpected_message`. + +After the `m.key.verification.start` event is sent, the devices may exchange +messages (if any) according to the verification method in use. + #### 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: +To reject a key verification, Alice or 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.reference` @@ -135,7 +156,13 @@ properties in its contents: This provides a record within the room of the result of the verification. -Any subsequent key verification messages relating to the same request are ignored. +Any subsequent key verification messages relating to the same request are +ignored. + +Although a client may have successfully completed its side of the verification, +it may wait until receiving an `m.key.verification.done` (or +`m.key.verification.cancel`) event from the other device before informing the +user that the verification was successful or unsuccessful. #### Other events @@ -145,7 +172,7 @@ 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.reference` that refer to a verification where it is not the requester +`m.reference` that refer to a verification where it is neither the requester nor the accepter. Clients should not redact or edit verification messages. A client may ignore @@ -242,13 +269,16 @@ then the hash commitment will be based on the message contents: Messages sent by the verification methods, after the initial key verification request message, could be sent as to-device messages. The -`m.key.verification.start`, `m.key.verification.cancel`, and +`m.key.verification.ready`, `m.key.verification.cancel`, and `m.key.verification.done` messages must be still be sent in the room, as the -`m.key.verification.start` notifies the sender's other devices that the request +`m.key.verification.ready` notifies the sender's other devices that the request has been acknowledged, and the `m.key.verification.cancel` and `m.key.verification.done` provide a record of the status of the key verification. +However, it seems more natural to have all messages sent via the same +mechanism. + ## Potential issues If a user wants to verify their own device, this will require the creation of a @@ -262,8 +292,8 @@ decryption keys are sent to all of the target user's devices), or should be sent unencrypted, so that unverified devices will be able to be verified. Users might have multiple Direct Messaging rooms with other users. In this -case, clients will need to prompt the user to select the room in which they -want to perform the verification. +case, clients could need to prompt the user to select the room in which they +want to perform the verification, or could select a room. ## Security considerations From 4a779784efce85a31df7f7c7b56fae0c0299ab13 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Sun, 6 Dec 2020 09:43:53 -0500 Subject: [PATCH 16/18] Update proposals/2241-e2e-verification-in-dms.md Co-authored-by: poljar --- proposals/2241-e2e-verification-in-dms.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2241-e2e-verification-in-dms.md b/proposals/2241-e2e-verification-in-dms.md index 90fa59fc7f9..f8d9ac97f29 100644 --- a/proposals/2241-e2e-verification-in-dms.md +++ b/proposals/2241-e2e-verification-in-dms.md @@ -152,7 +152,7 @@ properties in its contents: - `m.relates_to`: an object with the properties: - `rel_type`: `m.reference` - - `event_id`: the event ID of the key verification that is being cancelled + - `event_id`: the event ID of the key verification that is being concluded This provides a record within the room of the result of the verification. From affa240543c94a275685191465bd8ce9be68b25f Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Mon, 14 Dec 2020 11:33:33 -0500 Subject: [PATCH 17/18] use `reason` for human-readable cancel reason for consistency with non-DM version --- proposals/2241-e2e-verification-in-dms.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2241-e2e-verification-in-dms.md b/proposals/2241-e2e-verification-in-dms.md index f8d9ac97f29..46f303c2d45 100644 --- a/proposals/2241-e2e-verification-in-dms.md +++ b/proposals/2241-e2e-verification-in-dms.md @@ -132,7 +132,7 @@ contents: - `m.relates_to`: an object with the properties: - `rel_type`: `m.reference` - `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 +- `reason`: 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 From 609641636dcd9fa3008f3a815af10886410443c9 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Tue, 13 Apr 2021 12:29:58 -0400 Subject: [PATCH 18/18] decouple from MSC1849/MSC2674 --- proposals/2241-e2e-verification-in-dms.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/proposals/2241-e2e-verification-in-dms.md b/proposals/2241-e2e-verification-in-dms.md index 46f303c2d45..dc2797f218d 100644 --- a/proposals/2241-e2e-verification-in-dms.md +++ b/proposals/2241-e2e-verification-in-dms.md @@ -89,9 +89,6 @@ verification itself. To accept a key verification, Bob will send an `m.key.verification.ready` event with the following properties in its contents: -TODO: MSC1849 may use `m.relationship` rather than `m.relates_to`, in which -case this proposal should follow suit. - - `m.relates_to`: an object with the properties: - `rel_type`: `m.reference` - `event_id`: the event ID of the key verification request that is being @@ -100,6 +97,10 @@ case this proposal should follow suit. - `from_device`: Bob's device ID. This is required since some verification methods may use the device IDs as part of the verification process. +(Note: the form of the `m.relates_to` property is based on the current state of +[MSC2674](https://github.com/matrix-org/matrix-doc/pull/2674), but is +independent from it since this MSC does not rely on any aggregations features.) + Clients should ignore `m.key.verification.ready` events that correspond to verification requests that they did not send.