From 8521c2d6963e878c60a91ffa5ab3d03c245e1cfa Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Tue, 13 Nov 2018 11:31:41 -0500 Subject: [PATCH 01/10] initial proposal for key verification methods --- proposals/xxxx-key_verification.md | 126 +++++++++++++++++++++++++++++ 1 file changed, 126 insertions(+) create mode 100644 proposals/xxxx-key_verification.md diff --git a/proposals/xxxx-key_verification.md b/proposals/xxxx-key_verification.md new file mode 100644 index 000000000..b71fcf34a --- /dev/null +++ b/proposals/xxxx-key_verification.md @@ -0,0 +1,126 @@ +# Key verification mechanisms + +Key verification is an essential part of ensuring that end-to-end encrypted +messages are secure. Matrix may support multiple verification methods that +require sending events; in fact, two such methods have already been proposed. + +This proposal tries to present a common framework for verification methods to +use, and presents a way to request key verification. + +## Proposal + +Each key verification method is identified by a name. Verification method +names defined in the Matrix spec will begin with `m.`, and verification method +names that are not defined in the Matrix spec must be namespaced following the +Java package naming convention. + +If Alice wants to verify keys with Bob, Alice's device may send `to_device` +events to Bob's devices with the `type` set to `m.key.verification.request`, as +described below. The event lists the verification methods that Alice's device +supports. Upon receipt of this message, Bob's client should prompt him to +verify keys with Alice using one of the applicable methods. In order to avoid +displaying stale key verification prompts, if Bob does not interact with the +prompt, it should be automatically hidden 10 minutes after the message is sent +(according to the `timestamp` field), or 2 minutes after the client receives +the message, whichever comes first. The prompt should also be hidden if an +appropriate `m.key.verification.cancel` message is received. If Bob chooses to +reject the key verification request, Bob's client should send a +`m.key.verification.cancel` message to Alice's device. If Bob's client does +not understand any of the methods offered, it should display a message to Bob +saying so. + +To initiate a key verification process, Bob's device sends a `to_device` event +to one of Alice's devices with the `type` set to `m.key.verification.start`. +This may either be done in response to an `m.key.verification.request` message, +or can be done independently. If Alice's device receives an +`m.key.verification.start` message in response to an +`m.key.verification.request` message, it should send an +`m.key.verification.cancel` message to Bob's other devices that it had +originally sent an `m.key.verification.request` to, in order to cancel the key +verification request. + +Verification methods can define other events required to complete the +verification. Event types for verification methods defined in the Matrix spec +should be in the `m.key.verification` namespace. Event types that are not +defined in the Matrix spec must be namespaced following the Java package naming +convention. + +Alice's or Bob's devices can cancel a key verification process or a key +verification request by sending a `to_device` event with `type` set to +`m.key.verification.cancel`. + +### Event Definitions + +#### `m.key.verification.request` + +Requests a key verification. + +Properties: + +- `from_device` (string): the device ID of the device requesting verification. +- `transaction_id` (string): an identifier for the verification request. Must + be unique with respect to the pair of devices. +- `methods` ([string]): the verification methods supported by the sender. +- `timestamp` (integer): the time when the request was made. If the timestamp + is in the future (by more than 5 minutes, to allow for clock skew), or more + than 10 minutes in the past, then the message must be ignored. + +#### `m.key.verification.start` + +Begins a key verification process. + +Properties: + +- `method` (string): the verification method to use. +- `from_device` (string): The device ID of the device starting the verification + process. +- `transaction_id` (string): an identifier for the verification process. If + this message is sent in reponse to an `m.key.verification.request` event, then + it must use the same `transaction_id` as the one given in the + `m.key.verification.request`. + +Key verification methods can define additional properties to be included. + +#### `m.key.verification.cancel` + +Cancels a key verification process or a key verification request. Upon +receiving an `m.key.verification.cancel` message, the receiving device must +cancel the verification or the request. If it is a verification process that +is cancelled, or a verification request initiated by the recipient of the +cancellation message, the device should inform the user of the reason. + +Properties: + +- `transaction_id` (string): the identifier for the request or key verification + to cancel. +- `code` (string): machine-readable reason for cancelling. Possible reasons + are: + - `m.user`: the user cancelled the verification. + - `m.timeout`: the verification process has timed out. Different verification + methods may define their own timeouts. + - `m.unknown_transaction`: the device does not know about the given transaction + ID. + - `m.unknown_method`: the device does not know how to handle the given method. + This can be sent in response to an `m.key.verification.start` message, or + can be sent in response to other verification method-specific messages. + - `m.unexpected_message`: the device received an unexpected message. For + example, a message for a verification method may have been received when it + was not expected. +- `reason` (string): human-readable reason for cancelling. This should only be + used if the recieving client does not understand the code given. + +Verification methods may define their own additional cancellation codes. +Cancellation codes defined in the Matrix spec will begin with `m.`; other +cancellation codes must be namespaced following the Java package naming +convention. + +## Tradeoffs + +## Potential issues + +## Security considerations + +## Conclusion + +This proposal presents common event definitions for use by key verification +methods and defines a way for users to request key verification. From ec2e02e8b5479b4734b0d8a6ed5aa8953f495a67 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Tue, 13 Nov 2018 11:45:18 -0500 Subject: [PATCH 02/10] rename to match MSC number --- proposals/{xxxx-key_verification.md => 1717-key_verification.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename proposals/{xxxx-key_verification.md => 1717-key_verification.md} (100%) diff --git a/proposals/xxxx-key_verification.md b/proposals/1717-key_verification.md similarity index 100% rename from proposals/xxxx-key_verification.md rename to proposals/1717-key_verification.md From c02ecb58aec48778d9ca4531bb84f5e875d71210 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Tue, 8 Jan 2019 16:11:00 -0500 Subject: [PATCH 03/10] mark which fields are required --- proposals/1717-key_verification.md | 30 ++++++++++++++++-------------- 1 file changed, 16 insertions(+), 14 deletions(-) diff --git a/proposals/1717-key_verification.md b/proposals/1717-key_verification.md index b71fcf34a..fa1d73733 100644 --- a/proposals/1717-key_verification.md +++ b/proposals/1717-key_verification.md @@ -57,13 +57,15 @@ Requests a key verification. Properties: -- `from_device` (string): the device ID of the device requesting verification. -- `transaction_id` (string): an identifier for the verification request. Must - be unique with respect to the pair of devices. -- `methods` ([string]): the verification methods supported by the sender. -- `timestamp` (integer): the time when the request was made. If the timestamp - is in the future (by more than 5 minutes, to allow for clock skew), or more - than 10 minutes in the past, then the message must be ignored. +- `from_device` (string): Required. The device ID of the device requesting + verification. +- `transaction_id` (string): Required. An identifier for the verification + request. Must be unique with respect to the pair of devices. +- `methods` ([string]): Required. The verification methods supported by the + sender. +- `timestamp` (integer): Required. The time when the request was made. If the + timestamp is in the future (by more than 5 minutes, to allow for clock skew), + or more than 10 minutes in the past, then the message must be ignored. #### `m.key.verification.start` @@ -71,13 +73,13 @@ Begins a key verification process. Properties: -- `method` (string): the verification method to use. -- `from_device` (string): The device ID of the device starting the verification - process. -- `transaction_id` (string): an identifier for the verification process. If - this message is sent in reponse to an `m.key.verification.request` event, then - it must use the same `transaction_id` as the one given in the - `m.key.verification.request`. +- `method` (string): Required. The verification method to use. +- `from_device` (string): Required. The device ID of the device starting the + verification process. +- `transaction_id` (string): Required. An identifier for the verification + process. If this message is sent in reponse to an + `m.key.verification.request` event, then it must use the same + `transaction_id` as the one given in the `m.key.verification.request`. Key verification methods can define additional properties to be included. From ff0b9eac76cfa65222dd82d45ff3358570ab1fd1 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Tue, 8 Jan 2019 16:11:15 -0500 Subject: [PATCH 04/10] add ability to start verifications that happen in two stages --- proposals/1717-key_verification.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/proposals/1717-key_verification.md b/proposals/1717-key_verification.md index fa1d73733..8acc46549 100644 --- a/proposals/1717-key_verification.md +++ b/proposals/1717-key_verification.md @@ -80,6 +80,10 @@ Properties: process. If this message is sent in reponse to an `m.key.verification.request` event, then it must use the same `transaction_id` as the one given in the `m.key.verification.request`. +- `next_method` (string): Optional. If the selected verification method only + verifies one user's key, then this property can be used to indicate the + method to use to verify the other user's key, which will be started + immediately after after the current key verification is complete. Key verification methods can define additional properties to be included. From 09a547d67e0a4b835405af0be9ce739f9dfe400a Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Tue, 8 Jan 2019 17:45:13 -0500 Subject: [PATCH 05/10] add some cancellation codes, and mention existing verification MSCs --- proposals/1717-key_verification.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/proposals/1717-key_verification.md b/proposals/1717-key_verification.md index 8acc46549..b536be0e6 100644 --- a/proposals/1717-key_verification.md +++ b/proposals/1717-key_verification.md @@ -2,7 +2,8 @@ Key verification is an essential part of ensuring that end-to-end encrypted messages are secure. Matrix may support multiple verification methods that -require sending events; in fact, two such methods have already been proposed. +require sending events; in fact, two such methods (such as MSC1267 and MSC1543) +have already been proposed. This proposal tries to present a common framework for verification methods to use, and presents a way to request key verification. @@ -112,6 +113,12 @@ Properties: - `m.unexpected_message`: the device received an unexpected message. For example, a message for a verification method may have been received when it was not expected. + - `m.key_mismatch`: the key was not verified. + - `m.user_mismatch`: the expected user did not match the user verified. + - `m.invalid_message`: an invalid message was received. + - `m.accepted`: when an `m.key.verification.request` is accepted by one + device, an `m.key.verification.cancel` message with `code` set to + `m.accepted` is sent to the other devices - `reason` (string): human-readable reason for cancelling. This should only be used if the recieving client does not understand the code given. From f9a00fc943d9ae49ae32845a7a971578ff84c4a0 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Wed, 13 Mar 2019 23:25:11 -0400 Subject: [PATCH 06/10] clarify that not understanding a verification method should not auto-cancel --- proposals/1717-key_verification.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/proposals/1717-key_verification.md b/proposals/1717-key_verification.md index b536be0e6..10ccf7851 100644 --- a/proposals/1717-key_verification.md +++ b/proposals/1717-key_verification.md @@ -28,7 +28,10 @@ appropriate `m.key.verification.cancel` message is received. If Bob chooses to reject the key verification request, Bob's client should send a `m.key.verification.cancel` message to Alice's device. If Bob's client does not understand any of the methods offered, it should display a message to Bob -saying so. +saying so. However, it should not send a `m.key.verification.cancel` message +to Alice's device unless Bob chooses to reject the verification request, as Bob +may have another device that is capable of verifying using one of the given +methods. To initiate a key verification process, Bob's device sends a `to_device` event to one of Alice's devices with the `type` set to `m.key.verification.start`. From 4842a718d8ab3c4000e86270d3ef3aea6cf42154 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Wed, 13 Mar 2019 23:39:00 -0400 Subject: [PATCH 07/10] fill in some of the other sections --- proposals/1717-key_verification.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/proposals/1717-key_verification.md b/proposals/1717-key_verification.md index 10ccf7851..9296cf402 100644 --- a/proposals/1717-key_verification.md +++ b/proposals/1717-key_verification.md @@ -132,10 +132,18 @@ convention. ## Tradeoffs -## Potential issues +Rather than broadcasting verification requests to Bob's devices, Alice could +simply send an `m.key.verification.start` request to a single device. However, +this would require Alice to choose the right device to send to, which may be +hard for Alice to do if, for example, Bob has many devices, or if his devices +have similar names. ## Security considerations +An attacker could try to spam a user with verification requests. Clients +should take care that such requests do not interfere with a user's use of the +client. + ## Conclusion This proposal presents common event definitions for use by key verification From 1749a91344786815ecbae43a53e19fb53157c307 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Wed, 13 Mar 2019 23:41:43 -0400 Subject: [PATCH 08/10] make MSC mentions into links --- proposals/1717-key_verification.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/proposals/1717-key_verification.md b/proposals/1717-key_verification.md index 9296cf402..02018ef9d 100644 --- a/proposals/1717-key_verification.md +++ b/proposals/1717-key_verification.md @@ -2,8 +2,10 @@ Key verification is an essential part of ensuring that end-to-end encrypted messages are secure. Matrix may support multiple verification methods that -require sending events; in fact, two such methods (such as MSC1267 and MSC1543) -have already been proposed. +require sending events; in fact, two such methods (such as [MSC +1267](https://github.com/matrix-org/matrix-doc/issues/1267) and [MSC +1543](https://github.com/matrix-org/matrix-doc/issues/1543)) have already been +proposed. This proposal tries to present a common framework for verification methods to use, and presents a way to request key verification. From 696e568fb2101480826d873fac83897ae904472a Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Tue, 26 Mar 2019 15:10:14 -0400 Subject: [PATCH 09/10] add some clarifications --- proposals/1717-key_verification.md | 46 +++++++++++++++++++----------- 1 file changed, 30 insertions(+), 16 deletions(-) diff --git a/proposals/1717-key_verification.md b/proposals/1717-key_verification.md index 02018ef9d..6c9e2341b 100644 --- a/proposals/1717-key_verification.md +++ b/proposals/1717-key_verification.md @@ -19,26 +19,40 @@ Java package naming convention. If Alice wants to verify keys with Bob, Alice's device may send `to_device` events to Bob's devices with the `type` set to `m.key.verification.request`, as -described below. The event lists the verification methods that Alice's device -supports. Upon receipt of this message, Bob's client should prompt him to -verify keys with Alice using one of the applicable methods. In order to avoid -displaying stale key verification prompts, if Bob does not interact with the -prompt, it should be automatically hidden 10 minutes after the message is sent -(according to the `timestamp` field), or 2 minutes after the client receives -the message, whichever comes first. The prompt should also be hidden if an -appropriate `m.key.verification.cancel` message is received. If Bob chooses to -reject the key verification request, Bob's client should send a -`m.key.verification.cancel` message to Alice's device. If Bob's client does -not understand any of the methods offered, it should display a message to Bob -saying so. However, it should not send a `m.key.verification.cancel` message -to Alice's device unless Bob chooses to reject the verification request, as Bob -may have another device that is capable of verifying using one of the given -methods. +described below. The `m.key.verification.request` messages should all have the +same `transaction_id`, and are considered to be a single request. Thus, for +example, if Bob rejects the request on one device, then the entire request +should be considered as rejected across all of his devices. Similarly, if Bob +accepts the request on one device, that device is now in charge of completing +the key verification, and Bob's other devices no longer need to be involved. + +The `m.key.verification.request` event lists the verification methods that +Alice's device supports, and upon receipt of this message, Bob's client should +prompt him to verify keys with Alice using one of the applicable methods. In +order to avoid displaying stale key verification prompts, if Bob does not +interact with the prompt, it should be automatically hidden 10 minutes after +the message is sent (according to the `timestamp` field), or 2 minutes after +the client receives the message, whichever comes first. The prompt should also +be hidden if an appropriate `m.key.verification.cancel` message is received. + +If Bob chooses to reject the key verification request, Bob's client should send +a `m.key.verification.cancel` message to Alice's device. This indicates to +Alice that Bob does not wish to verify keys with her. In this case, Alice's +device should send an `m.key.verification.cancel` message to all of Bob's +devices to notify them that the request has been rejected. + +If one of Bob's clients does not understand any of the methods offered, it +should display a message to Bob saying so. However, it should not send a +`m.key.verification.cancel` message to Alice's device unless Bob chooses to +reject the verification request, as Bob may have another device that is capable +of verifying using one of the given methods. To initiate a key verification process, Bob's device sends a `to_device` event to one of Alice's devices with the `type` set to `m.key.verification.start`. This may either be done in response to an `m.key.verification.request` message, -or can be done independently. If Alice's device receives an +or can be done independently. If it is done in response to an +`m.key.verification.request` messsage, it should use the same `transaction_id` +as the `m.key.verification.request` message. If Alice's device receives an `m.key.verification.start` message in response to an `m.key.verification.request` message, it should send an `m.key.verification.cancel` message to Bob's other devices that it had From 84f0d9d7e4467460a9caf9128cd739ddd2fb03b6 Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Tue, 28 May 2019 20:07:45 -0400 Subject: [PATCH 10/10] add clarification --- proposals/1717-key_verification.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/proposals/1717-key_verification.md b/proposals/1717-key_verification.md index 6c9e2341b..429e3a97b 100644 --- a/proposals/1717-key_verification.md +++ b/proposals/1717-key_verification.md @@ -139,7 +139,8 @@ Properties: device, an `m.key.verification.cancel` message with `code` set to `m.accepted` is sent to the other devices - `reason` (string): human-readable reason for cancelling. This should only be - used if the recieving client does not understand the code given. + used if the recieving client does not understand the code given in the `code` + property. Verification methods may define their own additional cancellation codes. Cancellation codes defined in the Matrix spec will begin with `m.`; other