From ad81d0efa3f127f10e8b0e09b2bf5541e23422cb Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Mon, 3 Jun 2024 09:29:58 +0100 Subject: [PATCH 1/6] Be specific about encoding of QR codes --- .../modules/end_to_end_encryption.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/content/client-server-api/modules/end_to_end_encryption.md b/content/client-server-api/modules/end_to_end_encryption.md index 1b3bd7b32..9d17d0922 100644 --- a/content/client-server-api/modules/end_to_end_encryption.md +++ b/content/client-server-api/modules/end_to_end_encryption.md @@ -1179,10 +1179,16 @@ The process between Alice and Bob verifying each other would be: ###### QR code format -The QR codes to be displayed and scanned using this format will encode binary -strings in the general form: +The QR codes to be displayed and scanned must be +[ISO/IEC 18004:2015](https://www.iso.org/standard/62021.html) compatible and +contain a single segment that uses the byte mode encoding. -- the ASCII string `MATRIX` +The error correction level can be chosen by the device displaying the QR code. + +The binary segment must be of the following form: + +- the string `MATRIX` encoded as one ASCII byte per character (i.e. `0x4D`, + `0x41`, `0x54`, `0x52`, `0x49`, `0x58`) - one byte indicating the QR code version (must be `0x02`) - one byte indicating the QR code verification mode. Should be one of the following values: @@ -1210,7 +1216,7 @@ strings in the general form: secret, and it is not a fixed size, clients will just use the remainder of binary string as the shared secret. -For example, if Alice displays a QR code encoding the following binary string: +For example, if Alice displays a QR code encoding the following binary data: ``` "MATRIX" |ver|mode| len | event ID From 19f3e210a7725a9e9817d4a786acdf46da7359c1 Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Mon, 3 Jun 2024 09:41:18 +0100 Subject: [PATCH 2/6] Changelog --- changelogs/client_server/newsfragments/1839.clarification | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/1839.clarification diff --git a/changelogs/client_server/newsfragments/1839.clarification b/changelogs/client_server/newsfragments/1839.clarification new file mode 100644 index 000000000..eea109b17 --- /dev/null +++ b/changelogs/client_server/newsfragments/1839.clarification @@ -0,0 +1 @@ +Specify the encoding to be used when generating QR codes for device verification. From f353b2ce40839ba2bac037f91c79cc959f650cd9 Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Wed, 5 Jun 2024 11:09:51 +0100 Subject: [PATCH 3/6] Clarifications around "strings" --- content/client-server-api/modules/end_to_end_encryption.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/client-server-api/modules/end_to_end_encryption.md b/content/client-server-api/modules/end_to_end_encryption.md index 9d17d0922..a77fb5b1b 100644 --- a/content/client-server-api/modules/end_to_end_encryption.md +++ b/content/client-server-api/modules/end_to_end_encryption.md @@ -1200,7 +1200,7 @@ The binary segment must be of the following form: 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 ID encoded as a UTF-8 string (i.e. one UTF-8 byte per character) - the first key, as 32 bytes. The key to use depends on the mode field: - if `0x00` or `0x01`, then the current user's own master cross-signing public key - if `0x02`, then the current device's Ed25519 signing key @@ -1211,10 +1211,10 @@ The binary segment must be of the following form: key is - if `0x02`, 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 +- a random shared secret, as a sequence of bytes. 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. + binary segment as the shared secret. For example, if Alice displays a QR code encoding the following binary data: From 454dacd82e60014edff1adc2f87862988d952f30 Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Wed, 12 Jun 2024 16:57:12 +0100 Subject: [PATCH 4/6] Apply suggestions from code review Thank you! Co-authored-by: Johannes Marbach Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --- content/client-server-api/modules/end_to_end_encryption.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/client-server-api/modules/end_to_end_encryption.md b/content/client-server-api/modules/end_to_end_encryption.md index a77fb5b1b..610e6d33a 100644 --- a/content/client-server-api/modules/end_to_end_encryption.md +++ b/content/client-server-api/modules/end_to_end_encryption.md @@ -1179,13 +1179,13 @@ The process between Alice and Bob verifying each other would be: ###### QR code format -The QR codes to be displayed and scanned must be -[ISO/IEC 18004:2015](https://www.iso.org/standard/62021.html) compatible and +The QR codes to be displayed and scanned MUST be +compatible with [ISO/IEC 18004:2015](https://www.iso.org/standard/62021.html) and contain a single segment that uses the byte mode encoding. The error correction level can be chosen by the device displaying the QR code. -The binary segment must be of the following form: +The binary segment MUST be of the following form: - the string `MATRIX` encoded as one ASCII byte per character (i.e. `0x4D`, `0x41`, `0x54`, `0x52`, `0x49`, `0x58`) From cb4c33bf0486e7dfbdf0d8175366b5cef8f038ec Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Wed, 12 Jun 2024 16:59:35 +0100 Subject: [PATCH 5/6] Update content/client-server-api/modules/end_to_end_encryption.md --- content/client-server-api/modules/end_to_end_encryption.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/client-server-api/modules/end_to_end_encryption.md b/content/client-server-api/modules/end_to_end_encryption.md index 610e6d33a..672914c62 100644 --- a/content/client-server-api/modules/end_to_end_encryption.md +++ b/content/client-server-api/modules/end_to_end_encryption.md @@ -1200,7 +1200,7 @@ The binary segment MUST be of the following form: 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 encoded as a UTF-8 string (i.e. one UTF-8 byte per character) + - the ID encoded as a UTF-8 string - the first key, as 32 bytes. The key to use depends on the mode field: - if `0x00` or `0x01`, then the current user's own master cross-signing public key - if `0x02`, then the current device's Ed25519 signing key From d57b23269d3ba582112167b236d41216e0c53cd1 Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Wed, 12 Jun 2024 17:02:00 +0100 Subject: [PATCH 6/6] Clarify that we are talking about public keys --- content/client-server-api/modules/end_to_end_encryption.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/client-server-api/modules/end_to_end_encryption.md b/content/client-server-api/modules/end_to_end_encryption.md index 672914c62..ef36a0574 100644 --- a/content/client-server-api/modules/end_to_end_encryption.md +++ b/content/client-server-api/modules/end_to_end_encryption.md @@ -1206,11 +1206,11 @@ The binary segment MUST be of the following form: - if `0x02`, then the current device's Ed25519 signing key - the second key, as 32 bytes. The key to use depends on the mode field: - if `0x00`, then what the device thinks the other user's master - cross-signing key is + cross-signing public key is - if `0x01`, then what the device thinks the other device's Ed25519 signing + public key is + - if `0x02`, then what the device thinks the user's master cross-signing public key is - - if `0x02`, then what the device thinks the user's master cross-signing key - is - a random shared secret, as a sequence of bytes. 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