Introduce CanoKey QEMU
PATCH v3 1/6 hw/usb: Add CanoKey Implementation
In reply to Hongren (Zenithal) ZhengThis commit added a new emulated device called CanoKey to QEMU.
CanoKey implements platform independent features in canokey-core
https://github.com/canokeys/canokey-core, and leaves the USB implementation to the platform.
In this commit the USB part was implemented in QEMU using QEMU's USB APIs, therefore the emulated CanoKey can communicate with the guest OS using USB.
--- hw/usb/canokey.c | 326 +++++++++++++++++++++++++++++++++++++++++++++++ hw/usb/canokey.h | 60 +++++++++ 2 files changed, 386 insertions(+) create mode 100644 hw/usb/canokey.c create mode 100644 hw/usb/canokey.h
hw/usb/canokey.c new file +326 -0
@@ -0,0 +1,326 @@ +/* +* CanoKey QEMU device implementation. +* +* Copyright (c) 2021-2022 Canokeys.org <[email protected]> +* Written by Hongren (Zenithal) Zheng <[email protected]> +* +* This code is licensed under the Apache-2.0. +*/ + +#include "qemu/osdep.h" +#include <canokey-qemu.h> + +#include "qemu/module.h" +#include "qemu/thread.h" +#include "qemu/main-loop.h" +#include "qapi/error.h" +#include "hw/usb.h" +#include "hw/qdev-properties.h" +#include "desc.h" +#include "canokey.h" + +#define CANOKEY_EP_IN (ep) ((ep) & 0x7F) + +#define CANOKEY_VENDOR_NUM 0x20a0 +#define CANOKEY_PRODUCT_NUM 0x42d2 + +/* +* placeholder, canokey-qemu implements its own usb desc +* Namely we do not use usb_desc_handle_contorl +*/ +enum { +STR_MANUFACTURER =1 , +STR_PRODUCT , +STR_SERIALNUMBER +}; + +static const USBDescStrings desc_strings = { + [STR_MANUFACTURER ] ="canokeys.org" , + [STR_PRODUCT ] ="CanoKey QEMU" , + [STR_SERIALNUMBER ] ="0" +}; + +static const USBDescDevice desc_device_canokey = { + .bcdUSB =0x0 , + .bMaxPacketSize0 =16 , + .bNumConfigurations =0 , + .confs =NULL , +}; + +static const USBDesc desc_canokey = { + .id = { + .idVendor =CANOKEY_VENDOR_NUM , + .idProduct =CANOKEY_PRODUCT_NUM , + .bcdDevice =0x0100 , + .iManufacturer =STR_MANUFACTURER , + .iProduct =STR_PRODUCT , + .iSerialNumber =STR_SERIALNUMBER , + }, + .full = &desc_device_canokey, + .str = desc_strings, +}; + + +/* Implement canokey-qemu functions */ +int canokey_emu_stall_ep (void *base,uint8_t ep) +{ +CanoKeyState *key = base; +uint8_t ep_in =CANOKEY_EP_IN (ep);/* INTR IN has ep 129 */ +qemu_mutex_lock (&key->ep_in_mutex[ep_in]); + key->ep_in_size[ep_in] =0 ; + key->ep_in_status[ep_in] =CANOKEY_EP_IN_STALL ; +qemu_mutex_unlock (&key->ep_in_mutex[ep_in]); +return 0 ; +} + +int canokey_emu_set_address (void *base,uint8_t addr) +{ +CanoKeyState *key = base; + key->dev.addr = addr; +return 0 ; +} + +int canokey_emu_prepare_receive ( +void *base,uint8_t ep,uint8_t *pbuf,uint16_t size) +{ +CanoKeyState *key = base; +/* +* No mutex here because it is usually called by +* canokey_emu_data_out (qemu thread), which already has mutex +*/ + key->ep_out[ep] = pbuf; + key->ep_out_size[ep] = size; +return 0 ; +} + +int canokey_emu_transmit ( +void *base,uint8_t ep,const uint8_t *pbuf,uint16_t size) +{ +CanoKeyState *key = base; +uint8_t ep_in =CANOKEY_EP_IN (ep);/* INTR IN has ep 129 */ +qemu_mutex_lock (&key->ep_in_mutex[ep_in]); +memcpy (key->ep_in[ep_in], pbuf, size); + key->ep_in_size[ep_in] = size; + key->ep_in_status[ep_in] =CANOKEY_EP_IN_READY ; +qemu_mutex_unlock (&key->ep_in_mutex[ep_in]); +return 0 ; +} + +uint32_t canokey_emu_get_rx_data_size (void *base,uint8_t ep) +{ +CanoKeyState *key = base; +return key->ep_out_size[ep]; +} + +static void *canokey_thread (void *arg) +{ +CanoKeyState *key = arg; + +while (true) { +/* Wait signal */ +qemu_mutex_lock (&key->key_mutex); +qemu_cond_wait (&key->key_cond, &key->key_mutex); +qemu_mutex_unlock (&key->key_mutex); + +/* Exit thread check */ +if (key->stop_thread) { + key->stop_thread = false; +break ; + } + +canokey_emu_device_loop (); + } +return NULL ; +} + +static void canokey_handle_reset (USBDevice *dev) +{ +CanoKeyState *key =CANOKEY (dev); +for (int i =0 ; i !=CANOKEY_EP_NUM ; ++i) { + key->ep_in_status[i] =CANOKEY_EP_IN_WAIT ; + key->ep_in_pos[i] =0 ; + } +canokey_emu_reset (); +} + +static void canokey_handle_control (USBDevice *dev,USBPacket *p, +int request,int value,int index,int length,uint8_t *data) +{ +CanoKeyState *key =CANOKEY (dev); + +canokey_emu_setup (request, value, index, length); +qemu_cond_signal (&key->key_cond); + +uint8_t ep_in =CANOKEY_EP_IN (p->ep->nr); +uint32_t dir_in = request & DeviceRequest; +if (!dir_in) { +/* OUT */ +qemu_mutex_lock (&key->key_mutex); +if (key->ep_out[0 ] !=NULL ) { +memcpy (key->ep_out[0 ], data, length); + } +canokey_emu_data_out (p->ep->nr, data); +qemu_cond_signal (&key->key_cond); +qemu_mutex_unlock (&key->key_mutex); + } + +/* IN */ +qemu_mutex_lock (&key->ep_in_mutex[ep_in]); +if (key->ep_in_status[ep_in] ==CANOKEY_EP_IN_WAIT ) { + p->status =USB_RET_NAK ; +qemu_mutex_unlock (&key->ep_in_mutex[ep_in]); +return ; + } +if (key->ep_in_status[ep_in] ==CANOKEY_EP_IN_STALL ) { + p->status =USB_RET_STALL ; + } + key->ep_in_status[ep_in] =CANOKEY_EP_IN_WAIT ; +memcpy (data, key->ep_in[ep_in], key->ep_in_size[ep_in]); + p->actual_length = key->ep_in_size[ep_in]; + +qemu_mutex_unlock (&key->ep_in_mutex[ep_in]); +} + +static void canokey_handle_data (USBDevice *dev,USBPacket *p) +{ +CanoKeyState *key =CANOKEY (dev); + +uint8_t ep_in =CANOKEY_EP_IN (p->ep->nr); +uint8_t ep_out = p->ep->nr; +uint32_t in_len; +switch (p->pid) { +case USB_TOKEN_OUT : +qemu_mutex_lock (&key->key_mutex); +if (p->iov.size > key->ep_out_size[ep_out]) { +/* unlikely we will reach here, but check still needed */ + p->status =USB_RET_NAK ; +qemu_mutex_unlock (&key->key_mutex); +break ; + } +usb_packet_copy (p, key->ep_out[ep_out], p->iov.size); + key->ep_out_size[ep_out] = p->iov.size; +canokey_emu_data_out (ep_out,NULL ); +qemu_cond_signal (&key->key_cond); +qemu_mutex_unlock (&key->key_mutex); +break ; +case USB_TOKEN_IN : +qemu_mutex_lock (&key->ep_in_mutex[ep_in]); +if (key->ep_in_pos[ep_in] ==0 ) { +canokey_emu_data_in (ep_in); +qemu_cond_signal (&key->key_cond); +if (key->ep_in_status[ep_in] ==CANOKEY_EP_IN_WAIT ) { + p->status =USB_RET_NAK ; +qemu_mutex_unlock (&key->ep_in_mutex[ep_in]); +break ; + } +if (key->ep_in_status[ep_in] ==CANOKEY_EP_IN_STALL ) { + p->status =USB_RET_STALL ; + } + key->ep_in_status[ep_in] =CANOKEY_EP_IN_WAIT ; + + in_len =MIN (key->ep_in_size[ep_in], p->iov.size); +usb_packet_copy (p, key->ep_in[ep_in], in_len); +if (in_len < key->ep_in_size[ep_in]) { + key->ep_in_pos[ep_in] = in_len; + } + }else { + in_len =MIN (key->ep_in_size[ep_in] - key->ep_in_pos[ep_in], + p->iov.size); +usb_packet_copy (p, + key->ep_in[ep_in] + key->ep_in_pos[ep_in], in_len); + key->ep_in_pos[ep_in] += in_len; +if (key->ep_in_pos[ep_in] == key->ep_in_size[ep_in]) { + key->ep_in_pos[ep_in] =0 ; + } + } +qemu_mutex_unlock (&key->ep_in_mutex[ep_in]); +break ; +default : + p->status =USB_RET_STALL ; +break ; + } +} + +static void canokey_realize (USBDevice *base,Error **errp) +{ +CanoKeyState *key =CANOKEY (base); + +if (key->file ==NULL ) { +error_setg (errp,"You must provide file=/path/to/canokey-file" ); +return ; + } + +usb_desc_init (base); + +/* Synchronization */ +qemu_cond_init (&key->key_cond); +qemu_mutex_init (&key->key_mutex); +for (int i =0 ; i !=CANOKEY_EP_NUM ; ++i) { +qemu_mutex_init (&key->ep_in_mutex[i]); + key->ep_in_status[i] =CANOKEY_EP_IN_WAIT ; + key->ep_in_pos[i] =0 ; + } + +if (canokey_emu_init (key, key->file)) { +error_setg (errp,"canokey can not create or read %s" , key->file); +return ; + } + +/* Thread */ + key->stop_thread = false; +qemu_thread_create (&key->key_thread,"canokey" , canokey_thread, + key,QEMU_THREAD_JOINABLE ); +} + +static void canokey_unrealize (USBDevice *base) +{ +CanoKeyState *key =CANOKEY (base); + +/* Thread */ + key->stop_thread = true; +qemu_cond_signal (&key->key_cond); +qemu_thread_join (&key->key_thread); + +/* Synchronization */ +qemu_cond_destroy (&key->key_cond); +qemu_mutex_destroy (&key->key_mutex); +for (int i =0 ; i !=CANOKEY_EP_NUM ; ++i) { +qemu_mutex_destroy (&key->ep_in_mutex[i]); + } +} + +static Property canokey_properties[] = { +DEFINE_PROP_STRING ("file" , CanoKeyState, file), +DEFINE_PROP_END_OF_LIST (), +}; + +static void canokey_class_init (ObjectClass *klass,void *data) +{ +DeviceClass *dc =DEVICE_CLASS (klass); +USBDeviceClass *uc =USB_DEVICE_CLASS (klass); + + uc->product_desc ="CanoKey QEMU" ; + uc->usb_desc = &desc_canokey; + uc->handle_reset = canokey_handle_reset; + uc->handle_control = canokey_handle_control; + uc->handle_data = canokey_handle_data; + uc->handle_attach = usb_desc_attach; + uc->realize = canokey_realize; + uc->unrealize = canokey_unrealize; + dc->desc ="CanoKey QEMU" ; +device_class_set_props (dc, canokey_properties); +} + +static const TypeInfo canokey_info = { + .name =TYPE_CANOKEY , + .parent =TYPE_USB_DEVICE , + .instance_size =sizeof (CanoKeyState), + .class_init = canokey_class_init +}; + +static void canokey_register_types (void ) +{ +type_register_static (&canokey_info); +} + +type_init (canokey_register_types)
hw/usb/canokey.h new file +60 -0
60 lines not on this page · raw message
Signature · 1 line
2.34.1
PATCH v3 2/6 hw/usb/canokey: Add trace events
In reply to Hongren (Zenithal) Zheng--- hw/usb/canokey.c | 18 ++++++++++++++++++ hw/usb/trace-events | 17 +++++++++++++++++ 2 files changed, 35 insertions(+)
hw/usb/canokey.c +18 -0
@@ -16,6 +16,7 @@#include "qapi/error.h" #include "hw/usb.h" #include "hw/qdev-properties.h" +#include "trace.h" #include "desc.h" #include "canokey.h"
@@ -64,6 +65,7 @@ static const USBDesc desc_canokey = {/* Implement canokey-qemu functions */ int canokey_emu_stall_ep (void *base,uint8_t ep) { +trace_canokey_emu_stall_ep (ep);CanoKeyState *key = base;uint8_t ep_in =CANOKEY_EP_IN (ep);/* INTR IN has ep 129 */ qemu_mutex_lock (&key->ep_in_mutex[ep_in]);
@@ -75,6 +77,7 @@ int canokey_emu_stall_ep(void *base, uint8_t ep)int canokey_emu_set_address (void *base,uint8_t addr) { +trace_canokey_emu_set_address (addr);CanoKeyState *key = base; key->dev.addr = addr;return 0 ;
@@ -83,6 +86,7 @@ int canokey_emu_set_address(void *base, uint8_t addr)int canokey_emu_prepare_receive (void *base,uint8_t ep,uint8_t *pbuf,uint16_t size) { +trace_canokey_emu_prepare_receive (ep, size);CanoKeyState *key = base;/* * No mutex here because it is usually called by
@@ -96,6 +100,7 @@ int canokey_emu_prepare_receive(int canokey_emu_transmit (void *base,uint8_t ep,const uint8_t *pbuf,uint16_t size) { +trace_canokey_emu_transmit (ep, size);CanoKeyState *key = base;uint8_t ep_in =CANOKEY_EP_IN (ep);/* INTR IN has ep 129 */ qemu_mutex_lock (&key->ep_in_mutex[ep_in]);
@@ -114,6 +119,7 @@ uint32_t canokey_emu_get_rx_data_size(void *base, uint8_t ep)static void *canokey_thread (void *arg) { +trace_canokey_thread_start ();CanoKeyState *key = arg;while (true) {
@@ -124,6 +130,7 @@ static void *canokey_thread(void *arg)/* Exit thread check */ if (key->stop_thread) { +trace_canokey_thread_stop (); key->stop_thread = false;break ; }
@@ -135,6 +142,7 @@ static void *canokey_thread(void *arg)static void canokey_handle_reset (USBDevice *dev) { +trace_canokey_handle_reset ();CanoKeyState *key =CANOKEY (dev);for (int i =0 ; i !=CANOKEY_EP_NUM ; ++i) { key->ep_in_status[i] =CANOKEY_EP_IN_WAIT ;
@@ -146,6 +154,7 @@ static void canokey_handle_reset(USBDevice *dev)static void canokey_handle_control (USBDevice *dev,USBPacket *p,int request,int value,int index,int length,uint8_t *data) { +trace_canokey_handle_control_setup (request, value, index, length);CanoKeyState *key =CANOKEY (dev);canokey_emu_setup (request, value, index, length);
@@ -155,6 +164,7 @@ static void canokey_handle_control(USBDevice *dev, USBPacket *p,uint32_t dir_in = request & DeviceRequest;if (!dir_in) {/* OUT */ +trace_canokey_handle_control_out ();qemu_mutex_lock (&key->key_mutex);if (key->ep_out[0 ] !=NULL ) {memcpy (key->ep_out[0 ], data, length);
@@ -179,6 +189,8 @@ static void canokey_handle_control(USBDevice *dev, USBPacket *p, p->actual_length = key->ep_in_size[ep_in];qemu_mutex_unlock (&key->ep_in_mutex[ep_in]); + +trace_canokey_handle_control_in (p->actual_length); }static void canokey_handle_data (USBDevice *dev,USBPacket *p)
@@ -190,9 +202,12 @@ static void canokey_handle_data(USBDevice *dev, USBPacket *p)uint32_t in_len;switch (p->pid) {case USB_TOKEN_OUT : +trace_canokey_handle_data_out (ep_out);qemu_mutex_lock (&key->key_mutex);if (p->iov.size > key->ep_out_size[ep_out]) {/* unlikely we will reach here, but check still needed */ +trace_canokey_handle_data_out_err ( + ep_out, p->iov.size, key->ep_out_size[ep_out]); p->status =USB_RET_NAK ;qemu_mutex_unlock (&key->key_mutex);break ;
@@ -213,6 +228,7 @@ static void canokey_handle_data(USBDevice *dev, USBPacket *p)qemu_mutex_unlock (&key->ep_in_mutex[ep_in]);break ; } +trace_canokey_handle_data_in (ep_in);if (key->ep_in_status[ep_in] ==CANOKEY_EP_IN_STALL ) { p->status =USB_RET_STALL ; }
@@ -243,6 +259,7 @@ static void canokey_handle_data(USBDevice *dev, USBPacket *p)static void canokey_realize (USBDevice *base,Error **errp) { +trace_canokey_realize ();CanoKeyState *key =CANOKEY (base);if (key->file ==NULL ) {
@@ -274,6 +291,7 @@ static void canokey_realize(USBDevice *base, Error **errp)static void canokey_unrealize (USBDevice *base) { +trace_canokey_unrealize ();CanoKeyState *key =CANOKEY (base);/* Thread */
hw/usb/trace-events +17 -0
@@ -345,3 +345,20 @@ usb_serial_set_baud(int bus, int addr, int baud) "dev %d:%u baud rate %d" usb_serial_set_data(int bus, int addr, int parity, int data, int stop) "dev %d:%u parity %c, data bits %d, stop bits %d" usb_serial_set_flow_control(int bus, int addr, int index) "dev %d:%u flow control %d" usb_serial_set_xonxoff(int bus, int addr, uint8_t xon, uint8_t xoff) "dev %d:%u xon 0x%x xoff 0x%x" + +# canokey.c +canokey_emu_stall_ep(uint8_t ep) "ep %d" +canokey_emu_set_address(uint8_t addr) "addr %d" +canokey_emu_prepare_receive(uint8_t ep, uint16_t size) "ep %d size %d" +canokey_emu_transmit(uint8_t ep, uint16_t size) "ep %d size %d" +canokey_thread_start(void) +canokey_thread_stop(void) +canokey_handle_reset(void) +canokey_handle_control_setup(int request, int value, int index, int length) "request 0x%04X value 0x%04X index 0x%04X length 0x%04X" +canokey_handle_control_out(void) +canokey_handle_control_in(int actual_len) "actual len %d" +canokey_handle_data_out(uint8_t ep_out) "ep %d" +canokey_handle_data_out_err(uint8_t ep_out, uint32_t income, uint32_t buffer_size) "ep %d overflow! income %d, buffer size %d" +canokey_handle_data_in(uint8_t ep_out) "ep %d" +canokey_realize(void) +canokey_unrealize(void)
Signature · 1 line
2.34.1
PATCH v3 6/6 MAINTAINERS: add myself as CanoKey maintainer
In reply to Hongren (Zenithal) Zheng--- MAINTAINERS | 8 ++++++++ 1 file changed, 8 insertions(+)
MAINTAINERS +8 -0
@@ -2296,6 +2296,14 @@ F: hw/timer/mips_gictimer.c F: include/hw/intc/mips_gic.h F: include/hw/timer/mips_gictimer.h +CanoKey +M: Hongren (Zenithal) Zheng <[email protected]> +S: Maintained +R: Canokeys.org <[email protected]> +F: hw/usb/canokey.c +F: hw/usb/canokey.h +F: docs/canokey.txt + Subsystems ---------- Overall Audio backends
Signature · 1 line
2.34.1
PATCH v3 3/6 meson: Add CanoKey
In reply to Hongren (Zenithal) Zheng--- hw/usb/Kconfig | 5 +++++ hw/usb/meson.build | 3 +++ meson.build | 6 ++++++ meson_options.txt | 2 ++ scripts/meson-buildoptions.sh | 3 +++ 5 files changed, 19 insertions(+)
hw/usb/Kconfig +5 -0
@@ -119,6 +119,11 @@ config USB_U2F default y depends on USB +config USB_CANOKEY + bool + default y + depends on USB + config IMX_USBPHY bool default y
hw/usb/meson.build +3 -0
@@ -63,6 +63,9 @@ if u2f.found() softmmu_ss.add(when: 'CONFIG_USB_U2F', if_true: [u2f, files('u2f-emulated.c')]) endif +# CanoKey +softmmu_ss.add(when: 'CONFIG_USB_CANOKEY', if_true: [canokey, files('canokey.c')]) + # usb redirect if usbredir.found() usbredir_ss = ss.source_set()
meson.build +6 -0
@@ -1186,6 +1186,12 @@ if have_system method: 'pkg-config', kwargs: static_kwargs) endif +canokey = not_found +if have_system + canokey = dependency('canokey-qemu', required: get_option('canokey'), + method: 'pkg-config', + kwargs: static_kwargs) +endif usbredir = not_found if not get_option('usb_redir').auto() or have_system usbredir = dependency('libusbredirparser-0.5', required: get_option('usb_redir'),
meson_options.txt +2 -0
@@ -143,6 +143,8 @@ option('spice_protocol', type : 'feature', value : 'auto', description: 'Spice protocol support') option('u2f', type : 'feature', value : 'auto', description: 'U2F emulation support') +option('canokey', type : 'feature', value : 'auto', + description: 'CanoKey support') option('usb_redir', type : 'feature', value : 'auto', description: 'libusbredir support') option('l2tpv3', type : 'feature', value : 'auto',
scripts/meson-buildoptions.sh +3 -0
@@ -28,6 +28,7 @@ meson_options_help() { printf "%s\n" ' bpf eBPF support' printf "%s\n" ' brlapi brlapi character device driver' printf "%s\n" ' bzip2 bzip2 support for DMG images' + printf "%s\n" ' canokey CanoKey support' printf "%s\n" ' cap-ng cap_ng support' printf "%s\n" ' cocoa Cocoa user interface (macOS only)' printf "%s\n" ' coreaudio CoreAudio sound support'
@@ -115,6 +116,8 @@ _meson_option_parse() { --disable-brlapi) printf "%s" -Dbrlapi=disabled ;; --enable-bzip2) printf "%s" -Dbzip2=enabled ;; --disable-bzip2) printf "%s" -Dbzip2=disabled ;; + --enable-canokey) printf "%s" -Dcanokey=enabled ;; + --disable-canokey) printf "%s" -Dcanokey=disabled ;; --enable-cap-ng) printf "%s" -Dcap_ng=enabled ;; --disable-cap-ng) printf "%s" -Dcap_ng=disabled ;; --enable-capstone) printf "%s" -Dcapstone=enabled ;;
Signature · 1 line
2.34.1
PATCH v3 4/6 docs: Add CanoKey documentation
In reply to Hongren (Zenithal) Zheng--- docs/system/device-emulation.rst | 1 + docs/system/devices/canokey.rst | 158 +++++++++++++++++++++++++++++++ 2 files changed, 159 insertions(+) create mode 100644 docs/system/devices/canokey.rst
docs/system/device-emulation.rst +1 -0
@@ -89,3 +89,4 @@ Emulated Devices devices/vhost-user.rst devices/virtio-pmem.rst devices/vhost-user-rng.rst + devices/canokey.rst
docs/system/devices/canokey.rst new file +158 -0
158 lines not on this page · raw message
Signature · 1 line
2.34.1
v3 cover Introduce CanoKey QEMU
- 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
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 | 3 + hw/usb/Kconfig | 5 + hw/usb/canokey.c | 344 +++++++++++++++++++++++++++++++ hw/usb/canokey.h | 60 ++++++ hw/usb/meson.build | 3 + hw/usb/trace-events | 17 ++ meson.build | 6 + meson_options.txt | 2 + scripts/meson-buildoptions.sh | 3 + 12 files changed, 610 insertions(+) create mode 100644 docs/system/devices/canokey.rst create mode 100644 hw/usb/canokey.c create mode 100644 hw/usb/canokey.h
Signature · 1 line
2.34.1
PATCH v3 5/6 docs/system/devices/usb: Add CanoKey to USB devices examples
--- docs/system/devices/usb.rst | 3 +++ 1 file changed, 3 insertions(+)
docs/system/devices/usb.rst +3 -0
@@ -199,6 +199,9 @@ option or the ``device_add`` monitor command. Available devices are: ``u2f-{emulated,passthru}`` Universal Second Factor device +``canokey`` + An Open-source Secure Key implementing FIDO2, OpenPGP, PIV and more. + Physical port addressing ^^^^^^^^^^^^^^^^^^^^^^^^
Signature · 1 line
2.34.1
Re: [PATCH v3 6/6] MAINTAINERS: add myself as CanoKey maintainer
In reply to Hongren (Zenithal) ZhengQuoted 1 line · Hongren (Zenithal) Zheng
+F:
docs/canokey.txt
I forgot to change this line, I will change it in the next version along with other requested changes.
Re: [PATCH v3 5/6] docs/system/devices/usb: Add CanoKey to USB devices examples
In reply to Hongren (Zenithal) ZhengQuoted 10 lines · Hongren (Zenithal) Zheng
Signed-off-by Hongren (Zenithal) Zheng <[email protected]>--- docs/system/devices/usb.rst | 3 +++ 1 file changed, 3 insertions(+)docs/system/devices/usb.rst +0
-0
docs/system/devices/usb.rst option or the ``device_add`` monitor command. Available devices are: · line 203
Quoted 5 lines
docs/system/devices/usb.rst +2
-0@@ -199,6 +199,9 @@ option or the ``device_add`` monitor command. Available devices are: ``u2f-{emulated,passthru}`` Universal Second Factor device +``canokey`` + An Open-source Secure Key implementing FIDO2, OpenPGP, PIV and more.
Just an additional idea: It might be helpful for the users if you put a link to the separate documentation from the previous patch here?
Thomas
Re: [PATCH v3 5/6] docs/system/devices/usb: Add CanoKey to USB devices examples
Quoted 18 lines · Thomas Huth
Quoted 10 lines · Hongren (Zenithal) Zheng
Signed-off-by Hongren (Zenithal) Zheng <[email protected]>--- docs/system/devices/usb.rst | 3 +++ 1 file changed, 3 insertions(+)docs/system/devices/usb.rst +0
-0docs/system/devices/usb.rst option or the ``device_add`` monitor command. Available devices are: · line 202
Quoted 4 lines
docs/system/devices/usb.rst +2
-0@@ -199,6 +199,9 @@ option or the ``device_add`` monitor command. Available devices are: ``u2f-{emulated,passthru}`` Universal Second Factor device +``canokey`` + An Open-source Secure Key implementing FIDO2, OpenPGP, PIV and more.Reviewed-by Thomas Huth <[email protected]>
Quoted 2 lines
Just an additional idea: It might be helpful for the users if you put a link to the separate documentation from the previous patch here?
Will be added in the next version.
Quoted 3 lines
Thomas