From a4af2d6ad26fc90b49b82a43943cc8ba189a5b1e Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Mon, 3 Nov 2025 16:20:33 +0000 Subject: [PATCH] Update QR code format under "type" 0x03 The byte immediately following the `MATRIX` prefix is repurposed as a type which gives a more sensible way to namespace in future. This also means that we can call the second byte the "intent" very clearly rather than having to call it "mode" to match the existing cross verification QR spec. --- proposals/4108-oidc-qr-login.md | 77 +++++++++--------- proposals/images/4108-qr-intent00.png | Bin 0 -> 810 bytes .../images/4108-qr-intent01-unstable.png | Bin 0 -> 815 bytes proposals/images/4108-qr-intent01.png | Bin 0 -> 817 bytes proposals/images/4108-qr-mode03.png | Bin 809 -> 0 bytes proposals/images/4108-qr-mode04-unstable.png | Bin 813 -> 0 bytes proposals/images/4108-qr-mode04.png | Bin 816 -> 0 bytes 7 files changed, 40 insertions(+), 37 deletions(-) create mode 100644 proposals/images/4108-qr-intent00.png create mode 100644 proposals/images/4108-qr-intent01-unstable.png create mode 100644 proposals/images/4108-qr-intent01.png delete mode 100644 proposals/images/4108-qr-mode03.png delete mode 100644 proposals/images/4108-qr-mode04-unstable.png delete mode 100644 proposals/images/4108-qr-mode04.png diff --git a/proposals/4108-oidc-qr-login.md b/proposals/4108-oidc-qr-login.md index 78e906786..bf488099c 100644 --- a/proposals/4108-oidc-qr-login.md +++ b/proposals/4108-oidc-qr-login.md @@ -399,26 +399,29 @@ Mitigations that are included in this proposal: ### QR code format -Once a device creates the rendezvous session it then generates a QR code that contains sufficient information for the -scanning device to locate the rendezvous session and establish the secure channel (as described in the -[next section](#secure-channel)). +To get a good trade-off between visual compactness and high level of error correction we use a binary mode QR with a +similar structure to that of the existing Device Verification QR code encoding described in [Client-Server +API](https://spec.matrix.org/v1.9/client-server-api/#qr-code-format). It is proposed that the QR code format that is currently used in the Client-Server API for [device verification](https://spec.matrix.org/v1.16/client-server-api/#qr-code-format) be extended to be more general -purpose and accommodate this new use case. +purpose and accommodate this new use case, and future use cases. -The "QR code verification mode" would be changed to be something more general like "QR code mode". +The "QR code version" would be repurposed to be a "QR code type" and used as the way to distinguish the format of the +subsequent data. -We then define two new modes to allow for the two login device dispositions: the new device wishing to login; an existing -device wishing to facilitate the login of the new device; +The existing cross verification code would be type `0x02`. I suspect that type `0x01` and `0x00` might correspond to +earlier iterations of the cross signing flow and so might want to be "reserved". + +This proposal then adds a new type `0x03`. The QR codes to be displayed and scanned using this format will encode binary strings in the general form: - the ASCII string `MATRIX` -- one byte indicating the QR code version (must be `0x02`) -- one byte indicating the QR code mode. Should be one of the following values: - - `0x03` a new device wishing to login and self-verify - - `0x04` an existing device wishing to facilitate the login of a new device and self-verify that other device +- one byte indicating the QR code type: `0x03` which identifies that the QR is part of this proposal +- one byte indicating the intent of the device generating the QR: + - `0x00` a new device wishing to login and self-verify + - `0x01` an existing device wishing to facilitate the login of a new device and self-verify that other device - the ephemeral Curve25519 public key that will be used for [secure channel establishment](#establishment), as 32 bytes - the rendezvous session ID encoded as: - two bytes in network byte order (big-endian) indicating the length in bytes of the rendezvous session ID as a UTF-8 @@ -429,7 +432,7 @@ The QR codes to be displayed and scanned using this format will encode binary st - the server name as a UTF-8 string If a new version of this QR sign in capability is needed in future (perhaps with updated secure channel protocol) then -additional "mode" values can be added. +an additional type can then be allocated which would clearly distinguish this later version. #### Example for QR code generated on new device @@ -440,7 +443,7 @@ encoded) at rendezvous session ID `e8da6355-550b-4a32-a193-1619d9830668` on home ``` 4D 41 54 52 49 58 -02 03 +03 00 d8 86 68 6a b2 19 7b 78 0e 30 0a 9d 4a 21 47 48 07 00 d7 92 9f 39 ab 31 b9 e5 14 37 02 48 ed 6b 00 24 65 38 64 61 36 33 35 35 2D 35 35 30 62 2D 34 61 33 32 2D 61 31 39 33 2D 31 36 31 39 64 39 38 33 30 36 36 38 @@ -453,14 +456,14 @@ Which looks as follows as a QR with error correction level Q: Generated with: nix-shell -p qrencode --run 'echo "4D 41 54 52 49 58 -02 03 +03 00 d8 86 68 6a b2 19 7b 78 0e 30 0a 9d 4a 21 47 48 07 00 d7 92 9f 39 ab 31 b9 e5 14 37 02 48 ed 6b 00 24 65 38 64 61 36 33 35 35 2D 35 35 30 62 2D 34 61 33 32 2D 61 31 39 33 2D 31 36 31 39 64 39 38 33 30 36 36 38 00 0A -6d 61 74 72 69 78 2e 6f 72 67" | xxd -r -p | qrencode -8 -l Q -t PNG -o ./proposals/images/4108-qr-mode03.png' +6d 61 74 72 69 78 2e 6f 72 67" | xxd -r -p | qrencode -8 -l Q -t PNG -o ./proposals/images/4108-qr-intent00.png' --> -![Example QR for mode 0x03](images/4108-qr-mode03.png) +![Example QR for intent 0x00](images/4108-qr-intent00.png) #### Example for QR code generated on existing device @@ -469,7 +472,7 @@ encoded), at rendezvous session ID `e8da6355-550b-4a32-a193-1619d9830668` on hom ``` 4D 41 54 52 49 58 -02 04 +03 01 d8 86 68 6a b2 19 7b 78 0e 30 0a 9d 4a 21 47 48 07 00 d7 92 9f 39 ab 31 b9 e5 14 37 02 48 ed 6b 00 24 65 38 64 61 36 33 35 35 2D 35 35 30 62 2D 34 61 33 32 2D 61 31 39 33 2D 31 36 31 39 64 39 38 33 30 36 36 38 @@ -482,14 +485,14 @@ Which looks as follows as a QR with error correction level Q: Generated with: nix-shell -p qrencode --run 'echo "4D 41 54 52 49 58 -02 04 +03 01 d8 86 68 6a b2 19 7b 78 0e 30 0a 9d 4a 21 47 48 07 00 d7 92 9f 39 ab 31 b9 e5 14 37 02 48 ed 6b 00 24 65 38 64 61 36 33 35 35 2D 35 35 30 62 2D 34 61 33 32 2D 61 31 39 33 2D 31 36 31 39 64 39 38 33 30 36 36 38 00 0A -6d 61 74 72 69 78 2e 6f 72 67" | xxd -r -p | qrencode -8 -l Q -t PNG -o ./proposals/images/4108-qr-mode04.png' +6d 61 74 72 69 78 2e 6f 72 67" | xxd -r -p | qrencode -8 -l Q -t PNG -o ./proposals/images/4108-qr-intent01.png' --> -![Example QR for mode 0x04](images/4108-qr-mode04.png) +![Example QR for intent 0x01](images/4108-qr-intent01.png) ### Secure channel @@ -537,7 +540,10 @@ with an empty payload. It parses the **ID** received. 3. **Initial key exchange** -Device G displays a QR code containing: +Device G displays a QR code containing sufficient information for the scanning device to locate the rendezvous session +and establish the secure channel (as described in the [next section](#secure-channel)). + +The information to be encoded is: - Its public key **Gp** - The insecure rendezvous session **ID** @@ -545,11 +551,7 @@ Device G displays a QR code containing: that wishes to facilitate the login of the new device - the Matrix homeserver **[server name](https://spec.matrix.org/v1.15/appendices/#server-name)** -To get a good trade-off between visual compactness and high level of error correction we use a binary mode QR with a -similar structure to that of the existing Device Verification QR code encoding described in [Client-Server -API](https://spec.matrix.org/v1.9/client-server-api/#qr-code-format). - -This is defined in detail in a separate section of this proposal. +The format of this QR is defined in detail in a [separate section](#qr-code-format) of this proposal. Device S scans and parses the QR code to obtain **Gp**, the rendezvous session **ID**, **intent** and the Matrix homeserver **[server name](https://spec.matrix.org/v1.15/appendices/#server-name)**. @@ -1634,15 +1636,14 @@ will soon be verified. ### Alternative QR code formats -Instead of extending the existing QR code format and adding new "modes", alternatives include: +An earlier version of this proposal kept the "version" byte at `0x02` and added additional "mode" +values of `0x03` (which is now intent `0x00`) and `0x04` (which is now intent `0x01`). -- using a different prefix to namespace the data (e.g. `MATRIX_LOGIN` instead of `MATRIX`) -- keep the `MATRIX` prefix and repurpose the current "version" byte to be something like "type". For example: - - type = `0x02` could be the verification format described in the current spec - - type = `0x03` could be for this proposal +The current usage of converting the "version" to be a "type" _feels_ like a more intuitive use of +the bytespace. -The purpose being that we end up with the QR being better namespaced (whilst also remaining compact) making future -versioning simpler. +Another alternative was to use a human readable prefix such as `MATRIX_LOGIN` instead of `MATRIX`. +This was discounted on the basis of wanting to keep the QR reasonably compact. ## Security considerations @@ -1715,7 +1716,7 @@ encoded), at rendezvous session ID `e8da6355-550b-4a32-a193-1619d9830668` on hom ``` 49 4F 5F 45 4C 45 4D 45 4E 54 5F 4D 53 43 34 31 30 38 -02 04 +03 01 d8 86 68 6a b2 19 7b 78 0e 30 0a 9d 4a 21 47 48 07 00 d7 92 9f 39 ab 31 b9 e5 14 37 02 48 ed 6b 00 24 65 38 64 61 36 33 35 35 2D 35 35 30 62 2D 34 61 33 32 2D 61 31 39 33 2D 31 36 31 39 64 39 38 33 30 36 36 38 @@ -1728,14 +1729,16 @@ Which looks as follows as a QR with error correction level Q: Generated with: nix-shell -p qrencode --run 'echo "49 4F 5F 45 4C 45 4D 45 4E 54 5F 4D 53 43 34 31 30 38 -02 04 +03 01 d8 86 68 6a b2 19 7b 78 0e 30 0a 9d 4a 21 47 48 07 00 d7 92 9f 39 ab 31 b9 e5 14 37 02 48 ed 6b 00 24 65 38 64 61 36 33 35 35 2D 35 35 30 62 2D 34 61 33 32 2D 61 31 39 33 2D 31 36 31 39 64 39 38 33 30 36 36 38 00 0A -6d 61 74 72 69 78 2e 6f 72 67" | xxd -r -p | qrencode -8 -l Q -t PNG -o ./proposals/images/4108-qr-mode04-unstable.png' +6d 61 74 72 69 78 2e 6f 72 67" | xxd -r -p | qrencode -8 -l Q -t PNG -o ./proposals/images/4108-qr-intent01-unstable.png' --> -![Example QR for mode 0x04](images/4108-qr-mode04-unstable.png) +![Example QR for intent 0x01](images/4108-qr-intent01-unstable.png) + +It is suggested that this unstable QR prefix convention could be used by future proposals. ### M_CONCURRENT_WRITE errcode diff --git a/proposals/images/4108-qr-intent00.png b/proposals/images/4108-qr-intent00.png new file mode 100644 index 0000000000000000000000000000000000000000..beed4414556306c188e53900d408c650ceed3f7c GIT binary patch literal 810 zcmV+_1J(SAP)C zmpjg*FcgI^a^Ws)z>>G&&RfD82(SUzk~?q1k~aXI3yV9)dFY>FMw&}IC?V)eL~@_! zg!qpK{onW?nqyghMSy@BF>D2uFp1Af1PppRR?fZs5z&@ENK0^!C#Bl;eZ!-a(sCJq)^2yBwbpj3%#; zr!lrMwONiYDtqcZxad6cs~_d~K)H19Um`OktYI_D@kRD<86nQmOb%Q8lR+8QCNN<| zg@|pJLwZ+UhELoqT7)mSg1m!dOSO5NfWt_p%r>gJFzt z?$SE>?^jCj<#4kcDt;sOHgPVn`Qk;xZop`lKBIEn^UZ3} ojWD1U68BD(4FBc7)PIbB0cUlCI3%rw5dZ)H07*qoM6N<$f@(~GhX4Qo literal 0 HcmV?d00001 diff --git a/proposals/images/4108-qr-intent01-unstable.png b/proposals/images/4108-qr-intent01-unstable.png new file mode 100644 index 0000000000000000000000000000000000000000..886b8b0eb559342452c6579dc0951b4496e130d6 GIT binary patch literal 815 zcmV+~1JL}5P)C zm%WYTFbsuhC{SiMU_fmsQ%iOO{%OE&NtxOZpa$$rfneU#%q(_;3y#7?cZ0#e_zc)2 z#rMb|{_ThUZ+sC=npRGCj=eLtr%sMTx5v*aZ+d_Txh7vgu^AXSD~K+c4q^ z<{`YqoUM4yWkGb5HmA4^bD79+j%&d0xPB)uz^L~e#_#Xf%Q5@X6BL;aoe=3_Qv-e|ogQU2JFCl)rw2utGd#vTuFRR%5PQuH z7;5MpdIvWVW7_DezaQb)<2er%b^)m0x!Zpiep)GUE@g1o1u_q`S*9niG<@nOo?IueTCII~V zqe~gSxn_1}K5XnQ{N`OM8GbZx4vw2Piy6zff66gh5B6}8LZoobnyVZ?7|uTJ!JHUt zoZwrh9Amm7xgn2>9^cJ4H{eiZjTv&(lD`%ZIer{`C7l7!HoK2&{$we_cc=wE2ooLw z)<$T+>@if$VPO@JxcXXKWEg@*y?iD)`fA%=)O2W<@8yJL>M3V)9F#~vRF*EaggKJj*KF~tLnah_snu!_d)mC2Yp%V zx?%1HT-)F5q3$e@6y{_j_L$Pxj;o~Z{2oVQJZa3sh!Ks29h=?WfRQC!%0kwtcNs#N tC zmobi{Fc3uxIdBFSu;gnv^Of)g8n^&l$(gTVi3>pHz@qlMo6$_LD{YYuq7i!C0=ugI zuWI7I9`w8MK{UmEcIHLAYCa=%a(r?fX#rgmKtg-3WQc8j_9 zc_?aoieDakHAHGDil1SwQ{vg9EM_-}ks zo*4V9M77sBaQjAz4{tdk;Ra{#?5goAF$N2BS?$_tnKR5p)Jetne3sFc_OzjF(c}O93$SN z-_NKHpF`x0zg{W92VqgUi|pYt);L9|3NC&}P=>t; zOt7dB;dVKsPv&L#EcT3chA|*cjGx#|j`8W<5h4vW>@(e^DZ-aiSmO{C3}$1+t(L`@ z84NPQwYApKf4x$IFNcTaP_Rb$H%!8Gatu9%(ryp8bIQH`^fVcUSFM`5XnIJz?5q3i zQijo2QFoA3DEr|oT;~BkTfHFdC;Eon4~o5ws;F^#W z&rY3keCRqvBnt87<~Mhrmth2R>)O1O0e&Gk0F?{i?F>YYA+_`+p vM}}LxSZFUEfW<2r29PK#cE00000NkvXXu0mjfE;WM> literal 0 HcmV?d00001 diff --git a/proposals/images/4108-qr-mode03.png b/proposals/images/4108-qr-mode03.png deleted file mode 100644 index f7c459e69d041215ce01bd7382a83d12f9e360ba..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 809 zcmV+^1J?YBP)C zmqD(pFbqYF7-R+;h?H$)mMy^s3f(~2QfApkq-+3Y8ASMB(>}d7_+R>F`VgY%vg|L0W%!8H>G8pBqVfv-#EoxV0@34W=hPpmf7a`oXugG)>b96i z&SUMjyZ8|ht0j`<`5xxBBwhoqmV92mgI8eWdrtQI{C*7zd>!R9ZHfF$ZTu;S|Hdcf zg$q|i*#?tmmT$Cp4~~-^W4{JFc=s~+l^Szu2yUQ)#82|5o^RkN>&=M~=$vS&cG2TA z&38G!4t9rxNaV{i<_@{PgArDq zuxiM2FFoq<9tdw9`XvM3g$>(9k56*D&r?7vu#<<2e=?}U!Ol#u zs5!#zP+K2CsPIwU5#0)7h%gxZ#BF*E!|tvO5z4}sl^pBw>1B`bDj3YhJ&Tsrm>CRZ zgsZgHDSRHO!dQFbJXh=yH35^bogVMdOO@N*7fyLF@1CZ^D9V@E4CGvnT3-Ggr4FO7 zPUs26b361hYhZ1O@e6KaEj` zF@<63saTj_-aVu3^q8w-F-`=E-GRO9Qisow34tb5HnI-i&C3mZ?NKI5kCNim_lF+u zrVX+xp1|TapFXd{IF6VJO&}uN@?_iT@iik~jwSOKCeyD@qQNpFoBouw2~|Ghn;RG{ z$P`SqWH5I$NU^(x(MDFWhlXx27<&^l@=a2gB=Za3z>MLGSA%f_gEpqiw|sP1^3DBf nnkccN#l2Id!~gg%^^5Tz4G?LvM%Jpu00000NkvXXu0mjfj#`Oo diff --git a/proposals/images/4108-qr-mode04-unstable.png b/proposals/images/4108-qr-mode04-unstable.png deleted file mode 100644 index 5ab3939a8a93e8882700e12838a7cf12533936b7..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 813 zcmV+|1JeA7P)C zmpzW-Fbsuhs8APQK!C2HPFJ!o;GYZFS5l{I2+#$r&V^v^lQWswVvD8Q2?8Ve3^3*s z`N$Ce^F_ZKA4DUomCYEbi?#&nzP+M=9rLHVN?*x2OmuL0JGgRZ;l3MFS08u zet<(AW1Ts#K^>X~&8r+AE_2KWrAaG}_)5JTqv(2u#&sfFPU_Cu$#Dr>B4oCgGvsM< z=m|MSuxJm>i??eu1HH>fhWWG`<;xpFerKH=&2oG=ID|dCd3iIQxc{y}8Aj|96V7Ts z@frP8dpSmPzo?R{(COtf3gH1hJS2zAC}$Wj@2qw?#%U80jfn^t*LOF_@IlbYE*dUX z;V~EpMUF3m-Y}RnMtjTljxEF<^$VLpY_t^m()4l+od~Cmt5#^QrR6HdXv#&mso1xu zY4UHqWw^C9)$UX~5=CRtXGBYIVT(lfsP^WX7zlQiWB5~tW7h_Thb%98&om)+YHyuX z@pKH&dxXoqDGW|+gkMnC=NLrzg252=7^Plh?9m#;I*=N5baDr6bH(3gz1 zu7gJ*w|T;H%$x>-*fjZ8MB~@8Aj3y1I#o_}xx8Vfoq3mI*d#pWwkvcwdVo?#(a#~)uYll7800000NkvXXu0mjf4_I}f diff --git a/proposals/images/4108-qr-mode04.png b/proposals/images/4108-qr-mode04.png deleted file mode 100644 index 829ee0032017c28c6b73c49e032ac1e6ba982a0b..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 816 zcmV-01JC@4P)C zmoe_7JPgH+Qlx_mM9MYN{3aYd>&$cxfZH=f*lQaOSPA`SZ|Tz6FuEQ8IjChD^RZ z&0dw5C!DD*a(vP8PDs+R>O67ph9JkMC(^xsiO^M$VYA5bMfP-g_OJqU6;%ArpbR?` zm>^LhLhW)$_s)xOskTIm5SIvn!B6a4j=9TZ&k#fcwY-vLIleUd+e}gIggsZ>Ygvq$ z!O%vy_9~eD{YeqN9A1_KWJW{3ArfYg;}i8#`|artPI=T{Pm^J2)vjrXX7op?$L_vS z$}oI&){Q*c`Z%2}$v(iP*9+c_5-_vJ=#eKmhNtx!tQp-fC41cql;NHsh$Z49RFL9& z8>0+k3ahHrt}eT?TQq|lbA`M1(dlwn9oV-oW%%-ab%mi-ZS>IHyga}?P=a!g4lTv2 zQ$>zX-9~B?e4szi^X>C8jH6)3`s{;nkB!YB$DbLw_xET1f+75N5((}zvQ`)DD8fn5 zPilLBVL=)`02RmF0j;{Hbt(SXNFN5_2BS6)F=NlE_a*iDg&$zXu)wRvxPd_%)8)5( uWVq*>)e4b7gH~AFH&rtHKmVovVf+iJ$7)5Ph_7$}0000R6-