From 33df2d1414fd034274d477876fb9df0cc006d8f5 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Mon, 25 Nov 2019 16:14:49 -0500 Subject: [PATCH 1/9] initial proposal of `m.key.verification.accept` --- proposals/xxxx-key-verification-accept.md | 53 +++++++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 proposals/xxxx-key-verification-accept.md diff --git a/proposals/xxxx-key-verification-accept.md b/proposals/xxxx-key-verification-accept.md new file mode 100644 index 00000000000..75ffa2a4ca8 --- /dev/null +++ b/proposals/xxxx-key-verification-accept.md @@ -0,0 +1,53 @@ +# Key verification flow addition: `m.key.verification.accept` + +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). + +## Proposal + +A new event type is added to the key verification framework: +`m.key.verification.accept`, which may 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.accept` + 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.accept` 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 ID is the smallest +is used, and the event sent by the user whose ID is the largest 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`. + +The `m.key.verification.accept` event is optional; the recipient of the +`m.key.verification.request` event may respond directly with a +`m.key.verification.start` event instead. This is for compatibility with the +current version of the spec. + +## Potential issues + +There are now three possible ways that a key verification can be performed: + +1. A device begins a verification by sending an `m.key.verification.start` + event. This is only possible for to-device verification. +2. A device sends an `m.key.verification.request` event and the recipient + replies with an `m.key.verification.start` event. +3. A device sends an `m.key.verification.request` event and the recipient + replies with an `m.key.verification.accept` event, and which point, either + device can send an `m.key.verification.start` event to begin the + verification. + +This increases the complexity of implementations. From abbba4788ce81d6fbbb36a4f9966179a1ebe5489 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Mon, 25 Nov 2019 16:16:34 -0500 Subject: [PATCH 2/9] rename to match MSC number --- ...key-verification-accept.md => 2366-key-verification-accept.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename proposals/{xxxx-key-verification-accept.md => 2366-key-verification-accept.md} (100%) diff --git a/proposals/xxxx-key-verification-accept.md b/proposals/2366-key-verification-accept.md similarity index 100% rename from proposals/xxxx-key-verification-accept.md rename to proposals/2366-key-verification-accept.md From 5f5f99fcc1c22ecdf919ef8a609c38625b83e5a9 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Tue, 26 Nov 2019 13:06:13 -0500 Subject: [PATCH 3/9] wording tweaks --- proposals/2366-key-verification-accept.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/proposals/2366-key-verification-accept.md b/proposals/2366-key-verification-accept.md index 75ffa2a4ca8..cd48463d217 100644 --- a/proposals/2366-key-verification-accept.md +++ b/proposals/2366-key-verification-accept.md @@ -25,9 +25,9 @@ or an in-room event. After the `m.key.verification.accept` 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 ID is the smallest -is used, and the event sent by the user whose ID is the largest is ignored. In -the case of a single user verifying two of their devices, the device ID is +verification method, then the event sent by the user whose user ID is the +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`. From 5742c30a96b2d4636196bddcbb3d9dfd904942cc Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Fri, 29 Nov 2019 09:22:09 -0500 Subject: [PATCH 4/9] s/accept/ready/ because we already have an m.key.verification.accept --- proposals/2366-key-verification-accept.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/proposals/2366-key-verification-accept.md b/proposals/2366-key-verification-accept.md index cd48463d217..5bd693dd2ab 100644 --- a/proposals/2366-key-verification-accept.md +++ b/proposals/2366-key-verification-accept.md @@ -1,4 +1,4 @@ -# Key verification flow addition: `m.key.verification.accept` +# Key verification flow addition: `m.key.verification.ready` The current key verification framework is asymmetrical in that the user who requests the verification is unable to select the key verification method. @@ -10,11 +10,11 @@ verifying in-person, but are using a trusted but remote channel of verification ## Proposal A new event type is added to the key verification framework: -`m.key.verification.accept`, which may be sent by the target of the +`m.key.verification.ready`, which may 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.accept` +- `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 @@ -22,7 +22,7 @@ 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.accept` event is sent, either party can send an +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 @@ -32,7 +32,7 @@ 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`. -The `m.key.verification.accept` event is optional; the recipient of the +The `m.key.verification.ready` event is optional; the recipient of the `m.key.verification.request` event may respond directly with a `m.key.verification.start` event instead. This is for compatibility with the current version of the spec. @@ -46,7 +46,7 @@ There are now three possible ways that a key verification can be performed: 2. A device sends an `m.key.verification.request` event and the recipient replies with an `m.key.verification.start` event. 3. A device sends an `m.key.verification.request` event and the recipient - replies with an `m.key.verification.accept` event, and which point, either + replies with an `m.key.verification.ready` event, and which point, either device can send an `m.key.verification.start` event to begin the verification. From 17abe054f2db56031cdb27020983dbc88a9cee76 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Fri, 29 Nov 2019 17:05:53 -0500 Subject: [PATCH 5/9] send m.key.verification.cancel to other devices when one device is ready --- proposals/2366-key-verification-accept.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/proposals/2366-key-verification-accept.md b/proposals/2366-key-verification-accept.md index 5bd693dd2ab..0fded02eb28 100644 --- a/proposals/2366-key-verification-accept.md +++ b/proposals/2366-key-verification-accept.md @@ -32,6 +32,14 @@ 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 optional; the recipient of the `m.key.verification.request` event may respond directly with a `m.key.verification.start` event instead. This is for compatibility with the From 22f7eaae0c0595ef8d9a57ee9ee80cca920932d4 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Tue, 3 Dec 2019 22:03:21 -0500 Subject: [PATCH 6/9] add example --- proposals/2366-key-verification-accept.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/proposals/2366-key-verification-accept.md b/proposals/2366-key-verification-accept.md index 0fded02eb28..9dd7a401bf5 100644 --- a/proposals/2366-key-verification-accept.md +++ b/proposals/2366-key-verification-accept.md @@ -7,6 +7,16 @@ 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. + ## Proposal A new event type is added to the key verification framework: From 4672a7083e6e646cb593d68a664911508b846915 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Wed, 15 Apr 2020 16:07:03 -0400 Subject: [PATCH 7/9] make .ready required, and add .done --- proposals/2366-key-verification-accept.md | 46 +++++++++++++---------- 1 file changed, 26 insertions(+), 20 deletions(-) diff --git a/proposals/2366-key-verification-accept.md b/proposals/2366-key-verification-accept.md index 9dd7a401bf5..a7b9f371a0c 100644 --- a/proposals/2366-key-verification-accept.md +++ b/proposals/2366-key-verification-accept.md @@ -1,4 +1,4 @@ -# Key verification flow addition: `m.key.verification.ready` +# 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. @@ -17,11 +17,22 @@ 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 -A new event type is added to the key verification framework: -`m.key.verification.ready`, which may be sent by the target of the -`m.key.verification.request` message, upon receipt of the +Two new event types are added to the key verification framework. 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 may 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` @@ -50,22 +61,17 @@ message to the recipient's other devices when it received an 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 optional; the recipient of the -`m.key.verification.request` event may respond directly with a -`m.key.verification.start` event instead. This is for compatibility with the -current version of the spec. +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. -## Potential issues +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. -There are now three possible ways that a key verification can be performed: - -1. A device begins a verification by sending an `m.key.verification.start` - event. This is only possible for to-device verification. -2. A device sends an `m.key.verification.request` event and the recipient - replies with an `m.key.verification.start` event. -3. A device sends an `m.key.verification.request` event and the recipient - replies with an `m.key.verification.ready` event, and which point, either - device can send an `m.key.verification.start` event to begin the - verification. +## Potential issues -This increases the complexity of implementations. +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. From 2e0ef11640c6adcb1c59669579e5b80a67094261 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Mon, 18 May 2020 11:22:51 -0400 Subject: [PATCH 8/9] Wording fixes --- proposals/2366-key-verification-accept.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/2366-key-verification-accept.md b/proposals/2366-key-verification-accept.md index a7b9f371a0c..e713abbf260 100644 --- a/proposals/2366-key-verification-accept.md +++ b/proposals/2366-key-verification-accept.md @@ -31,7 +31,7 @@ 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 may be sent by the +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: @@ -47,7 +47,7 @@ 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 -smallest is used, and the other `m.key.verification.start` event is ignored. +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 From c741049760a9ec5a5a4a154645a08afd2e7ef2c4 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Mon, 8 Jun 2020 22:57:11 -0400 Subject: [PATCH 9/9] more clarifications --- proposals/2366-key-verification-accept.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/proposals/2366-key-verification-accept.md b/proposals/2366-key-verification-accept.md index e713abbf260..bc355601ff9 100644 --- a/proposals/2366-key-verification-accept.md +++ b/proposals/2366-key-verification-accept.md @@ -26,7 +26,9 @@ verification as a whole. ## Proposal -Two new event types are added to the key verification framework. The new event +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. @@ -74,4 +76,5 @@ the device has successfully completed its side of the verification. 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. +this way yet -- to our knowledge, all clients that implement verification +implement this proposal.