From 3aba9b153b1d96bbff1538db85fcc3eca6c3178a Mon Sep 17 00:00:00 2001 From: Hubert Chathi Date: Mon, 20 Aug 2018 15:24:44 -0400 Subject: [PATCH] initial dump of proposal --- proposals/1543-qr_code_key_verification.md | 85 ++++++++++++++++++++++ 1 file changed, 85 insertions(+) create mode 100644 proposals/1543-qr_code_key_verification.md diff --git a/proposals/1543-qr_code_key_verification.md b/proposals/1543-qr_code_key_verification.md new file mode 100644 index 000000000..3f1ee6b10 --- /dev/null +++ b/proposals/1543-qr_code_key_verification.md @@ -0,0 +1,85 @@ +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. + +Other methods exist for making it easier to verify keys. In Matrix, +[MSC1267](https://github.com/matrix-org/matrix-doc/issues/1267) proposes +another method, which is useful when neither party is able to scan a QR code. + +Proposal +-------- + +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 + byte-encoded QR code using UTF-8 of the string `/verify + `. (This format matches the + `/verify` command in Riot.) +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.reciprocate` 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. Alice's device displays the result of the checks. +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.reciprocate` + +Tells Bob's device that Alice has verified his key, and requests that he verify +Alice's key in turn. + +message contents: + +- `device_id`: the ID of the device that Alice is using +- `transaction_id`: a unique identifier for the transaction (is this needed?) + +#### `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 +--------- + +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. + +Other Issues +------------ + +Conclusion +----------