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.