391 lines
10 KiB
XML
391 lines
10 KiB
XML
<?xml version="1.0" encoding="iso8859-1" ?>
|
|
<article ns="http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
|
|
<articleinfo>
|
|
<author>
|
|
<firstname>Andreas</firstname>
|
|
<surname>Jellinghaus</surname>
|
|
</author>
|
|
<title>Driver for USB Crypto Token</title>
|
|
</articleinfo>
|
|
|
|
<warning>
|
|
Usbtoken is obsolete. Please use OpenCT, a new and
|
|
much improved smartcard framework. You can download
|
|
OpenCT from
|
|
<ulink url="http://www.opensc.org/files/snapshots" />
|
|
</warning>
|
|
|
|
<para>
|
|
If you still want to use ustoken, you need to enable it
|
|
while configureing OpenSC. For example
|
|
<prompt>./configure --enable-usbtoken</prompt>
|
|
</para>
|
|
|
|
<toc></toc>
|
|
|
|
<section>
|
|
<title>About usbtoken</title>
|
|
|
|
<para>
|
|
This project implements a way for OpenSC to access
|
|
usb crypto tokens such as:
|
|
</para>
|
|
<orderedlist>
|
|
<listitem>Aladdin eToken PRO</listitem>
|
|
<listitem>Rainbow iKey 2032</listitem>
|
|
<listitem>Rainbow iKey 3000</listitem>
|
|
<listitem>Entron CryptoIdentity</listitem>
|
|
</orderedlist>
|
|
|
|
<para>
|
|
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.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Status</title>
|
|
|
|
<para>
|
|
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.
|
|
</para>
|
|
|
|
<para>
|
|
The Eutron CryptoIdentity IT-Sec works fine.
|
|
</para>
|
|
|
|
<para>
|
|
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.
|
|
</para>
|
|
|
|
<para>
|
|
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.
|
|
</para>
|
|
|
|
<para>
|
|
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.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Compatibility</title>
|
|
|
|
<para>
|
|
PKCS#11 is an API standard. It allowes applications
|
|
to use any library that implements PKCS#11 without
|
|
changeing code.
|
|
</para>
|
|
|
|
<para>
|
|
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.
|
|
</para>
|
|
|
|
<para>
|
|
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.
|
|
</para>
|
|
|
|
<para>
|
|
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.
|
|
</para>
|
|
|
|
<para>
|
|
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.
|
|
</para>
|
|
|
|
<para>
|
|
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.
|
|
</para>
|
|
|
|
<para>
|
|
Using OpenSC on Windows and Linux could solve
|
|
the situation, but I have no experience with
|
|
OpenSC under Windows, sorry.
|
|
</para>
|
|
|
|
<section>
|
|
<title>Compatibility List</title>
|
|
|
|
<para>
|
|
Aladdin: Their Windows and Unix drivers store
|
|
keys and certificates in the wrong place.
|
|
(not compatible with PKCS#15)
|
|
</para>
|
|
|
|
<para>
|
|
Eutron: Their Windows and Unix drivers store
|
|
keys and certificates in the wron place.
|
|
(not compatible with PKCS#15)
|
|
</para>
|
|
|
|
</section>
|
|
|
|
</section>
|
|
|
|
<section>
|
|
<title>Requirements</title>
|
|
|
|
<para>
|
|
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
|
|
<email>aj@dungeon.inka.de</email>
|
|
</para>
|
|
|
|
<para>
|
|
You need a kernel compiled with CONFIG_HOTPLUG
|
|
and CONFIG_USB_DEVICEFS, and the usb device filesystem
|
|
must be mounted to <filename>/proc/bus/usb</filename>.
|
|
And of course kernel support for your usb hub.
|
|
</para>
|
|
|
|
<para>
|
|
I guess any linux distribution with kernel 2.4
|
|
will be allright and require no changes.
|
|
</para>
|
|
|
|
<para>
|
|
Users of other operating systems, please see
|
|
the porting section.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Compiling OpenSC with USBtoken support</title>
|
|
|
|
<para>
|
|
Call configure with --enable-usbtoken and it
|
|
compile ok. No special libraries or stuff needed.
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Installation without hotplug utils</title>
|
|
|
|
<para>
|
|
<command>ls /sbin/hotplug</command>
|
|
</para>
|
|
|
|
<para>
|
|
If there is no such file, the installation
|
|
is very easy:
|
|
<screen>
|
|
ln -s /path/to/opensc/sbin/usbtoken /sbin/hotplug
|
|
mkdir /var/run/usbtoken
|
|
chmod 755 /var/run/usbtoken
|
|
</screen>
|
|
</para>
|
|
|
|
<para>
|
|
Now attach some usb token. The kernel will start
|
|
<filename>/sbin/hotplug</filename>, and you can
|
|
see some usbtoken running as daemon: you will find
|
|
a pid file in <filename>/var/run</filename>
|
|
and a socket in <filename>/var/run/usbtoken/</filename>.
|
|
</para>
|
|
|
|
</section>
|
|
|
|
<section>
|
|
<title>Installation with hotplut utils</title>
|
|
|
|
<para>
|
|
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.
|
|
</para>
|
|
|
|
<para>
|
|
Edit <filename>/etc/hotplug/usb.usermap</filename>
|
|
and add these lines:
|
|
<screen>
|
|
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
|
|
</screen>
|
|
</para>
|
|
|
|
<para>
|
|
Create the directory
|
|
<filename>/etc/hotplug/usb</filename> and add a symlink
|
|
to usbtoken. Also create the directory
|
|
<filename>/var/run/usbtoken</filename> and set
|
|
permissions to 0755 (everyone can access that
|
|
directory):
|
|
<screen>
|
|
ln -s /path/to/opensc/sbin/usbtoken /etc/hotplug/usb/
|
|
mkdir /var/run/usbtoken
|
|
chmod 0755 /var/run/usbtoken
|
|
</screen>
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Security</title>
|
|
|
|
<para>
|
|
By default everyone can use the usbtokens. If you want
|
|
to limit this to a certain user:
|
|
<screen>
|
|
chown user /var/run/usbtoken/
|
|
chmod 0700 /var/run/usbtoken/
|
|
</screen>
|
|
Or if you want to limit this to a certain group:
|
|
<screen>
|
|
chgrp group /var/run/usbtoken/
|
|
chmod 0750 /var/run/usbtoken/
|
|
</screen>
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Debugging</title>
|
|
|
|
<para>
|
|
TODO: send me problem reports and I will add
|
|
advice here.
|
|
</para>
|
|
|
|
<para>
|
|
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.
|
|
</para>
|
|
|
|
<para>
|
|
For development I use a special crafted
|
|
<filename>/sbin/hotplug</filename> shell script
|
|
that creates another script
|
|
<filename>/root/sim</filename> 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
|
|
<command>r usb</command>. My hotplug script:
|
|
<screen>
|
|
#!/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
|
|
</screen>
|
|
</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Porting</title>
|
|
|
|
<para>
|
|
To port usbtoken mainly <filename>usb.c</filename>
|
|
needs some changes. The core sequence for linux
|
|
is:
|
|
<screen><![CDATA[
|
|
|
|
#include <linux/usbdevice_fs.h>
|
|
|
|
...
|
|
|
|
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);
|
|
|
|
]]></screen>
|
|
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.
|
|
</para>
|
|
|
|
<para>
|
|
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.
|
|
</para>
|
|
|
|
<para>
|
|
Finaly usbtoken depends to be called by some
|
|
hotplug mechanism. Under linux the kernel
|
|
executes <filename>/sbin/hotplug</filename>
|
|
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.
|
|
</para>
|
|
|
|
<para>
|
|
Windows? Ugh. I have no idea about windows,
|
|
what we can do, how it works, etc. Volunteers
|
|
welcome.
|
|
</para>
|
|
</section>
|
|
</article>
|