[PATCH 3/6] docs: Add CanoKey documentation

[Hongren (Zenithal) Zheng]

Signed-off-by: Hongren (Zenithal) Zheng <i@zenithal.me>
---
 docs/canokey.txt | 133 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 133 insertions(+)
 create mode 100644 docs/canokey.txt

diff --git a/docs/canokey.txt b/docs/canokey.txt
new file mode 100644
index 0000000000..69262194c4
--- /dev/null
+++ b/docs/canokey.txt
@@ -0,0 +1,133 @@
+CanoKey QEMU Documentation.
+
+Contents
+1. CanoKey QEMU
+2. Building
+3. Using CanoKey QEMU
+4. Debuging
+5. Limitations
+6. References
+
+1. CanoKey QEMU
+
+CanoKey[1] is an open-source secure key with supports of
+
+ * U2F / FIDO2 with Ed25519 and HMAC-secret
+ * OpenPGP Card V3.4 with RSA4096, Ed25519 and more[2]
+ * PIV (NIST SP 800-73-4)
+ * HOTP / TOTP
+ * NDEF
+
+All these platform-independent code are in canokey-core[3].
+
+For different platforms, CanoKey has different implementations,
+including both hardware implementions and virtual cards:
+
+ * CanoKey STM32[4]
+ * CanoKey Pigeon[5]
+ * (virt-card) CanoKey USB/IP[6]
+
+In QEMU, yet another CanoKey virt-card is implemented.
+CanoKey QEMU exposes itself as a USB device to the guest OS.
+
+With the same configuration as what would be done for a hardware key,
+the guest OS can use all the functionalities of a secure key as if
+there was actually an hardware key plugged in.
+
+CanoKey QEMU provides much convenience for debuging:
+
+ * libcanokey-qemu supports debuging output thus developers can
+   trace what happens inside a secure key
+ * CanoKey QEMU supports debuging output, thus it can show USB packets.
+
+Then for developers:
+
+ * For developers on software with secure key support (e.g. FIDO2, OpenPGP),
+   they can see what happens inside the secure key
+ * For secure key developers, USB packets between guest OS and CanoKey
+   can be easily captured and analysed
+
+Also as this is a virtual card, it can be easily used in CI for testing
+on code coping with secure key.
+
+2. Building
+
+libcanokey-qemu is required to use CanoKey QEMU.
+
+    git clone https://github.com/canokeys/canokey-core
+    mkdir canokey-core/build
+    pushd canokey-core/build
+
+If you want to install libcanokey-qemu in a different place,
+add -DCMAKE_INSTALL_PREFIX=/path/to/your/place to cmake below.
+
+    cmake .. -DQEMU=ON
+    make
+    make install # may need sudo
+    popd
+
+Then configuring and building:
+
+    # depending on your env, lib/pkgconfig can be lib64/pkgconfig
+    export PKG_CONFIG_PATH=/path/to/your/place/lib/pkgconfig:$PKG_CONFIG_PATH
+    ./configure --enable-canokey && make
+
+3. Using CanoKey QEMU
+
+CanoKey QEMU stores all its data on a file of the host specified by the 
argument
+when invoking qemu.
+
+    qemu -usb -device canokey,file=$HOME/.canokey-file
+
+Note: you should keep this file carefully as it may contain your private key!
+
+The first time when the file is used, it is created and initialized by CanoKey,
+afterwards CanoKey QEMU would just read this file.
+
+After the guest OS boots, you can check that there is a USB device.
+
+For example, If the guest OS is an Linux machine. You may invoke lsusb
+and find CanoKey QEMU there:
+
+    $ lsusb
+    Bus 001 Device 002: ID 20a0:42d4 Clay Logic CanoKey
+
+You may setup the key as guided in https://docs.canokeys.org/
+
+The console for the key is at https://console.canokeys.org/
+
+4. Debuging
+
+CanoKey QEMU consists of two parts, libcanokey-qemu.so and canokey.c, the 
latter
+of which resides in QEMU. The former provides core functionality of a secure 
key
+while the latter provides platform-dependent functions: USB packet handling. 
+
+If you want to trace what happens inside the secure key, when compiling
+libcanokey-qemu, you should add -DENABLE_DEBUG_OUTPUT=ON in cmake command line:
+
+    cmake .. -DQEMU=ON -DENABLE_DEBUG_OUTPUT=ON
+
+And if you want to show the USB packet flow, you can uncomment DEBUG_CANOKEY
+in hw/usb/canokey.c and compile qemu again. Or even further if you want to
+show the USB packet payload, you can uncomment DEBUG_CANOKEY_DATA
+
+5. Limitations
+
+Currently libcanokey-qemu.so has dozens of global variables as it was 
originally
+designed for embedded systems. Thus one qemu instance can not have
+multiple CanoKey QEMU running, namely you can not
+
+    qemu -usb -device canokey,file=$HOME/.canokey-file\
+         -device canokey,file=$HOME/.canokey-file2
+
+Also, there is no lock on canokey-file, thus two CanoKey QEMU instance
+can not read one canokey-file at the same time.
+
+6. References
+
+[1] https://canokeys.org
+[2] https://docs.canokeys.org/userguide/openpgp/#supported-algorithm 
+[3] https://github.com/canokeys/canokey-core
+[4] https://github.com/canokeys/canokey-stm32
+[5] https://twitter.com/CanoKeys/status/1473647697744003072
+[6] https://github.com/canokeys/canokey-core#virt-card-usbip
-- 
2.34.0