matrix-spec/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:

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 as specified below.
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 with `method` set
   to `m.reciprocate.v1` 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.

Example flow 2:

1. Alice and Bob meet in person, and want to verify each other's keys.
2. Alice requests a key verification through her device by sending an
   `m.key.verification.request` message (see MSC1717).
3. Bob responds by sending an `m.key.verification.start` message with `method`
   set to `m.qr_code.scan.v1` and `next_method` set to `m.reciprocate.v1`.
4. Bob's device displays a QR code as specified below.
5. Alice scans the QR code.
6. Alice's device ensures that the user ID in the QR code is the same as the
   expected user ID (which it knows because it is the recipient of her
   `m.key.verification.request` message).  At this point, Alice's device has
   now verified Bob's key.
7. Alice's device sends a `m.key.verification.start` message with `method` set
   to `m.reciprocate.v1` to Bob's device.
8. 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.
9. 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.
10. 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.

### QR code format

The QR codes to be displayed and scanned using this format will encode URLs of
the form:
`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).

### Message types

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

Begins a key verification process.

message contents:

- `method`: the verification method to use.  For this method, this must be one of:
  - `m.qr_code.show.v1` to request that the other device show a QR code that
    can be scanned
  - `m.qr_code.scan.v1` to request that the other device scan a QR code
  - `m.reciprocate.v1` to tell the other device that its key has been verified,
    and to request that it verify this device's key in turn
- `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.
- `next_method` (only if `method` is `m.qr_code.show.v1` or `m.qr_code.scan.v1`)
- `keys_ids`: (only if `method` is `m.reciprocate.v1`) 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

### Cancellation

In addition to the cancellation codes specified in MSC1717, the following
cancellation codes may be used:

- `m.qr_code.invalid`: The QR code is invalid (e.g. it is not a URL of the
  required form)
- `m.invalid_signature`: The signature of the
  `m.key.verification.check_own_key` message was incorrect.

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.