From c77d04c70937e44fb24948f10d2cb4d285f6fd32 Mon Sep 17 00:00:00 2001
From: Hubert Chathi <hubert@uhoreg.ca>
Date: Tue, 18 Feb 2020 22:58:41 -0500
Subject: [PATCH] add base64 option

---
 proposals/1543-qr_code_key_verification.md | 70 +++++++++++++++++++++-
 1 file changed, 69 insertions(+), 1 deletion(-)

diff --git a/proposals/1543-qr_code_key_verification.md b/proposals/1543-qr_code_key_verification.md
index 084e80e1..50aa4ebc 100644
--- a/proposals/1543-qr_code_key_verification.md
+++ b/proposals/1543-qr_code_key_verification.md
@@ -170,7 +170,7 @@ This proposal defines three verification methods that can be used in
 
 ### QR code format
 
-Note: only one of the following will be supported.  They are both being
+Note: only one of the following will be supported.  They are all being
 documented here while we determine how well different formats are supported.
 
 #### Binary format
@@ -259,6 +259,74 @@ strings generated as follows:
 
 The QR code is then generated using alphanumeric encoding mode.
 
+#### Base64 format
+
+The QR codes to be displayed and scanned using this format will be a string of
+the following form:
+
+- the string "MATRIX"
+- one character indicating the version (must by "2")
+- one character indicating the QR code verification mode.  May be one of the
+  following values:
+  - "0" verifying another user with cross-signing
+  - "1" self-verifying in which the current device does trust the master key
+  - "2" self-verifying in which the current device does not yet trust the
+    master key
+- the event ID or `transaction_id` of the associated verification
+  request event, encoded as:
+  - two bytes in network byte order (big-endian), encoded in unpadded base64 (3
+    characters), indicating the length in bytes of the ID as a UTF-8 string
+  - the ID as a UTF-8 string
+- the first key as unpadded base64 (43 characters).  The key to use depends on
+  the mode field:
+  - if "0" or "1", then the user's own master cross-signing public key
+  - if "2", then the current device's device key
+- the second key as unpadded base64 (43 characters).  The key to use depends on
+  the mode field:
+  - if "0", then what the device thinks the other user's master
+    cross-signing key is
+  - if "1", then what the device thinks the other device's device key is
+  - if "2", then what the device thinks the user's master cross-signing key
+    is
+- a random shared secret, as an ASCII string.  It is suggested to use a secret
+  that is about 11 bytes long.  (This is approximately the length of 8 bytes as
+  a base64 string.)  Note: as we do not share the length of the secret, and it
+  is not a fixed size, clients will just use the remainder of binary string as
+  the shared secret.
+
+1. generate a binary string by concatenating:
+  - the event ID or `transaction_id` of the associated verification
+    request event, encoded as:
+    - two bytes in network byte order (big-endian) indicating the length in
+      bytes of the ID as a UTF-8 string
+    - the ID as a UTF-8 string
+  - the first key, as 32 bytes.  The key to use depends on the mode field as
+    described in step 3:
+    - if "0" or "1", then the user's own master cross-signing public key
+    - if "2", then the current device's device key
+  - the second key, as 32 bytes.  The key to use depends on the mode field:
+    - if "0", then what the device thinks the other user's master
+      cross-signing key is
+    - if "1", then what the device thinks the other device's device key is
+    - if "2", then what the device thinks the user's master cross-signing key
+      is
+  - a random shared secret, as a byte string.  It is suggested to use a secret
+    that is about 8 bytes long.  Note: as we do not share the length of the
+    secret, and it is not a fixed size, clients will just use the remainder of
+    binary string as the shared secret.
+2. encode the above string using unpadded base64
+3. prepend the resulting string with
+   - the string "MATRIX"
+   - one character indicating the version (must by "2")
+   - one character indicating the QR code verification mode.  May be one of the
+     following values:
+     - "0" verifying another user with cross-signing
+     - "1" self-verifying in which the current device does trust the master key
+     - "2" self-verifying in which the current device does not yet trust the
+           master key
+
+The QR code is then generated using byte encoding mode.
+
 ### Message types
 
 #### `m.key.verification.start`