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&pubkey=<device-signing-public-key-in-base64> (when mx: 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.

m.key.verification.check_own_key

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

message contents:

• key: The key that Bob's device has for Alice's device
• transaction_id: the transaction ID from the m.key.verification.reciprocate message
• signatures: signature of the key 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. 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