From nobody Tue Feb 10 04:13:31 2026 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of lists.xenproject.org designates 192.237.175.120 as permitted sender) client-ip=192.237.175.120; envelope-from=xen-devel-bounces@lists.xenproject.org; helo=lists.xenproject.org; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of lists.xenproject.org designates 192.237.175.120 as permitted sender) smtp.mailfrom=xen-devel-bounces@lists.xenproject.org; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1654852921; cv=none; d=zohomail.com; s=zohoarc; b=kKUuuOrV77CtOA5IbndzO7T9yxcgpZhmINSE06nIKN9VUG/R/BuZlBS5qoLQmTKgab7nO5HvvG4Us1wQ1UQtyrtg/n+BxAsJCyRx7tUskDmBO6CyzdobwYbOIKmS+fHR69FIGVsRtQH7AkYAGaBHANW7xLccSJG3Al9sI/t8IRo= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1654852921; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=Iypp4lhP0vK8zaOIYv4YGS15C6hr5eRaL+NEXu7qlj4=; b=DrBD959dqDHpJ+nXuK1/lA2Zpt6042PLu6pAAQvHRixt++X/N3QaIq94bUjUZzF/BA9n0caToZMUQSG9eMJXebI0CM8SFNaDqGDwfCWCH2SUpusogrkrjyHhCUDtPgxHUpF5K6Ib3wiXACjLdWH4gsRNSHfvZwO/FU1HjxQegIM= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of lists.xenproject.org designates 192.237.175.120 as permitted sender) smtp.mailfrom=xen-devel-bounces@lists.xenproject.org; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from lists.xenproject.org (lists.xenproject.org [192.237.175.120]) by mx.zohomail.com with SMTPS id 1654852921763595.29813272683; Fri, 10 Jun 2022 02:22:01 -0700 (PDT) Received: from list by lists.xenproject.org with outflank-mailman.346100.571885 (Exim 4.92) (envelope-from ) id 1nzapj-0008Bk-Tz; Fri, 10 Jun 2022 09:21:35 +0000 Received: by outflank-mailman (output) from mailman id 346100.571885; Fri, 10 Jun 2022 09:21:35 +0000 Received: from localhost ([127.0.0.1] helo=lists.xenproject.org) by lists.xenproject.org with esmtp (Exim 4.92) (envelope-from ) id 1nzapj-0008BP-Pj; Fri, 10 Jun 2022 09:21:35 +0000 Received: by outflank-mailman (input) for mailman id 346100; Fri, 10 Jun 2022 09:21:35 +0000 Received: from se1-gles-flk1-in.inumbo.com ([94.247.172.50] helo=se1-gles-flk1.inumbo.com) by lists.xenproject.org with esmtp (Exim 4.92) (envelope-from ) id 1nzapi-00050F-Sr for xen-devel@lists.xenproject.org; Fri, 10 Jun 2022 09:21:35 +0000 Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) by se1-gles-flk1.inumbo.com (Halon) with ESMTPS id b7d14d57-e89e-11ec-8179-c7c2a468b362; Fri, 10 Jun 2022 11:21:33 +0200 (CEST) Received: from mimecast-mx02.redhat.com (mx3-rdu2.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-199-ie5LO4fzPN-Uj95gsVZ9kw-1; Fri, 10 Jun 2022 05:21:29 -0400 Received: from smtp.corp.redhat.com (int-mx08.intmail.prod.int.rdu2.redhat.com [10.11.54.8]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id E493938149A2; Fri, 10 Jun 2022 09:21:28 +0000 (UTC) Received: from sirius.home.kraxel.org (unknown [10.39.192.40]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 6E551C53360; Fri, 10 Jun 2022 09:21:28 +0000 (UTC) Received: by sirius.home.kraxel.org (Postfix, from userid 1000) id A169F180062F; Fri, 10 Jun 2022 11:20:44 +0200 (CEST) X-Outflank-Mailman: Message body and most headers restored to incoming version X-BeenThere: xen-devel@lists.xenproject.org List-Id: Xen developer discussion List-Unsubscribe: , List-Post: List-Help: List-Subscribe: , Errors-To: xen-devel-bounces@lists.xenproject.org Precedence: list Sender: "Xen-devel" X-Inumbo-ID: b7d14d57-e89e-11ec-8179-c7c2a468b362 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1654852892; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=Iypp4lhP0vK8zaOIYv4YGS15C6hr5eRaL+NEXu7qlj4=; b=FhB15AM2+IRbBqhTlkRbxzl+jI7PYkf+c5YybuLkZ4roa7T0rkisLF7ZTXEktPDty0Njfi PX2UQIBmGN5Vbbo7rRX0M5gn3hSunDjgQVD59qMYSZeul5OhbK4yvziAeHZO1GgdOmr1jI +qgmHLjv9cYdSFvOitX8qDUv1nkhF50= X-MC-Unique: ie5LO4fzPN-Uj95gsVZ9kw-1 From: Gerd Hoffmann To: qemu-devel@nongnu.org Cc: "Canokeys.org" , "Michael S. Tsirkin" , Stefano Stabellini , Anthony Perard , Paul Durrant , Akihiko Odaki , Peter Maydell , "Hongren (Zenithal) Zheng" , xen-devel@lists.xenproject.org, Alex Williamson , Gerd Hoffmann , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= Subject: [PULL 08/17] docs: Add CanoKey documentation Date: Fri, 10 Jun 2022 11:20:34 +0200 Message-Id: <20220610092043.1874654-9-kraxel@redhat.com> In-Reply-To: <20220610092043.1874654-1-kraxel@redhat.com> References: <20220610092043.1874654-1-kraxel@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 2.85 on 10.11.54.8 X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1654852923272100001 Content-Type: text/plain; charset="utf-8" From: "Hongren (Zenithal) Zheng" Signed-off-by: Hongren (Zenithal) Zheng Message-Id: Signed-off-by: Gerd Hoffmann --- docs/system/device-emulation.rst | 1 + docs/system/devices/canokey.rst | 168 +++++++++++++++++++++++++++++++ 2 files changed, 169 insertions(+) create mode 100644 docs/system/devices/canokey.rst diff --git a/docs/system/device-emulation.rst b/docs/system/device-emulatio= n.rst index 3b729b920d7c..05060060563f 100644 --- a/docs/system/device-emulation.rst +++ b/docs/system/device-emulation.rst @@ -92,3 +92,4 @@ Emulated Devices devices/vhost-user.rst devices/virtio-pmem.rst devices/vhost-user-rng.rst + devices/canokey.rst diff --git a/docs/system/devices/canokey.rst b/docs/system/devices/canokey.= rst new file mode 100644 index 000000000000..169f99b8eb82 --- /dev/null +++ b/docs/system/devices/canokey.rst @@ -0,0 +1,168 @@ +.. _canokey: + +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 features 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 +* (virt-card) CanoKey FunctionFS + +In QEMU, yet another CanoKey virt-card is implemented. +CanoKey QEMU exposes itself as a USB device to the guest OS. + +With the same software configuration as 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 + inspect what happens inside a secure key +* CanoKey QEMU supports trace event thus event +* QEMU USB stack supports pcap thus USB packet between the guest + and key can be captured and analysed + +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 since this is a virtual card, it can be easily used in CI for testing +on code coping with secure key. + +Building +=3D=3D=3D=3D=3D=3D=3D=3D + +libcanokey-qemu is required to use CanoKey QEMU. + +.. code-block:: shell + + git clone https://github.com/canokeys/canokey-qemu + mkdir canokey-qemu/build + pushd canokey-qemu/build + +If you want to install libcanokey-qemu in a different place, +add ``-DCMAKE_INSTALL_PREFIX=3D/path/to/your/place`` to cmake below. + +.. code-block:: shell + + cmake .. + make + make install # may need sudo + popd + +Then configuring and building: + +.. code-block:: shell + + # depending on your env, lib/pkgconfig can be lib64/pkgconfig + export PKG_CONFIG_PATH=3D/path/to/your/place/lib/pkgconfig:$PKG_CONFIG= _PATH + ./configure --enable-canokey && make + +Using CanoKey QEMU +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +CanoKey QEMU stores all its data on a file of the host specified by the ar= gument +when invoking qemu. + +.. parsed-literal:: + + |qemu_system| -usb -device canokey,file=3D$HOME/.canokey-file + +Note: you should keep this file carefully as it may contain your private k= ey! + +The first time when the file is used, it is created and initialized by Can= oKey, +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: + +.. code-block:: shell + + $ lsusb + Bus 001 Device 002: ID 20a0:42d4 Clay Logic CanoKey QEMU + +You may setup the key as guided in [6]_. The console for the key is at [7]= _. + +Debuging +=3D=3D=3D=3D=3D=3D=3D=3D + +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 ``-DQEMU_DEBUG_OUTPUT=3DON`` in cmake comm= and +line: + +.. code-block:: shell + + cmake .. -DQEMU_DEBUG_OUTPUT=3DON + +If you want to trace events happened in canokey.c, use + +.. parsed-literal:: + + |qemu_system| --trace "canokey_*" \\ + -usb -device canokey,file=3D$HOME/.canokey-file + +If you want to capture USB packets between the guest and the host, you can: + +.. parsed-literal:: + + |qemu_system| -usb -device canokey,file=3D$HOME/.canokey-file,pcap=3Dk= ey.pcap + +Limitations +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +Currently libcanokey-qemu.so has dozens of global variables as it was orig= inally +designed for embedded systems. Thus one qemu instance can not have +multiple CanoKey QEMU running, namely you can not + +.. parsed-literal:: + + |qemu_system| -usb -device canokey,file=3D$HOME/.canokey-file \\ + -device canokey,file=3D$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. + +Another limitation is that this device is not compatible with ``qemu-xhci`= `, +in that this device would hang when there are FIDO2 packets (traffic on +interrupt endpoints). If you do not use FIDO2 then it works as intended, +but for full functionality you should use old uhci/ehci bus and attach can= okey +to it, for example + +.. parsed-literal:: + + |qemu_system| -device piix3-usb-uhci,id=3Duhci -device canokey,bus=3Duh= ci.0 + +References +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +.. [1] ``_ +.. [2] `= `_ +.. [3] ``_ +.. [4] ``_ +.. [5] ``_ +.. [6] ``_ +.. [7] ``_ --=20 2.36.1