Andreas Jellinghaus

This project implements a way for OpenSC to access usb crypto tokens such as: Aladdin eToken PRO Rainbow iKey 2032 Rainbow iKey 3000 Entron CryptoIdentity This project is the successor of the etoken project which created an PC/SC ifdhandler for the Aladdin eToken PRO. Interfacing directly with OpenSC is much easier than using one of the old but well known interfaces like CT-API or PC/SC.

The Aladdin eToken PRO works fine. Beware: versions older than 4.1.57 or so might have a problem with USB controllers found on mainboards with VIA chipsets or any uhci based USB controllers. I don't know the details. The Eutron CryptoIdentity IT-Sec works fine. The Eutron CryptoIdentity blue/grey has a smart card operating system by Algorithmic Research. Documentation is only available under a NDA. I'm to busy to sign it and implement support for their driver right now. The usb layer works fine, but I don't know the commands i could send or how a valid response would look like. The Rainbow iKey 2032 has a smart card operating system by DataKey. Documentation is only available under a NDA: I'm to busy to sign it and implement support for their driver right now. The usb layer is supposed to work fine, but I cannot test that without knowing the commands and responses. The Rainbow iKey 3000 has a smart card operating system by Gersike and Devrient called StarCos SPK 2.3. The usb layer is supposed to work fine, but not tested. Further work on the card driver in OpenSC and pkcs11 and pkcs15 framework is currently done, please be patient.

PKCS#11 is an API standard. It allowes applications to use any library that implements PKCS#11 without changeing code. PKCS#15 is a standard that describes how a PKCS#11 library should work. Smartcards have a filesystem, and PKCS#15 makes sure every PCKS#11 library saves data in the right directory, and reads from the right directory. OpenSC offers library implementing the PKCS#11 API according to the PKCS#15 standard. Compatibility has been tested with cards that contain data according to PKCS#15 like the finish and swedish ID card. However even if OpenSC can use the usbtoken driver to access a smartcard in a usb token, it will only look in directories where the certificates should be according to PKCS#15. Problem is: most vendors do not install the certificates and keys in the right place, they do not implement PKCS#15 in their drivers and libraries. The result is this: you can create a PKCS#15 structure under linux, can put certifiactes and keys and data in it, but when using the vendors drivers you will not see it. Also if you use the vendors driver to store keys, certificates and data, OpenSC will not see it. Using OpenSC on Windows and Linux could solve the situation, but I have no experience with OpenSC under Windows, sorry.

Aladdin: Their Windows and Unix drivers store keys and certificates in the wrong place. (not compatible with PKCS#15) Eutron: Their Windows and Unix drivers store keys and certificates in the wron place. (not compatible with PKCS#15)

Currently the usbtoken only works with linux (kernel 2.4.* series and kernel 2.5.* series were tested), but ports to other operating systems should be possible. If you want to port usbtoken, please contact: Andreas Jellinghaus aj@dungeon.inka.de You need a kernel compiled with CONFIG_HOTPLUG and CONFIG_USB_DEVICEFS, and the usb device filesystem must be mounted to /proc/bus/usb. And of course kernel support for your usb hub. I guess any linux distribution with kernel 2.4 will be allright and require no changes. Users of other operating systems, please see the porting section.

Call configure with --enable-usbtoken and it compile ok. No special libraries or stuff needed.

ls /sbin/hotplug If there is no such file, the installation is very easy: ln -s /path/to/opensc/sbin/usbtoken /sbin/hotplug mkdir /var/run/usbtoken chmod 755 /var/run/usbtoken Now attach some usb token. The kernel will start /sbin/hotplug, and you can see some usbtoken running as daemon: you will find a pid file in /var/run and a socket in /var/run/usbtoken/.

First the general instructions, then the debian specific instructions. As usual debian does everything a bit different. That doesn't mean it is necessarily better or worse. Edit /etc/hotplug/usb.usermap and add these lines: usbtoken 0x0003 0x0529 0x050c 0x0000 0x0001 0xff 0x00 0x00 0xff 0x00 0x00 0x00000000 usbtoken 0x0003 0x0529 0x0514 0x0000 0x0001 0xff 0x00 0x00 0xff 0x00 0x00 0x00000000 usbtoken 0x0003 0x04b9 0x1202 0x0000 0x0001 0xff 0x00 0x00 0xff 0x00 0x00 0x00000000 usbtoken 0x0003 0x04b9 0x1300 0x0000 0x0001 0xff 0x00 0x00 0xff 0x00 0x00 0x00000000 usbtoken 0x0003 0x073d 0x0005 0x0020 0x0001 0xff 0x00 0x00 0xff 0x00 0x00 0x00000000 Create the directory /etc/hotplug/usb and add a symlink to usbtoken. Also create the directory /var/run/usbtoken and set permissions to 0755 (everyone can access that directory): ln -s /path/to/opensc/sbin/usbtoken /etc/hotplug/usb/ mkdir /var/run/usbtoken chmod 0755 /var/run/usbtoken

By default everyone can use the usbtokens. If you want to limit this to a certain user: chown user /var/run/usbtoken/ chmod 0700 /var/run/usbtoken/ Or if you want to limit this to a certain group: chgrp group /var/run/usbtoken/ chmod 0750 /var/run/usbtoken/

TODO: send me problem reports and I will add advice here. Edit src/usbtoken/Makefile and Makefile.in and add "-DUSB_DEBUG" to CFLAGS. make clean, make, make install. Now it will dump all usb traffic to syslog. I should be able to understand what is going wrong based on that log file. For development I use a special crafted /sbin/hotplug shell script that creates another script /root/sim whis I invoke in an xterm. That script spawns gdb so I can debug the whole process. In gdb I usualy set a breakpoint, and run the command with r usb. My hotplug script: #!/bin/sh if [ -n "$PRODUCT" ] then if [ "$ACTION" = "add" ] then export > /root/sim echo "echo $*" >> /root/sim echo gdb /home/aj/opensc/sbin/usbtoken >> /root/sim fi fi exit 0

To port usbtoken mainly usb.c needs some changes. The core sequence for linux is: ... struct usbdevfs_ctrltransfer ctrl; int rc; ctrl.requesttype = type; ctrl.request = req; ctrl.value = value; ctrl.index = index; ctrl.length = size; ctrl.data = buf; ctrl.timeout = 10000; rc = ioctl(usbtoken.usbfd, USBDEVFS_CONTROL, &ctrl); ]]> rc now has the error (-1/errno/strerror) or the number of bytes read/written on success. Change it to suit your OS, or let me know how to do it, and usb should work. Usbtoken also needs an usb device filesystem or some device it can open and use with I/O controls. That should be available with every OS. Finaly usbtoken depends to be called by some hotplug mechanism. Under linux the kernel executes /sbin/hotplug everytime a device is added (or removed, but I don't use that). If your OS has no such service, you can write a daemon that somehow finds out when a device is added and start usbtoken with the required environment settings. Windows? Ugh. I have no idea about windows, what we can do, how it works, etc. Volunteers welcome.