MSC1544: Key verification using QR codes

proposals/1543-qr_code_key_verification.md

@@ -0,0 +1,166 @@
+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.