matrix-spec-proposals/proposals/1543-qr_code_key_verification.md

Key verification using QR codes
===============================

Problem/Background
------------------

Key verification is essential in ensuring that end-to-end encrypted messages
cannot be read by unauthorized parties.  Traditionally, key verification is
done by comparing long strings.  To save users from the tedium of reading out
long strings, some systems allow one party to verify the other party by
scanning a QR code; by doing this twice, both parties can verify each other.
In this proposal, we present a method for both parties to verify each other by
only scanning one QR code.

Proposal
--------

When Alice and Bob meet in person to verify keys, Alice will scan a QR code
generated by Bob's device.  This easily allows Alice to verify Bob's key, but
does not give Bob any information about Alice's key in order to verify it.
However, Bob's device can now send to Alice's device what it thinks is her key
(signed by his key, so that Alice can verify that the message actually came
from his device), and Alice's device can do the verification on behalf of Bob
and display the result.

Example flow:

1. Alice and Bob meet in person, and want to verify each other's keys.
2. Bob tells his device to display a QR code.  Bob's device displays a
   QR code that encodes the URL
   `https://matrix.to/#/<user-id>?device=<device-id>action=verify&key_<keyid>=<key-in-base64>...`
   (when `matrix:` URLs are specced, this will be used instead).
3. Alice scans the QR code.
4. Alice's device ensures that the user ID in the QR code is the same as the
   expected user ID.  This can be done by prompting Alice with the user ID, or
   can be done automatically if the device already knows what user ID to
   expect.  At this point, Alice's device has now verified Bob's key.
5. Alice's device sends a `m.key.verification.start` message (see below)
   as a to-device message to Bob's device (using the user ID and device ID from
   the QR code.)
6. Bob's device fetches Alice's public key, signs it, and sends it to Alice's
   device in a `m.key.verification.check_own_key` to-device message (see
   below).  Bob's device displays a message saying that Alice wants him to
   verify her key, and presents a button for him to press /after/ Alice's
   device says that things match.
7. Alice's device receives the `m.key.verification.check_own_key` message,
   checks Bob's signature, and checks that the key is the same as her device
   key, as well as checking that the rest of the contents match the expected
   values.  Alice's device displays whether the verification was successful or
   not.
8. Bob sees Alice's device confirm that the key matches, and presses the button
   on his device to indicate that Alice's key is verified.

### Message types

#### `m.key.verification.start`

Tells Bob's device that Alice has verified his key, and requests that he verify
Alice's key in turn.

message contents:

- `method`: the verification method to use.  Must be `m.reciprocate.v1`.
- `from_device`: the ID of the device that Alice is using
- `transaction_id`: an identifier for the transaction.  Must be unique on
  Alice's device.
- `keys_ids`: array of key IDs to verify.

#### `m.key.verification.check_own_key`

Tells Alice's device what Bob's device thinks her key is.

message contents:

- `keys`: A map of key IDs to the key that Bob's device has
- `transaction_id`: the transaction ID from the `m.key.verification.start`
  message
- `signatures`: signature of the keys and transaction ID, signed using Bob's key

Tradeoffs/Alternatives
----------------------

Other methods of verifying keys, which do not require scanning QR codes, are
needed for devices that are unable to scan QR codes.  One such method is
[MSC1267](https://github.com/matrix-org/matrix-doc/issues/1267).  These methods
are not exclusive to each other.

Security Considerations
-----------------------

Step 4 is to ensure that Bob does not present a QR code claiming to be Carol's
key.  Without this check, Bob will be able to trick Alice into verifying a key
under his control, and evesdropping on Alice's communications with Carol.

The security of verifying Alice's key depends on Bob not hitting the "Verified"
button until after Alice's device indicates success.  However, users have a
tendency to click on buttons without reading what the screen says.  This might
be addressed by:

- allowing Bob to easily undo the verification if Alice's device subsequently
  gives an error
- posing Bob a dummy question that he cannot answer until after Alice's device
  displays the check results.  For example: "Does Alice's device show a cat or
  a dog?"  Alice's device will show one or the other after it has checked the
  key received from Bob, forcing Bob to wait for the check to complete.
  (Whether a cat or a dog is displayed could be keyed to, for example, a bit in
  the transaction ID.)
- (possibly other ways)

Other Issues
------------

Conclusion
----------

This proposal presents a method for bi-directional key verification by scanning
a QR code and a very simplified out-of-band verification.