476 lines
16 KiB
HTML
476 lines
16 KiB
HTML
<?xml version="1.0" encoding="utf-8"?>
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
|
|
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<meta http-equiv="Content-Type"
|
|
content="text/html; charset=UTF-8" />
|
|
<title>Driver for USB Crypto Token</title>
|
|
<link rel="stylesheet" href="opensc.css" type="text/css" />
|
|
<meta name="generator"
|
|
content="DocBook XSL Stylesheets V1.60.1" />
|
|
</head>
|
|
<body>
|
|
<div class="article" lang="en" xml:lang="en">
|
|
<div class="titlepage">
|
|
<div>
|
|
<div>
|
|
<h1 class="title">
|
|
<a id="id2799405"></a>Driver for USB Crypto Token</h1>
|
|
</div>
|
|
<div>
|
|
<div class="author">
|
|
<h3 class="author">
|
|
<span class="firstname">Andreas</span>
|
|
<span class="surname">Jellinghaus</span>
|
|
</h3>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div></div>
|
|
<hr />
|
|
</div>
|
|
<div class="toc">
|
|
<p>
|
|
<b>Table of Contents</b>
|
|
</p>
|
|
<dl>
|
|
<dt>
|
|
<a href="#id2799452">About usbtoken</a>
|
|
</dt>
|
|
<dt>
|
|
<a href="#id2799883">Status</a>
|
|
</dt>
|
|
<dt>
|
|
<a href="#id2799935">Compatibility</a>
|
|
</dt>
|
|
<dd>
|
|
<dl>
|
|
<dt>
|
|
<a href="#id2799997">Compatibility List</a>
|
|
</dt>
|
|
</dl>
|
|
</dd>
|
|
<dt>
|
|
<a href="#id2800018">Requirements</a>
|
|
</dt>
|
|
<dt>
|
|
<a href="#id2800062">Compiling OpenSC with USBtoken
|
|
support</a>
|
|
</dt>
|
|
<dt>
|
|
<a href="#id2800076">Installation without hotplug
|
|
utils</a>
|
|
</dt>
|
|
<dt>
|
|
<a href="#id2800125">Installation with hotplut
|
|
utils</a>
|
|
</dt>
|
|
<dt>
|
|
<a href="#id2800184">Security</a>
|
|
</dt>
|
|
<dt>
|
|
<a href="#id2800210">Debugging</a>
|
|
</dt>
|
|
<dt>
|
|
<a href="#id2800262">Porting</a>
|
|
</dt>
|
|
</dl>
|
|
</div>
|
|
<div class="warning"
|
|
style="margin-left: 0.5in; margin-right: 0.5in;">
|
|
<h3 class="title">Warning</h3>Usbtoken is obsolete. Please
|
|
use OpenCT, a new and much improved smartcard framework. You
|
|
can download OpenCT from
|
|
<a href="http://www.opensc.org/files/snapshots"
|
|
target="_top">http://www.opensc.org/files/snapshots</a></div>
|
|
<p>If you still want to use ustoken, you need to enable it
|
|
while configureing OpenSC. For example
|
|
<tt class="prompt">./configure --enable-usbtok</tt></p>
|
|
<div class="section" lang="en" xml:lang="en">
|
|
<div class="titlepage">
|
|
<div>
|
|
<div>
|
|
<h2 class="title" style="clear: both">
|
|
<a id="id2799452"></a>About usbtoken</h2>
|
|
</div>
|
|
</div>
|
|
<div></div>
|
|
</div>
|
|
<p>This project implements a way for OpenSC to access usb
|
|
crypto tokens such as:</p>
|
|
<div class="orderedlist">
|
|
<ol type="1">
|
|
<li>Aladdin eToken PRO</li>
|
|
<li>Rainbow iKey 2032</li>
|
|
<li>Rainbow iKey 3000</li>
|
|
<li>Entron CryptoIdentity</li>
|
|
</ol>
|
|
</div>
|
|
<p>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.</p>
|
|
</div>
|
|
<div class="section" lang="en" xml:lang="en">
|
|
<div class="titlepage">
|
|
<div>
|
|
<div>
|
|
<h2 class="title" style="clear: both">
|
|
<a id="id2799883"></a>Status</h2>
|
|
</div>
|
|
</div>
|
|
<div></div>
|
|
</div>
|
|
<p>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.</p>
|
|
<p>The Eutron CryptoIdentity IT-Sec works fine.</p>
|
|
<p>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.</p>
|
|
<p>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.</p>
|
|
<p>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.</p>
|
|
</div>
|
|
<div class="section" lang="en" xml:lang="en">
|
|
<div class="titlepage">
|
|
<div>
|
|
<div>
|
|
<h2 class="title" style="clear: both">
|
|
<a id="id2799935"></a>Compatibility</h2>
|
|
</div>
|
|
</div>
|
|
<div></div>
|
|
</div>
|
|
<p>PKCS#11 is an API standard. It allowes applications to
|
|
use any library that implements PKCS#11 without changeing
|
|
code.</p>
|
|
<p>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.</p>
|
|
<p>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.</p>
|
|
<p>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.</p>
|
|
<p>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.</p>
|
|
<p>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.</p>
|
|
<p>Using OpenSC on Windows and Linux could solve the
|
|
situation, but I have no experience with OpenSC under
|
|
Windows, sorry.</p>
|
|
<div class="section" lang="en" xml:lang="en">
|
|
<div class="titlepage">
|
|
<div>
|
|
<div>
|
|
<h3 class="title">
|
|
<a id="id2799997"></a>Compatibility List</h3>
|
|
</div>
|
|
</div>
|
|
<div></div>
|
|
</div>
|
|
<p>Aladdin: Their Windows and Unix drivers store keys and
|
|
certificates in the wrong place. (not compatible with
|
|
PKCS#15)</p>
|
|
<p>Eutron: Their Windows and Unix drivers store keys and
|
|
certificates in the wron place. (not compatible with
|
|
PKCS#15)</p>
|
|
</div>
|
|
</div>
|
|
<div class="section" lang="en" xml:lang="en">
|
|
<div class="titlepage">
|
|
<div>
|
|
<div>
|
|
<h2 class="title" style="clear: both">
|
|
<a id="id2800018"></a>Requirements</h2>
|
|
</div>
|
|
</div>
|
|
<div></div>
|
|
</div>
|
|
<p>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
|
|
<tt class="email"><
|
|
<a href="mailto:aj@dungeon.inka.de">
|
|
aj@dungeon.inka.de</a>></tt></p>
|
|
<p>You need a kernel compiled with CONFIG_HOTPLUG and
|
|
CONFIG_USB_DEVICEFS, and the usb device filesystem must be
|
|
mounted to
|
|
<tt class="filename">/proc/bus/usb</tt>. And of course
|
|
kernel support for your usb hub.</p>
|
|
<p>I guess any linux distribution with kernel 2.4 will be
|
|
allright and require no changes.</p>
|
|
<p>Users of other operating systems, please see the porting
|
|
section.</p>
|
|
</div>
|
|
<div class="section" lang="en" xml:lang="en">
|
|
<div class="titlepage">
|
|
<div>
|
|
<div>
|
|
<h2 class="title" style="clear: both">
|
|
<a id="id2800062"></a>Compiling OpenSC with USBtoken
|
|
support</h2>
|
|
</div>
|
|
</div>
|
|
<div></div>
|
|
</div>
|
|
<p>Call configure with --enable-usbtoken and it compile ok.
|
|
No special libraries or stuff needed.</p>
|
|
</div>
|
|
<div class="section" lang="en" xml:lang="en">
|
|
<div class="titlepage">
|
|
<div>
|
|
<div>
|
|
<h2 class="title" style="clear: both">
|
|
<a id="id2800076"></a>Installation without hotplug
|
|
utils</h2>
|
|
</div>
|
|
</div>
|
|
<div></div>
|
|
</div>
|
|
<p>
|
|
<b class="command">ls /sbin/hotplug</b>
|
|
</p>
|
|
<p>If there is no such file, the installation is very
|
|
easy:</p>
|
|
<table border="0" bgcolor="#E0E0E0">
|
|
<tr>
|
|
<td>
|
|
<pre class="screen">
|
|
ln -s /path/to/opensc/sbin/usbtoken /sbin/hotplug
|
|
mkdir /var/run/usbtoken
|
|
chmod 755 /var/run/usbtoken
|
|
</pre>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p></p>
|
|
<p>Now attach some usb token. The kernel will start
|
|
<tt class="filename">/sbin/hotplug</tt>, and you can see
|
|
some usbtoken running as daemon: you will find a pid file
|
|
in
|
|
<tt class="filename">/var/run</tt>and a socket in
|
|
<tt class="filename">/var/run/usbtoken/</tt>.</p>
|
|
</div>
|
|
<div class="section" lang="en" xml:lang="en">
|
|
<div class="titlepage">
|
|
<div>
|
|
<div>
|
|
<h2 class="title" style="clear: both">
|
|
<a id="id2800125"></a>Installation with hotplut
|
|
utils</h2>
|
|
</div>
|
|
</div>
|
|
<div></div>
|
|
</div>
|
|
<p>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.</p>
|
|
<p>Edit
|
|
<tt class="filename">/etc/hotplug/usb.usermap</tt>and add
|
|
these lines:</p>
|
|
<table border="0" bgcolor="#E0E0E0">
|
|
<tr>
|
|
<td>
|
|
<pre class="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
|
|
</pre>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p></p>
|
|
<p>Create the directory
|
|
<tt class="filename">/etc/hotplug/usb</tt>and add a symlink
|
|
to usbtoken. Also create the directory
|
|
<tt class="filename">/var/run/usbtoken</tt>and set
|
|
permissions to 0755 (everyone can access that
|
|
directory):</p>
|
|
<table border="0" bgcolor="#E0E0E0">
|
|
<tr>
|
|
<td>
|
|
<pre class="screen">
|
|
ln -s /path/to/opensc/sbin/usbtoken /etc/hotplug/usb/
|
|
mkdir /var/run/usbtoken
|
|
chmod 0755 /var/run/usbtoken
|
|
</pre>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p></p>
|
|
</div>
|
|
<div class="section" lang="en" xml:lang="en">
|
|
<div class="titlepage">
|
|
<div>
|
|
<div>
|
|
<h2 class="title" style="clear: both">
|
|
<a id="id2800184"></a>Security</h2>
|
|
</div>
|
|
</div>
|
|
<div></div>
|
|
</div>
|
|
<p>By default everyone can use the usbtokens. If you want
|
|
to limit this to a certain user:</p>
|
|
<table border="0" bgcolor="#E0E0E0">
|
|
<tr>
|
|
<td>
|
|
<pre class="screen">
|
|
chown user /var/run/usbtoken/
|
|
chmod 0700 /var/run/usbtoken/
|
|
</pre>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p>Or if you want to limit this to a certain group:</p>
|
|
<table border="0" bgcolor="#E0E0E0">
|
|
<tr>
|
|
<td>
|
|
<pre class="screen">
|
|
chgrp group /var/run/usbtoken/
|
|
chmod 0750 /var/run/usbtoken/
|
|
</pre>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p></p>
|
|
</div>
|
|
<div class="section" lang="en" xml:lang="en">
|
|
<div class="titlepage">
|
|
<div>
|
|
<div>
|
|
<h2 class="title" style="clear: both">
|
|
<a id="id2800210"></a>Debugging</h2>
|
|
</div>
|
|
</div>
|
|
<div></div>
|
|
</div>
|
|
<p>TODO: send me problem reports and I will add advice
|
|
here.</p>
|
|
<p>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.</p>
|
|
<p>For development I use a special crafted
|
|
<tt class="filename">/sbin/hotplug</tt>shell script that
|
|
creates another script
|
|
<tt class="filename">/root/sim</tt>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
|
|
<b class="command">r usb</b>. My hotplug script:</p>
|
|
<table border="0" bgcolor="#E0E0E0">
|
|
<tr>
|
|
<td>
|
|
<pre class="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
|
|
</pre>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p></p>
|
|
</div>
|
|
<div class="section" lang="en" xml:lang="en">
|
|
<div class="titlepage">
|
|
<div>
|
|
<div>
|
|
<h2 class="title" style="clear: both">
|
|
<a id="id2800262"></a>Porting</h2>
|
|
</div>
|
|
</div>
|
|
<div></div>
|
|
</div>
|
|
<p>To port usbtoken mainly
|
|
<tt class="filename">usb.c</tt>needs some changes. The core
|
|
sequence for linux is:</p>
|
|
<table border="0" bgcolor="#E0E0E0">
|
|
<tr>
|
|
<td>
|
|
<pre class="screen">
|
|
|
|
#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);
|
|
|
|
</pre>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<p>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.</p>
|
|
<p>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.</p>
|
|
<p>Finaly usbtoken depends to be called by some hotplug
|
|
mechanism. Under linux the kernel executes
|
|
<tt class="filename">/sbin/hotplug</tt>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.</p>
|
|
<p>Windows? Ugh. I have no idea about windows, what we can
|
|
do, how it works, etc. Volunteers welcome.</p>
|
|
</div>
|
|
</div>
|
|
</body>
|
|
</html>
|