initial proposal for key verification methods
parent
767af87744
commit
8521c2d696
@ -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.
|
Loading…
Reference in New Issue