From 24e2242f8d1e790df641b084d5541b8752ea9b16 Mon Sep 17 00:00:00 2001 From: Hugh Nimmo-Smith Date: Thu, 4 Apr 2024 15:53:03 +0100 Subject: [PATCH] Add description of QR format --- proposals/4108-oidc-qr-login.md | 63 +++++++++++++++++++++++++++- proposals/images/4108-qr-mode03.png | Bin 0 -> 921 bytes proposals/images/4108-qr-mode04.png | Bin 0 -> 1019 bytes 3 files changed, 62 insertions(+), 1 deletion(-) create mode 100644 proposals/images/4108-qr-mode03.png create 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 c7b23eb3..7a9a605f 100644 --- a/proposals/4108-oidc-qr-login.md +++ b/proposals/4108-oidc-qr-login.md @@ -1297,7 +1297,68 @@ Example: ### QR code format -TODO +The proposed format of the QR code intends to be similar to that which is already described in the Client-Server API for +[device verification](https://spec.matrix.org/v1.9/client-server-api/#qr-code-format). + +Additional modes are added to the byte used for "QR code verification mode" to allow for the two login intents: initiate +on a new device; reciprocate on an existing device; + +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 intent/mode. Should be one of the following values: + - `0x03` a new device wishing to initiate a login and self-verify + - `0x04` an existing device wishing to reciprocate the login of a new device and self-verify that other device +- the ephemeral Curve25519 public key, as 32 bytes +- the rendezvous session URL encoded as: + - two bytes in network byte order (big-endian) indicating the length in bytes of the rendezvous session URL as a UTF-8 + string + - the rendezvous session URL as a UTF-8 string +- If the QR code intent/mode is `0x04` then the homeserver base URL encode as: + - two bytes in network byte order (big-endian) indicating the length in bytes of the homeserver base URL as a UTF-8 string + - the homeserver base URL as a UTF-8 string + +For example, if Alice displays a QR code encoding the following binary string: + +This indicates that Alice is a new device that wishes to initiate a login using her ephemeral public key of +`0001020304050607...` (which is `AAECAwQFBg…` in base64), via the rendezvous session at URL `https:/…`. + +#### Example for QR code generated on new device + +A full example for a new device using ephemeral public key `2IZoarIZe3gOMAqdSiFHSAcA15KfOasxueUUNwJI7Ws` (base64 +encoded) at rendezvous session `https://rendezvous.lab.element.dev/e8da6355-550b-4a32-a193-1619d9830668` is as follows: +(Whitespace is for readability only) + +``` +4D 41 54 52 49 58 02 03 +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 47 +68 74 74 70 73 3a 2f 2f 72 65 6e 64 65 7a 76 6f 75 73 2e 6c 61 62 2e 65 6c 65 6d 65 6e 74 2e 64 65 76 2f 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 +``` + +Which looks as follows as a QR with error correction level Q: + +![Example QR for mode 0x03](images/4108-qr-mode03.png) + +#### Example for QR code generated on existing device + +A full example for an existing device using ephemeral public key `2IZoarIZe3gOMAqdSiFHSAcA15KfOasxueUUNwJI7Ws` (base64 +encoded), at rendezvous session `https://rendezvous.lab.element.dev/e8da6355-550b-4a32-a193-1619d9830668` on homeserver +`https://matrix-client.matrix.org` is as follows: (Whitespace is for readability only) + +``` +4D 41 54 52 49 58 02 04 +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 47 +68 74 74 70 73 3a 2f 2f 72 65 6e 64 65 7a 76 6f 75 73 2e 6c 61 62 2e 65 6c 65 6d 65 6e 74 2e 64 65 76 2f 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 20 +68 74 74 70 73 3a 2f 2f 6d 61 74 72 69 78 2d 63 6c 69 65 6e 74 2e 6d 61 74 72 69 78 2e 6f 72 67 +``` + +Which looks as follows as a QR with error correction level Q: + +![Example QR for mode 0x04](images/4108-qr-mode04.png) ### Discoverability of the capability diff --git a/proposals/images/4108-qr-mode03.png b/proposals/images/4108-qr-mode03.png new file mode 100644 index 0000000000000000000000000000000000000000..4e1a629f17d2a711eb724b615c60a25e2ff2390c GIT binary patch literal 921 zcmV;K17`e*P)-o(5S${5q66 zbxOYQwZ-wx=j_HIj%q%2d=y>@@y*^GC6oE=y-jo-QNt6}A)N0r_Rb#h zc@7$$Ba+3Rw3I6cyL)py`L^;zIKfIDw}$%e*>=!yB)dsZn%$jCxYq7Mk16==&K|Ym zaVR)PwCFc}D^J*4xVY5bGlH+4xo9}z6VVVPcu)2wvpw~1<;h=LvDoMA$GNk2$J^(< zjXX2Lqsc2o00Q;GMfMt=JW{T`JKyn2&L)2jtl_zwL!sGUIM9UC?C>@XPaf@!u7JLo z9SRWfH4V?Pk`rxQyNadT@$RjHBgfT0H`kf1h}Pja6#RBX9$6dcEmpBb>U12DuZ;Yd9mm&Ek(VLoGext9X$HSUXs@*&@`5$Z0sEVscX+ zM|1Y}CVhOQm2-uxZPBb9ERs21pZn6vF*e*JbI1_jAZUj1yZ=U>Jj51Dv_$wU`rKsJ za3r`pc=R|hif=g5^yJ&hbEq>m8K1<-X1Rl`;Ver_G`l~^!5q&wYdAKB;cAJJH5VM{ z_|cPQUM`rm1Sgpvl603lc(q~R<_ zm$}h?{koMiW-8PTrZ4%f-tOPIv5hC_8{rvK1Vjn0jb3F1hav8r;ez2owD<1Ns8+!r z$H$n5HZTX~^GL6t;tYR8rZ5qhBjUr|G+gH4zz5?f%_dU~Mq*a*XFi9RRLtk(Wynt- zziZ_|^glg)zLWU%Ctn4ZhQzHAvBhyn8Fd^LgSWyWk3yLGe(6jjN4_5A!oUyp#$_?T v=BqZ2`Y)nvk}vLWPmmN1|5N`j|DF6Fc-by`AI33y00000NkvXXu0mjfFv!BI literal 0 HcmV?d00001 diff --git a/proposals/images/4108-qr-mode04.png b/proposals/images/4108-qr-mode04.png new file mode 100644 index 0000000000000000000000000000000000000000..68dc9c93b337ca6361f5a6ff9c74ca2389568f7e GIT binary patch literal 1019 zcmVCx^6yHZ!DU#pYmCk>|l zy!RO5|N77$^1tLHnk#cG7dNs*ArFx{Ey0C3-&$+ zeM<1T@$_tt)cQbEkjtzkcW51>sNf_=uDl1{wB(ZeU=nEw%qf$_9OXevaGxRZZP8~r z{>tb)>4`Nrj#(X9j8B`aTVtN}q)i@oaFfSGn=QJ5$3sg_UryOtv*Eneb%3?4T5=Qm zgYhvZxgq5#j2C8HOHOYNmbvZ&23&fDN~~IP)lB%?$>DA!V_5D`SW9jiPtUu>qdQ38 z5&0EHHQ`EYLc`reWvk;+F*v!?k}H-Ml`DxbZ>XqueQ>LmFpHd=)*Kbruq&uRQxmCy z9dA!vl%1Pn?$Wqv3DkX-^FoYWZ_%ID)6bS@2tzd!T9onVL&Y^fTD9c#Q1rY&u@cn% z5m79PmT)pxg=6H2(ByK;5VcuLt|Ya*WCmg2Z3>yl99nV`Rs_}!CBP~}m7j&ylB;5( z8=?eRM;@!po9v&GFq#v_JB+*dt!UoGr6y zFD*Ge_O;y5X2Px%t};G@mf(r6WM08Q?2%UBy2w6MaVHCn-St z^=%EgDy-F*AR%xR%xOq`+MG^#DPvrm|KUpu4rB)HF#dde)^*$ z5>If_Enz>LI2-@o=X3H%yV#BhgQO>e%(!Zayw9B@$|rYj>iB1002ovPDHLkV1m3z<&ppZ literal 0 HcmV?d00001