Table of Contents
This is OpenCT, a middleware framework for smart card terminals.
It all started with a reader driver library - Olaf wanted to write a library to provide a framework for people writing drivers for smart card readers. The idea was to provide all the usualy stuff (T=0, T=1, serial vs USB device handling, etc) in a single place, and reduce driver writing to interaction with the device itself.
Olaf added interface bindings for CTAPI and PCSC, both of which are broken at the moment because he ended up writing my own resource manager.
OpenCT is an open source implmentation providing card terminal drivers. OpenCT was written by Olaf Kirch < okir@suse.de>with contributions from the following people:
OpenCT provides CT-API drivers, ifdhandler drivers as well as it's own resource manager for direct use by applications.
Most of OpenCT is copyright by Olaf Kirch < okir@suse.de>, but see every source file for the individual authors.
FIXME: Olaf should realy assign some license to the whole think. I vote for LGPL or BSD license (or both).
To use OpenCT with smart card readers attached to the serial port, you only need a kernel with a working serial port, nothing special is required.
To use OpenCT with smart card readers attached via USB you need a bit more: your kernel needs to support USB and your kernel needs to support the usb controller you are using. On most computers the usb controller is part of the mainboard. If your mainboard uses intel chips you need most likely the "uhci" usb controller support, for other vendors most likely the "ohci" controller support.
FIXME: I'd like to link to some USB howto with all the details and more help. Is there such a HOWTO?
You also need to compile your kernel with support for the USB device filesystem and mount the filesystem to /proc/bus/usb. The kernel option is CONFIG_USB_DEVICEFS, please turn it on. To mount the filesystem, please edit your /etc/fstab. For a linux kernel 2.4.* system, it should have a line
none /proc/bus/usb usbdevfs defaults 0 0 |
and for a linux kernel 2.5.* or 2.6.* system, it should have a line:
none /proc/bus/usb usbfs defaults 0 0 |
Run mount -aafter editing the file /etc/fstabfor the changes to take effect. You can also reboot. If you are using sometimes linux kernels 2.4.* and sometimes 2.5.*/2.6.*, use the line for kernel 2.4.*. You will get a warning, but it will still work.
Your kernel also needs to be compiled with hotplugging support. The relevant kernel option is CONFIG_HOTPLUG. You don't need any of the hardware adaptors.
Table of Contents
First create the directory /var/run/openctand set the permissions. Do this with the commands:
$ mkdir /var/run/openct $ chmod 755 /var/run/openct |
These default permissions will allow everyone on your system to use smart card readers available via OpenCT. For details and a more restricitive setup, please consult the chapter on Security.
Second you need a config file /etc/openct.conf. Copy the file from the source code to /etc:
$ cp etc/openct.conf /etc/ |
You need to edit the config file for any serial reader you might have. If you are only using usb tokens, the default file is already fine.
Third you need an init script to perform some operations on startip and shutdown. OpenCT ships with an init script that should work at least on debian systems. Install the script by copying it from the source directory:
$ cp etc/init-script /etc/init.d/openct |
Now configure your runlevels to start the init script everytime the system boots, and to stop the init script everytime the system shuts down. Use whatever your distribution provides or a gui tool like the kde runlevel editor.
Debian users can do this with a single command:
$ update-rc.d openct start 90 2 3 4 5 . stop 10 0 1 6 . |
Call the init script once with "start". Or reboot. :-)
$ /etc/init.d/openct start |
And now the last task: if you want to use usb readers or usb crypto tokens, you need to configure the hotplug system to call openct everytime there is a new smart card reader or crypto token.
This section applies, if your system does not have hotplug utils installed. If this command suceeds, go to the other section:
$ ls /sbin/hotplug |
If there is no such file, the installation is very easy:
ln -s /path/to/openct/sbin/hotplug.openct /sbin/hotplug |
Now attach some usb smart card reader or usb crypto token. The kernel will start /sbin/hotplug, and openct-tool listshould list the new reader.
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.usermapand add these lines:
openct 0x0003 0x0973 0x0001 0x0000 0x0001 0xff 0x00 0x00 0xff 0x00 0x00 0x0000 0000 openct 0x0003 0x0529 0x050c 0x0000 0x0001 0xff 0x00 0x00 0xff 0x00 0x00 0x0000 0000 openct 0x0003 0x0529 0x0514 0x0000 0x0001 0xff 0x00 0x00 0xff 0x00 0x00 0x0000 0000 openct 0x0003 0x073d 0x0005 0x0000 0x0001 0xff 0x00 0x00 0xff 0x00 0x00 0x0000 0000 openct 0x0003 0x04b9 0x1300 0x0000 0x0001 0xff 0x00 0x00 0xff 0x00 0x00 0x0000 0000 openct 0x0003 0x076b 0x0596 0x0000 0x0001 0xff 0x00 0x00 0xff 0x00 0x00 0x0000 0000 |
Create the directory /etc/hotplug/usband add a symlink "openct" to hotplug.openc.
mkdir /etc/hotplug/openct ln -s /path/to/openct/sbin/hotplug.openct /etc/hotplug/usb/openct |
Edit openct.confand set debug to 4.
If the problem is with some usb crypto token (e.g. Aladdin eToken PRO), please grep for usb_control - these are the lines I need to see what is happening (or not working).
Table of Contents
This chapter will list all tools and files and explain what they do.
This directory holds status files for openct. Create it with:
mkdir /var/run/openct chmod 755 /var/run/openct |
By default everyone can use smartcards via openct. You can create a group "openct", assign users to that group, and limit access to smartcards via openct like this:
chgrp openct /var/run/openct chmod 750 /var/run/openct |
Run openct-control once to setup the statusfile in /var/run/openct. Without that file OpenCT will not work.
aj@simulacron:~/openct$ sbin/openct-control usage: openct-control [-d] [-f configfile] command -d enable debugging; repeat to increase verbosity -f specify config file (default /etc/openct.conf -h display this message Where command is one of: init - initialize OpenCT attach device ident - attach a hotplug device shutdown - shutdown OpenCT |
FIXME: maybe run openct-control everytime on bootup ?
On debian systems install the init script like this:
# update-rc.d openct start 99 2 3 4 5 . stop 01 0 1 6 . Adding system startup for /etc/init.d/openct ... /etc/rc0.d/K01openct -> ../init.d/openct /etc/rc1.d/K01openct -> ../init.d/openct /etc/rc6.d/K01openct -> ../init.d/openct /etc/rc2.d/S99openct -> ../init.d/openct /etc/rc3.d/S99openct -> ../init.d/openct /etc/rc4.d/S99openct -> ../init.d/openct /etc/rc5.d/S99openct -> ../init.d/openct # |
If your kernel has hotplugging, you can configure your linux, so it will launch the driver when a usb crypto token is plugged in (and it terminates when you unplug your key).
If the file /proc/sys/kernel/hotplugexists, then your kernel supports hotplugging. If not, it does not (check CONFIG_HOTPLUG in your kernel configuration).
If your linux has no script /sbin/hotplugyou can simply
ln -s /path/to/openct/sbin/hotplug.openct /sbin/htplug |
This app is called by openct-control to handle onde device, e.g. a smartcard read or an usb token.
aj@simulacron:~/openct/bin$ ./ifdhandler usage: ifdhandler [-Hds] driver device socket -d enable debugging; repeat to increase verbosity -H hotplug device, monitor for detach -s send error and debug messages to syslog -h display this message |
aj@simulacron:~/openct/bin$ ./openct-tool usage: print-atr [-d] [-f configfile] [-r reader] command ... -d enable debugging; repeat to increase verbosity -f specify config file (default /etc/ifd.conf -r specify index of reader to use -h display this message command: can be one of the following list list all readers found atr print ATR of card in selected reader wait wait for card to be inserted mf try to select ATR of card |
# Set debug level
debug = 0;
#
# Enable hot plugging
hotplug = yes;
#
# Path to ifdhandler
ifdhandler = /usr/sbin/ifdhandler;
#
# Statically configure non-hotplug aware readers here
reader towitoko {
driver = towitoko;
device = /dev/ttyS1;
};
#
# Hotplug IDs
driver etoken {
ids = {
usb:0529/050c,
};
};
driver egate {
ids = {
usb:0973/0001,
};
};
|
aj@simulacron:~/openct$ ls include/openct/ apdu.h conf.h driver.h ifd.h openct.h protocol.h socket.h buffer.h device.h error.h logging.h pathnames.h server.h tlv.h |
Install and configure the directory /etc/openct.confas discussed. Configure your CT-API application to load lib/ifd-ctapi.so.
For example to use openct with pcsc-lite, configure /etc/reader.confthis way:
FIXME: add valid reader.conf entry to use openct ifd-ctapi.so |
If your application does not support shared libraries, maybe you have better luck with the static library lib/ifd-ctapi.a. (This is completely untested.)
Install and configure the directory /etc/openct.confas discussed. Configure your CT-API application to load lib/ifdhandler.so.
For example to use openct with pcsc-lite, configure /etc/reader.confthis way:
FIXME: add valid reader.conf entry to use openct ifdhandeler.so |
OpenCT has a proprietory, but very easy to use interface. Take a look at the header files include/opensc/*.hand the library lib/libopenct*.
If your application uses autoconf, we made it easy for you to search for openct and link with libopenct by shipping openct with a pkg-config file: lib/pkg-config/libopenct.pc
See the pkg-config man page for detailed information.
Table of Contents
If something does not work, please join the OpenSC mailing list and ask for help. For details on the mailing list take a look at http://www.opensc.org/
If you try to use a usb device, please try this: Do you have a /procfilesystem? This command should work: ls /proc/sys
Is your kernel compiled with usb support? Does the usb support work? This command should list all usb devices: lsusb
Is your kernel compiled with hotplugging support? This command give the same output on your system:
$ cat /proc/sys/kernel/hotplug /sbin/hotplug $ |
Do you have a hotplug script? This command should work: ls /sbin/hotplug
Did you create the directory /var/run/openct? What files are in there? What are the file permissions? Try this command, it should work and give you a similiar output:
$ ls -la /var/run/openct/ total 8 drwxr-xr-x 2 root root 4096 2003-07-02 08:13 ./ drwxr-xr-x 8 root root 4096 2003-07-02 08:13 ../ -rw-r--r-- 1 root root 1728 2003-07-02 08:13 status $ |
See the security chapter for details on file permissions of this directory.
Are you using an usb smart card reader or usb crypto token? What is it's usb vendor and product id? lsusbwill tell you.
Is that product id listed in openct.conf? If not, please add it.
If you have a file /etc/hotplug/usb.usermal, is the vendor and product id listed in that file? If not, add a line similar to the install chapter. The vendor ID is the second number, the product ID the third number.
If that solves the proble, please let the openct developers know, so we can improve the default configuration and documentation. You can reach us using the OpenSC developer mailing list at < opensc-devel@opensc.org>.
The default setting is not very secure: all users can access your smart card readers. Several processes can use the same smart card reader at the same time, but they always have to be owned by the same users. (FIXME: is it necessary to issue a LOCK command for this, or will it always work like this?)
You can restrict access to smart card readers using OpenCT to one user with these commands:
$ chown user /var/run/openct $ chmod 700 /var/run/openct |
You can also create a group, add users to that group and restrict access to smart card readers using OpenCT to that group with these commands:
$ chgrp group /var/run/openct $ chmod 750 /var/run/openct |
In both cases root can still access the smart card readers. Replace user and group with the user and group of your choice.
If you want all users to be able to access smart card readers using OpenCT:
$ chmod 755 /var/run/openct |