system/devices/canokey.rst

4 ------------
6 CanoKey [1]_ is an open-source secure key with supports of
8 * U2F / FIDO2 with Ed25519 and HMAC-secret
10 * PIV (NIST SP 800-73-4)
14 All these platform-independent features are in canokey-core [3]_.
21 * (virt-card) CanoKey USB/IP
22 * (virt-card) CanoKey FunctionFS
24 In QEMU, yet another CanoKey virt-card is implemented.
28 the guest OS can use all the functionalities of a secure key as if
33 * libcanokey-qemu supports debugging output thus developers can
34   inspect what happens inside a secure key
41 * For developers on software with secure key support (e.g. FIDO2, OpenPGP),
42   they can see what happens inside the secure key
43 * For secure key developers, USB packets between guest OS and CanoKey
47 on code coping with secure key.
52 libcanokey-qemu is required to use CanoKey QEMU.
54 .. code-block:: shell
56     git clone https://github.com/canokeys/canokey-qemu
57     mkdir canokey-qemu/build
58     pushd canokey-qemu/build
60 If you want to install libcanokey-qemu in a different place,
61 add ``-DCMAKE_INSTALL_PREFIX=/path/to/your/place`` to cmake below.
63 .. code-block:: shell
72 .. code-block:: shell
76     ./configure --enable-canokey && make
84 .. parsed-literal::
86     |qemu_system| -usb -device canokey,file=$HOME/.canokey-file
98 .. code-block:: shell
108 CanoKey QEMU consists of two parts, ``libcanokey-qemu.so`` and ``canokey.c``,
110 of a secure key while the latter provides platform-dependent functions:
113 If you want to trace what happens inside the secure key, when compiling
114 libcanokey-qemu, you should add ``-DQEMU_DEBUG_OUTPUT=ON`` in cmake command
117 .. code-block:: shell
119     cmake .. -DQEMU_DEBUG_OUTPUT=ON
123 .. parsed-literal::
125     |qemu_system| --trace "canokey_*" \\
126         -usb -device canokey,file=$HOME/.canokey-file
130 .. parsed-literal::
132     |qemu_system| -usb -device canokey,file=$HOME/.canokey-file,pcap=key.pcap
137 Currently libcanokey-qemu.so has dozens of global variables as it was originally
141 .. parsed-literal::
143     |qemu_system| -usb -device canokey,file=$HOME/.canokey-file \\
144          -device canokey,file=$HOME/.canokey-file2
146 Also, there is no lock on canokey-file, thus two CanoKey QEMU instance
147 can not read one canokey-file at the same time.
153 .. [2] `<https://docs.canokeys.org/userguide/openpgp/#supported-algorithm>`_
154 .. [3] `<https://github.com/canokeys/canokey-core>`_
155 .. [4] `<https://github.com/canokeys/canokey-stm32>`_
156 .. [5] `<https://github.com/canokeys/canokey-pigeon>`_