switch QR code to URL, add introductory text, add clarifications, reorganize

proposals/1543-qr_code_key_verification.md

@@ -12,20 +12,24 @@ 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
 --------
 
+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
-   byte-encoded QR code using UTF-8 of the string `/verify <user-id>
-   <device-id> <device-signing-public-key>`.  (This format matches the
-   `/verify` command in Riot.)
+   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
@@ -41,7 +45,9 @@ Example flow:
    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.
+   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.
 
@@ -55,7 +61,10 @@ 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?)
+- `transaction_id`: an identifier for the transaction.  Must be unique on
+  Alice's device.
+
+FIXME: Alice's device should be allowed to expire verification requests.
 
 #### `m.key.verification.check_own_key`
 
@@ -71,10 +80,10 @@ message contents:
 Tradeoffs/Alternatives
 ----------------------
 
-The exact format for the QR code is not nailed down.  Another possibility is
-that it could be a URL, so that a user can scan the code in any QR code
-scanner, and have it automatically open the user's Matrix client to begin the
-verification.
+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
 -----------------------