WebUSB

1. Overview

CanoKey supports the WebUSB protocol for easier management. You can use our open-source console to manage your CanoKey. Or, you can develop your own console via WebUSB APIs.

1.1 Driver

CanoKey is a WinUSB device, whose firmware defines certain Microsoft operating system (OS) feature descriptors that report the compatible ID as “WINUSB”. Therefore, you do not need additional drivers when you use it on Windows. And of course, no drivers are required on Linux or macOS.

1.2 Interface & Pipe

CanoKey uses the interface with index 1, and the transfer type is control transfer. The default EP size is 16 bytes.

2. Messages

Basically, the messages on the WebUSB interface are APDU commands. To transceive a pair of APDU commands, two phases are required:

  1. Send a command APDU
  2. Get the response APDU

Each type of message is a vendor-specific request, defined as:

bRequest Value
CMD 00h
RESP 01h
STAT 02h

2.1 Command APDU

The following control pipe request is used to send a command APDU.

bmRequestType bRequest wValue wIndex wLength Data
01000001B CMD 0000h 1 length of data bytes

2.2 Get the response APDU

The following control pipe request is used to get the response APDU.

bmRequestType bRequest wValue wIndex wLength Data
11000001B RESP 0000h 1 0 N/A

The device will send the response no more than 1500 bytes.

2.3 Get the execution status

The following control pipe request is used to get the status of the card.

bmRequestType bRequest wValue wIndex wLength Data
11000001B STAT 0000h 1 0 N/A

The response data is 1-byte long, 0x01 for in progress and 0x00 for finishing processing and you can fetch the result using RESP command, and other values for invalid states.

If the command is still under processing, the response will be empty.

3. Demo Code

If you have CanoKey, you can try it now.

3.1 Connect

Click the following button to connect a CanoKey.

Show me the code

3.2 Transceive

Once you connect your CanoKey, input the command APDU here, e.g., 00A4040005F000000000, then click “Send”.

Response:

Show me the code