- One sentense With this patch series, QEMU would fully emulate an open-source secure key, CanoKey, with supports of various features listed below:
* U2F / FIDO2 with Ed25519 and HMAC-secret * OpenPGP Card V3.4 with RSA4096, Ed25519 and more * PIV (NIST SP 800-73-4) * HOTP / TOTP - What's New Although we have seen multiple emulated devices providing different functionalities for different purposes such as U2F (hw/usb/u2f-emulated.c) and CAC (hw/usb/ccid-card-emulated.c), modern secure key needs more advanced protocols like FIDO2 (WebAuthn, in comparison to U2f) and PIV (in comparison to CAC), which is not implemented previously. Other features like OpenPGP / TOTP are also not implemented before, at least as an emulated functionality. - Why get upstreamed At Canokeys.org, virtual cards on its own are for testing and debugging on the key itself. We have implemented various virt-cards including fido-hid-over-udp and USB/IP on our CI for testing and developer debuging. As we found emulated U2F and CAC in QEMU mainline, we estimated we could implement such features as well, which is good for testing since now we can emulate the whole key as an USB device, and we implemented it! as presented by this patch series. The story doesn't end here. As CanoKey QEMU is a fully functional key and it is inside QEMU, we think this emulated device could reach a wider audience other than CanoKey developers: projects using secure key can also benefit from it. For example, this device can be used in CI for projects using secure key. Bringing up a VM using QEMU with CanoKey QEMU, now we have an environment with secure key, and we can test the correctness of the behavior of the code. Another example is that as it is fully emulated rather than some hardware, all traces/debug logs can be easily extracted, which is helpful for developpers to debug. One note though, using CanoKey QEMU as a daily secure key is not recommended as the secret key in the emulated key is not protected by hardware. - Implementation details CanoKey implements all these platform independent features in canokey-core https://github.com/canokeys/canokey-core, and leaves the USB implementation to the platform, thus in this patch series we implemented the USB part in QEMU platform using QEMU's USB APIs, therefore the emulated CanoKey can communicate with the guest OS using USB. Some note though, CanoKey also has a NFC interface, thus we can implement the NFC part in QEMU and expose CanoKey to the guest as an NFC device. This is left as future work. In the meanwhile, unlike other emulated device which has a passthrough counterpart, CanoKey QEMU does not provide a passthrough mode as a whole since CanoKey has multiple interfaces which is hard to passthrough. (Left as future work, passthrough via WebUSB interface) You may try to use u2f-passthru and ccid-card-passthru to pass the U2F and CCID (e.g. OpenPGP, PIV) part of a real (or virtual, referring to USB/IP) CanoKey on the host to the guest. --- v1 -> v2: * Use trace events instead of printf to log canokey.c function call * Update debug instructions (trace, pcap) in CanoKey doc * Drop commit about legacy -usbdevice usage v2 -> v3: * Fix code style in commit hw/usb/canokey: Add trace events * Move docs/canokey.txt to docs/system/devices/canokey.rst v3 -> v4: * Refactor canokey.c into single thread version. This version is much easier to understand and review * Add more comments * Add links to canokey.rst in usb.rst * Update MAINTAINERS canokey docs file v4 -> v5: * Fix compile when there is no libcanokey-qemu * Separate canokey-qemu repo from canokey-core (doc change) * Categorize canokey into Misc devices * Add high speed support (thus usb-ehci) can use it * State the limitation when used with qemu-xhci About the qemu-xhci issue, see patch [PATCH v5 4/6] for more detail This patchset passes the CI, see https://gitlab.com/ZenithalHourlyRate/qemu/-/pipelines/543016316 Hongren (Zenithal) Zheng (6): hw/usb: Add CanoKey Implementation hw/usb/canokey: Add trace events meson: Add CanoKey docs: Add CanoKey documentation docs/system/devices/usb: Add CanoKey to USB devices examples MAINTAINERS: add myself as CanoKey maintainer MAINTAINERS | 8 + docs/system/device-emulation.rst | 1 + docs/system/devices/canokey.rst | 168 +++++++++++++++++ docs/system/devices/usb.rst | 4 + hw/usb/Kconfig | 5 + hw/usb/canokey.c | 313 +++++++++++++++++++++++++++++++ hw/usb/canokey.h | 69 +++++++ hw/usb/meson.build | 5 + hw/usb/trace-events | 16 ++ meson.build | 6 + meson_options.txt | 2 + scripts/meson-buildoptions.sh | 3 + 12 files changed, 600 insertions(+) create mode 100644 docs/system/devices/canokey.rst create mode 100644 hw/usb/canokey.c create mode 100644 hw/usb/canokey.h -- 2.35.1
