Table of Contents
This is OpenCT, a middleware framework for smart card terminals.
It all started with a reader driver library - Olaf Kirch wanted to write a library to provide a framework for people writing drivers for smart card readers. The idea was to provide all the usual 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.
OpenCT provides a native OpenCT, CT-API and PC/SC Lite IFD interface with an OpenCT ifdhandler resource manager.
OpenCT is an open source implementation providing card terminal drivers. OpenCT was written by Olaf Kirch < okir@suse.de > with contributions from the following people:
Most of OpenCT is copyright by Olaf Kirch < okir@suse.de > under BSD license, but see every source file for the individual authors.
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 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: Add an URL to a generic USB 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 -a after editing the file /etc/fstab for 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 adapters.
First, you need to build the OpenCT libraries and utilities. You do this by first invoking the configure script, for instance
% ./configure --prefix=/usr --sysconfdir=/etc
|
This will try configure OpenCT so it is installed below /usr , and so that it expects its configuration file /etc . If you omit the "--sysconfdir" option, OpenCT will look for the configuration file in $PREFIX/etc .
Next, you need to compile and install all libraries and utilities using
% make
% make install
|
Once that has completed, create the directory /var/run/openct and 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 restrictive setup, please consult the chapter on Security .
Next, you need the configuration file openct.conf . The exact location of the file depends on how you invoked the configure script, but using the options shown above, the file should go 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 startup 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 every time the system boots, and to stop the init script every time 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 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
#
|
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 every time there is a new smart card reader or crypto token. The future releases will work better without hotplug scripts because of multi-OS support issues. For now, we recommend you to install Linux hotplug package before installing OpenCT. After that, the standard install mechanism should add all required files correctly to directory /etc/hotplug .
Edit openct.conf and set debug to 4.
If the problem is with some USB crypto token, please grep for usb_control - these are the lines we need to see what is happening.
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 smart cards via OpenCT. You can create a group "openct", assign users to that group, and limit access to smart cards via openct like this:
chgrp openct /var/run/openct
chmod 750 /var/run/openct
|
Run openct-control once to setup the status file in /var/run/openct . Without that file OpenCT will not work.
# /usr/sbin/openct-control
usage: openct-control [-d] [-f configfile]
command
-d enable debugging; repeat to increase
verbosity
-n disable coldplugging
-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
status - display status of all readers present
shutdown - shutdown OpenCT
|
This app is called by openct-control to handle one device, e.g. a smart card reader or an USB token.
# /usr/sbin/ifdhandler
usage: ifdhandler [-Hds] [-r reader] driver
[device]
-r specify index of reader
-F stay in foreground
-H hotplug device, monitor for detach
-s send error and debug messages to syslog
-d enable debugging; repeat to increase
verbosity
-h display this message
|
# /usr/bin/openct-tool
usage: openct-tool [-d] [-f configfile] [-r
reader] command ...
-d enable debugging; repeat to increase
verbosity
-f specify config file (default
/etc/openct.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
rwait wait for reader to attached
mf try to select main folder of card
read dump memory of synchronous card
|
# Set debug level
debug = 0;
#
# Enable hot plugging
hotplug = yes;
#
# Path to ifdhandler
ifdhandler = /usr/sbin/ifdhandler;
# Configure static, non-hotplug aware readers
here
#
# For a list of drivers try command 'ifdhandler
-i', please
# notice that not all drivers have serial device
capability.
#reader towitoko {
# driver = towitoko;
# device = serial:/dev/ttyS0;
#};
#
# Hotplug IDs
driver egate {
ids = {
usb:0973/0001,
};
};
driver etoken {
ids = {
usb:0529/050c,
usb:0529/0514,
};
};
driver eutron {
ids = {
usb:073d/0005,
};
};
driver ikey2k {
ids = {
usb:04b9/1202,
};
};
driver ikey3k {
ids = {
usb:04b9/1300,
};
};
driver cardman {
ids = {
usb:076b/0596,
};
};
|
Install and configure the file /etc/openct.conf as discussed. Configure your CT-API application to load lib/libopenctapi.so .
Install and configure the file /etc/openct.conf as discussed. Configure PC/SC Lite /etc/reader.conf to load lib/openct-ifd.so .
FRIENDLYNAME "OpenCT"
DEVICENAME OPENCT_DEV
LIBPATH /usr/lib/openct-ifd.so
CHANNELID 1
|
OpenCT has a proprietary, but very easy to use interface. Take a look at the header files include/openct/*.h and 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 /proc filesystem? 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 similar 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? lsusb will tell you.
Is that product id listed in openct.conf ? If not, please add it.
If you have a file /etc/hotplug/usb/openct.usermap , is the vendor and product id listed in that file?
If that solves the problem, 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
|