- 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


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  | 158 ++++++++++++++++
 docs/system/devices/usb.rst      |   4 +
 hw/usb/Kconfig                   |   5 +
 hw/usb/canokey.c                 | 311 +++++++++++++++++++++++++++++++
 hw/usb/canokey.h                 |  69 +++++++
 hw/usb/meson.build               |   3 +
 hw/usb/trace-events              |  16 ++
 meson.build                      |   6 +
 meson_options.txt                |   2 +
 scripts/meson-buildoptions.sh    |   3 +
 12 files changed, 586 insertions(+)
 create mode 100644 docs/system/devices/canokey.rst
 create mode 100644 hw/usb/canokey.c
 create mode 100644 hw/usb/canokey.h

-- 
2.34.1

Hi,

Is there any further feedback on this patch set.

Regards,

Zenithal

On Sat, Feb 12, 2022 at 09:29:47PM +0800, Hongren (Zenithal) Zheng wrote:
> Hi,
> 
> Is there any further feedback on this patch set.

Sorry for the looong delay, I'm rather busy with edk2.

Tried to queue up this, noticed it breaks the build in case the
canokey library is not installed.

I'd suggest to run the patch series through the qemu gitlab CI
before sending out v5.

take care,
  Gerd

On Fri, Mar 04, 2022 at 11:51:19AM +0100, Gerd Hoffmann wrote:
> On Sat, Feb 12, 2022 at 09:29:47PM +0800, Hongren (Zenithal) Zheng wrote:
> > Hi,
> > 
> > Is there any further feedback on this patch set.
> 
> Sorry for the looong delay, I'm rather busy with edk2.

Fully understandable. There is also delay on my side, sorry for that
too.

> 
> Tried to queue up this, noticed it breaks the build in case the
> canokey library is not installed.

Yes, this is my fault. I forgot to put `softmmu_ss.add(canokey)`
inside a `if canokey.found()` conditional check.

I've fixed it with 
https://gitlab.com/ZenithalHourlyRate/qemu/-/commit/5d8604c70abefc8146dbb4f7836f3215bc9df966
which will be contained in v5.

> 
> I'd suggest to run the patch series through the qemu gitlab CI
> before sending out v5.

I have gone through qemu gitlab CI and the result is in
https://gitlab.com/ZenithalHourlyRate/qemu/-/pipelines/497317417
Except check-dco and check-patch (I only generate Signed-off-by line
when `git format-patch`), other failed checks are "allowed to fail" and
I've checked the log, these failures are about Debian RISC-V packages
instead of qemu itself.

Is this appropriate for sending out v5?

By the way, we are planning to separate libcanokey-qemu.so
from canokey-core to a dedicated repo at
https://github.com/canokeys/canokey-qemu
(not done yet), which would result in changes in documentation.
I will contain these changes in v5 once we are done.

> 
> take care,
>   Gerd
> 

Regards,

Hongren

  Hi,

> > I'd suggest to run the patch series through the qemu gitlab CI
> > before sending out v5.
> 
> I have gone through qemu gitlab CI and the result is in
> https://gitlab.com/ZenithalHourlyRate/qemu/-/pipelines/497317417
> Except check-dco and check-patch (I only generate Signed-off-by line
> when `git format-patch`), other failed checks are "allowed to fail" and
> I've checked the log, these failures are about Debian RISC-V packages
> instead of qemu itself.

Sounds fine.  The risc-v bits seem to be in progress still, I have
failures with them too.

> Is this appropriate for sending out v5?
> 
> By the way, we are planning to separate libcanokey-qemu.so
> from canokey-core to a dedicated repo at
> https://github.com/canokeys/canokey-qemu
> (not done yet), which would result in changes in documentation.
> I will contain these changes in v5 once we are done.

If you want split the library it makes sense to do that (and test in CI)
before sending out v5.

No need to hurry right now, qemu is in freeze for the 7.0 release so it
can be merged only after the tree re-opens for 7.1 development (roughly
one month from now).

take care,
  Gerd